クイックスタート

Agent SDK を使って、コードを読み取り、バグを見つけ、修正する AI エージェントを構築しましょう。すべて手動の介入なしで行えます。

このガイドで行うこと：

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

前提条件

• Node.js 18+ または Python 3.10+
• Anthropic アカウント（こちらでサインアップ）

セットアップ

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

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    # エージェントループ：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())

このコードには3つの主要な部分があります：

1. query：エージェントループを作成するメインのエントリポイントです。非同期イテレータを返すため、async for を使って Claude が作業する間メッセージをストリーミングします。完全な API については Python または TypeScript SDK リファレンスを参照してください。

2. prompt：Claude に実行してほしいことです。Claude はタスクに基づいて使用するツールを判断します。

3. options：エージェントの設定です。この例では allowedTools を使って Claude を Read、Edit、Glob に制限し、permissionMode: "acceptEdits" でファイル変更を自動承認しています。その他のオプションには systemPrompt、mcpServers などがあります。すべてのオプションについては Python または TypeScript を参照してください。

async for ループは、Claude が思考し、ツールを呼び出し、結果を観察し、次に何をするかを決定する間、実行し続けます。各イテレーションでメッセージが生成されます：Claude の推論、ツール呼び出し、ツール結果、または最終的な結果です。SDK がオーケストレーション（ツール実行、コンテキスト管理、リトライ）を処理するため、ストリームを消費するだけで済みます。ループは Claude がタスクを完了するか、エラーが発生した時点で終了します。

ループ内のメッセージ処理は、人間が読みやすい出力をフィルタリングしています。フィルタリングなしでは、システム初期化や内部状態を含む生のメッセージオブジェクトが表示されます。これはデバッグには有用ですが、通常はノイズになります。

エージェントを実行する

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

実行後、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"
)

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."
)

ターミナルでコマンドを実行する：

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)

Bash を有効にして、次を試してみてください："Write unit tests for utils.py, run them, and fix any failures"

主要な概念

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

パーミッションモードは、どの程度の人間の監視が必要かを制御します：

上記の例では acceptEdits モードを使用しており、ファイル操作を自動承認するため、エージェントはインタラクティブなプロンプトなしで実行できます。ユーザーに承認を求めたい場合は、default モードを使用し、ユーザー入力を収集する canUseTool コールバックを提供してください。より詳細な制御については、パーミッションを参照してください。

次のステップ

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

• パーミッション：エージェントができることと、承認が必要なタイミングを制御する
• フック：ツール呼び出しの前後にカスタムコードを実行する
• セッション：コンテキストを維持するマルチターンエージェントを構築する
• MCP サーバー：データベース、ブラウザ、API、その他の外部システムに接続する
• ホスティング：Docker、クラウド、CI/CD にエージェントをデプロイする
• エージェントの例：完全な例を参照：メールアシスタント、リサーチエージェントなど