Bridgic Amphibious
デュアルモードエージェントフレームワーク：エージェントは LLM 駆動（on_agent）と決定論的（on_workflow）モードで動作し、自動的にフォールバックします。
依存関係
bridgic-amphibious プロジェクトには以下のパッケージが必要です：
| パッケージ | 説明 |
|---|---|
bridgic-core | コアフレームワーク（Worker、Automa、GraphAutoma、ASL） |
bridgic-amphibious | デュアルモードエージェントフレームワーク |
bridgic-llms-openai | LLM プロバイダ（AGENT / AMPHIFLOW モードのみ必須） |
python-dotenv | .env ファイルの読み込み |
このパッケージを使用する前に、提供されているインストールスクリプトを使って依存関係をインストールする必要があります：
bash "skills/bridgic-amphibious/scripts/install-deps.sh" "$PWD"
スクリプトは uv の可用性を確認し、必要に応じて uv プロジェクトを初期化し、uv add で不足しているパッケージをインストールし、uv sync を実行して環境を確定します。正常に終了すると、プロジェクトは完全に初期化され、すぐに使用可能になります。手動での uv add / uv sync のフォローアップは不要です。
LLM セットアップ
Amphibious エージェントは、bridgic LLM プロバイダパッケージの astructure_output プロトコルを持つ BaseLlm インスタンスを受け入れます。LLM は AGENT および AMPHIFLOW モードで必須です。純粋な WORKFLOW モードは LLM なしで実行できます。
from bridgic.llms.openai import OpenAILlm, OpenAIConfiguration
llm = OpenAILlm(
api_key="your-api-key",
api_base="https://api.openai.com/v1", # またはカスタムエンドポイント
configuration=OpenAIConfiguration(model="gpt-4o", temperature=0.0),
)
同じプロトコルを持つ他のプロバイダ：bridgic.llms.vllm.VllmServerLlm（セルフホスト vLLM）。
クイックスタート
from bridgic.amphibious import (
AmphibiousAutoma, CognitiveContext, CognitiveWorker, think_unit,
)
from bridgic.core.agentic.tool_specs import FunctionToolSpec
async def get_weather(city: str) -> str:
"""都市の天気を取得します。"""
return f"晴れ、{city} で 22°C"
class WeatherAgent(AmphibiousAutoma[CognitiveContext]):
planner = think_unit(
CognitiveWorker.inline("天気を調べて要約してください。"),
max_attempts=5,
)
async def on_agent(self, ctx: CognitiveContext):
await self.planner
agent = WeatherAgent(llm=llm, verbose=True)
result = await agent.arun(
goal="東京とロンドンの天気を確認してください。",
tools=[FunctionToolSpec.from_raw(get_weather)],
)
プロジェクトスキャフォールディング
CLI を使用して新しいプロジェクトをブートストラップします：
bridgic-amphibious create -n my_project
bridgic-amphibious create -n my_project --task "example.com に移動してデータを抽出"
bridgic-amphibious create -n my_project --base-dir /path/to/projects
作成されるファイル：task.md、config.py、tools.py、workers.py、agents.py、skills/、result/、log/。
コアコンセプト
エージェント = 思考ユニット + コンテキストオーケストレーション。 エージェントは CognitiveWorker 思考ユニットを宣言し、on_agent() または on_workflow() でオーケストレーションすることで定義されます。
4層アーキテクチャ：
Exposure— データ可視性の抽象化（LayeredExposure / EntireExposure）CognitiveContext— 状態コンテナ（goal、tools、skills、history）CognitiveWorker— 純粋な思考ユニット（観察-思考-行動）AmphibiousAutoma— オーケストレーションエンジン（モードルーティング、ライフサイクル）
OTC サイクル： 観察 -> 思考 -> 行動、各フェーズにフックポイントあり。
4つの実行モード： AGENT（LLM 駆動）、WORKFLOW（決定論的）、AMPHIFLOW（ワークフロー + エージェントフォールバック）、AUTO（オーバーライドされたメソッドから自動検出、デフォルト）。
AUTO 解決： on_agent のみオーバーライド -> AGENT；on_workflow のみオーバーライド -> WORKFLOW；両方オーバーライド -> AMPHIFLOW。
主要パターン
エージェントモード — LLM が決定
class MyAgent(AmphibiousAutoma[CognitiveContext]):
worker = think_unit(CognitiveWorker.inline("次のステップを決定します。"), max_attempts=10)
async def on_agent(self, ctx):
await self.worker
ワークフローモード — 開発者が決定
from bridgic.amphibious import ActionCall
class MyWorkflow(AmphibiousAutoma[CognitiveContext]):
async def on_workflow(self, ctx):
result = yield ActionCall("tool_name", arg1="value")
# result は List[ToolResult]
# 純粋なワークフローモードは LLM を必要としません。
await MyWorkflow().arun(goal="...", tools=[...])
Amphiflow モード — ワークフロー + エージェントフォールバック
from bridgic.amphibious import RunMode, AgentCall
class MyHybrid(AmphibiousAutoma[CognitiveContext]):
fixer = think_unit(CognitiveWorker.inline("問題を修正します。"), max_attempts=5)
async def on_agent(self, ctx): await self.fixer
async def on_workflow(self, ctx):
yield ActionCall("fill_field", name="user", value="john")
yield ActionCall("click_button", name="submit")
await MyHybrid(llm=llm).arun(
goal="...", tools=[...],
mode=RunMode.AMPHIFLOW, max_consecutive_fallbacks=2,
)
人間参加型ループ（Human-in-the-Loop）
from bridgic.amphibious import ActionCall, HumanCall
class MyAgent(AmphibiousAutoma[CognitiveContext]):
worker = think_unit(CognitiveWorker.inline("ステップを実行します。"), max_attempts=10)
async def on_agent(self, ctx):
await self.worker
feedback = await self.request_human("続行しますか？") # エントリ1: コードレベル
async def on_workflow(self, ctx):
yield ActionCall("do_something", arg="value")
feedback = yield HumanCall(prompt="確認しますか？") # エントリ2: ワークフローでの yield
# エントリ3: LLM ツール — `request_human` はすべてのエージェントの
# ツールに自動注入されるため、LLM は tools=[...] にリストしなくても呼び出せます。
# （`request_human_tool` を明示的に渡しても問題ありません。重複排除されます。）
await MyAgent(llm=llm).arun(goal="...", tools=[my_tool])
# 明示的にしたい場合は、インポートして渡しても問題ありません。
from bridgic.amphibious.builtin_tools import request_human_tool
await agent.arun(goal="...", tools=[request_human_tool, ...]) # これでも OK
カスタム Pydantic 出力
from pydantic import BaseModel
class Plan(BaseModel):
phases: list[str]
class Planner(AmphibiousAutoma[CognitiveContext]):
plan = think_unit(
CognitiveWorker.inline("計画を立ててください。", output_schema=Plan),
max_attempts=1,
)
async def on_agent(self, ctx):
result = await self.plan # Plan インスタンスを返す
フェーズアノテーション（スナップショット）
async def on_agent(self, ctx):
async with self.snapshot(goal="リサーチフェーズ"):
await self.researcher
async with self.snapshot(goal="ライティングフェーズ"):
await self.writer
参考ファイル
- アーキテクチャ詳細（実行モード、露出システム、メモリ階層、認知ポリシー）：references/architecture.md を参照
- 完全な API リファレンス（すべてのクラス、メソッド、パラメータ、型）：references/api-reference.md を参照
- コードパターンと例の完全版（すべてのフックタイプ、スキル、トレーシング、フィルタリングなど）：references/patterns.md を参照