なぜClaude Code SDKを使用するのか?

Claude Code SDKは、本番環境対応のエージェントを構築するために必要なすべての構成要素を提供します:

  • 最適化されたClaude統合: 自動プロンプトキャッシュと パフォーマンス最適化
  • 豊富なツールエコシステム: ファイル操作、コード実行、ウェブ検索、 MCPの拡張性
  • 高度な権限管理: エージェント機能の細かい制御
  • 本番環境の必需品: 組み込みエラーハンドリング、セッション管理、 監視

SDKで何を構築できるか?

作成できるエージェントタイプの例をいくつか紹介します:

コーディングエージェント:

  • 本番環境の問題を診断・修正するSREエージェント
  • 脆弱性についてコードを監査するセキュリティレビューボット
  • インシデントをトリアージするオンコールエンジニアリングアシスタント
  • スタイルとベストプラクティスを強制するコードレビューエージェント

ビジネスエージェント:

  • 契約とコンプライアンスをレビューする法務アシスタント
  • レポートと予測を分析する財務アドバイザー
  • 技術的問題を解決するカスタマーサポートエージェント
  • マーケティングチーム向けのコンテンツ作成アシスタント

SDKは現在TypeScriptとPythonで利用可能で、迅速なプロトタイピング用のコマンドラインインターフェース(CLI)も提供しています。

クイックスタート

5分以内で最初のエージェントを実行しましょう:

1

SDKをインストール

NPMから@anthropic-ai/claude-codeをインストール:

npm install -g @anthropic-ai/claude-code
2

APIキーを設定

Anthropic ConsoleからAPIキーを取得し、ANTHROPIC_API_KEY環境変数を設定:

export ANTHROPIC_API_KEY="your-api-key-here"
3

最初のエージェントを作成

以下のサンプルエージェントのいずれかを作成:

# シンプルな法務アシスタントを作成
claude -p "この契約条項の潜在的な問題をレビューしてください:'当事者は無制限の責任に同意する...'" \
  --append-system-prompt "あなたは法務アシスタントです。リスクを特定し、改善を提案してください。"
4

エージェントを実行

上記のコマンドをターミナルに直接コピー&ペーストしてください。

上記の各例は、以下を行う動作するエージェントを作成します:

  • Claudeの推論能力を使用してプロンプトを分析
  • 問題を解決するための多段階アプローチを計画
  • ファイル操作、bashコマンド、ウェブ検索などのツールを使用してアクションを実行
  • 分析に基づいて実行可能な推奨事項を提供

基本的な使用方法

概要

Claude Code SDKを使用すると、アプリケーションから非インタラクティブモードでClaude Codeとインターフェースできます。

前提条件

  • Node.js 18+
  • NPMから@anthropic-ai/claude-code

基本的な使用方法

Claude Codeの主要なコマンドラインインターフェースはclaudeコマンドです。--print(または-p)フラグを使用して非インタラクティブモードで実行し、最終結果を印刷します:

claude -p "システムパフォーマンスを分析" \
  --append-system-prompt "あなたはパフォーマンスエンジニアです" \
  --allowedTools "Bash,Read,WebSearch" \
  --permission-mode acceptEdits \
  --cwd /path/to/project

設定

SDKはClaude Codeで利用可能なすべてのCLIオプションを活用します。SDK使用のための主要なオプションは以下の通りです:

フラグ説明
--print, -p非インタラクティブモードで実行claude -p "query"
--output-format出力形式を指定(text, json, stream-jsonclaude -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-configJSONファイルからMCPサーバーを読み込みclaude --mcp-config servers.json
--permission-prompt-tool権限プロンプトを処理するMCPツール(--printでのみ)claude --permission-prompt-tool mcp__auth__prompt

CLIオプションと機能の完全なリストについては、CLIリファレンスドキュメントを参照してください。

認証

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 BedrockGoogle Vertex AIのドキュメントを参照してください。

マルチターン会話

マルチターン会話の場合、会話を再開したり、最新のセッションから継続したりできます:

# 最新の会話を継続
claude --continue "今度はパフォーマンス向上のためにリファクタリング"

# セッションIDで特定の会話を再開
claude --resume 550e8400-e29b-41d4-a716-446655440000 "テストを更新"

# 非インタラクティブモードで再開
claude --resume 550e8400-e29b-41d4-a716-446655440000 "すべてのリンティング問題を修正" --no-interactive

プランモードの使用

プランモードを使用すると、Claudeは変更を加えることなくコードを分析でき、コードレビューや変更の計画に便利です。

claude -p "このコードをレビュー" --permission-mode plan

プランモードは編集、ファイル作成、コマンド実行を制限します。詳細については権限モードを参照してください。

カスタムシステムプロンプト

システムプロンプトはエージェントの役割、専門知識、行動を定義します。ここで構築するエージェントの種類を指定します:

# SREインシデント対応エージェント
claude -p "APIがダウン、調査" \
  --append-system-prompt "あなたはSREエキスパートです。問題を体系的に診断し、実行可能な解決策を提供してください。"

# 法的文書レビューエージェント  
claude -p "この契約をレビュー" \
  --append-system-prompt "あなたは企業弁護士です。リスクを特定し、改善を提案し、コンプライアンスを確保してください。"

# デフォルトシステムプロンプトに追加
claude -p "この関数をリファクタリング" \
  --append-system-prompt "常に包括的なエラーハンドリングとユニットテストを含めてください。"

高度な使用方法

MCP経由のカスタムツール

Model Context Protocol(MCP)を使用すると、エージェントにカスタムツールと機能を提供できます。これは、ドメイン固有の統合が必要な専門エージェントを構築するために重要です。

エージェントツール設定の例:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {"SLACK_TOKEN": "your-slack-token"}
    },
    "jira": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-jira"],
      "env": {"JIRA_TOKEN": "your-jira-token"}
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {"DB_CONNECTION_STRING": "your-db-url"}
    }
  }
}

