テンプレート実装の
アーキテクチャ読解

1ファイル構成 — 依存の向きが設計そのもの

このテンプレートで最も重要な一行は、README に書かれたこれ。
「agentXX.py は他の agentYY.py を import しません。」 依存先は config.py だけで、エージェント同士の接続はすべて core.py が行う。

2AgentModule プロトコル — agentXX.py を同じ形で扱う約束

core.py は、agent01.py の中身を詳しく読みに行かない。 見るのは NAME、CARD、agent、run() の4つだけ。 この4つが揃っていれば、core.py は「これは呼び出せるエージェントだ」と判断できる。

つまり AgentModule は「実装の中身」ではなく、他のファイルから見える入口の形を決める約束。 Python のクラス継承ではなく、必要な名前と関数が揃っているかを見るための型だと考えると分かりやすい。

NAME = "agent01"

CARD = AgentCard(
    name=NAME,
    title="偵察",
    description=("ポート、サービス、HTTP エンドポイント、技術スタックを列挙し、"
                 "脆弱性候補を evidence 付きの findings にまとめる。"),
    tags=["recon", "enumeration", "pentest"],
    example_query="10.10.10.5 の攻撃面を調べて",
)

agent = Agent(
    build_model(NAME),              # AGENT01_MODEL_NAME で個別に差し替えられる
    name=NAME,
    deps_type=AppDeps,              # ← 座学②の「依存の注入」
    output_type=Agent01Output,      # ← 座学②の「出力の型」
    instructions=INSTRUCTIONS,
    model_settings=build_model_settings(temperature=0.1),
    retries=get_settings().max_retries,
    capabilities=CAPABILITIES,      # ネイティブ Web 検索（→ 8節）
)

async def run(query, deps, *, usage=None, usage_limits=None, message_history=None):
    async with track_run(deps, NAME, query) as record:   # ← 記録（→ 6節）
        result = await agent.run(query, deps=deps, usage=usage,
                                  usage_limits=usage_limits or build_usage_limits(),
                                  message_history=message_history)
        record.set_output(result.output)
        return result.output

32つの実行モード — 委譲と決め打ち

同じ3体のエージェントを、2通りの繋ぎ方で動かせる。 座学③で扱った「トポロジ」の実例が、そのまま両方入っている。

async def run_pipeline(query: str, deps: AppDeps) -> RunResult:
    usage = RunUsage()
    limits = build_usage_limits()

    async with track_run(deps, "pipeline", query) as record:
        recon = await agent01.run(query, deps, usage=usage, usage_limits=limits)

        exploit_prompt = (
            f"# 依頼\n{query}\n\n"
            f"# 偵察結果 (agent01)\n{recon.model_dump_json(indent=2)}\n\n"   # ← 丸ごと埋め込む
            "上記の候補から、承認ゲートを通して侵入可否を検証してください。"
        )
        foothold = await agent02.run(exploit_prompt, deps, usage=usage, usage_limits=limits)

        privesc_prompt = (
            f"# 依頼\n{query}\n\n"
            f"# 偵察結果 (agent01)\n{recon.model_dump_json(indent=2)}\n\n"
            f"# 侵入結果 (agent02)\n{foothold.model_dump_json(indent=2)}\n\n"
            "取得済みの足がかりを使って権限昇格を試み、証拠を残してください。"
        )
        privesc = await agent03.run(privesc_prompt, deps, usage=usage, usage_limits=limits)

        output = PipelineOutput(query=query, recon=recon, foothold=foothold, privesc=privesc)
        record.set_output(output)
        return RunResult(output, usage)     # usage は3体ぶんが合算されている

4委譲の実装 — SubAgents と RecordingAgent

座学③では「委譲ツールの中で別の Agent を run する」と説明したが、 このテンプレートは委譲ツールを手書きしていない。 pydantic-ai-harness の SubAgents に宣言するだけで生成される。

SUBAGENTS = [
    SubAgent(
        RecordingAgent(module.agent, module.NAME),      # ← 入出力を記録するラッパー（後述）
        name=module.NAME,
        description=f"{module.CARD.title}: {module.CARD.description}",   # ← CARD がここで効く
        usage_limits=build_usage_limits(),              # 委譲1回あたりの上限
        timeout_seconds=get_settings().api_timeout,     # 時間切れ
        max_calls=2,                                 # 同じ相手を呼べる回数 ← ループ抑制
        on_failure=(f"{module.NAME} の委譲に失敗しました。"
                    "これは回復可能な事象として扱い、手元の情報で判断を続けてください。"),
    )
    for module in AGENT_MODULES.values()      # ← レジストリから自動生成
]

