クイックスタート

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():
    # Agentic loop: 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: agentic ループを作成するメインエントリーポイント。非同期イテレータを返すため、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 がタスクを完了するか、エラーに遭遇するとループが終了します。

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

エージェントを実行

エージェントの準備ができました。次のコマンドで実行してください:

python3 agent.py

実行後、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 にエージェントをデプロイ
• サンプルエージェント: 完全な例を参照: メールアシスタント、リサーチエージェント、その他