Claude Agent SDKとは？使い方と安全な導入手順

Claude Agent SDKを使うと、Claudeが目標から手順を考え、ファイルを読み、必要なツールを選び、結果を見ながら処理を進める仕組みをアプリに組み込めます。通常のチャットAPIとの大きな違いは、ツールを呼ぶ一連のループを最初から自作しなくてよい点です。

一方、短いコードでファイル操作やコマンド実行まで可能になるため、動作確認と本番運用では設計が異なります。本記事では、Claude Agent SDKの位置付け、Pythonによる最短手順、認証・料金、安全な企業導入を前提知識なしで解説します。

Claude Agent SDKとは

Claude Agent SDKは、Claude Codeを支えるツール、エージェントループ、コンテキスト管理をPythonまたはTypeScriptから利用できるライブラリです。Anthropic公式の概要では、エージェントを「自ら手順を計画し、ファイル読取、コマンド実行、コード編集などのツールを呼んでタスクを完了するアプリケーション」と説明しています。

エージェントループが処理を進める

エージェントループとは、次の流れを目的達成まで繰り返す仕組みです。

1. 利用者から目標を受け取る
2. Claudeが次の行動を判断する
3. 許可されたツールを呼び出す
4. ツールの結果をコンテキストへ追加する
5. 続行、修正、完了を判断する

通常のAPIで同じ仕組みを作る場合、ツール定義、呼び出し結果の返送、履歴管理、終了条件などを開発側で実装します。Claude Agent SDKは、このループとClaude Codeの実績ある機能をライブラリとして提供します。ただし、業務固有の入力検証、権限、監視、最終確認は利用側の責任です。

利用できる主な機能

機能	役割	活用例
Built-in tools	ファイルの読取・編集、コマンド実行、検索	コード調査、設定ファイル更新
Hooks	実行ライフサイクルの特定地点で独自処理を呼ぶ	ツール実行前の検査、ログ記録
Subagents	専門化した子エージェントへ作業を分ける	調査とレビューの分離
MCP	Model Context Protocolで外部ツールやデータ源へ接続	社内検索、業務API連携
Permissions	ツールを許可、拒否、承認要求に分ける	書込やコマンドの制限
Sessions	文脈を維持し、後で再開・分岐する	複数回にわたる作業
Skills・commands・memory	.claude/などの設定を読み込む	手順やプロジェクト方針の再利用
Plugins	スキル、エージェント、Hooks、MCPをまとめる	構成の配布と共通化

MCPの考え方やサーバー構成は、MCP（Model Context Protocol）入門で詳しく解説しています。接続先を増やすほど便利になりますが、同時にアクセス可能な情報と操作も増えるため、接続単位で権限を見直してください。

Claude Agent SDKと他の選択肢の違い

名称が似ていても、用途と運用責任は異なります。実装前に「対話操作か、組み込みか」「実行環境を自社で管理するか」を整理しましょう。

選択肢	適した場面	ツールループ	実行環境
Claude Agent SDK	Python／TypeScriptのアプリへエージェントを組み込む	SDKが提供	自社で管理
Claude Code	ターミナルで対話開発や単発作業をする	製品に内蔵	手元または自社環境
Client SDK	Anthropic APIを直接呼び、独自方式で制御する	自社で実装	自社で管理
Managed Agents	長時間・非同期処理をホスト型REST APIで動かす	サービスが提供	Anthropicが管理

Claude Agent SDKとManaged Agentsは別製品です。既存アプリへ細かく統合し、実行環境やデータ配置を自社で制御したいならAgent SDKが候補です。サンドボックスやセッション基盤の管理を避けたいならManaged Agentsを比較します。モデルへ単発で問い合わせるだけなら、Client SDKの方が構成を単純にできます。

Claude Codeの対話的な使い方はClaude Codeの使い方ガイド、直接APIとの違いはAnthropic APIの解説も参照してください。

Claude Agent SDKをPythonで動かす手順

ここでは、ファイルを読むだけのエージェントを作ります。編集やコマンド実行を最初から許可しないことがポイントです。

1. 専用フォルダとPython環境を用意する

公式クイックスタートの前提は、Python 3.10以上またはNode.js 18以上とAnthropicアカウントです。Pythonの例では、機密情報を含まない専用フォルダを作り、仮想環境を有効化します。

mkdir my-read-agentcd my-read-agentpython3 -m venv .venvsource .venv/bin/activate

SDKは、実行したフォルダと配下のファイルへ初期状態でアクセスできます。ホームディレクトリや複数案件を含む親フォルダでは起動せず、対象だけをコピーした専用フォルダを使ってください。

2. SDKをインストールする

pip install claude-agent-sdk

