メインコンテンツへスキップ
Agent SDK を使用して、コードを読み、バグを見つけ、すべて手動操作なしで修正する AI エージェントを構築します。 実行内容：
  1. Agent SDK でプロジェクトをセットアップする
  2. バグのあるコードを含むファイルを作成する
  3. バグを自動的に見つけて修正するエージェントを実行する

​
前提条件

​
セットアップ

1

プロジェクトフォルダを作成する

このクイックスタート用に新しいディレクトリを作成します：
mkdir my-agent && cd my-agent
独自のプロジェクトの場合、任意のフォルダから SDK を実行できます。デフォルトでは、そのディレクトリとそのサブディレクトリ内のファイルにアクセスできます。
2

SDK をインストールする

お使いの言語用の Agent SDK パッケージをインストールします：
npm install @anthropic-ai/claude-agent-sdk
TypeScript SDK は、プラットフォーム用のネイティブ Claude Code バイナリをオプションの依存関係としてバンドルしているため、Claude Code を別途インストールする必要はありません。
3

API キーを設定する

Claude Console から API キーを取得し、プロジェクトディレクトリに .env ファイルを作成します：
ANTHROPIC_API_KEY=your-api-key
SDK は、サードパーティ API プロバイダーを介した認証もサポートしています：
  • Amazon Bedrock：CLAUDE_CODE_USE_BEDROCK=1 環境変数を設定し、AWS 認証情報を構成します
  • Google Vertex AI：CLAUDE_CODE_USE_VERTEX=1 環境変数を設定し、Google Cloud 認証情報を構成します
  • Microsoft Azure：CLAUDE_CODE_USE_FOUNDRY=1 環境変数を設定し、Azure 認証情報を構成します
詳細については、Bedrock、Vertex AI、または Azure AI Foundry のセットアップガイドを参照してください。
事前に承認されていない限り、Anthropic は、Claude Agent SDK で構築されたエージェントを含む、サードパーティ開発者が claude.ai ログインまたはレート制限を提供することを許可していません。代わりに、このドキュメントで説明されている API キー認証方法を使用してください。

​
バグのあるファイルを作成する

このクイックスタートでは、コード内のバグを見つけて修正できるエージェントを構築する手順を説明します。まず、エージェントが修正するための意図的なバグを含むファイルが必要です。my-agent ディレクトリに utils.py を作成し、次のコードを貼り付けます： 
def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()
このコードには 2 つのバグがあります：
  1. calculate_average([]) はゼロで除算してクラッシュします
  2. get_user_name(None) は TypeError でクラッシュします

​
バグを見つけて修正するエージェントを構築する

Python SDK を使用している場合は agent.py を作成し、TypeScript の場合は agent.ts を作成します： 
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # Agentic ループ：Claude が動作するときにメッセージをストリーミングします
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Claude が使用できるツール
            permission_mode="acceptEdits",  # ファイル編集を自動承認
        ),
    ):
        # 人間が読める出力を印刷します
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Claude の推論
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # 呼び出されているツール
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # 最終結果


asyncio.run(main())
このコードには 3 つの主要な部分があります：
  1. query：agentic ループを作成するメインエントリーポイント。非同期イテレーターを返すため、async for を使用して Claude が動作するときにメッセージをストリーミングします。完全な API については、Python または TypeScript SDK リファレンスを参照してください。
  2. prompt：Claude に実行させたいこと。Claude はタスクに基づいて使用するツールを判断します。
  3. options：エージェントの構成。この例では、allowedTools を使用して Read、Edit、Glob を事前承認し、permissionMode: "acceptEdits" を使用してファイル変更を自動承認します。その他のオプションには、systemPrompt、mcpServers などがあります。Python または TypeScript のすべてのオプションを参照してください。
