Claude Code SDK
Claude Code SDKでカスタムAIエージェントを構築する
なぜClaude Code SDKを使用するのか?
Claude Code SDKは、本番環境対応のエージェントを構築するために必要なすべての構成要素を提供します:
- 最適化されたClaude統合: 自動プロンプトキャッシュと パフォーマンス最適化
- 豊富なツールエコシステム: ファイル操作、コード実行、ウェブ検索、 MCPの拡張性
- 高度な権限管理: エージェント機能の細かい制御
- 本番環境の必需品: 組み込みエラーハンドリング、セッション管理、 監視
SDKで何を構築できるか?
作成できるエージェントタイプの例をいくつか紹介します:
コーディングエージェント:
- 本番環境の問題を診断・修正するSREエージェント
- 脆弱性についてコードを監査するセキュリティレビューボット
- インシデントをトリアージするオンコールエンジニアリングアシスタント
- スタイルとベストプラクティスを強制するコードレビューエージェント
ビジネスエージェント:
- 契約とコンプライアンスをレビューする法務アシスタント
- レポートと予測を分析する財務アドバイザー
- 技術的問題を解決するカスタマーサポートエージェント
- マーケティングチーム向けのコンテンツ作成アシスタント
SDKは現在TypeScriptとPythonで利用可能で、迅速なプロトタイピング用のコマンドラインインターフェース(CLI)も提供しています。
クイックスタート
5分以内で最初のエージェントを実行しましょう:
SDKをインストール
NPMから@anthropic-ai/claude-code
をインストール:
NPMから@anthropic-ai/claude-code
をインストール:
NPMから@anthropic-ai/claude-code
をインストール:
PyPIからclaude-code-sdk
とNPMから@anthropic-ai/claude-code
をインストール:
(オプション)インタラクティブ開発用にIPythonをインストール:
APIキーを設定
Anthropic ConsoleからAPIキーを取得し、ANTHROPIC_API_KEY
環境変数を設定:
最初のエージェントを作成
以下のサンプルエージェントのいずれかを作成:
エージェントを実行
上記のコマンドをターミナルに直接コピー&ペーストしてください。
上記のコマンドをターミナルに直接コピー&ペーストしてください。
- プロジェクトをセットアップ:
-
package.jsonに
"type": "module"
を追加 -
上記のコードを
legal-agent.ts
として保存し、実行:
上記の各例は、以下を行う動作するエージェントを作成します:
- Claudeの推論能力を使用してプロンプトを分析
- 問題を解決するための多段階アプローチを計画
- ファイル操作、bashコマンド、ウェブ検索などのツールを使用してアクションを実行
- 分析に基づいて実行可能な推奨事項を提供
基本的な使用方法
概要
Claude Code SDKを使用すると、アプリケーションから非インタラクティブモードでClaude Codeとインターフェースできます。
前提条件
- Node.js 18+
- NPMから
@anthropic-ai/claude-code
基本的な使用方法
Claude Codeの主要なコマンドラインインターフェースはclaude
コマンドです。--print
(または-p
)フラグを使用して非インタラクティブモードで実行し、最終結果を印刷します:
設定
SDKはClaude Codeで利用可能なすべてのCLIオプションを活用します。SDK使用のための主要なオプションは以下の通りです:
フラグ | 説明 | 例 |
---|---|---|
--print , -p | 非インタラクティブモードで実行 | claude -p "query" |
--output-format | 出力形式を指定(text , json , stream-json ) | claude -p --output-format json |
--resume , -r | セッションIDで会話を再開 | claude --resume abc123 |
--continue , -c | 最新の会話を継続 | claude --continue |
--verbose | 詳細ログを有効化 | claude --verbose |
--append-system-prompt | システムプロンプトに追加(--print でのみ) | claude --append-system-prompt "カスタム指示" |
--allowedTools | 許可されたツールのスペース区切りリスト、または カンマ区切りツールリストの文字列 | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | 拒否されたツールのスペース区切りリスト、または カンマ区切りツールリストの文字列 | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | JSONファイルからMCPサーバーを読み込み | claude --mcp-config servers.json |
--permission-prompt-tool | 権限プロンプトを処理するMCPツール(--print でのみ) | claude --permission-prompt-tool mcp__auth__prompt |
CLIオプションと機能の完全なリストについては、CLIリファレンスドキュメントを参照してください。
前提条件
- Node.js 18+
- NPMから
@anthropic-ai/claude-code
基本的な使用方法
Claude Codeの主要なコマンドラインインターフェースはclaude
コマンドです。--print
(または-p
)フラグを使用して非インタラクティブモードで実行し、最終結果を印刷します:
設定
SDKはClaude Codeで利用可能なすべてのCLIオプションを活用します。SDK使用のための主要なオプションは以下の通りです:
フラグ | 説明 | 例 |
---|---|---|
--print , -p | 非インタラクティブモードで実行 | claude -p "query" |
--output-format | 出力形式を指定(text , json , stream-json ) | claude -p --output-format json |
--resume , -r | セッションIDで会話を再開 | claude --resume abc123 |
--continue , -c | 最新の会話を継続 | claude --continue |
--verbose | 詳細ログを有効化 | claude --verbose |
--append-system-prompt | システムプロンプトに追加(--print でのみ) | claude --append-system-prompt "カスタム指示" |
--allowedTools | 許可されたツールのスペース区切りリスト、または カンマ区切りツールリストの文字列 | claude --allowedTools mcp__slack mcp__filesystem claude --allowedTools "Bash(npm install),mcp__filesystem" |
--disallowedTools | 拒否されたツールのスペース区切りリスト、または カンマ区切りツールリストの文字列 | claude --disallowedTools mcp__splunk mcp__github claude --disallowedTools "Bash(git commit),mcp__github" |
--mcp-config | JSONファイルからMCPサーバーを読み込み | claude --mcp-config servers.json |
--permission-prompt-tool | 権限プロンプトを処理するMCPツール(--print でのみ) | claude --permission-prompt-tool mcp__auth__prompt |
CLIオプションと機能の完全なリストについては、CLIリファレンスドキュメントを参照してください。
前提条件
- Node.js 18+
- NPMから
@anthropic-ai/claude-code
TypeScript SDKのソースコードを表示するには、NPMの@anthropic-ai/claude-code
ページをご覧ください。
基本的な使用方法
TypeScript SDKの主要なインターフェースはquery
関数で、メッセージが到着するとストリーミングする非同期イテレータを返します:
設定
TypeScript SDKはコマンドラインでサポートされているすべての引数と、以下の追加オプションを受け入れます:
引数 | 説明 | デフォルト |
---|---|---|
abortController | アボートコントローラー | new AbortController() |
cwd | 現在の作業ディレクトリ | process.cwd() |
executable | 使用するJavaScriptランタイム | Node.jsで実行時はnode 、Bunで実行時はbun |
executableArgs | 実行可能ファイルに渡す引数 | [] |
pathToClaudeCodeExecutable | Claude Code実行可能ファイルのパス | @anthropic-ai/claude-code に同梱の実行可能ファイル |
permissionMode | セッションの権限モード | "default" (オプション: "default" , "acceptEdits" , "plan" , "bypassPermissions" ) |
前提条件
- Python 3.10+
- PyPIから
claude-code-sdk
- Node.js 18+
- NPMから
@anthropic-ai/claude-code
Python SDKのソースコードを表示するには、claude-code-sdk
リポジトリを参照してください。
インタラクティブ開発にはIPythonを使用してください:pip install ipython
基本的な使用方法
Python SDKは2つの主要なインターフェースを提供します:
ClaudeSDKClient
クラス(推奨)
ストリーミングレスポンス、マルチターン会話、インタラクティブアプリケーションに最適:
SDKは構造化メッセージと画像入力の渡しもサポートしています:
このページのPythonの例ではasyncio
を使用していますが、anyio
も使用できます。
query
関数
シンプルなワンショットクエリ用:
設定
Python SDKはClaudeCodeOptions
クラスを通じてコマンドラインでサポートされているすべての引数を受け入れます。
認証
Anthropic APIキー
基本認証の場合、Anthropic ConsoleからAnthropic APIキーを取得し、クイックスタートで示されているようにANTHROPIC_API_KEY
環境変数を設定します。
サードパーティAPIクレデンシャル
SDKはサードパーティAPIプロバイダー経由の認証もサポートしています:
- Amazon Bedrock:
CLAUDE_CODE_USE_BEDROCK=1
環境変数を設定し、AWSクレデンシャルを設定 - Google Vertex AI:
CLAUDE_CODE_USE_VERTEX=1
環境変数を設定し、Google Cloudクレデンシャルを設定
サードパーティプロバイダーの詳細な設定手順については、Amazon BedrockとGoogle Vertex AIのドキュメントを参照してください。
マルチターン会話
マルチターン会話の場合、会話を再開したり、最新のセッションから継続したりできます:
プランモードの使用
プランモードを使用すると、Claudeは変更を加えることなくコードを分析でき、コードレビューや変更の計画に便利です。
プランモードは編集、ファイル作成、コマンド実行を制限します。詳細については権限モードを参照してください。
カスタムシステムプロンプト
システムプロンプトはエージェントの役割、専門知識、行動を定義します。ここで構築するエージェントの種類を指定します:
高度な使用方法
MCP経由のカスタムツール
Model Context Protocol(MCP)を使用すると、エージェントにカスタムツールと機能を提供できます。これは、ドメイン固有の統合が必要な専門エージェントを構築するために重要です。
エージェントツール設定の例:
使用例:
MCPツールを使用する場合、--allowedTools
フラグを使用して明示的に許可する必要があります。MCPツール名はmcp__<serverName>__<toolName>
のパターンに従います:
serverName
はMCP設定ファイルのキーtoolName
はそのサーバーが提供する特定のツール
このセキュリティ対策により、MCPツールは明示的に許可された場合にのみ使用されます。
サーバー名のみを指定した場合(つまり、mcp__<serverName>
)、そのサーバーのすべてのツールが許可されます。
グロブパターン(例:mcp__go*
)はサポートされていません。
カスタム権限プロンプトツール
オプションで、--permission-prompt-tool
を使用して、ユーザーが特定のツールを呼び出すモデルに権限を付与するかどうかをチェックするために使用するMCPツールを渡すことができます。モデルがツールを呼び出すと、以下が発生します:
- まず権限設定をチェック:すべてのsettings.jsonファイル、およびSDKに渡された
--allowedTools
と--disallowedTools
;これらのいずれかがツール呼び出しを許可または拒否する場合、ツール呼び出しを続行 - そうでなければ、
--permission-prompt-tool
で提供したMCPツールを呼び出し
--permission-prompt-tool
MCPツールはツール名と入力を渡され、結果を含むJSON文字列化されたペイロードを返す必要があります。ペイロードは以下のいずれかである必要があります:
実装例:
使用上の注意:
- 権限プロンプトがその入力を変更したことをモデルに伝えるために
updatedInput
を使用します;そうでなければ、上記の例のようにupdatedInput
を元の入力に設定します。例えば、ツールがファイル編集の差分をユーザーに表示し、ユーザーが差分を手動で編集できるようにする場合、権限プロンプトツールはその更新された編集を返すべきです。 - ペイロードはJSON文字列化されている必要があります
出力形式
SDKは複数の出力形式をサポートしています:
テキスト出力(デフォルト)
JSON出力
メタデータを含む構造化データを返します:
レスポンス形式:
ストリーミングJSON出力
受信した各メッセージをストリーミングします:
各会話は初期のinit
システムメッセージで始まり、ユーザーとアシスタントのメッセージのリストが続き、統計を含む最終的なresult
システムメッセージで終わります。各メッセージは個別のJSONオブジェクトとして出力されます。
メッセージスキーマ
JSON APIから返されるメッセージは、以下のスキーマに従って厳密に型付けされています:
まもなく、これらの型をJSONSchema互換形式で公開予定です。この形式への破壊的変更を伝えるために、メインのClaude Codeパッケージにセマンティックバージョニングを使用しています。
Message
とMessageParam
型はAnthropic SDKで利用可能です。例えば、AnthropicのTypeScriptとPythonSDKを参照してください。
入力形式
SDKは複数の入力形式をサポートしています:
テキスト入力(デフォルト)
ストリーミングJSON入力
各メッセージがユーザーターンを表すstdin
経由で提供されるメッセージのストリーム。これにより、claude
バイナリを再起動することなく会話の複数ターンが可能になり、リクエストを処理している間にモデルにガイダンスを提供できます。
各メッセージは出力メッセージスキーマと同じ形式に従う JSON ‘User message’ オブジェクトです。メッセージはjsonl形式を使用してフォーマットされ、入力の各行が完全なJSONオブジェクトです。ストリーミングJSON入力には-p
と--output-format stream-json
が必要です。
現在、これはテキストのみのユーザーメッセージに制限されています。
エージェント統合例
SREインシデント対応ボット
自動セキュリティレビュー
マルチターン法務アシスタント
Python固有のベストプラクティス
主要パターン
IPython/Jupyterのヒント
ベストプラクティス
-
レスポンスのプログラム的解析にはJSON出力形式を使用:
-
エラーを適切に処理 - 終了コードとstderrをチェック:
-
マルチターン会話でコンテキストを維持するためにセッション管理を使用
-
長時間実行される操作にはタイムアウトを考慮:
-
複数のリクエストを行う際は呼び出し間に遅延を追加してレート制限を尊重
関連リソース
- CLI使用方法と制御 - 完全なCLIドキュメント
- GitHub Actions統合 - ClaudeでGitHubワークフローを自動化
- 一般的なワークフロー - 一般的な使用例のステップバイステップガイド