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

前提条件

セットアップ

1

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

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

SDK をインストールする

お使いの言語用の Agent SDK パッケージをインストールします:
package.json"type": "module" を設定すると、エージェントスクリプトでトップレベルの await を使用でき、tsx は TypeScript ファイルを直接実行します。
TypeScript SDK は、プラットフォーム用のネイティブ Claude Code バイナリをオプションの依存関係としてバンドルしているため、Claude Code を別途インストールする必要はありません。
3

API キーを設定する

Claude Console から API キーを取得し、エージェントを実行するシェルで環境変数として設定します:
SDK はエージェントを実行するプロセスの環境からキーを読み取ります。.env ファイルを自動的に読み込みません。キーを .env ファイルに保持している場合は、SDK を呼び出す前に、たとえば dotenv パッケージを使用して自分で読み込んでください。SDK はサードパーティ API プロバイダーを介した認証もサポートしています:
  • Amazon BedrockCLAUDE_CODE_USE_BEDROCK=1 環境変数を設定し、AWS 認証情報を構成します
  • Claude Platform on AWSCLAUDE_CODE_USE_ANTHROPIC_AWS=1ANTHROPIC_AWS_WORKSPACE_ID を設定し、AWS 認証情報を構成します
  • Google Cloud の Agent PlatformCLAUDE_CODE_USE_VERTEX=1 環境変数を設定し、Google Cloud 認証情報を構成します
  • Microsoft AzureCLAUDE_CODE_USE_FOUNDRY=1 環境変数を設定し、Azure 認証情報を構成します
詳細については、Amazon BedrockClaude Platform on AWSGoogle Cloud の Agent Platform、または Microsoft Foundry のセットアップガイドを参照してください。
事前に承認されていない限り、Anthropic は、Claude Agent SDK で構築されたエージェントを含む、サードパーティ開発者が claude.ai ログインまたはレート制限を提供することを許可していません。代わりに、このドキュメントで説明されている API キー認証方法を使用してください。

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

このクイックスタートでは、コード内のバグを見つけて修正できるエージェントを構築する手順を説明します。まず、エージェントが修正するための意図的なバグを含むファイルが必要です。my-agent ディレクトリに utils.py を作成し、次のコードを貼り付けます:
このコードには 2 つのバグがあります:
  1. calculate_average([]) はゼロで除算してクラッシュします
  2. get_user_name(None) は TypeError でクラッシュします

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

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

エージェントを実行する

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

他のプロンプトを試す

エージェントがセットアップされたので、いくつかの異なるプロンプトを試してください:
  • "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 検索機能を追加する:
Claude にカスタムシステムプロンプトを提供する:
ターミナルでコマンドを実行する:
Bash を有効にして、次を試してください:"Write unit tests for utils.py, run them, and fix any failures"

主要な概念

ツール はエージェントが何ができるかを制御します: 権限モード は、必要な人間の監視の量を制御します: 上記の例は acceptEdits モードを使用しており、ファイル操作を自動承認するため、エージェントはインタラクティブなプロンプトなしで実行できます。ユーザーに承認を促す場合は、default モードを使用し、ユーザー入力を収集する canUseTool コールバック を提供します。より詳細な制御については、権限 を参照してください。

次のステップ

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