
Claude Agent SDK を使用したエージェントの構築
以下の記事が面白かったので、簡単にまとめました。
1. はじめに
ここ数ヶ月、「Claude Code」はコーディングツールの枠をはるかに超える存在へと成長しました。Anthropicでは、深層学習、動画作成、メモ作成など、コーディング以外の様々な用途に活用しています。
つまり、「Claude Code」を支えるエージェントハーネス「Claude Code SDK」は、他の多くの種類のエージェントにも活用できるということです。この幅広いビジョンを反映するため、「Claude Code SDK」を「Claude Agent SDK」に名称変更します。
この記事では、「Claude Agent SDK」を開発した理由、それを使って独自のエージェントを構築する方法、そしてベストプラクティスを紹介します。
2. Claudeにコンピュータを与える
「Claude Code」の根底にある設計原則は、「Claudeにもプログラマーが日常的に使用するのと同じツールが必要」ということです。コードベースから適切なファイルを見つけ、ファイルの作成と編集を行い、コードをリントチェックし、実行し、デバッグと編集を行い、そして時にはこれらのアクションをコードが成功するまで繰り返し実行できる必要があります。
「Claude」にユーザーのコンピュータ (ターミナル経由) へのアクセスを与えることで、プログラマーのようにコードを書くために必要なものが得られることがわかりました。
しかし、これにより「Claude Code」の「Claude」は、コーディング以外のタスクでも効果的に機能するようになりました。bashコマンドの実行、ファイルの編集、ファイルの作成と検索などのツールを与えることで、「Claude」はCSVファイルの読み取り、Web検索、視覚化の構築、メトリクスの解釈、その他あらゆるデジタル作業を実行できます。つまり、コンピュータを備えた汎用エージェントを作成できるのです。
3. 新しいタイプのエージェントの作成
「Claude」にコンピュータを提供することで、これまで効果的ではなかったエージェントを開発できるようになりました。例えば、開発者は次のようなエージェントを開発できます。
・ファイナンスエージェント
ポートフォリオと目標を理解し、外部APIへのアクセス、データの保存、コード実行による計算によって投資評価を支援できるエージェントを構築します。
・パーソナルアシスタントエージェント
社内データソースに接続し、アプリケーション間のコンテキストを追跡することで、旅行の予約やカレンダー管理、アポイントメントのスケジュール設定、概要の作成などを支援するエージェントを構築します。
・カスタマーサポートエージェント
ユーザーデータの収集と確認、外部APIへの接続、ユーザーへのメッセージ返信、必要に応じて人間へのエスカレーションなどにより、カスタマーサービスチケットなどの曖昧性が高いユーザーリクエストを処理できるエージェントを構築します。
・ディープリサーチエージェント
ファイルシステムの検索、複数のソースからの情報の分析と統合、ファイル間のデータの相互参照、詳細なレポートの生成などにより、大規模なドキュメントコレクション全体にわたる包括的なリサーチを実行できるエージェントを構築します。
その他にも、自動化したいワークフローに合わせてエージェントを構築するための基本機能を提供します。
4. エージェントループの構築
「Claude Code」では、「Claude」は多くの場合、「コンテキストの収集 → アクションの実行 → 作業の検証 → この繰り返し」という、特定のフィードバックループで動作します。

これは、他のエージェントについて、そしてそれらにどのような機能を持たせるべきかを考える上で、非常に役立つ方法です。これを説明するために、「Claude Agent SDK」でメールエージェントを構築する例を見てみます。
5. コンテキストの収集
エージェントを開発する際には、単なるプロンプト以上のものを提供する必要があります。エージェントは独自のコンテキストを取得・更新できる必要があります。SDKの機能がどのように役立つか、以下に説明します。
5-1. エージェントによる検索とファイルシステム
「ファイルシステム」は、モデルのコンテキストに取り込むことができる情報を表します。
「Claude」は、ログやユーザーがアップロードしたファイルなどの大きなファイルに遭遇すると、grep や tail などのbashスクリプトを使用して、これらのファイルをコンテキストに読み込む方法を決定します。本質的には、エージェントのフォルダとファイル構造は、コンテキストエンジニアリングの一形態となります。
メールエージェントは、過去の会話を「会話」というフォルダに保存するとします。これにより、過去の会話について尋ねられた際に、過去の会話からコンテキストを検索できるようになります。