orchestrator: Agent[AppDeps, OrchestratorOutput] = Agent(
    build_model(ORCHESTRATOR_NAME),
    ...
    capabilities=[
        SubAgents(
            agents=SUBAGENTS,
            agent_folders=None,       # ディスクからの自動読み込みは切る（登録場所を1つに集約）
            forward_usage=True,      # ← 親の usage を子へ。ツリー全体で上限判定
        )
    ],
)

SubAgent 宣言の4つのつまみは、そのまま座学③の設計判断

1回の委譲で何が起きているか

RecordingAgent がなぜ必要か

ここは実装の都合から生まれた仕掛けで、しかも読み飛ばすと後で必ず混乱する。 SubAgents は各サブエージェントの Agent.run() を直接呼ぶ。 つまり agent01.run()（＝track_run で包んだ関数）を通らない。

class RecordingAgent(WrapperAgent[Any, Any]):
    def __init__(self, wrapped, name: str) -> None:
        super().__init__(wrapped)
        self._record_name = name

    async def run(self, user_prompt=None, **kwargs):
        deps = kwargs.get("deps")
        if not isinstance(deps, AppDeps):          # 記録先が無ければ素通し
            return await self.wrapped.run(user_prompt, **kwargs)

        async with track_run(deps, self._record_name, str(user_prompt or "")) as record:
            result = await self.wrapped.run(user_prompt, **kwargs)
            record.set_output(result.output)
            return result

output.used_agents = [run.agent for run in deps.runs if run.agent in AGENT_MODULES]

5AppDeps — 共有状態と依存注入

座学②で見た deps_type の実体。 全エージェント・全ツールが ctx.deps で触る唯一の共有物で、 ここに何が入っているかを把握すれば、エージェント間で何を共有できるかが分かる。

# config.py — 汎用の口だけを提供する（AGENT01_* を知らない）
def agent_flag(agent_key: str, name: str, *, default: bool = False) -> bool: ...
def agent_int(agent_key: str, name: str, *, default: int) -> int: ...

# agent01.py — 自分の設定は自分で読む（AGENT01_ENABLE_WEB_SEARCH）
ENABLE_WEB_SEARCH = agent_flag(NAME, "ENABLE_WEB_SEARCH", default=True)
WEB_FETCH_MAX_CHARS = agent_int(NAME, "WEB_FETCH_MAX_CHARS", default=4000)

# agent02.py
ENABLE_PYTHON = agent_flag(NAME, "ENABLE_PYTHON", default=True)
PYTHON_TIMEOUT = agent_int(NAME, "PYTHON_TIMEOUT", default=30)

@agent.tool
async def web_fetch(ctx: RunContext[AppDeps], url: str, max_chars: int = WEB_FETCH_MAX_CHARS):
    """公開 Web ページを取得し、タグを除いた本文テキストを返す。"""
    _validate_public_url(url)                        # SSRF 検査（→ 8節）

    try:
        response = await ctx.deps.http.get(url)     # ← 共有クライアントを借りる
        response.raise_for_status()
    except Exception as exc:
        ctx.deps.record(NAME, "web_fetch_failed", url=url, error=str(exc))
        raise ModelRetry(f"ページの取得に失敗しました: {exc}") from exc
    ...
    ctx.deps.record(NAME, "web_fetch", url=page.url, status=page.status, chars=len(page.text))
    return page

6ログ設計 — trace と runs の2層

座学③で「ログはデバッグのためではなく切り分けのために設計する」と述べた。 このテンプレートは、その考え方を2つの別の型として実装している。 ここが読解のいちばんの収穫になるはず。

class TraceStep(BaseModel):
    agent: str
    message: str       # "start"/"done"/ツール名
    at: str
    data: dict       # 引数など

class AgentRunRecord(BaseModel):
    agent: str
    input: str        # プロンプト全文
    output: dict | None
    events: list[TraceStep]  # ツール呼び出し
    duration_ms: float | None
    error: str | None

record() の地味だが効いている実装

def record(self, agent: str, message: str, **data) -> None:
    step = TraceStep(agent=agent, message=message, data=data)
    self.trace.append(step)
    if message not in ("start", "done", "error"):
        for run in reversed(self.runs):          # ← 実行中の record を後ろから探す
            if run.agent == agent and not run.finished:
                run.events.append(step)              # ← そこにツール呼び出しをぶら下げる
                break

1回の record() で、時系列（trace）と実行単位（runs[].events）の両方に入る。 ツール呼び出しが「どのエージェントのどの実行で起きたか」に正しく紐づくのはこの5行のおかげ。 同じエージェントを2回呼んだときに、1回目と2回目のツール呼び出しが混ざらないのが要点。

