クイックスタート

Python または TypeScript Agent SDK を使用して、自律的に動作する AI エージェントを構築する方法を学びます

Agent SDK を使用して、コードを読み、バグを見つけ、すべて手動操作なしで修正する AI エージェントを構築します。

実行内容：

1. Agent SDK でプロジェクトをセットアップする
2. バグのあるコードを含むファイルを作成する
3. バグを自動的に見つけて修正するエージェントを実行する

前提条件

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

セットアップ

mkdir my-agent
cd my-agent

npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

uv init
uv add claude-agent-sdk

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

export ANTHROPIC_API_KEY=your-api-key

$env:ANTHROPIC_API_KEY = "your-api-key"

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

このクイックスタートでは、コード内のバグを見つけて修正できるエージェントを構築する手順を説明します。まず、エージェントが修正するための意図的なバグを含むファイルが必要です。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 を作成します。既存のプロジェクトが 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 つの主要な部分があります：

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 がタスクを完了するか、エラーに達するとループが終了します。

ループ内のメッセージ処理は、人間が読める出力をフィルタリングします。フィルタリングなしでは、システム初期化と内部状態を含む生のメッセージオブジェクトが表示されます。これはデバッグに役立ちますが、そうでない場合はノイズが多くなります。

エージェントを実行する

エージェントの準備ができました。次のコマンドで実行します：

npx tsx agent.ts

uv run agent.py

python agent.py

実行すると、エージェントは推論と呼び出す各ツールを印刷し、Done: success で終了します。実行後、utils.py を確認します。空のリストと null ユーザーを処理する防御的なコードが表示されます。エージェントは自律的に：

1. 読み取り utils.py でコードを理解する
2. 分析 ロジックを分析し、クラッシュを引き起こすエッジケースを特定する
3. 編集 ファイルを編集して適切なエラーハンドリングを追加する

これが 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"

各スニペットは同じオプションオブジェクトのフィールドを設定します。詳細については、エージェントを構成する を参照してください。

主要な概念

ツール はエージェントが何ができるかを制御します：

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

次のステップ

最初のエージェントを作成したので、その機能を拡張し、ユースケースに合わせてカスタマイズする方法を学びます：

• エージェントを設定する：オプションオブジェクトを構成し、各設定をカバーするページを見つける
• 権限：エージェントが何ができるか、いつ承認が必要かを制御する
• Hooks：ツール呼び出しの前後にカスタムコードを実行する
• セッション：コンテキストを維持するマルチターンエージェントを構築する
• MCP サーバー：データベース、ブラウザー、API、その他の外部システムに接続する
• ホスティング：Docker、クラウド、CI/CD にエージェントをデプロイする
• サンプルエージェント：完全な例を参照：メールアシスタント、リサーチエージェント、その他
• トラブルシューティング：Agent SDK エラーを表示されるメッセージで修正する