Claude開発者ガイド
Claude Agent SDKとは｜アプリにエージェントを組み込む
APIでClaudeを呼ぶと、質問に対する答えが返ってきます。Agent SDKが返すのは「答え」ではなく「作業の結果」です。ファイルを読み、コマンドを実行し、目的が達成されるまで自分で進む──Claude Codeがやっていることの中身を、自分のプログラムの一部として使えるようにしたものと考えると位置づけが掴めます。
このサイトは Anthropic や Claude の公式サイトではありません。Claudeの基本的な使い方、ChatGPTとの違い、文章作成・長文整理・仕事での活用を初心者向けに整理する非公式ガイドです。機能・料金・提供状況は変更される可能性があるため、重要な判断ではAnthropic公式情報も確認してください。
ふつうのAPI呼び出しとの違い
| APIを直接呼ぶ | Agent SDK | |
|---|---|---|
| 返ってくるもの | 1回分の応答 | 目的が達成された結果 |
| 途中の処理 | 自分で組む | SDK側が回す |
| ツールの実行 | 呼び出しを受けて自分で実行し、結果を返す | 実行と往復をまとめて任せられる |
| 向いている用途 | 1問1答、分類、要約 | 複数手順が必要な作業 |
差が出るのは3行目です。APIを直接使う場合、「AIがツールを使いたいと言う→自分で実行する→結果を返す→また考えさせる」というループを自分で書く必要があります。この往復の管理がエージェント開発でいちばん面倒な部分で、そこを引き受けるのがSDKです。
関連する3つの選択肢
「AIに作業させる仕組みを作る」には複数の道があり、名前が似ていて混乱しやすいので整理します。
| 選択肢 | 性格 | 向いている場面 |
|---|---|---|
| Agent SDK | エージェントの中身を自分のアプリに組み込む | 自社ツールに機能として埋め込みたい |
| Managed Agents | サーバー側で動くエージェント。実行環境も用意される | 実行環境を自分で用意したくない |
| ツール実行のループ | 自作ツールを渡して往復を回してもらう仕組み | 既存のAPI利用を少し発展させたい |
| Claude Codeのヘッドレス実行 | コマンドとして呼ぶ（-p） | まずはこれで足りることが多い |
最後の行が実務的な助言です。SDKを使う前に、Claude Codeをコマンドとして呼ぶ形で足りないか検討してください。シェルスクリプトから claude -p "指示" を叩くだけで済む要件は多く、その場合SDKは過剰です（ヘッドレス実行の解説）。
向いている用途
- 社内ツールに「直す」機能を足す──エラーを検知したら、原因を調べて修正案まで出すところまで自動化する
- 問い合わせに応じて調査を走らせる──内容を読んで、必要な情報を集めて、まとめて返す
- 定型の運用作業を担当させる──設定変更、レポート生成、データ整形など
- 複数の作業を並行させる──役割ごとにエージェントを分けて、それぞれに任せる
共通しているのは「1回のやり取りでは終わらない」という点です。1問1答で済むならAPIを直接呼ぶ方が単純で、速く、安く済みます。
設計で必ず決めること
エージェントは「自分で判断して進む」ので、放っておくと想定外の動きをします。組む前に決めておくべき点を挙げます。
- 止める条件──実行時間、試行回数、費用の上限。これを設けないと、失敗を延々リトライして費用だけ積み上がります。無人実行で最も多い事故です
- 触れる範囲──どのディレクトリ、どのAPI、どのデータまで。範囲は物理的に囲ってください（専用フォルダ、コンテナ、読み取り専用の接続）
- 人が確認する地点──取り消せない操作（送信、削除、公開、決済）は自動で通さない設計にします
- ログ──何を判断してどう動いたかを残します。無人実行では、これが無いと失敗の原因が永久に分かりません
費用の考え方
SDK経由の利用はAPIの従量課金です。定額プランの枠ではありません。
費用は「処理した量 × モデルの単価」で決まり、エージェントは1つの依頼で内部的に何度もやり取りするため、単純なAPI呼び出しより消費が大きくなります。見積もる時は「1回の依頼」ではなく「1回の依頼で何往復するか」で考えてください。
抑えるコツは、作業に見合ったモデルを選ぶこと（モデル選択）、渡す情報を絞ること、そして繰り返す前提部分でキャッシュが効くよう組み立てることです。詳しくは従量課金のページにまとめました。
始める順番
- まずClaude Codeで手動でやってみる──自動化したい作業を、対話で1回通します。ここで手順と落とし穴が見えます
- ヘッドレス実行で試す──
claude -pで1回実行できる形にします。ここで足りるならSDKは不要です - 足りない部分を特定してからSDKへ──「自作アプリに埋め込みたい」「細かく制御したい」という具体的な理由ができてから移ります
いきなりSDKから入ると、実際にやりたい作業の輪郭が曖昧なまま実装することになります。手で1回通してから自動化するのは、AI以前から変わらない鉄則です。
AIガイド群
FAQ
プログラミングの知識は必要ですか？
必要です。ただしSDKを使ったツールを作る作業自体をClaude Codeに手伝わせられるので、実際の障壁は思うより低い場面もあります。
どの言語で使えますか？
TypeScript版とPython版が提供されています。最新の対応状況は公式ドキュメントをご確認ください。
定額プランの枠で使えますか？
使えません。API従量課金になります。定額プランは人が対話して使う形が前提です（プランの整理）。
Claude Codeとどちらを使うべきですか？
まずClaude Codeで足りないか確認してください。コマンドとして呼ぶ形で済む要件は多く、その場合SDKは過剰です。「自作アプリに組み込む」という要件が出てから検討するのが順番です。