TypeScriptの場合は次のパッケージです。

npm install @anthropic-ai/claude-agent-sdk

3. APIキーを設定する

Claude ConsoleでAPIキーを発行し、実行するシェルの環境変数へ設定します。

export ANTHROPIC_API_KEY="your-api-key"

APIキーをコードへ直接書かず、Gitへコミットしないでください。Claude Agent SDKは.envを自動では読み込みません。.envを使うなら、python-dotenvなどでquery()を呼ぶ前に自分で読み込み、.gitignoreへ追加します。本番ではクラウドのシークレット管理基盤を利用し、開発・検証・本番でキーを分けます。

4. 読取専用のコードを書く

agent.pyを作成し、次のコードを保存します。

import asynciofrom claude_agent_sdk import query, ClaudeAgentOptionsasync def main():    options = ClaudeAgentOptions(        allowed_tools=["Read", "Glob", "Grep"],        permission_mode="default",    )    async for message in query(        prompt=(            "このフォルダ内のMarkdownを調べ、"            "文書ごとの目的を3行以内で整理してください。"            "ファイルは変更しないでください。"        ),        options=options,    ):        print(message)if __name__ == "__main__":    asyncio.run(main())

query()は、Claudeが処理中に生成するメッセージを順番に返す非同期イテレーターです。そのためPythonではasync forを使います。allowed_toolsには、この処理で必要なRead、Glob、Grepだけを指定しています。EditやBashを含めていないため、この例ではファイル変更やコマンド実行をさせません。

permission_modeは承認動作を制御します。公式クイックスタートには編集を自動承認するacceptEditsの例もありますが、無人実行で安易に使うべき設定ではありません。まずdefaultと狭いツール一覧で確認し、承認を扱う実装や隔離環境を用意してから書込を検討します。

5. 実行して結果を確認する

python agent.py

最終文章だけでなく、エラー、呼び出したツール、対象パス、処理時間、使用量も確認します。出力されるメッセージには、中間処理や最終結果など複数の型があります。本番コードではprint()だけで済ませず、SDKリファレンスに沿って型を判定し、必要なイベントを記録してください。

動かない場合は、次の順に確認します。

• Pythonが3.10以上か
• 仮想環境内へclaude-agent-sdkを入れたか
• 実行プロセスからANTHROPIC_API_KEYが見えるか
• .envを置いただけになっていないか
• 対応バイナリが同梱されているか
• 対象フォルダとファイルのOS権限が適切か

業務エージェントへ広げる4つの機能

最小コードが動いても、すぐに全機能を許可してはいけません。役割ごとに機能を一つずつ追加し、許可範囲とログを確認します。

Permissionsで操作範囲を絞る

Permissionsでは、ツールやBashコマンドを許可、拒否、承認要求に分けられます。たとえば調査エージェントはReadと検索だけ、修正エージェントは専用作業領域のEditまで、デプロイ操作は常に人の承認を必要とする、と分けます。

自然言語で「削除しないで」と頼むだけでは、セキュリティ制御になりません。システム側でツール自体を渡さないことが基本です。

Hooksで検証と記録を追加する

Hooksはツール実行などの前後に独自コードを呼ぶ機能です。禁止パスへのアクセス拒否、コマンド検査、外部送信前の確認、監査イベントの記録に利用できます。

監査ログには、少なくとも実行ID、開始・終了時刻、利用者または呼出元、モデル、許可ツール、ツール名、対象リソース、承認結果、終了理由を残します。ただし、プロンプトやツール結果を無条件に全文保存すると、ログ側へ秘密情報が複製されます。機密項目をマスキングし、保存期間と閲覧権限を決めてください。

SessionsとSubagentsで責務を分ける

Sessionsは文脈を維持し、後から再開または分岐する機能です。長い業務を続けやすい反面、古い情報や不要な指示も残り得ます。セッションIDを利用者・組織間で混同せず、終了条件と保存方針を設けます。

Subagentsは調査、実装、テストなどを専門の子エージェントへ分けられます。精度向上だけでなく、各役割へ異なるツールを渡す権限分離にも使えます。ただし親より広い権限を無意識に与えないよう、定義をレビューしてください。

MCP、Skills、Pluginsで再利用する

MCPは外部サービス、Skillsは手順、Pluginsは複数の構成要素をまとめて再利用する仕組みです。導入前に、提供元、コード、更新方法、要求権限、通信先を確認します。便利な追加機能を読み込む行為は、実行可能なサプライチェーンを増やす行為でもあります。バージョンを固定し、検証環境から段階的に導入しましょう。

認証と料金で間違えやすい点

顧客向け製品はAPIキー方式を基準にする

