Claude Agent SDK: 機能とその評価方法

Claude Agent SDK は、Claude が制限されたツールを使用したワークフローを実行できるアプリケーションを構築するための開発者画面です。 SDK はセッションの管理、ツールの呼び出し、作業の調整を行うことができますが、アプリケーションの権限、ソース管理、評価、または人間による承認の必要性がなくなるわけではありません。完全な運用システムではなく、エージェントランタイムコンポーネントとして扱います。

エージェントランタイムを所有せずにソースベースの作業を完了する必要があるチームに、Ottermind は管理されたワークスペースパスを提供します。これにより、ユーザーが結果をレビューしている間、ファイル、調査コンテキスト、意思決定、成果物を接続したままにできます。 SDK とマネージドワークスペースは、さまざまな運用上の問題を解決します。

研究と開示: このガイドは、2026 年 9 月 3 日にレビューされた Claude Agent SDK リポジトリ、Anthropic ツール使用説明書、および AWS AgentCore Claude Agent SDK ドキュメントに基づいています。API と制限は進化しています。実装前に現在のリリースを確認してください。

コア構成要素

ビルディングブロック	責任	アプリケーション制御
セッション	実行とその会話状態を維持します	有効期限、分離、および監査記録
モデル	コンテキストを解釈し、手順を提案する	モデルバージョン、予算、および出力契約
ツール	境界付き操作を実行する	スキーマ、タイムアウト、権限、および冪等性
サブエージェント	真に独立したロールを処理する	スコープ、予算、およびエスカレーションルール
権限モード	エージェントがアクセスまたは変更できる内容を制御します。	許可リストと人間による確認
結果	テキスト、構造化データ、または成果物を返します。	検証とレビュー担当者への引き渡し

まず、可逆的なタスクを1つ実行します。

承認済みのリポジトリファイルを変更概要に変換するなど、読み取り処理の多いワークフローをプロトタイプ化します。入力セット、プロンプト、モデルバージョン、ツール呼び出し、出力、レビュー担当者の修正、最終決定を記録します。トレースが理解可能で、障害発生時に復旧できることを確認した後でのみ、書き込みアクセスを追加します。

最小限のタスク契約

Prompt

目標：ソースコードに基づいた実装概要を作成する。
使用可能なソースコード：添付のリポジトリファイルのみ。
使用可能なツール：ファイル一覧表示とファイル読み取り。書き込みとネットワーク呼び出しは不可。
出力：調査結果、提案された変更、証拠、リスク、および未解決の疑問点。
停止条件：必要なソースコードが見つからない場合、または権限が不明確な場合。

セッションとサブエージェント

ワークフローが複数のステップにわたって継続性を必要とする場合は、セッションを使用してください。役割、ツール、または評価基準が明らかに異なる場合にのみ、サブエージェントを使用してください。エージェントが増えると、連携、遅延、障害発生経路が増加します。各役割に必要な最小限のコンテキストを渡し、ステータスと証拠を含む構造化された結果を返します。

実用的なアーキテクチャ

SDKをアプリケーション境界の背後に配置し、以下の5つの役割を担わせます。

リクエストハンドラー: ユーザーを認証し、許可されたプロジェクトを選択し、予算を設定します。
コンテキストローダー: 許可されたファイルのみを取得し、その識別子と日付を記録します。
エージェントランナー: セッションを開始し、ツールを提供し、各ツールのリクエストと結果を永続化します。
ポリシーレイヤー: 引数を検証し、許可されていないアクションをブロックし、確認を求めます。
結果アダプタ: 返されたシェイプを検証し、ドラフトをレビュー担当者または次のシステムに渡します。

この分離は重要です。SDK はモデルがツールを要求するのを支援できますが、その要求を許可するかどうかはアプリケーションが決定します。認証ロジックをプロンプトに記述したり、モデルがテナント境界を自動的に保持すると想定したりしないでください。

セッション、再開、および障害

すべての実行に、completed、needs_review、blocked、または failed のような明示的な識別子と終端状態を付与してください。モデルと SDK のバージョン、プロンプトのリビジョン、入力ソース、ツール呼び出し、およびレビュー担当者の決定を永続化してください。書き込み後にネットワークエラーが発生した場合は、冪等性キーを使用し、再試行する前に記録システムに問い合わせてください。人間による編集後にセッションが再開された場合、不透明な会話を再生するのではなく、編集された成果物と変更理由を含めるようにしてください。

ツール設計例

汎用シェルツールよりも、create_draft_task(title, owner, due_date)のような関数を優先してください。この限定的な関数は、日付形式、許可された所有者、プロジェクト範囲、ドラフト専用ステータスなどを強制できます。ファイル検索ツールは、ドライブ全体を無断で公開するのではなく、ファイル識別子と抜粋を返すようにしてください。ブラウザツールは、許可リストを使用し、認証または支払いの前に停止してください。

