Building agents with the Claude Agent SDK

概要

この記事は、Anthropic が提供する Claude Agent SDK（エージェント開発キット） を使って、AI エージェントを構築する方法とベストプラクティスを解説しています。

1. エージェントループ：核心的なフレームワーク

3ステップのフィードバックループ

Claude Code のエージェントは、以下のループで動作します。

1. Gather Context（コンテキスト収集） - 必要な情報を集める
2. Take Action（アクション実行） - 実際に作業を行う
3. Verify Work（作業検証） - 結果をチェックする

この記事では、メールエージェントを例に、各ステップを解説しています。

2. ステップ1：コンテキスト収集（Gather Context）

エージェントには、プロンプトだけでなく、自分でコンテキストを取得・更新する能力が必要です。

2.1 エージェント検索とファイルシステム

ファイルシステムは、モデルのコンテキストに取り込める情報の「倉庫」のようなものです。

Claude は大きなファイル（ログやユーザーがアップロードしたファイルなど）に遭遇すると、以下のようなbashコマンドを使って効率的に情報を取得します。

メールエージェントの例：
過去の会話を「Conversations」フォルダに保存しておけば、必要な時にそこから検索できます。

📁 Conversations/
   ├── 2025-01-meeting.txt
   ├── 2025-02-project-update.txt
   └── 2025-03-feedback.txt

2.2 セマンティック検索（Semantic Search）

セマンティック検索の仕組み：

1. コンテキストを「チャンク」（小さな塊）に分割
2. 各チャンクをベクトル（数値の配列）に変換
3. クエリもベクトル化して、類似度で検索

推奨： セマンティック検索には限界があるため、まずはエージェンティック検索から始めましょう。セマンティック検索は通常、エージェンティック検索よりも高速ですが、精度が低く、メンテナンスが難しく、透明性も低くなります。より高速な結果やより多くのバリエーションが必要な場合にのみセマンティック検索を追加することをお勧めします。

2.3 サブエージェント（Subagents）

サブエージェントとは、メインのエージェントから呼び出される「子エージェント」です。

サブエージェントの2つの利点：

1. 並列化（Parallelization）

   • 複数のサブエージェントを同時に起動
   • 異なるタスクを並行して処理

2. コンテキスト管理

   • 各サブエージェントは独自のコンテキストウィンドウを持つ
   • 関連情報だけを親に返す（全コンテキストではなく）
   • 大量の情報から必要な部分だけを抽出するタスクに最適

メールエージェントの例：

メインエージェント
    │
    ├── 検索サブエージェント1（クエリA）
    ├── 検索サブエージェント2（クエリB）
    └── 検索サブエージェント3（クエリC）
         ↓
    関連する抜粋だけを返す（フルスレッドではなく）

2.4 コンパクション（Compaction）

エージェントが長時間動作すると、コンテキストがいっぱいになってしまいます。

コンパクション機能：

• コンテキスト制限に近づくと、自動的に以前のメッセージを要約
• エージェントがコンテキスト切れを起こさないようにする

3. ステップ2：アクション実行（Take Action）

コンテキストを収集したら、柔軟にアクションを取れるようにします。

3.1 ツール（Tools）

ツールはエージェントの主要な行動手段です。

重要なポイント：

• ツールは Claude のコンテキストウィンドウで目立つ位置にある
• Claude がタスクを完了する方法を決める際、最初に考慮される
• コンテキスト効率を最大化するために設計を工夫する

3.2 コード生成（Code Generation）

コードは以下の特性を持つため、エージェントの出力として理想的です。

Claude.ai のファイル作成機能の例：

Claude.ai では、Excel スプレッドシート、PowerPointプレゼンテーション、Word文書を作成する際、Claude が python スクリプトを書いて生成しています。

3.3 MCP（Model Context Protocol）

MCPは外部サービスとの標準化された連携方法を提供します。

MCP の利点：

• 認証や API 呼び出しを自動的に処理
• カスタム統合コードを書く必要がない
• OAuth（認証）フローの管理が不要

メールエージェントの例：

・Slack メッセージを検索してチームの状況を理解
・Asana タスクをチェックして、担当者を確認

MCPサーバーを使えば、これらの統合がすぐに動作します。

4. ステップ3：作業検証（Verify Work）

自分の出力をチェックして改善できるエージェントは、根本的に信頼性が高くなります。

4.1 ルールの定義

最良のフィードバック： 出力に対する明確なルールを定義し、どのルールが失敗したか、なぜ失敗したかを説明する。

コードリンティング（Linting）の例：

TypeScript > JavaScript

TypeScriptを使うと、JavaScriptよりも多くのフィードバック（型チェックなど）が得られます。

メールエージェントの例：

4.2 視覚的フィードバック（Visual Feedback）

UI 生成やテストなど、視覚的なタスクには、スクリーンショットやレンダリング結果が役立ちます。

チェック項目：

• レイアウト - 要素が正しく配置されているか
• スタイリング - 色、フォント、書式が意図通りか
• コンテンツ階層 - 情報が正しい順序で、適切に強調されているか
• レスポンシブ性 - 壊れていたり、詰まっていたりしないか

Playwright MCPサーバーを使うと、この視覚的フィードバックループを自動化できます。

4.3 LLM をジャッジとして使う

別の言語モデルに、エージェントの出力を「判定」させる方法です。

メールエージェントの例：
サブエージェントに下書きのトーンを判定させ、ユーザーの過去のメッセージと合っているか確認する。

5. エージェントのテストと改善

エージェントループを数回実行した後、エージェントをテストし、タスクに適切に対応できることを確認することをお勧めします。エージェントを改善する最良の方法は、その出力、特に失敗したケースを注意深く観察し、エージェントの立場に立って考えることです。

自問すべきチェックリスト