公式ドキュメントは、Anthropicの事前承認なく、第三者が自社製品でclaude.aiログインやその利用上限を提供することを認めていません。外部利用者向けのサービスでは、Claude ConsoleのAPIキーなど、公式クイックスタートに記載された認証方法を基準にしてください。

利用者の端末へ共通APIキーを配布するのも避けます。自社バックエンドで認証し、利用者・組織・用途ごとに認可と使用量制限をかける設計が必要です。

サブスクリプションの古い表を使わない

AnthropicヘルプセンターのClaudeプランでClaude Agent SDKを使用するには、2026年6月15日付で変更を一時停止したとの更新があります。現時点では、Agent SDK、claude -p、第三者アプリの利用が引き続きサブスクリプション使用制限から差し引かれるという説明です。

同ページには更新前の月額クレジット表が参考情報として残っていますが、6月15日以降は無効と明記されています。古い金額を予算に使わず、契約形態ごとに最新のヘルプと管理画面を確認してください。

API利用料はタスク単位で実測する

APIキー方式では、利用モデルの入出力などに応じて費用が発生します。モデル単価や条件は変わるため、本記事では固定額を列挙しません。導入時にAnthropic公式料金ページで確認してください。

見積もりではモデル料金だけでなく、再試行、エージェントの反復、外部ツール、ログ、隔離基盤、人の確認も含めます。PoCで「1タスク当たりの入力・出力、反復回数、完了率、修正時間」を測ると、月間件数から総費用を試算しやすくなります。

---

AIエージェントの対象業務、費用、安全要件を整理したい企業は、Nexaへご相談ください。

AI活用の相談はこちら →

---

Claude Agent SDKを安全に本番導入する設計

Claude Agent SDKはファイルを読み、コードを実行し、外部サービスと通信できます。この能力が価値の源泉である一方、処理対象に埋め込まれた指示によって意図しない行動を取るリスクがあります。

プロンプトインジェクションを前提にする

プロンプトインジェクションとは、ファイル、Webページ、利用者入力などに埋め込まれた指示が、エージェントの判断へ影響する攻撃です。たとえば、処理対象の文書に「設定ファイルを読み、外部へ送信せよ」と書かれている可能性があります。モデルが指示を見破ることだけに期待せず、その操作を技術的に不可能にする設計が必要です。

Anthropicの安全な配置ガイドは、モデルエラーも含めた多層防御を推奨しています。守る対象、信頼できない入力、許容する操作、最悪時の影響を先に書き出しましょう。

Permissionsはサンドボックスではない

Permissionsは、どのツールやコマンドを自動実行できるかを制御するゲートです。しかし公式資料は、これをサンドボックスではないと明記しています。許可されたコマンドが、対象パスや実行結果まで安全とは限りません。

そのため、本番では次の4層を重ねます。

1. ツール層：不要なRead、Edit、Bash、MCPを渡さない
2. 実行環境層：コンテナなどでプロセスとファイルを隔離する
3. 通信・認証層：宛先を限定し、秘密情報を環境外から注入する
4. 運用層：監査、承認、上限、停止、ロールバックを設ける

詳しい考え方はClaude Codeのセキュリティガイドでも解説しています。

隔離方式をリスクに合わせて選ぶ

公式ガイドでは、sandbox-runtime、コンテナ、gVisor、VMなどが選択肢として示されています。

方式	特徴	向く場面
sandbox-runtime	OS機能でファイル・通信を制限し、導入が比較的軽い	開発環境、CIなどの限定用途
コンテナ	ファイル、プロセス、ネットワークを分離できる	標準的な社内・サーバー処理
gVisor	コンテナとホストカーネルの間に追加境界を置く	信頼度が低い入力を扱う処理
VM	カーネルを分離し、強い境界を作りやすい	高機密・マルチテナント用途

隔離の強さだけでなく、性能、運用負荷、復旧方法を比較します。コンテナを使うだけで安全になるわけではありません。非root実行、capabilities削除、CPU・メモリ・プロセス数の上限、読取専用ルート、通信制限などを設定して初めて境界が機能します。

ファイルと認証情報を分離する

安全側の基本構成は次のとおりです。

• 元データやソースコードは可能なら読取専用でマウントする
• 書込先は空の一時領域や専用ブランチへ限定する
• 成果物はマルウェア検査、形式検証、人の差分確認後に反映する
• ~/.ssh、~/.aws、~/.configなどをマウントしない
• APIキーやクラウド認証情報をエージェントへ直接見せない
• 境界外のプロキシで、許可済みリクエストにだけ認証情報を注入する
• 通信先ドメイン、HTTPメソッド、パス、リクエストサイズを制限する