5-2. セマンティック検索
「セマンティック検索」は通常、エージェント検索よりも高速ですが、精度が低く、メンテナンスが難しく、透明性も低くなります。「セマンティック検索」では、関連するコンテキストを「チャンク化」し、これらのチャンクをベクトルとして埋め込み、それらのベクトルに対してクエリを実行することで概念を検索します。セマンティック検索には限界があるため、まずはエージェント検索から始め、より高速な結果やより多くのバリエーションが必要な場合にのみセマンティック検索を追加することをお勧めします。
5-3. サブエージェント
「Claude Agent SDK」はデフォルトで「サブエージェント」をサポートしています。サブエージェントが便利なのは主に2つの理由があります。1つ目は、並列処理を可能にすることです。複数のサブエージェントを起動して、異なるタスクを同時に処理できます。2つ目は、コンテキストの管理が容易なことです。サブエージェントはそれぞれ独立したコンテキストウィンドウを使用し、オーケストレーターにコンテキスト全体ではなく、関連する情報のみを返します。そのため、大量の情報を精査する必要があるタスク (そのほとんどは役に立たない) に最適です。
メールエージェントを設計する際には、「サブエージェント検索」機能を追加することも考えられます。メールエージェントは複数の検索サブエージェントを並列に起動し、それぞれがメール履歴に対して異なるクエリを実行し、メールスレッド全体ではなく、関連する抜粋のみを返すようにすることができます。
5-4. 圧縮
エージェントを長時間実行する場合、コンテキストの維持が重要になります。「Claude Agent SDK」の「圧縮」機能は、コンテキスト制限に近づくと以前のメッセージを自動的に要約するため、エージェントがコンテキストを使い果たすことはありません。これは、「Claude Code」のcompactスラッシュコマンドを基盤としています。
6. アクションの実行
コンテキストを収集したら、エージェントが柔軟に「アクション」を実行する必要があります。
6-1. ツール
「ツール」は、エージェントの実行における主要な構成要素です。「ツール」は「Claude」のコンテキストウィンドウに大きく表示されるため、「Claude」がタスクの完了方法を決定する際に最初に検討するアクションとなります。つまり、コンテキストの効率を最大限に高めるには、「ツール」の設計方法を意識する必要があります。その他のベストプラクティスについては、ブログ記事「エージェント向けの効果的なツールの作成 - エージェントと共に」を参照してください。
したがって、「ツール」はエージェントに実行してほしい主要なアクションである必要があります。「Claude Agent SDK」でカスタムツールを作成する方法を参照してください。
メールエージェントの場合、「fetchInbox」や「searchEmails」などのツールを、エージェントが最も頻繁に実行する主要なアクションとして定義できます。
6-2. Bashとスクリプト
「Bash」は、エージェントがコンピュータを使って柔軟な作業を行うための汎用ツールとして役立ちます。
メールエージェントでは、ユーザーの重要な情報が添付ファイルに保存されている場合があります。「Claude」は、以下に示すように、PDFをダウンロードしてテキストに変換し、呼び出してファイル全体を検索し、有用な情報を見つけるコードを作成できます。

6-3. コード生成
「Claude Agent SDK」はコード生成に優れています。それには理由があります。コードは正確で、構成可能であり、無限に再利用できるため、複雑な操作を信頼性高く実行する必要があるエージェントにとって理想的な出力となります。
エージェントを構築する際には、どのタスクをコードで表現することでメリットが得られるかを検討してください。多くの場合、その答えによって大きな機能が実現されます。
例えば、Claude.AI で最近リリースされたファイル作成機能は、完全にコード生成に依存しています。「Claude」はPythonスクリプトを使用してExcelスプレッドシート、PowerPointプレゼンテーション、Wordドキュメントを作成し、一貫性のある書式設定と、他の方法では実現が難しい複雑な機能を実現します。
メールエージェントでは、ユーザーが受信メールのルールを作成できるようにしたい場合があります。これを実現するには、イベント発生時に実行されるコードを記述します。

