クイックスタート
Python または TypeScript Agent SDK を使用して、自律的に動作する AI エージェントを構築する方法を学びます
Agent SDK を使用して、コードを読み、バグを見つけ、すべて手動操作なしで修正する AI エージェントを構築します。
実行内容：
- Agent SDK でプロジェクトをセットアップする
- バグのあるコードを含むファイルを作成する
- バグを自動的に見つけて修正するエージェントを実行する
前提条件
- Node.js 18+ または Python 3.10+
- Anthropic アカウント（こちらでサインアップ）
セットアップ
プロジェクトフォルダを作成する
このクイックスタート用に新しいディレクトリを作成します：
mkdir my-agent && cd my-agent
独自のプロジェクトの場合、任意のフォルダから SDK を実行できます。デフォルトでは、そのディレクトリとそのサブディレクトリ内のファイルにアクセスできます。
SDK をインストールする
お使いの言語用の Agent SDK パッケージをインストールします：
npm install @anthropic-ai/claude-agent-sdk
uv Python パッケージマネージャーは、仮想環境を自動的に処理する高速な Python パッケージマネージャーです：
uv init && uv add claude-agent-sdk
まず仮想環境を作成してからインストールします：
python3 -m venv .venv && source .venv/bin/activate
pip3 install claude-agent-sdk
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 のセットアップガイドを参照してください。
バグのあるファイルを作成する
このクイックスタートでは、コード内のバグを見つけて修正できるエージェントを構築する手順を説明します。まず、エージェントが修正するための意図的なバグを含むファイルが必要です。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 つのバグがあります：
calculate_average([])はゼロで除算してクラッシュします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())
import { query } from "@anthropic-ai/claude-agent-sdk";
// Agentic ループ：Claude が動作するときにメッセージをストリーミングします
for await (const message of query({
prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options: {
allowedTools: ["Read", "Edit", "Glob"], // Claude が使用できるツール
permissionMode: "acceptEdits" // ファイル編集を自動承認
}
})) {
// 人間が読める出力を印刷します
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text); // Claude の推論
} else if ("name" in block) {
console.log(`Tool: ${block.name}`); // 呼び出されているツール
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`); // 最終結果
}
}
このコードには 3 つの主要な部分があります：
-
query：agentic ループを作成するメインエントリーポイント。非同期イテレーターを返すため、async forを使用して Claude が動作するときにメッセージをストリーミングします。完全な API については、Python または TypeScript SDK リファレンスを参照してください。 -
prompt：Claude に実行させたいこと。Claude はタスクに基づいて使用するツールを判断します。 -
options：エージェントの構成。この例では、allowedToolsを使用してRead、Edit、Globを事前承認し、permissionMode: "acceptEdits"を使用してファイル変更を自動承認します。その他のオプションには、systemPrompt、mcpServersなどがあります。Python または TypeScript のすべてのオプションを参照してください。
async for ループは、Claude が考え、ツールを呼び出し、結果を観察し、次に何をするかを決定する間、実行し続けます。各反復は、メッセージを生成します：Claude の推論、ツール呼び出し、ツール結果、または最終的な結果。SDK はオーケストレーション（ツール実行、コンテキスト管理、再試行）を処理するため、ストリームを消費するだけです。Claude がタスクを完了するか、エラーに達するとループが終了します。
ループ内のメッセージ処理は、人間が読める出力をフィルタリングします。フィルタリングなしでは、システム初期化と内部状態を含む生のメッセージオブジェクトが表示されます。これはデバッグに役立ちますが、そうでない場合はノイズが多くなります。
エージェントを実行する
エージェントの準備ができました。次のコマンドで実行します：
python3 agent.py
npx tsx agent.ts
実行後、utils.py を確認します。空のリストと null ユーザーを処理する防御的なコードが表示されます。エージェントは自律的に：
- 読み取り
utils.pyでコードを理解する - 分析 ロジックを分析し、クラッシュを引き起こすエッジケースを特定する
- 編集 ファイルを編集して適切なエラーハンドリングを追加する
これが Agent SDK を異なるものにする理由です：Claude は、実装するよう求める代わりに、ツールを直接実行します。
他のプロンプトを試す
エージェントがセットアップされたので、いくつかの異なるプロンプトを試してください：
"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"
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
permissionMode: "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.",
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits",
systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
}
};
ターミナルでコマンドを実行する：
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "Bash"],
permissionMode: "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 |
ファイル編集と一般的なファイルシステムコマンドを自動承認し、他のアクションについては確認します | 信頼できる開発ワークフロー |
dontAsk |
allowedTools にないものを拒否します |
ロックダウンされたヘッドレスエージェント |
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 以降にアップグレードしてください。
次のステップ
最初のエージェントを作成したので、その機能を拡張し、ユースケースに合わせてカスタマイズする方法を学びます：