コストとレイテンシ

実行開始前に予算を設定します。最大モデル回転数、ツール呼び出し回数、トークン数、経過時間、サブエージェント数などです。品質が許す限り、抽出処理はより小さなモデルにルーティングし、複雑な推論は曖昧なステップに限定します。実際の使用状況を結果とともに記録することで、デモが成功したとしても非効率的なワークフローが隠蔽されるのを防ぎます。長時間かかるタスクは非同期で、キャンセル可能であり、ユーザーに可視化されるべきです。

SDKとマネージドワークスペースの比較

チームがアプリケーション固有のツール、デプロイメント制御、またはカスタムランタイムを必要とし、セキュリティ、可観測性、およびメンテナンスを自社で管理できる場合は、SDKを使用して構築します。主な要件が、ファイル、調査、意思決定、および成果物を人間のレビューのために接続することである場合は、マネージドワークスペースの方が適しています。どちらを選択するかは、どちらのラベルがより自律的に聞こえるかではなく、運用責任の問題です。

例：調査から概要作成までのエージェント

毎週の競合分析概要を必要とするチームを想像してみてください。リクエストハンドラはアナリストのIDを確認し、承認済みのプロジェクトを選択します。コンテキストローダーはソースリストを取得し、取得日を記録します。エージェントセッションはsearch_approved_sourcesとdraft_briefのみを呼び出すことができます。ポリシーレイヤーは、任意のURL、外部投稿、またはプロジェクト外のファイルへのリクエストを拒否します。結果アダプタは、レビュー担当者にドラフトを提示する前に、調査結果、引用、不確実性、および未解決の質問に関するセクションを必要とします。

有用な成果物は、最終的な文章だけではありません。それはトレースです。どのソースが利用可能だったか、どのツールが呼び出されたか、何がブロックされたか、レビュー担当者が何を変更したか、そして概要が承認されたかどうか。このトレースは、デバッグ、コスト分析、およびモデルやSDKが変更された際の再現可能な評価セットをサポートします。

バージョン管理とアップグレード

各環境でSDKとモデルのバージョンを固定してください。権限モード、ツールスキーマ、セッション動作、およびサポート対象モデルの変更点については、リリースノートを参照してください。アップグレード前に回帰テストを実行し、禁止ツールが引き続き禁止されていることを確認するテストを含めてください。ロールバックバージョンを用意し、移行計画なしに長時間実行中のワークフローの途中でアップグレードすることは避けてください。

本番環境準備チェックリスト

認証とテナントチェックは、コンテキスト取得の前に実行されます。
すべてのツールには、限定的なスキーマ、タイムアウト、および認証チェックがあります。
セッションには、予算、キャンセル、有効期限、および終了状態があります。
出力は、記録システムに到達する前に検証されます。
機密性の高い操作には、明示的な人間の承認が必要です。
ログには、機密情報を保存することなく障害を再現できる十分な来歴情報が含まれています。
評価ケースは、品質、安全性、コスト、およびレイテンシを対象としています。

権限とセキュリティの境界

アプリケーションコード内のツール引数を検証します。認証情報はプロンプト以外では使用せず、ファイルシステムとネットワークへのアクセス範囲を限定し、タイムアウトを設定し、送信、削除、購入、アクセス権限の変更には確認を必須としてください。関連するツール呼び出しはすべて、実行したIDと承認決定とともにログに記録してください。

デモではなく、ワークフローを評価してください。

通常、不完全、矛盾、攻撃的、および権限に敏感なケースを含むテストセットを作成してください。正しい完了、安全なエスカレーション、ツールエラー、レイテンシ、コスト、およびレビュー担当者による修正を測定してください。各評価実行ごとにモデルとSDKのバージョンを固定してください。

よくある質問

Claude Agent SDKはClaude APIツールの使用と同じですか？

いいえ。ツールの使用はモデルインタラクションパターンです。SDKはエージェントセッションとワークフローのためのアプリケーションレベルの構成要素をより多く提供しますが、ポリシー、ストレージ、権限、評価は引き続きアプリケーションが管理します。

複数のエージェントが必要ですか？

通常、最初は必要ありません。ツールが限定的で明確なチェックポイントを持つ単一のエージェントの方が、テストと運用が容易です。

SDKは安全にファイルを編集したり、コマンドを実行したりできますか？

そのようなツールに接続することは可能ですが、安全性はサンドボックス、許可リスト、検証、レビュー、ロールバックの設計によって確保されます。生成されたコマンドを事前に承認されたものとして扱わないでください。

より広範なシステム境界については、AI エージェントのアーキテクチャおよびAIエージェントのセキュリティを参照してください。