Claude Code SDK
Claude Code SDKを使用してClaudeCodeをアプリケーションにプログラム的に統合する方法について学びます。
Claude Code SDKは、Claude CodeをサブプロセスとしてRunning可能にし、Claudeの機能を活用したAI駆動のコーディングアシスタントやツールを構築する方法を提供します。
SDKは、コマンドライン、TypeScript、およびPythonでの使用が可能です。
認証
Claude Code SDKを使用するには、専用のAPIキーを作成することをお勧めします:
- Anthropic ConsoleでAnthropic APIキーを作成します
- 次に、
ANTHROPIC_API_KEY
環境変数を設定します。このキーを安全に保存することをお勧めします(例:Github secretを使用)
基本的なSDKの使用方法
Claude Code SDKを使用すると、アプリケーションから非対話モードでClaude Codeを使用できます。
コマンドライン
コマンドラインSDKの基本的な例をいくつか示します:
TypeScript
TypeScript SDKは、NPMのメイン@anthropic-ai/claude-code
パッケージに含まれています:
TypeScript SDKは、コマンドラインSDKでサポートされているすべての引数に加えて、以下を受け入れます:
引数 | 説明 | デフォルト |
---|---|---|
abortController | アボートコントローラー | new AbortController() |
cwd | 現在の作業ディレクトリ | process.cwd() |
executable | 使用するJavaScriptランタイム | Node.jsで実行時はnode 、Bunで実行時はbun |
executableArgs | 実行可能ファイルに渡す引数 | [] |
pathToClaudeCodeExecutable | Claude Code実行可能ファイルへのパス | @anthropic-ai/claude-code に付属の実行可能ファイル |
Python
Python SDKは、PyPIでclaude-code-sdk
として利用できます:
前提条件:
- Python 3.10+
- Node.js
- Claude Code CLI:
npm install -g @anthropic-ai/claude-code
基本的な使用方法:
Python SDKは、ClaudeCodeOptions
クラスを通じてコマンドラインSDKでサポートされているすべての引数を受け入れます:
高度な使用方法
以下のドキュメントでは、例としてコマンドラインSDKを使用していますが、TypeScriptおよびPython SDKでも使用できます。
マルチターン会話
マルチターン会話の場合、会話を再開したり、最新のセッションから続行したりできます:
カスタムシステムプロンプト
Claudeの動作を導くためにカスタムシステムプロンプトを提供できます:
デフォルトのシステムプロンプトに指示を追加することもできます:
MCP設定
Model Context Protocol(MCP)を使用すると、外部サーバーからの追加ツールやリソースでClaude Codeを拡張できます。--mcp-config
フラグを使用して、データベースアクセス、API統合、カスタムツールなどの専門機能を提供するMCPサーバーを読み込むことができます。
MCPサーバーでJSON設定ファイルを作成します:
次に、Claude Codeで使用します:
MCPツールを使用する場合、--allowedTools
フラグを使用して明示的に許可する必要があります。MCPツール名はmcp__<serverName>__<toolName>
のパターンに従います。ここで:
serverName
はMCP設定ファイルのキーですtoolName
はそのサーバーが提供する特定のツールです
このセキュリティ対策により、MCPツールは明示的に許可された場合にのみ使用されることが保証されます。
サーバー名のみを指定した場合(つまり、mcp__<serverName>
)、そのサーバーのすべてのツールが許可されます。
Globパターン(例:mcp__go*
)はサポートされていません。
カスタム権限プロンプトツール
オプションで、--permission-prompt-tool
を使用して、ユーザーが特定のツールを呼び出す権限をモデルに付与するかどうかをチェックするために使用するMCPツールを渡すことができます。モデルがツールを呼び出すと、次のことが起こります:
- まず権限設定をチェックします:すべてのsettings.jsonファイル、およびSDKに渡された
--allowedTools
と--disallowedTools
;これらのいずれかがツール呼び出しを許可または拒否する場合、ツール呼び出しを続行します - そうでなければ、
--permission-prompt-tool
で提供したMCPツールを呼び出します
--permission-prompt-tool
MCPツールには、ツール名と入力が渡され、結果を含むJSON文字列化されたペイロードを返す必要があります。ペイロードは次のいずれかである必要があります:
例えば、TypeScript MCP権限プロンプトツールの実装は次のようになります:
このツールを使用するには、MCPサーバーを追加し(例:--mcp-config
で)、次のようにSDKを呼び出します:
使用上の注意:
updatedInput
を使用して、権限プロンプトが入力を変更したことをモデルに伝えます;そうでなければ、上記の例のようにupdatedInput
を元の入力に設定します。例えば、ツールがファイル編集の差分をユーザーに表示し、差分を手動で編集させる場合、権限プロンプトツールはその更新された編集を返すべきです。- ペイロードはJSON文字列化されている必要があります
利用可能なCLIオプション
SDKは、Claude Codeで利用可能なすべてのCLIオプションを活用します。SDK使用のための主要なものは次のとおりです:
フラグ | 説明 | 例 |
---|---|---|
--print , -p | 非対話モードで実行 | claude -p "クエリ" |
--output-format | 出力形式を指定(text 、json 、stream-json ) | claude -p --output-format json |
--resume , -r | セッションIDで会話を再開 | claude --resume abc123 |
--continue , -c | 最新の会話を続行 | claude --continue |
--verbose | 詳細ログを有効化 | claude --verbose |
--max-turns | 非対話モードでのエージェントターンを制限 | claude --max-turns 3 |
--system-prompt | システムプロンプトを上書き(--print でのみ) | claude --system-prompt "カスタム指示" |
--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リファレンスドキュメントを参照してください。
出力形式
SDKは複数の出力形式をサポートしています:
テキスト出力(デフォルト)
レスポンステキストのみを返します:
JSON出力
メタデータを含む構造化データを返します:
レスポンス形式:
ストリーミングJSON出力
受信した各メッセージをストリーミングします:
各会話は初期のinit
システムメッセージで始まり、ユーザーとアシスタントのメッセージのリストが続き、統計情報を含む最終的なresult
システムメッセージで終わります。各メッセージは個別のJSONオブジェクトとして出力されます。
メッセージスキーマ
JSON APIから返されるメッセージは、次のスキーマに従って厳密に型付けされています:
これらの型をJSONSchema互換形式で間もなく公開予定です。この形式への破壊的変更を伝えるために、メインのClaude Codeパッケージにセマンティックバージョニングを使用しています。
Message
とMessageParam
型は、Anthropic SDKで利用できます。例えば、Anthropic TypeScriptおよびPython SDKを参照してください。
入力形式
SDKは複数の入力形式をサポートしています:
テキスト入力(デフォルト)
入力テキストは引数として提供できます:
または、入力テキストはstdin経由でパイプできます:
ストリーミングJSON入力
各メッセージがユーザーターンを表すstdin
経由で提供されるメッセージのストリーム。これにより、claude
バイナリを再起動することなく会話の複数ターンが可能になり、リクエストを処理している間にモデルにガイダンスを提供できます。
各メッセージは、出力メッセージスキーマと同じ形式に従う JSON ‘User message’オブジェクトです。メッセージはjsonl形式を使用してフォーマットされ、入力の各行が完全なJSONオブジェクトです。ストリーミングJSON入力には-p
と--output-format stream-json
が必要です。
現在、これはテキストのみのユーザーメッセージに制限されています。
例
シンプルなスクリプト統合
Claudeでファイルを処理
セッション管理
ベストプラクティス
-
プログラム的なレスポンス解析にはJSON出力形式を使用:
-
エラーを適切に処理 - 終了コードとstderrをチェック:
-
マルチターン会話でコンテキストを維持するためにセッション管理を使用
-
長時間実行される操作にはタイムアウトを考慮:
-
複数のリクエストを行う際は、呼び出し間に遅延を追加してレート制限を尊重
実世界のアプリケーション
Claude Code SDKは、開発ワークフローとの強力な統合を可能にします。注目すべき例の一つはClaude Code GitHub Actionsで、SDKを使用してGitHubワークフロー内で自動コードレビュー、PR作成、課題トリアージ機能を直接提供します。
関連リソース
- CLI使用方法とコントロール - 完全なCLIドキュメント
- GitHub Actions統合 - ClaudeでGitHubワークフローを自動化
- 一般的なワークフロー - 一般的な使用例のステップバイステップガイド