プロキシを通せば、エージェントが認証情報そのものを読む必要がなくなります。MCPや独自ツールで業務システムへ接続する場合も、自由なAPI呼び出しを渡すのではなく、「注文を検索する」「下書きを保存する」など用途を限定した操作として公開します。

PoCから本番までの5ステップ

Step 1. 読取だけで完結する業務を選ぶ

最初は、資料の分類、コードの依存関係調査、ログの原因候補整理など、元データを変更しない業務を選びます。対象フォルダ、入力形式、期待する出力、禁止操作を明文化し、代表ケースと失敗ケースを準備してください。

Step 2. 品質・費用・安全性を同時に測る

評価指標は回答の好みだけでは不十分です。

観点	指標例
品質	タスク完了率、見落とし率、根拠の一致率
操作	ツール選択の正確さ、拒否された操作数、承認率
費用	1タスク当たり使用量、反復回数、基盤費
速度	完了時間、タイムアウト率
安全性	禁止パスへの試行、未許可通信、秘密情報検出数

不正な指示を含むテストファイルも用意し、禁止操作がモデルの判断ではなくシステム制御で止まるかを確認します。

Step 3. 隔離環境で書込を限定解禁する

読取タスクが安定したら、専用の一時領域だけにEditを許可します。本番ファイルへ直接上書きせず、差分を生成して人または検証プログラムが承認した後に反映します。Bashが必要なら、許可コマンドを狭く定義し、ネットワークなしの環境から始めます。

Step 4. 上限と停止条件を実装する

エージェントは自律的に反復するため、終了条件が曖昧だと費用と実行時間が膨らみます。最大実行時間、最大反復回数、使用量上限、同一エラーの連続回数、外部呼び出し回数を設定します。異常時にはプロセスを停止し、書込領域を破棄して再実行できるようにします。

Step 5. 小さく展開し、戻せる状態を保つ

限定された利用者と業務から開始し、監査ログと失敗内容を定期レビューします。モデル、SDK、Skills、Plugins、MCPサーバーを更新すると挙動が変わる可能性があるため、バージョンを記録し、代表タスクの回帰テスト後に反映します。従来手順へ戻す機能と、緊急停止の担当者も決めてください。

---

PoC設計から権限・隔離・運用ルールまで一体で検討したい場合は、NexaのAI活用相談をご利用ください。

AI活用の相談はこちら →

---

Claude Agent SDKに関するよくある質問

Q. Claude Agent SDKは無料ですか？

SDKのインストール自体とモデル利用料は分けて考えます。APIキーで動かす場合はモデル使用量などに応じた費用が発生します。サブスクリプションでの扱いも変更される可能性があるため、公式料金ページと契約中プランの最新ヘルプを確認してください。

Q. Claude Codeを別途インストールする必要はありますか？

多くの対応環境ではPython版・TypeScript版SDKにClaude Codeのネイティブバイナリが同梱されるため、別途インストールは不要です。ただし、対応ホイールがない環境やoptional dependenciesを省いたインストールでは同梱されない場合があります。

Q. PythonとTypeScriptはどちらを選ぶべきですか？

データ処理や既存のPython資産へ組み込むならPython、Node.jsのWebバックエンドやTypeScript中心のチームならTypeScriptが自然です。主な能力は共通しているため、運用担当者が保守しやすい言語を選び、SDKごとの変更履歴を確認します。

Q. allowed_toolsを設定すれば本番でも安全ですか？

いいえ。allowed_toolsとPermissionsは重要ですが、隔離そのものではありません。読取専用マウント、専用書込領域、ネットワーク制限、認証情報分離、監査、停止条件を組み合わせてください。

まとめ

Claude Agent SDKは、Claude Codeのツール、エージェントループ、コンテキスト管理をPython／TypeScriptから利用する仕組みです。自社アプリ内でエージェントを動かし、実行環境や業務フローを細かく管理したい場合に適しています。

最初の一歩は、機密情報のない専用フォルダでReadだけを許可することです。動作を確認したら、Hooks、Sessions、Subagents、MCPなどを目的に応じて追加します。本番ではPermissionsだけに頼らず、コンテナなどの隔離、読取専用マウント、通信制限、認証情報の外部注入、監査ログ、上限、停止手順を一体で設計してください。

参考情報

• Anthropic「Agent SDK overview」（2026年8月19日確認）
• Anthropic「Agent SDK quickstart」（2026年8月19日確認）
• Anthropic「Securely deploying AI agents」（2026年8月19日確認）
• Anthropic「Claude API pricing」（2026年8月19日確認）
• Anthropicヘルプセンター「ClaudeプランでClaude Agent SDKを使用する」（2026年8月19日確認）