使用例:

# 監視ツール付きSREエージェント
claude -p "決済サービスの停止を調査" \
  --mcp-config sre-tools.json \
  --allowedTools "mcp__datadog,mcp__pagerduty,mcp__kubernetes" \
  --append-system-prompt "あなたはSREです。監視データを使用して問題を診断してください。"

# CRMアクセス付きカスタマーサポートエージェント
claude -p "顧客チケット#12345の解決を支援" \
  --mcp-config support-tools.json \
  --allowedTools "mcp__zendesk,mcp__stripe,mcp__user_db" \
  --append-system-prompt "あなたは技術サポートスペシャリストです。"

MCPツールを使用する場合、--allowedToolsフラグを使用して明示的に許可する必要があります。MCPツール名はmcp__<serverName>__<toolName>のパターンに従います:

  • serverNameはMCP設定ファイルのキー
  • toolNameはそのサーバーが提供する特定のツール

このセキュリティ対策により、MCPツールは明示的に許可された場合にのみ使用されます。

サーバー名のみを指定した場合(つまり、mcp__<serverName>)、そのサーバーのすべてのツールが許可されます。

グロブパターン(例:mcp__go*)はサポートされていません。

カスタム権限プロンプトツール

オプションで、--permission-prompt-toolを使用して、ユーザーが特定のツールを呼び出すモデルに権限を付与するかどうかをチェックするために使用するMCPツールを渡すことができます。モデルがツールを呼び出すと、以下が発生します:

  1. まず権限設定をチェック:すべてのsettings.jsonファイル、およびSDKに渡された--allowedTools--disallowedTools;これらのいずれかがツール呼び出しを許可または拒否する場合、ツール呼び出しを続行
  2. そうでなければ、--permission-prompt-toolで提供したMCPツールを呼び出し

--permission-prompt-tool MCPツールはツール名と入力を渡され、結果を含むJSON文字列化されたペイロードを返す必要があります。ペイロードは以下のいずれかである必要があります:

// ツール呼び出しが許可される
{
  "behavior": "allow",
  "updatedInput": {...}, // 更新された入力、または元の入力をそのまま返す
}

// ツール呼び出しが拒否される
{
  "behavior": "deny",
  "message": "..." // 権限が拒否された理由を説明する人間が読める文字列
}

実装例:

# MCPサーバー設定で使用
claude -p "セキュリティ問題を分析して修正" \
  --permission-prompt-tool mcp__security__approval_prompt \
  --mcp-config security-tools.json \
  --allowedTools "Read,Grep" \
  --disallowedTools "Bash(rm*),Write"

# カスタム権限ルールで
claude -p "コードベースをリファクタリング" \
  --permission-prompt-tool mcp__custom__permission_check \
  --mcp-config custom-config.json \
  --output-format json

使用上の注意:

  • 権限プロンプトがその入力を変更したことをモデルに伝えるためにupdatedInputを使用します;そうでなければ、上記の例のようにupdatedInputを元の入力に設定します。例えば、ツールがファイル編集の差分をユーザーに表示し、ユーザーが差分を手動で編集できるようにする場合、権限プロンプトツールはその更新された編集を返すべきです。
  • ペイロードはJSON文字列化されている必要があります

出力形式

SDKは複数の出力形式をサポートしています:

テキスト出力(デフォルト)

claude -p "ファイルsrc/components/Header.tsxを説明"
# 出力: これは...を表示するReactコンポーネントです

JSON出力

メタデータを含む構造化データを返します:

claude -p "データレイヤーはどのように動作しますか?" --output-format json

レスポンス形式:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "ここにレスポンステキスト...",
  "session_id": "abc123"
}

ストリーミングJSON出力

受信した各メッセージをストリーミングします:

$ claude -p "アプリケーションを構築" --output-format stream-json

各会話は初期のinitシステムメッセージで始まり、ユーザーとアシスタントのメッセージのリストが続き、統計を含む最終的なresultシステムメッセージで終わります。各メッセージは個別のJSONオブジェクトとして出力されます。

メッセージスキーマ

JSON APIから返されるメッセージは、以下のスキーマに従って厳密に型付けされています:

type SDKMessage =
  // アシスタントメッセージ
  | {
      type: "assistant";
      message: Message; // Anthropic SDKから
      session_id: string;
    }

  // ユーザーメッセージ
  | {
      type: "user";
      message: MessageParam; // Anthropic SDKから
      session_id: string;
    }

  // 最後のメッセージとして出力
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // 最大ターン数に達した場合の最後のメッセージとして出力
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // 会話の開始時に最初のメッセージとして出力
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

まもなく、これらの型をJSONSchema互換形式で公開予定です。この形式への破壊的変更を伝えるために、メインのClaude Codeパッケージにセマンティックバージョニングを使用しています。

MessageMessageParam型はAnthropic SDKで利用可能です。例えば、AnthropicのTypeScriptPythonSDKを参照してください。

入力形式

SDKは複数の入力形式をサポートしています:

テキスト入力(デフォルト)

# 直接引数
claude -p "このコードを説明"

# stdinから
echo "このコードを説明" | claude -p

ストリーミングJSON入力

各メッセージがユーザーターンを表すstdin経由で提供されるメッセージのストリーム。これにより、claudeバイナリを再起動することなく会話の複数ターンが可能になり、リクエストを処理している間にモデルにガイダンスを提供できます。

各メッセージは出力メッセージスキーマと同じ形式に従う JSON ‘User message’ オブジェクトです。メッセージはjsonl形式を使用してフォーマットされ、入力の各行が完全なJSONオブジェクトです。ストリーミングJSON入力には-p--output-format stream-jsonが必要です。

現在、これはテキストのみのユーザーメッセージに制限されています。

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"このコードを説明"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

エージェント統合例

SREインシデント対応ボット

#!/bin/bash

# 自動インシデント対応エージェント
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"
    
    claude -p "インシデント: $incident_description (重要度: $severity)" \
      --append-system-prompt "あなたはSREエキスパートです。問題を診断し、影響を評価し、即座の行動項目を提供してください。" \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# 使用方法
investigate_incident "決済APIが500エラーを返している" "high"

自動セキュリティレビュー

# プルリクエスト用セキュリティ監査エージェント
audit_pr() {
    local pr_number="$1"
    
    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "あなたはセキュリティエンジニアです。このPRの脆弱性、安全でないパターン、コンプライアンス問題をレビューしてください。" \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# 使用方法とファイルに保存
audit_pr 123 > security-report.json

マルチターン法務アシスタント

# セッション永続化付き法的文書レビュー
session_id=$(claude -p "法的レビューセッションを開始" --output-format json | jq -r '.session_id')

# 複数ステップで契約をレビュー
claude -p --resume "$session_id" "contract.pdfの責任条項をレビュー"
claude -p --resume "$session_id" "GDPR要件のコンプライアンスをチェック" 
claude -p --resume "$session_id" "リスクの要約を生成"

Python固有のベストプラクティス

主要パターン

import asyncio
from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions

# 常にコンテキストマネージャーを使用
async with ClaudeSDKClient() as client:
    await client.query("このコードを分析")
    async for msg in client.receive_response():
        # ストリーミングメッセージを処理
        pass

# 複数のエージェントを同時実行
async with ClaudeSDKClient() as reviewer, ClaudeSDKClient() as tester:
    await asyncio.gather(
        reviewer.query("main.pyをレビュー"),
        tester.query("main.pyのテストを作成")
    )

# エラーハンドリング
from claude_code_sdk import CLINotFoundError, ProcessError

try:
    async with ClaudeSDKClient() as client:
        # ここにコード
        pass
except CLINotFoundError:
    print("CLIをインストール: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"プロセスエラー: {e}")

# メタデータ付き完全レスポンスを収集
async def get_response(client, prompt):
    await client.query(prompt)
    text = []
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    text.append(block.text)
        if type(msg).__name__ == "ResultMessage":
            return {'text': ''.join(text), 'cost': msg.total_cost_usd}

IPython/Jupyterのヒント

# Jupyterでは、セル内で直接awaitを使用
client = ClaudeSDKClient()
await client.connect()
await client.query("data.csvを分析")
async for msg in client.receive_response():
    print(msg)
await client.disconnect()

# 再利用可能なヘルパー関数を作成
async def stream_print(client, prompt):
    await client.query(prompt)
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    print(block.text, end='', flush=True)

ベストプラクティス

  • レスポンスのプログラム的解析にはJSON出力形式を使用

    # jqでJSONレスポンスを解析
    result=$(claude -p "コードを生成" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  • エラーを適切に処理 - 終了コードとstderrをチェック:

    if ! claude -p "$prompt" 2>error.log; then
        echo "エラーが発生しました:" >&2
        cat error.log >&2
        exit 1
    fi
    
  • マルチターン会話でコンテキストを維持するためにセッション管理を使用

  • 長時間実行される操作にはタイムアウトを考慮

    timeout 300 claude -p "$complex_prompt" || echo "5分後にタイムアウト"
    
  • 複数のリクエストを行う際は呼び出し間に遅延を追加してレート制限を尊重

関連リソース