クイックスタート
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 init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx
package.json で "type": "module" を設定すると、エージェントスクリプトでトップレベルの await を使用でき、tsx は TypeScript ファイルを直接実行します。
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx
tsx は TypeScript ファイルを直接実行します。プロジェクトが CommonJS を使用している場合は、エージェントスクリプトを agent.ts の代わりに agent.mts という名前にしてください。.mts 拡張子により、tsx はファイルを ES モジュールとして扱うため、プロジェクト全体を ES モジュールに変換することなく、トップレベルの await が機能します。このクイックスタートの後の作成と実行のステップで、agent.ts の代わりに agent.mts を使用してください。
uv は、仮想環境を自動的に処理する高速な Python パッケージマネージャーです：
uv init
uv add claude-agent-sdk
仮想環境を作成してアクティベートしてから、パッケージをインストールします。
macOS または Linux の場合：
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
Windows の場合：
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk
PowerShell が実行ポリシーエラーで Activate.ps1 をブロックする場合は、まず Set-ExecutionPolicy -Scope Process RemoteSigned を実行してください。
API キーを設定する
Claude Console から API キーを取得し、エージェントを実行するシェルで環境変数として設定します：
export ANTHROPIC_API_KEY=your-api-key
$env:ANTHROPIC_API_KEY = "your-api-key"
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 Vertex AI：
CLAUDE_CODE_USE_VERTEX=1環境変数を設定し、Google Cloud 認証情報を構成します - Microsoft Azure：
CLAUDE_CODE_USE_FOUNDRY=1環境変数を設定し、Azure 認証情報を構成します
詳細については、Bedrock、Claude Platform on AWS、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 を作成します。既存のプロジェクトが CommonJS を使用している場合は、代わりに agent.mts を使用してください：
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"], # これらのツールを自動承認します
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"], // これらのツールを自動承認します
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 がタスクを完了するか、エラーに達するとループが終了します。
ループ内のメッセージ処理は、人間が読める出力をフィルタリングします。フィルタリングなしでは、システム初期化と内部状態を含む生のメッセージオブジェクトが表示されます。これはデバッグに役立ちますが、そうでない場合はノイズが多くなります。
エージェントを実行する
エージェントの準備ができました。次のコマンドで実行します：
npx tsx agent.ts
スクリプトを agent.mts という名前にした場合は、代わりに npx tsx agent.mts を実行してください。
uv run agent.py
仮想環境がまだアクティブな状態で：
python agent.py
実行すると、エージェントは推論と呼び出す各ツールを印刷し、Done: success で終了します。実行後、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 |
ファイル編集と一般的なファイルシステムコマンドを自動承認し、他のアクションについては確認します | 信頼できる開発ワークフロー |
plan |
読み取り専用ツールを実行します。ファイル編集は自動承認されず、canUseTool コールバックに到達します |
実行を承認する前にタスクをスコープする |
dontAsk |
allowedTools にないものを拒否します |
ロックダウンされたヘッドレスエージェント |
auto（TypeScript のみ） |
モデル分類器が各ツール呼び出しを承認または拒否します | 安全ガードレール付きの自律エージェント |
bypassPermissions |
明示的な ask ルール に一致しない限り、プロンプトなしですべてのツールを実行します |
サンドボックス化された CI、完全に信頼できる環境 |
default |
承認を処理するために canUseTool コールバックが必要です |
カスタム承認フロー |
上記の例は acceptEdits モードを使用しており、ファイル操作を自動承認するため、エージェントはインタラクティブなプロンプトなしで実行できます。ユーザーに承認を促す場合は、default モードを使用し、ユーザー入力を収集する canUseTool コールバック を提供します。より詳細な制御については、権限 を参照してください。
次のステップ
最初のエージェントを作成したので、その機能を拡張し、ユースケースに合わせてカスタマイズする方法を学びます：