昨年11月、Claude で動く エージェントをクライアントに納入しました。受信サポートチケットを自動分類し、適切な部門にルーティングして、初期回答案を作成するものでした。構築に3週間かかりました。ステージング環境では完璧に見えました。本番初日、実在しない返金ポリシーを幻覚し、17件のチケットを誤ったキューにルーティングし、配送データへのアクセスがないのに「木曜日までに到着する」と顧客に自信満々で言い張りました。
というわけで、学んだことがあります。
この記事は、そのエージェントを正しく再構築して、その後も何件も本番運用した今、私が知っていることについてのものです。理論ではなく、実際に下した判断、手にした道具、二度と繰り返さない失敗です。エージェンシーオーナーやフリーランサーで Claude Agent SDK のデモ段階から先に進みたい方向けに書きました。
---
Claude Agent SDK は実は何か（そして何でないか）
まず第一に：SDK は魔法ではありません。Claude にツールへのアクセスを与え、複数ターンにわたって会話コンテキストを管理し、いわば意思決定ループをオーケストレーションするための体系的な方法です。Claude はタスクについて推論し、ツール呼び出しが必要かどうかを判断し、結果を取得して、再び推論し、別のツールを呼び出すか最終回答を出力するかのいずれかを行います。
そのループは単純に見えます。実は単純なのです。複雑さはすべて、その周りに置くもののなかに存在しています。
SDK は配管を提供します。水圧、配管の太さ、掘削を開始する前に本管を閉じたかどうかは、あなたの責任です。エージェンシーオーナーが SDK を後輩デベロッパーに渡して、スプリント内に完成品を期待して、技術的には動くが喜んでいるユースケース以外のすべての入力で崩壊するものが返ってくるのを見たことがあります。
実践ではループがこのように見えます
ツールを JSON スキーマとして定義します。Claude はそのスキーマを読み、いつ使うかを判断し、構造化された引数を渡し、あなたのコードが実際のロジックを実行します。Claude は直接コードを実行しません。それはあなたに任せます。あなたのシステムが仕事をします。その後 Claude は結果を取得して続行します。
その分離は多くの人が実感するより重要です。Claude は常にオーケストレーターであり、実行者ではないということです。そしてそのフレーミングは、あなたが下すあらゆるアーキテクチャ上の判断に影響を与えるべきです。
---
Claude が実際に使えるツール設計
ここでほとんどの構築が失敗します。過去1年で他のデベロッパーのエージェントコードベースを15件ほどレビューしましたが、最も一般的な問題はプロンプトエンジニアリングやモデル選択ではありません。設計が悪いツールなのです。
実践では「設計が悪い」とはこういう意味です：
- 渡すパラメータに応じて5つの無関係な処理を実行する
process_dataというツール - 内部コードコメントのように読める ツール説明（「認証ヘッダー付きで v2 エンドポイントを呼び出す」）
typeやmodeという名前のパラメータで、列挙型ではなく任意の文字列を受け入れるもの- 戻り値にエラー情報がないため、Claude は呼び出しが成功したかどうか判断できません
2023年初頭、Seahawkはコンテンツパイプラインプロジェクトに取り組んでいました。manage_contentツールを構築し、actionパラメータ（create、update、delete、publish、unpublish、archive）を受け取っていたのです。Claudeはスキーマだけからは区別が明確でなかったため、何度も誤ったアクションを選んでいました。そこで、それを6つの独立したツールに分割しました。その決定の精度が、内部評価で約60%から94%に跳ね上がりました。1つの変更です。
現在私が守るルール
- 1つのツール、1つの仕事。ツールの目的を「～と」なしで1文では説明できなければ、分割してください。
- 可能な限りenumを使用してください。Claudeに文字列を推測させないでください。
- 人間の開発者ではなく、Claudeのために説明を書いてください。Claudeはあなたのコードベースを知りません。あなたが伝えることしか知りません。
- 明示的な成功/失敗フィールドを持つ構造化データを常に返してください。Claudeに沈黙から推測させないでください。
- ツール名は動詞から始めてください。search_orders、create_draft、fetch_customer_recordのように。ordersやdraft、customerではなく。
Anthropicのツール使用ドキュメントはスキーマ構造についてさらに深く掘り下げており、ざっと読むのではなく、注意深く読む価値があります。
---
コンテキスト管理は隠れたコスト
誰も十分に話さないことがあります。トークンは無料ではなく、エージェントは貪欲です。
ループの各ターンには、完全な会話履歴、すべてのツールスキーマ、システムプロンプト、ツール結果が含まれます。10個のツールと詳細なシステムプロンプトを持つ中程度に複雑なエージェントは、ユーザーが1文字も入力する前に、各セッションを3,000～4,000トークンで開始する可能性があります。5～6個のツール呼び出しと結果を追加すると、解決されたタスクあたり15,000～20,000トークンを見ることになります。Claudeの現在のAPI価格では、ボリュームがあれば急速に積み上がります。
今は執拗にこれを追跡しています。配信するすべてのエージェントについて、QA中にコスト・パー・レゾリューション数を実行しています。クライアントと事前に合意したしきい値を超えている場合は、システムプロンプトを緊める、ツールスキーマを削除する、またはAnthropicが追加した、そして私が実際にすべてのプロジェクトで使用しているプロンプトキャッシュを使用して静的コンテキストをキャッシュできるかどうかを検討します。キャッシュ対象トークンは、キャッシュヒット時に標準入力レートの約10%です。1日に何千回も同じシステムプロンプトを再実行する忙しいエージェントでは、これは四捨五入のエラーではありません。
壊さないようにトリミング
すべてのエッジケースをカバーする豊かで詳細なシステムプロンプトを書く誘惑があります。それに抵抗してください。追加する行ごとに、すべてのターンでトークンが消費されます。一般的なケースのために書いてください。エッジケースはツール戻り値で、または適切な瞬間に挿入される短いコンテキスト内命令で処理してください。
エージェントが動作するようになったら、ツール説明も容赦なくカットしています。説明が「このツールは注文データベースを検索し、クエリと一致する注文のリストを返します。注文ID、顧客名、行アイテム、配送ステータス、タイムスタンプを含む」と言っている場合、「クエリ文字列で注文を検索してください。一致する注文レコードを返す」に短縮します。Claudeは十分スマートです。戻りスキーマがそれらのフィールドを適切に文書化していれば、ツール説明にフィールドリストは必要ありません。
---
マルチエージェントオーケストレーション：1つのエージェントでは不十分な場合
シングルエージェントシステムは、一定の複雑性の天井で破綻します。昨年春、賃貸物件管理会社のプロジェクトでその天井に達しました。エージェントはメンテナンスリクエストを処理し、契約業者と通信し、Notionデータベースを更新し、SendGrid経由でテンプレートメールを送信し、カスタム構築カレンダーAPIから可用性データを取得する必要がありました。7つのツール、その多くはサブワークフローを持っていました。
すべてをコーディネートしようとする1つのエージェントは信頼できなくなりました。コンテキストが乱雑になりました。Claudeは時々、ループの途中でどのサブタスクを実行しているかを見失っていました。
修正は後から見れば明らかでした：オーケストレーターとスペシャリストです。1つのトップレベルClaudeエージェントはインテント分類とルーティングを処理します。スペシャリストサブエージェントは特定のドメイン（通信、スケジューリング、データ更新）を処理し、構造化された結果を報告します。オーケストレーターは各スペシャリストが何をしたかの内部を見ません。出力だけを見ます。
このパターンはAnthropicのマルチエージェントガイダンスで説明されており、人間のチームをどのように設計するかに密接に対応しています。プロジェクトマネージャーが個人的にすべてのメールを書いたり、すべてのスプレッドシートを更新したりするわけではありません。委譲し、確認を待ち、先に進みます。
サブエージェント設計の実践的な注意事項
- 各サブエージェントに厳密で具体的なシステムプロンプトを与えてください。ドメイン間の命令は含めないでください。
- サブエージェントは、自身のドメインに必要以上のツールを持つべきではない。ツールの過剰積載はメインオーケストレーターと同じくらいサブエージェントにとって危険だ。
- コンテキストは明示的に渡す。サブエージェントが上流で何が起きたか「知っている」と仮定するな。必要な情報をそのまま渡し、余分なものは一切渡さない。
---
障害を適切に処理する（それらは必ず発生する）
本番環境のエージェントは失敗する。タイムアウトする。外部APIが500を返す。予想外のインプットをユーザーが送信する。Claudeが時々ツールスキーマを誤読し、不正な引数を渡す。
問題はエージェントが失敗するかどうかではなく、それが安全に失敗するかどうかだ。
今、私はすべてのエージェントに例外なく3つのことを組み込んでいる。
- すべての外部ツール呼び出しに対するバックオフ付き再試行ロジック。レート制限エラーだけじゃなく、すべての非200レスポンスに対応する。
- エージェントがタスクを解決せずにN回以上のツール呼び出しを行った場合のフォールバックパス。Nは変わるが、私は通常8を超えることはない。その時点で何かが間違っており、人間が介入する必要がある。
- システムプロンプトに明確な不確実性の処理。Claudeに告げる：確信を持って行動するのに十分な情報がない場合は、仮定に基づいて進むのではなく、明確化の質問をしろ。
その3番目のものが、最初に触れたチケット仕分けエージェントを救った。再構築されたバージョンは、ルーティングが不確実な場合に1つの明確化の質問をするようになった。ユーザーは気にしない。チケットが間違ったキューに入るよりは、質問に答えることを望む。
---
評価：これなしではシップできない
私は最初のサポートチケットエージェントのバージョンで適切な評価を行わなかった。本当のところ、それが間違いだった。他はすべてその症状だった。
評価は派手である必要はない。今、私がしているのは、構築を始める前に40～60個の代表的なインプットのセットを作ること。通常のケース、エッジケース、敵対的なインプットをカバーしている。重大な変更後、すべてに対してエージェントを実行する。3つの数字を追跡する：タスク完了率、ツール呼び出しの精度（正しいツールを正しい引数で呼んだか）、そして幻覚率（ツール結果に基づかない何かを主張したか）。
本番環境のエージェントについては、タスク完了率88%未満ではシップしない。また、顧客向けメッセージのような高リスク出力での幻覚についてはゼロトレランス（日付、価格、ポリシーなど特定の主張を含む）。
Stanfordの HELM ベンチマーキングフレームワークは、学術規模で実行していないとしても、評価設計の参考になる価値がある。彼らがテストしたカテゴリーは本番環境の要件にうまくマップする。
---
システムプロンプトは構造を支えている
この1年間で考えを変えた。システムプロンプトをセットアップテキストのように扱い、一度書いたら忘れるものだと思っていた。今、それをプロジェクトで最も重要なファイルとして扱っている。
適切に書かれたシステムプロンプトは4つのことを実行する：
- エージェントのアイデンティティとスコープを明確に定義する（何をするか、そして重要なことに、明示的に何をしないか）
- トーンと出力フォーマットの期待を設定する
- 最も一般的な失敗モードを積極的に処理する（「注文が見つからない場合は、推測するのではなく明示的にそう言え」）
- エスカレーション基準を確立する
スコープ定義は、ほとんどの開発者がスキップするもの。それがないと、Claudeは意図しない方法で親切になろうとする。プロパティマネジメントエージェントでは、最初のシステムプロンプトは金銭的助言を明示的に除外していなかった。テナントがそのエージェントに料金に異議を唱えるべきか聞いた。Claudeは親切に意見を述べた。それはクライアントが支払ったものではなく、エージェントが構築されたものでもない。
1文でそれを直した：「あなたは金銭紛争、法的事項、またはリース解釈に関するアドバイスを提供する権限がない。これらのトピックについては、ユーザーにオフィスに直接連絡するよう指示しろ。」
スコープ外の各ドメインについてその文を書いてください。Claude が境界を推論すると仮定しないでください。
---
FAQ
Claude Agent SDK は Claude API を直接使うのとどう違いますか？
API は単一のリクエスト・レスポンスを提供します。Agent SDK（および Anthropic がそれを中心に文書化しているエージェント パターン）は、Claude が複数の決定を下し、ツールを呼び出し、結果を受け取り、ターン全体で推論を続けることができる構造化されたループを提供します。これは個別のソフトウェア パッケージというより、パターンです。ツール定義、マルチターン コンテキスト管理、オーケストレーション ロジック。そのループを可能にするために API の周りにスカフォールディングを構築しています。
本番環境対応のエージェントをデプロイするのに現実的なタイムラインはどのくらいですか？
正直に言うと、非自明なものなら4～6週間です。そのうち2週間はツールの構築と配線。1週間はプロンプト エンジニアリングと反復。1～2週間は評価、エッジケース処理、QA です。本番エージェントを1週間で提供すると約束している人は、以前にデプロイした経験がないか、デモを製品として扱っているかのどちらかです。
マルチエージェント システムのすべてのサブエージェントに Claude を使うべきですか、それはモデルを混ぜるべきですか？
ニュアンスのある推論が必要な場合、または出力品質がエンドユーザーにとって重要な場合は Claude を使います。シンプルな分類タスクや高ボリューム低リスクのルーティングなら、より小さく安いモデルでも機能します。ただしモデルを混ぜると統合のオーバーヘッドが増し、デバッグがより難しくなります。すべてに Claude から始めて、本番データで軽いモデルが十分な箇所があるのを確認してから最適化してください。
エージェントが脚本から外れるのを防ぐにはどうすればよいですか？
3つのことが連携して機能します。明示的なスコープ外声明を含む厳密なシステム プロンプト、特定のアクションを物理的に防ぐツール設計（エージェントが使うべきでないツールを与えない）、カスタマー対応の出力に対する検証です。システム プロンプトだけに頼ることはできません。多層防御です。
エージェント メモリで開発者が犯す最大の間違いは何ですか？
コンテキスト ウィンドウを無限だと扱うことです。そうではありません。私が見た質の低いエージェントの失敗のほとんどは、無関係な履歴が肥大化したコンテキストから来ており、Claude はノイズを通して推論するしかなくなります。積極的に刈り込んでください。できるところは要約してください。エージェントが現在のタスクを完了するために本当に必要なものだけを持ち越してください。
---
正直な要約はこれです。SDK が難しい部分ではありません。難しい部分はソフトウェアにおける昔からのことと同じです。スコープについて明確に考え、失敗に備えて設計し、デプロイする前にテストすること。Claude は驚くほど有能な推論レイヤーですが、その周りにある設計の悪いシステムを補うことはできません。まず配管をちゃんとしてください。