AIエージェントの基礎

1計画・実行・観測・評価のループ

LLM 単体は「入力に対して1回テキストを返す関数」でしかない。 エージェントは、その周りにツール実行と結果の再入力を置いてループさせたもの。 ループを回しているのは LLM ではなく、あなたが書いたプログラムである点が最初の勘所。

2ツール利用（function calling）の実際

「LLM がツールを実行する」は正確ではない。実際には LLM は「この関数をこの引数で呼んでほしい」という構造化データを返すだけで、 実行するのはあなたのコード。結果を次のメッセージとして戻す。ここを誤解していると、失敗の切り分けができない。

ツールの説明文は、プロンプトの一部である

ツール定義の docstring と引数名・型は、システムプロンプトと同じ重みで LLM の判断に効く。 「なんとなく動く」ツールを増やすと、ツール選択の精度が落ちる（→ 座学③で定量的に扱う）。

@agent.tool
async def scan(ctx, target: str, opt: str) -> str:
    """スキャンする。"""

@agent.tool
async def port_scan(
    ctx: RunContext[Deps],
    ports: str = "1-1000",
    udp: bool = False,
) -> str:
    """TCP/UDPポートを列挙し版を推定する。
    ports は nmap 記法（"1-1000" / "-p-"）。
    全ポートは数分かかる。まず既定範囲で試す。"""

3状態の持ち方とコンテキスト管理

ペンテストは長い。nmap の生出力、ディレクトリ列挙の結果、大量のエラー。素直に全部を履歴に積むと、すぐに必要な情報を保持できなくなる。 ここがマルチエージェントを導入する最大の動機になるので、目で見て納得しておきたい。

from dataclasses import dataclass, field
from pydantic import BaseModel, Field

class Service(BaseModel):
    port: int
    proto: Literal["tcp", "udp"]
    product: str | None = None
    version: str | None = None
    evidence: str = Field(description="この判断の根拠になった生出力の抜粋")

class EngagementState(BaseModel):
    """標的1台ぶんの共有状態。全エージェントがここを見る。"""
    target: str
    services: list[Service] = []
    credentials: list[Credential] = []
    shells: list[ShellHandle] = []
    tried: list[Attempt] = []      # 何を試して何が起きたか＝ループ検知の材料
    artifacts_dir: Path            # 生ログはファイルへ。履歴には入れない

4失敗回復

ペンテストにおいて失敗は例外ではなく常態。PoC は動かないのが普通で、 「失敗をどう扱うか」がエージェントの性能そのものになる。失敗の層を分けて考える。

from pydantic_ai import Agent, RunContext, ModelRetry

@exploit_agent.tool
async def run_on_shell(ctx: RunContext[Deps], shell_id: str, cmd: str) -> str:
    """取得済みシェル上でコマンドを実行する。shell_id は list_shells() の値。"""
    if shell_id not in ctx.deps.state.shell_ids():
        # 層1：LLMの誤りなので、訂正のヒント付きで差し戻す
        raise ModelRetry(f"shell_id={shell_id} は存在しない。"
                         f"有効なID: {ctx.deps.state.shell_ids()}")
    return await ctx.deps.shells.exec(shell_id, cmd)


@exploit_agent.output_validator
async def require_evidence(ctx: RunContext[Deps], out: ExploitResult) -> ExploitResult:
    # 層4：証拠なき成功報告を受け付けない
    if out.shell_obtained and not out.id_output:
        raise ModelRetry(
            "シェル取得を主張するなら run_on_shell で `id` を実行し、"
            "その生出力を id_output に入れること。未実行なら shell_obtained=False。"
        )
    return out

5Pydantic AI での書き方

ここまでの概念が、コード上でどの部品に対応するかを押さえる。 テンプレート実装を読む前に、この対応表を頭に入れておくと座学④が速い。

from dataclasses import dataclass
from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    """ツールが必要とする外界。テスト時は差し替えられる。"""
    target: str
    shell: ShellRunner
    state: EngagementState

class ReconResult(BaseModel):
    services: list[Service]
    next_targets: list[str]
    stopped_because: str   # 打ち切り理由を必ず書かせる（TYPE C の可視化）

recon_agent = Agent(
    "anthropic:claude-sonnet-5",
    deps_type=Deps,
    output_type=ReconResult,
    system_prompt=(
        "あなたは偵察担当。攻撃面の確定が目的で、侵入は行わない。"
        "列挙は網羅より優先順位。打ち切ったら理由を stopped_because に書く。"
    ),
)

@recon_agent.tool
async def port_scan(ctx: RunContext[Deps], ports: str = "1-1000") -> str:
    """TCPポートを列挙し版を推定する。ports は nmap 記法。
    "-p-" は全65535ポートで数分かかる。まず既定範囲から。"""
    raw = await ctx.deps.shell.run(f"nmap -sV -p {ports} {ctx.deps.target}")
    ctx.deps.state.save_artifact("nmap", raw)   # 生出力はファイルへ＝証拠
    return summarize_nmap(raw)                    # 履歴には要点だけ返す

# 現在の状態をプロンプトに差し込む。
# これがないと LLM は「今どこまで進んだか」を履歴から読み取るしかなく、
# ターンが伸びるほど取りこぼす。

@recon_agent.system_prompt
async def current_findings(ctx: RunContext[Deps]) -> str:
    s = ctx.deps.state
    return (
        f"## 標的\n{s.target}\n\n"
        f"## 確認済みサービス\n{s.render_services()}\n\n"
        f"## 既に試して失敗した手\n{s.render_tried()}\n"
        "上記と同じ試行を繰り返さないこと。"
    )

from pydantic_ai.usage import UsageLimits

result = await recon_agent.run(
    "標的の攻撃面を確定させてください。",
    deps=deps,
    usage_limits=UsageLimits(request_limit=25),   # 暴走の最終防波堤
)

result.output          # -> ReconResult（型が保証されている）
result.usage()         # -> 要求数・トークン数。評価指標そのもの
result.all_messages()  # -> 全メッセージ。次の実行に渡せばコンテキストを引き継げる

# 続きから走らせる場合
follow = await recon_agent.run(
    "UDPの主要ポートも確認してください。",
    deps=deps,
    message_history=result.all_messages(),   # ← ここが伸びる。何を渡すかが設計
)

＊この座学の要点

ここまではエージェント1体の話。しかし実際にペンテストをやらせると、 1体ではコンテキストが持たず、責務が混ざり、ツールが多すぎて選べなくなる。 次の 座学③ で、なぜ分けるのか・どう分けるのかを扱う。このコマの中心はここから。