← 試験の目次へ

Developer Foundations ドメイン1: エージェントとワークフロー（14.7%）

この章で学ぶこと: エージェントとワークフローの違い、Claude でエージェントを作る方法、よく使う設計パターン。

本番の53問のうち、このドメインから約8問出る計算です。

注意: 製品の機能名やパラメータ名は変わることがあります。この教材は2026年11月時点の公式ドキュメントにもとづきます。本番前に公式ドキュメントで最新を確認してください。

1. エージェントのアーキテクチャ（4.5%）

1.1 ワークフローとエージェントの違い

Anthropic は、LLM とツールを組み合わせたシステム全体を「エージェント型システム（agentic systems）」と呼び、その中を2つに分けています。

具体例:

• 請求書の処理（読む → 項目を抜き出す → 形式をチェック → 登録）は手順が決まっている。ワークフローが向く
• 「このバグを直して」は、何ファイル直すか事前にわからない。エージェントが向く

1.2 どちらを選ぶか: いちばん簡単な方法から

Anthropic の推奨は「できるだけ簡単な方法を選び、必要なときだけ複雑にする」です。

トレードオフ: エージェント型システムは、精度を上げる代わりにレイテンシとコストが増えます。エージェントは自律的なので、コストが高く、ミスが積み重なるおそれもあります。サンドボックスでの十分なテストとガードレールが推奨されています。

試験で問われやすい判断: 「エージェントにすべきか」と聞かれたら、まず「もっと簡単な方法で足りないか」を考えます。

1.3 基本の部品: 拡張 LLM（augmented LLM）

エージェント型システムの土台は、検索（retrieval）・ツール・メモリで強化された LLM です。Claude は自分で検索クエリを作り、ツールを選び、何を覚えておくかを決められます。これらをつなぐ方法の1つが MCP（Model Context Protocol）です。

1.4 5つのワークフローパターン

並列化とオーケストレーター・ワーカーの違い: 形は似ていますが、並列化はサブタスクが事前に決まっています。オーケストレーター・ワーカーは、入力を見てからサブタスクを決めます。

1.5 マネージャー/スーパーバイザー型の階層

マネージャー（スーパーバイザー）が仕事を分けて部下のエージェントに任せる構成です。Anthropic の Research 機能はこの形（オーケストレーター・ワーカー型）で作られています。

• リードエージェントが質問を分析し、戦略を立て、サブエージェントを並列に起動する
• サブエージェントは自分のコンテキストで検索をくり返し、要点だけをリードに返す
• リードが結果をまとめて最終回答を作る

Anthropic が公開した数字（社内評価）:

マルチエージェントが向かない場面: すべてのエージェントが同じコンテキストを共有する必要がある仕事や、エージェント同士の依存関係が多い仕事。例として、多くのコーディング作業は調査ほど並列にできません。

マネージャーへの指示のこつ（同じ記事より）:

• 各サブエージェントに、目的・出力形式・使うツールと情報源・仕事の範囲を伝える。指示があいまいだと、仕事が重なったり抜けたりする
• 質問の難しさに合わせて力の入れ方を決める。例: 簡単な事実確認は1エージェントでツール呼び出し3〜10回、複雑な調査は10以上のサブエージェント

1.6 サブエージェントがタスク実行を良くする理由

Claude Agent SDK のドキュメントは、サブエージェントの利点を4つ挙げています。

2. Claude でのエージェント構築（5.3%）

2.1 Claude で作る4つの方法

Python や TypeScript 以外の言語から同じループを使いたいときは、CLI を -p フラグと --output-format json 付きでサブプロセスとして起動する方法があります。

2.2 独自のエージェントループ（Messages API）

ツールを使うやりとりは、次のくり返しです。

1. ツールの定義（名前、説明、input_schema）とメッセージを送る
2. Claude がツールを使いたいとき、応答は stop_reason: "tool_use" になり、tool_use ブロックが入る
3. 自分のコードでそのツールを実行し、結果を tool_result ブロックで返す
4. stop_reason が "tool_use" でなくなる（例: "end_turn"）まで、2〜3 をくり返す

import anthropic

client = anthropic.Anthropic()  # APIキーは環境変数 ANTHROPIC_API_KEY から読む

tools = [{
    "name": "get_order_status",
    "description": "注文番号から注文の状況を返す。注文番号は '#' から始まる数字。",
    "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
    },
}]

messages = [{"role": "user", "content": "注文 #1234 はいつ届きますか？"}]

while True:
    response = client.messages.create(
        model="MODEL_ID",          # 使うモデルのIDを入れる
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    # Claude の応答を履歴に足す（ツール呼び出しも含めて）
    messages.append({"role": "assistant", "content": response.content})

    # ツールを使わなくなったら終わり
    if response.stop_reason != "tool_use":
        break

    # 要求されたツールをすべて実行し、結果を返す
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            result = run_tool(block.name, block.input)  # 自分で実装する関数
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,   # どの呼び出しへの結果かを対応づける
                "content": result,
            })
    messages.append({"role": "user", "content": tool_results})

print(response.content[-1].text)

ポイント:

• ツールの結果は会話の履歴に足していく。だから Claude は次の行動を考えられる
• ループを続けるか止めるかは stop_reason で判断する。応答の文章を読んで判断しない
• ツールには2種類ある。クライアントツール（自分のアプリで実行する）と、サーバーツール（web_search、web_fetch、code_execution など。Anthropic 側で実行される）

2.3 Claude Agent SDK

Agent SDK は、Claude Code を動かしている「ツール・エージェントループ・コンテキスト管理」を、Python と TypeScript のライブラリとして使えるようにしたものです。

ループの流れ:

1. プロンプトを受け取る（SDK は SystemMessage、subtype "init" を出す）
2. Claude が考え、文章かツール呼び出しを返す（AssistantMessage）
3. SDK がツールを実行し、結果を Claude に返す（UserMessage）。フックで実行前に止めたり変えたりできる
4. ツール呼び出しがなくなるまで 2〜3 をくり返す
5. 最後に ResultMessage（最終の文章、トークン使用量、コスト、セッションID）を出す

組み込みツールの例:

ループを制御するおもな設定（Python 名 / TypeScript 名）:

権限モード（permission mode）は6つです。

effort（推論の深さ）は5段階です。

注意: 使えるレベルと初期値はモデルごとに違います。多くのモデルの初期値は high ですが、medium が初期値のモデルもあります。xhigh や max に対応しないモデルもあります。

ResultMessage の subtype で結果を確かめます: success、error_max_turns、error_max_budget_usd、error_during_execution、error_max_structured_output_retries。最終の文章（result）は success のときだけ入ります。

権限モードの使い分け（公式の推奨）: 対話アプリは default と承認用コールバック、開発機でファイルを編集するエージェントは acceptEdits、bypassPermissions は CI やコンテナなど隔離された環境だけ。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage

async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Grep", "Glob", "Agent"],
        agents={
            "code-reviewer": AgentDefinition(
                description="コードの品質とセキュリティを確認するレビュー担当。",
                prompt="あなたはコードレビューの専門家です。問題点と修正案を挙げてください。",
                tools=["Read", "Grep", "Glob"],  # 読むだけ。編集はできない
            ),
        },
        max_turns=20,
    )
    async for message in query(prompt="src/auth をレビューして", options=options):
        if isinstance(message, ResultMessage):
            print(message.subtype, message.total_cost_usd)

asyncio.run(main())

2.4 配備のしかた: 自前ホスト と Anthropic ホスト

自前ホストのセッションの型（例）:

• 使い捨て（ephemeral）: 仕事ごとにコンテナを作り、終わったら消す。例: バグ調査と修正、請求書の抽出、文書の翻訳
• 長時間（long-running）: コンテナを動かし続ける。例: メールを仕分けて返信するエージェント、Slack のチャットボット

Managed Agents の4つの概念:

Managed Agents の注意点（2026年11月時点）:

• ベータ版です。すべてのモデルで、ベータとして提供されています
• すべてのエンドポイントにベータヘッダー managed-agents-2026-04-01 が必要です。公式 SDK を使うと自動で付きます
• 状態を持つ設計（会話履歴、サンドボックスの状態、出力をサーバー側に保存する）のため、現時点ではゼロデータ保持（Zero Data Retention）や HIPAA BAA の対象外です。医療データなどの要件があるときは注意します
• 保存されたデータは、API でセッションやアップロードしたファイルを削除して管理できます

2.5 フック: 決まった処理を確実に行う

フックは、ループの決まったタイミングで自分のコードを実行するしくみです。フックはアプリのプロセスで動くので、コンテキストを使いません。

なぜフックか: プロンプトで「〇〇しないで」と書いても、モデルが守る確率は100%ではありません。必ず守らせたいルール（例: rm -rf を止める、上限額を超える返金を止める）はフックで強制します。PreToolUse フックが拒否すると、ツールは実行されず、Claude は拒否のメッセージを受け取ります。

Agent SDK（Python）での例。公式の hooks ページの形に合わせています。

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

# フックの関数は3つの引数を受け取る
async def block_dangerous_bash(input_data, tool_use_id, context):
    # PreToolUse の入力には tool_name と tool_input が入る
    command = input_data["tool_input"].get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],  # "PreToolUse"
                "permissionDecision": "deny",
                "permissionDecisionReason": "rm -rf は禁止されています",
            }
        }
    # 空のオブジェクトを返すと、そのまま実行を許す
    return {}

options = ClaudeAgentOptions(
    # matcher で対象のツールを絞る（"Write|Edit" のように複数も書ける）
    hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[block_dangerous_bash])]}
)

フックの関数の入力と出力:

複数の PreToolUse フックが違う判断を返したときの優先順位: deny > defer > ask > allow。1つでも拒否すれば拒否になります。

3. エージェントのパターンとフレームワーク（4.9%）

3.1 ツール利用ループ

エージェントの中身は、多くの場合「環境からのフィードバックを見ながら、ループの中でツールを使う LLM」です。

• 各ステップで、ツールの結果やコードの実行結果などの「実際の結果（ground truth）」を得て、進み具合を判断する
• 止まる条件: 仕事が終わったら止まる。管理のために最大反復回数などの停止条件を足すことも多い
• 区切り（チェックポイント）や行き詰まったときに、人の判断を求めて止まることができる