async for ループは、Claude が考え、ツールを呼び出し、結果を観察し、次に何をするかを決定する間、実行し続けます。各反復は、メッセージを生成します：Claude の推論、ツール呼び出し、ツール結果、または最終的な結果。SDK はオーケストレーション（ツール実行、コンテキスト管理、再試行）を処理するため、ストリームを消費するだけです。Claude がタスクを完了するか、エラーに達するとループが終了します。 ループ内のメッセージ処理は、人間が読める出力をフィルタリングします。フィルタリングなしでは、システム初期化と内部状態を含む生のメッセージオブジェクトが表示されます。これはデバッグに役立ちますが、そうでない場合はノイズが多くなります。
この例はストリーミングを使用してリアルタイムで進行状況を表示します。ライブ出力が不要な場合（バックグラウンドジョブや CI パイプラインなど）、すべてのメッセージを一度に収集できます。詳細については、ストリーミング対単一ターンモード を参照してください。

​
エージェントを実行する

エージェントの準備ができました。次のコマンドで実行します： 
python3 agent.py
実行後、utils.py を確認します。空のリストと null ユーザーを処理する防御的なコードが表示されます。エージェントは自律的に：
  1. 読み取り utils.py でコードを理解する
  2. 分析 ロジックを分析し、クラッシュを引き起こすエッジケースを特定する
  3. 編集 ファイルを編集して適切なエラーハンドリングを追加する
これが Agent SDK を異なるものにする理由です：Claude は、実装するよう求める代わりに、ツールを直接実行します。
「API key not found」が表示される場合は、.env ファイルまたはシェル環境で ANTHROPIC_API_KEY 環境変数を設定していることを確認してください。詳細については、完全なトラブルシューティングガイド を参照してください。

​
他のプロンプトを試す

エージェントがセットアップされたので、いくつかの異なるプロンプトを試してください：
  • "Add docstrings to all functions in utils.py"
  • "Add type hints to all functions in utils.py"
  • "Create a README.md documenting the functions in utils.py"

​
エージェントをカスタマイズする

オプションを変更することで、エージェントの動作を変更できます。いくつかの例を次に示します： Web 検索機能を追加する： 
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)
Claude にカスタムシステムプロンプトを提供する： 
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)
ターミナルでコマンドを実行する： 
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)
Bash を有効にして、次を試してください："Write unit tests for utils.py, run them, and fix any failures"

​
主要な概念

ツール はエージェントが何ができるかを制御します：
ツールエージェントが実行できること
Read、Glob、Grep読み取り専用分析
Read、Edit、Globコードの分析と変更
Read、Edit、Bash、Glob、Grep完全な自動化
権限モード は、必要な人間の監視の量を制御します：
モード動作ユースケース
acceptEditsファイル編集と一般的なファイルシステムコマンドを自動承認し、他のアクションについては確認します信頼できる開発ワークフロー
dontAskallowedTools にないものを拒否しますロックダウンされたヘッドレスエージェント
auto（TypeScript のみ）モデル分類器が各ツール呼び出しを承認または拒否します安全ガードレール付きの自律エージェント
bypassPermissionsプロンプトなしですべてのツールを実行しますサンドボックス化された CI、完全に信頼できる環境
default承認を処理するために canUseTool コールバックが必要ですカスタム承認フロー
上記の例は acceptEdits モードを使用しており、ファイル操作を自動承認するため、エージェントはインタラクティブなプロンプトなしで実行できます。ユーザーに承認を促す場合は、default モードを使用し、ユーザー入力を収集する canUseTool コールバック を提供します。より詳細な制御については、権限 を参照してください。

​
トラブルシューティング

​
API エラー thinking.type.enabled はこのモデルではサポートされていません

Claude Opus 4.7 は thinking.type.enabled を thinking.type.adaptive に置き換えます。古い Agent SDK バージョンは、claude-opus-4-7 を選択すると次の API エラーで失敗します： 
API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}
Opus 4.7 を使用するには、Agent SDK v0.2.111 以降にアップグレードしてください。

​
次のステップ

最初のエージェントを作成したので、その機能を拡張し、ユースケースに合わせてカスタマイズする方法を学びます：
  • 権限：エージェントが何ができるか、いつ承認が必要かを制御する
  • Hooks：ツール呼び出しの前後にカスタムコードを実行する
  • セッション：コンテキストを維持するマルチターンエージェントを構築する
  • MCP サーバー：データベース、ブラウザー、API、その他の外部システムに接続する
  • ホスティング：Docker、クラウド、CI/CD にエージェントをデプロイする
  • サンプルエージェント：完全な例を参照：メールアシスタント、リサーチエージェント、その他