失敗も記録に残す

# core.py の execute() — 例外が出ても履歴に書いてから再送出する
try:
    result = runner.submit(coro_factory(deps, query), timeout=settings.api_timeout)
except Exception as exc:
    if store is not None:
        store.add(HistoryEntry(..., ok=False, error=f"{type(exc).__name__}: {exc}",
                               runs=deps.runs_dump(), trace=deps.trace_dump(), ...))
    raise

7Artifact — エージェント間のファイル受け渡し

テキストはプロンプトに埋め込めるが、画像は埋め込めない。 agent02 が作ったグラフを agent03 が本文に載せる、という連携をどう実装するか。 ここには「LLM に URL を捏造させない」ための仕掛けが入っている。

# agent02.py — 自分が作っていないグラフを報告できない
@agent.output_validator
def _validate_charts(ctx: RunContext[AppDeps], output: Agent02Output) -> Agent02Output:
    known = {a.url for a in ctx.deps.artifacts}
    unknown = [c.url for c in output.charts if c.url not in known]
    if unknown:
        raise ModelRetry(f"存在しないグラフ URL があります: {unknown}. "
                         "run_python が返した charts の url をそのまま使ってください。")
    return output

8ツール層 — 4種類のツールを見分ける

@agent.tool が付いていれば全部同じ、ではない。 このテンプレートには実行場所の違う4種類が入っていて、 それぞれ失敗の仕方も、対策すべきことも違う。

④ ネイティブツール — 制御できないぶん、縮退のさせ方が重要

# agent01.py
CAPABILITIES = [NativeTool(WebSearchTool(optional=True))] if ENABLE_WEB_SEARCH else []

③ run_python — 「サンドボックスではない」と明記してある

② SSRF 検査 — ツールの引数はモデルが自由に決められる

def _validate_public_url(url: str) -> str:
    parsed = urlparse(url)
    if parsed.scheme not in ("http", "https"):        raise ModelRetry(...)
    if parsed.username or parsed.password:              raise ModelRetry(...)
    host = (parsed.hostname or "").lower()
    if host in _BLOCKED_HOSTS or host.endswith(_BLOCKED_SUFFIXES): raise ModelRetry(...)
    try:
        address = ipaddress.ip_address(host)
    except ValueError:
        return url                                        # ホスト名はそのまま通す
    if address.is_private or address.is_loopback \
       or address.is_link_local or address.is_reserved:  raise ModelRetry(...)
    return url

169.254.169.254（クラウドのメタデータ）・localhost・プライベート IP・.internal・ 認証情報付き URL を拒否している。コメントに限界も書いてある — 「DNS 解決までは見ていない」。
ツールの引数は LLM が決めるという事実から出発すると、この種の検査が必要になる理由が分かる。 テストでは7パターンの拒否を検証している。

9暴走防止 — 3重の壁と、エラーの出口

座学③のループ検知・予算配分が、ここでは3つの独立した制限として実装されている。 どれか1つではなく、効く条件が違うものを重ねているのが要点。

エラーは HTTP ステータスに対応づけて外へ出す

座学②で「失敗を層に分ける」と述べた。 core.py はそれをFlask のエラーハンドラとして実装し、 症状を見ただけで原因の層が分かるようにしている。

10agent04 を足す — 何が自動で追従するか

ここまで見た仕掛けの見返りがこの節。 新しいエージェントを足すのに触るファイルは2つだけで済む。

vim agent02.py                    # プロンプト / ツールを修正
python agent02.py "テスト入力"      # 単体で動作確認（最速）
pytest tests/test_agent02.py -v   # 回帰していないか
python core.py --pipeline "…"      # 前段の出力を渡して確認

python agent02.py "…"              # ① 単体で正しいか
python core.py --agent agent02 "…" # ② レジストリ経由でも同じか
python core.py --pipeline "…"      # ③ 前段の出力を渡しても同じか
python core.py "…"                 # ④ 委譲でも同じか

11「なぜこの設計なのか」を議論する

ここからは解説ではなく、3人で議論しながら読むパート。 どれもトレードオフのある判断で、正解は用途によって変わる。 自分の答えを出してから開くこと。

12当日の読解手順

35分で 4,200 行は読めない。この順で、この問いを持って読む。

＊コマ1の締め

座学が終わったら、4本の要点を突き合わせてコマ2で最初にどこへ手をつけるかを3人で決める。読解メモに書き留めた改善の候補が、そのまま着手順の候補になる。