並列のツール実行（Agent SDK）: 1ターンで複数のツールが要求されたとき、読むだけのツール（Read、Glob、Grep、読み取り専用の MCP ツール）は同時に実行できます。状態を変えるツール（Edit、Write、Bash）は衝突を避けるため順番に実行します。

ツール設計も大事です。Anthropic はツールの説明を「新人に向けた良いドキュメント」のように書くことを勧めています。使用例、例外ケース、入力形式、ほかのツールとの境目を書きます。SWE-bench 用エージェントでは、相対パスで間違いが起きたため、ツールが常に絶対パスを要求するように変えたところ、間違いがなくなったそうです。

3.2 サブエージェント

Agent SDK でのサブエージェントの作り方は3つです。

サブエージェントは Agent ツール で起動されます。

名前についての注意（公式の Agent SDK サブエージェントのページより）:

• 今の名前は Agent。tool_use ブロックでは "Agent" と出る
• 古い名前は Task。Claude Code v2.1.63 より前は、tool_use ブロックでも "Task" と出ていた
• 今でも system:init のツール一覧では "Task" と表示される
• 公式ドキュメントは、どのバージョンでも動くよう、サブエージェントの検出で "Task" と "Agent" の両方を確かめるよう勧めている
• Architect Foundations の試験ガイドは古い名前（Task ツール）で書かれている。試験では両方の名前を同じものとして理解しておく

AgentDefinition のおもな項目:

サブエージェントが受け取るもの・受け取らないもの（フォーク以外）:

大事な結論: 親から子へ渡せるのは Agent ツールのプロンプトだけです。ファイルのパス、エラーメッセージ、決めたことなど、子に必要な情報はそのプロンプトに直接書きます。

その他:

• フォーク（fork）: 新しく始めるのではなく、それまでの会話をコピーしたサブエージェント
• サブエージェントの説明（description）は具体的に書く。Claude はそれを見て自動で呼ぶ。確実に呼ばせたいときはプロンプトで名前を出す
• サブエージェントは再開（resume）できる。完了時の結果に agentId が入る

3.3 メモリ

3.4 コンテキストウィンドウの管理

コンテキストウィンドウは、1つのセッションでモデルが使える情報の総量です。ターンが進んでもリセットされず、システムプロンプト、ツール定義、会話履歴、ツールの入出力がたまっていきます。

3.5 エージェントのフレームワーク

試験ガイドが例に挙げるフレームワーク:

フレームワークについての Anthropic の考え方:

• 利点: LLM の呼び出し、ツールの定義とパース、呼び出しの連結など、低レベルの作業を簡単にする
• 欠点: 抽象化の層が増えると、中のプロンプトと応答が見えにくくなり、デバッグが難しくなる。必要以上に複雑にしたくなる
• 推奨: まず LLM の API を直接使う（多くのパターンは数行で書ける）。フレームワークを使うなら、中のコードを理解しておく。中身についての思い込みはよくある失敗の原因

4. 試験に向けたまとめ

5. 用語集

出典

• Building effective agents（Anthropic Engineering）: ワークフローとエージェントの定義、5つのパターン、フレームワークの考え方、ツール設計
• How we built our multi-agent research system（Anthropic Engineering）: オーケストレーター・ワーカー、90.2%、約15倍のトークン、並列化
• Agent SDK overview（Claude Code Docs）: Agent SDK・CLI・Client SDK・Managed Agents の比較、機能一覧
• How the agent loop works（Claude Code Docs）: ループ、メッセージの種類、組み込みツール、権限モード、上限、圧縮、フック
• Subagents in the SDK（Claude Code Docs）: AgentDefinition、受け継ぐもの、Agent ツール、フォーク、再開
• Hosting the Agent SDK（Claude Code Docs）: サブプロセスのモデル、使い捨て・長時間のセッション
• Claude Managed Agents overview（Claude Platform Docs）: 4つの概念、使う場面、ベータヘッダー、ZDR / HIPAA BAA の対象外
• Tool use overview（Claude Platform Docs）: stop_reason: "tool_use"、クライアントツールとサーバーツール、tool_choice
• Subagents in the SDK: Detect subagent invocation（Claude Code Docs）: ツール名は今 "Agent"、v2.1.63 より前は "Task"、system:init では "Task"
• Intercept and control agent behavior with hooks（Claude Code Docs、Agent SDK）: フック関数の3つの引数、入力の共通項目、hookSpecificOutput、permissionDecision の値と優先順位
• Hooks reference（Claude Code Docs）: フックの JSON 出力の全項目
• Configure permissions（Claude Code Docs）: 6つの権限モードと manual の別名
• Effort（Claude Platform Docs）: 5つの effort レベル、モデルごとの初期値と対応
• Strands Agents（公式サイト） / Strands Agents の紹介（AWS ブログ）
• LangGraph overview（LangChain Docs）
• Pydantic AI（公式ドキュメント）

内容は上の出典を要約・言い換えたものです（ライセンスに配慮して書き直しています）。