Claude Agent SDK は、Claude 上でエージェントを構築するための Anthropic のツールキットであり、TypeScript と Python の両方で提供されている。以前は Claude Code SDK という名前だった。Anthropic は Claude Agent SDK でエージェントを構築する において、Claude Code を動かしている エージェントハーネスは他の多くの種類のエージェントも動かせるという理由で、これを改名した。同記事が示す SDK の 主要な設計原則は、エージェントにコンピュータ ― bash コマンドと、ファイルを作成・編集・検索する能力 ― を与え、 人間と同じように作業できるようにすることであり、この SDK で構築できるものとして、金融エージェント、 パーソナルアシスタントエージェント、カスタマーサポートエージェント、ディープリサーチエージェントを挙げている。
パーミッションのドキュメントは、SDK のもう一方の側面、すなわちエージェントがツールを使って何をしてよいかを
決める制御を扱っている。ドキュメントの位置づけでは、パーミッションモードとルールが自動的に許可されるものを定め、
canUseTool という名前のランタイムコールバックがそれ以外のすべてをその場で処理する。
ルールは SDK のオプションまたはプロジェクトの設定ファイルで宣言され、ドキュメントは、各種類のルールが効力を持つ 順序と、何がそれを上書きでき何が上書きできないかを規定している。
機能
改名を告げた記事は、SDK の機能を、エージェントがしばしばその中で動作するというフィードバックループ ―
コンテキストを収集し、行動し、作業を検証し、繰り返す ― を軸に整理している。コンテキストの収集については、
ファイルシステムに対する エージェント型検索、サブエージェント（デフォルトでサポートされており、
タスクの並列実行や、コンテキストの分離に役立つ。各サブエージェントは関連する情報だけをオーケストレーターに
返すためである）、そしてコンテキストの上限に近づくと以前のメッセージを自動的に要約する compact 機能
（Claude Code の /compact コマンドを基盤とする。コンパクション を参照）を挙げている。行動については、
カスタムツール、bash とスクリプト、コード生成、そして外部サービスとの連携のための
Model Context Protocol サーバーを列挙している。検証については、リンティングのようなルールベースの
フィードバック、スクリーンショットやレンダリング結果による視覚的フィードバック、そして
LLM-as-a-Judge を説明しており、後者については一般にあまり堅牢ではないとしている。これらは
ベンダー自身による自社製品の説明であり、自社チームでの導入から得たベストプラクティスとして示されている。
すべてのツール要求は、固定された順序の 6 つの段階を通過する。最初にフックが実行され、呼び出しを即座に
拒否するか、次に渡すことができる。フックが許可を返しても、その後に続く拒否ルールと確認ルールはスキップされない。
次に拒否ルールが確認され、最も寛容なモードであってもツールをブロックする。Bash のような名前だけの拒否は、
評価が始まる前にそのツールをモデルのコンテキストから完全に取り除くため、この段階で確認されるのは Bash(rm *)
のようなスコープ付きのルールだけである。確認ルールは、やはり最も寛容なモードであっても、呼び出しを確認の
ためにコールバックへ送る。その後にパーミッションモードが適用され、続いて許可ルールが適用される。
この段階では、読み取り専用のシェルコマンドや作業ディレクトリ内でのファイル読み取りのように、ツールが自ら承認する
呼び出しも、ルールなしで解決される。それでも解決されないものが canUseTool コールバックに到達する。
ドキュメント化されているモードは 6 つある。モードに基づく承認を何も追加しない default、本来なら確認を求める
ものをすべて拒否し、コールバックを一切呼び出さない dontAsk、ファイル編集とファイルシステム操作を自動承認する
acceptEdits、ドキュメント化された例外を除いてチェックをスキップする bypassPermissions、計画中に書き込みが
自動承認されないようにファイル編集をコールバックへ回す plan、そしてモデルの分類器が確認を承認または拒否する
auto である。
ドキュメントは、誤解しやすい 2 つの性質について率直に述べている。自動承認されたツールはコールバックに決して
到達しないため、コールバックにだけ置かれたパーミッションチェックは、それらのツールについては黙ってバイパスされる。
すべての呼び出しで実行されなければならないチェックについては、代わりに PreToolUse フックを使うよう読者に
指示している。フックは他のすべての段階より前に実行され、フックによる拒否は bypassPermissions でも適用される
からである。また、allowed_tools は bypassPermissions を制約しない。このモードと併せて Read だけを列挙しても、
すべてのツールが承認される。列挙されていないツールはどの許可ルールにも一致せず、モードへとフォールスルーする
ためである。ドキュメントはさらに、どのモードでも自動承認されない一連の操作に言及しており、それとは別に、
ユーザーとの対話を必要とするツールは bypassPermissions であっても常にコールバックへフォールスルーし、
dontAsk では拒否されると記している。
ルールにはスコープを付けることができる。Edit(path) ルールはすべての組み込みのファイル書き込みツールを対象とし、
パスのアンカーは明示的である ― 先頭のスラッシュが 2 つならファイルシステムの絶対パスを表し、1 つならルールの
定義元を起点とする。ツール名のグロブは拒否ルールでは受け付けられるが、許可ルールではグロブを含まないリテラルの
MCP サーバー接頭辞の後に限って受け付けられ、アンカーのない項目は無視されて起動時に警告が出される。
サブエージェントは親セッションのモードを継承するが、親が default、dontAsk、plan のいずれかである場合は、
サブエージェントは自身の定義にある permissionMode を使うことができる。ドキュメントはまた、親セッション自体が
bypassPermissions で動作していない限り、bypassPermissions がサブエージェントに適用されることは決してないと
述べている。
採用とエコシステム
パーミッションモードは、クエリの作成時に一度だけ設定することも、セッションの途中で変更することもでき、 ドキュメントはこれを、制限的な状態から始めて信頼が築かれるにつれて緩めていく方法として紹介している。ルールは プロジェクトの設定ファイルで宣言することもでき、プロジェクトの設定ソースが有効になっているときに読み込まれる。 ドキュメントは、いくつかの挙動について Claude Code の特定の最低バージョンが必要であると 記しており、Claude Code は SDK のパーミッションの挙動が記述される際の前提となるランタイムである。根底にある安全性の 姿勢については、拒否優先のパーミッション評価 と パーミッションモード を参照。
Anthropic の別の情報源は、この SDK を反対側から ― 何を制限するかではなく、何ができ、その能力がどこで尽きるかという 観点から ― 説明している。長時間稼働エージェントのための効果的なハーネス は、この SDK を、コーディングに 長けているだけでなく、モデルがツールを使ってコンテキストを収集し、計画し、実行する必要のある他のタスクにも長けた、 強力な汎用エージェントハーネスとして特徴づけており、コンパクション を含むコンテキスト管理の機能によって、 原理的にはエージェントが任意に長い時間有用に作業できるとしている。そのうえで同記事は、実際にはそれだけでは 不十分であると報告している。SDK 上で複数のコンテキストウィンドウにまたがってループ実行されたフロンティアモデルは、 高レベルのプロンプトから本番品質の Web アプリを構築するには依然として至らなかった。記事は 2 つの失敗パターン ― エージェントがアプリを一発で作ろうとして途中でコンテキストを使い果たすことと、後のセッションが進捗を見て作業完了を 宣言してしまうこと ― を説明し、前者はコンパクションを使っても起こると指摘している。コンパクションは、次のエージェントに 常に完全に明確な指示を渡すわけではないからである。したがって、この記事が SDK の上に付け加えているのは SDK の機能では なく、プロンプトとアーティファクトの規律 ― 異なるプロンプトを与えた最初のセッションと、永続的な進捗ファイル、git 履歴、 機能リスト（イニシャライザーエージェント を参照）― である。付随するコード例はクイックスタートとして公開されている。