6-4. MCP
「MCP」(Model Context Protocol) は、外部サービスとの標準化された統合を提供し、認証とAPI呼び出しを自動的に処理します。つまり、カスタム統合コードを記述したり、OAuthフローを自分で管理したりすることなく、エージェントをSlack、GitHub、Googleドライブ、Asanaなどのツールに接続できます。
メールエージェントの場合、チームの状況を把握するためにSlackメッセージを検索したり、顧客リクエストに対応する担当者がすでに割り当てられているかどうかを確認するためにAsanaタスクを確認したりする必要があるかもしれません。MCPサーバを使用すれば、これらの統合はすぐに利用できます。エージェントはsearch_slack_messagesやget_asana_tasksなどのツールを呼び出すだけで、残りの処理は「MCP」が処理します。
MCPエコシステムは成長を続けているため、事前に構築された統合が利用可能になると、エージェントに新しい機能を迅速に追加でき、エージェントの行動に集中できます。
7. 作業の検証
「Claude Code SDK」は、エージェントループを動作評価によって完了させます。自身の出力をチェックし、改善できるエージェントは、根本的に信頼性が高くなります。つまり、間違いが重なる前にそれを検知し、逸脱した場合には自己修正し、反復するにつれて改善していくのです。
重要なのは、「Claude」に具体的な動作評価方法を提供することです。ここでは、効果的だとわかった3つのアプローチご紹介します。
7-1. ルールの定義
フィードバックの最良の方法は、出力に対して明確に定義されたルールを提供し、どのルールが失敗したのか、そしてその理由を説明することです。
コードの lint チェックは、ルールベースのフィードバックとして非常に効果的です。フィードバックは詳細であればあるほど効果的です。例えば、TypeScript を生成して lint チェックする方が、純粋な JavaScript を生成するよりも効果的です。これは、TypeScript を生成して lint チェックする方が、複数の追加レイヤーのフィードバックが得られるためです。
メールを生成する際に、メールアドレスが有効かどうか (有効でない場合はエラーをスロー)、ユーザーが以前にそのメールアドレスにメールを送信したことがあるかどうか (送信済みの場合は警告をスロー) を「Claude」に確認させたい場合があります。
7-2. 視覚的なフィードバック
UI生成やテストといった視覚的なタスクをエージェントで実行する場合、スクリーンショットやレンダリング画像といった視覚的なフィードバックが役立ちます。例えば、HTML形式のメールを送信する場合、生成されたメールのスクリーンショットをモデルに提供し、視覚的な検証と反復的な改善を行うことができます。モデルは、視覚的な出力が要求されたものと一致しているかどうかを確認します。
例えば
・レイアウト
要素は正しく配置されているか? 間隔は適切か?
・スタイル
色、フォント、書式設定は意図したとおりに表示されているか?
・コンテンツの階層
情報は適切な順序で、適切な強調表示で表示されているか?
・レスポンシブ性
画面が崩れたり、窮屈に見えたりしていないか?
(1枚のスクリーンショットではビューポートの情報が限られています)
Playwright のような MCP サーバを使用すると、この視覚的なフィードバックループを自動化できます。レンダリングされた HTML のスクリーンショットの取得、さまざまなビューポート サイズのキャプチャ、さらにはインタラクティブな要素のテストなど、すべてエージェントのワークフロー内で実行できます。

7-3. LLM as a judge
エージェントの出力を、別の言語モデルにファジールールに基づいて「ジャッジ」させることもできます。これは一般的に堅牢な方法ではなく、レイテンシのトレードオフが大きくなる可能性がありますが、性能の向上がコストに見合うアプリケーションでは役立ちます。
メールエージェントでは、下書きのトーンを判定する別のサブエージェントを配置し、ユーザーの過去のメッセージと適合するかどうかを確認します。
8. エージェントのテストと改善
エージェントループを数回実行した後、エージェントをテストし、タスクに十分対応できることを確認することをお勧めします。エージェントを改善する最善の方法は、その出力、特に失敗したケースを注意深く観察し、エージェントの立場に立って考えることです。つまり、エージェントは適切なツールを備えているでしょうか?
エージェントがジョブを実行するのに十分な能力を備えているかどうかを評価する際に、他に自問すべき質問をいくつかご紹介します。
・エージェントがタスクを誤解している場合、重要な情報が不足している可能性があります。必要な情報を見つけやすくするために、検索APIの構造を変更できますか?
・エージェントがタスクに繰り返し失敗する場合は、ツール呼び出しに正式なルールを追加して、失敗を特定して修正できますか?
・エージェントがエラーを修正できない場合、問題へのアプローチ方法を変えるための、より有用で創造的なツールを提供できますか?
・機能を追加するとエージェントのパフォーマンスが変化する場合は、顧客の使用状況に基づいてプログラムによる評価 (または評価) を行うための代表的なテスト セットを構築します。
9. はじめる
「Claude Agent SDK」は、Claude が「コンピュータ」にアクセスしてファイルの書き込み、コマンドの実行、そして処理の反復処理を実行できるようにすることで、自律型エージェントの構築を容易にします。
エージェントループ (コンテキストの収集、アクションの実行、作業の検証) を念頭に置くことで、デプロイと反復処理が容易な信頼性の高いエージェントを構築できます。
「Claude Agent SDK」は今すぐ使いはじめることができます。既にSDKを利用して開発を行っている開発者は、こちらのガイドに従って最新バージョンに移行することを推奨します。