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

前提条件

  • Node.js 18+ または Python 3.10+
  • Anthropic アカウント。アカウントをお持ちでない場合は、こちらでサインアップしてください。

セットアップ

1

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

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

SDK をインストールする

お使いの言語用の Agent SDK パッケージをインストールします:
package.json で "type": "module" を設定すると、エージェントスクリプトでトップレベルの await を使用でき、tsx は TypeScript ファイルを直接実行します。npm はインストールが成功すると added N packages と出力します。
TypeScript SDK と Python SDK の両方は、ネイティブ Claude Code バイナリをバンドルしているため、ほとんどのインストールでは Claude Code を別途インストールする必要がありません。一部のインストールではバンドルされたバイナリがありません:
  • pip が Python SDK のソース配布をプラットフォームホイールの代わりにインストールする場合(たとえば ARM64 Windows)、バイナリはバンドルされません。Claude Code をネイティブにインストールしてください。Python SDK は PATH 上でそれを見つけます。
  • TypeScript SDK は npm オプション依存関係を通じてバイナリをインストールするため、それらをスキップするインストール(たとえば npm ci --omit=optional)は、サポートされているプラットフォームでもバイナリを取得しません。オプション依存関係をスキップせずに再インストールするか、Claude Code をネイティブにインストールして pathToClaudeCodeExecutable をそのパスに設定してください。
3

API キーを設定する

Claude Console から API キーを取得し、エージェントを実行するシェルで環境変数として設定します:
SDK はエージェントを実行するプロセスの環境からキーを読み取ります。.env ファイルを自動的に読み込みません。キーを .env ファイルに保持している場合は、SDK を呼び出す前に、たとえば dotenv パッケージを使用して自分で読み込んでください。SDK はサードパーティ API プロバイダーを介した認証もサポートしています:
  • Amazon Bedrock:CLAUDE_CODE_USE_BEDROCK=1 環境変数を設定し、AWS 認証情報を構成します
  • Claude Platform on AWS:CLAUDE_CODE_USE_ANTHROPIC_AWS=1 と ANTHROPIC_AWS_WORKSPACE_ID を設定し、AWS 認証情報を構成します
  • Google Cloud の Agent Platform:CLAUDE_CODE_USE_VERTEX=1 環境変数を設定し、Google Cloud 認証情報を構成します
  • Microsoft Foundry:CLAUDE_CODE_USE_FOUNDRY=1 環境変数を設定し、Azure 認証情報を構成します
詳細については、Amazon Bedrock、Claude Platform on AWS、Google 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 を使用して Read、Edit、Glob を事前承認し、permissionMode: "acceptEdits" を使用してファイル変更を自動承認します。その他のオプションには、systemPrompt、mcpServers などがあります。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 は、実装するよう求める代わりに、ツールを直接実行します。
Not logged in や Invalid API key などの認証エラーが表示される場合は、エージェントを実行するシェルで 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" 各スニペットは同じオプションオブジェクトのフィールドを設定します。詳細については、エージェントを構成する を参照してください。

主要な概念

ツール はエージェントが何ができるかを制御します: 権限モード は、必要な人間の監視の量を制御します。SDK は、アクティブなモードをあなたの許可ルールと拒否ルールと共に、権限がどのように評価されるか で説明されている固定の順序で評価します。モードの完全なリスト、その動作、および各モードをいつ使用するかについては、エージェントループの仕組みの権限モード を参照してください。

次のステップ

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