SpyBara
Go Premium

agent-sdk/quickstart.md 2026-11-03 23:58 UTC to 2026-11-04 23:59 UTC

No changes for this document in this history range.

2026

クイックスタート

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

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

実行内容：

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

前提条件

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

セットアップ

1. プロジェクトフォルダを作成する

このクイックスタート用に新しいディレクトリを作成します：

mkdir my-agent
cd my-agent

独自のプロジェクトの場合、任意のフォルダから SDK を実行できます。デフォルトでは、そのディレクトリとそのサブディレクトリ内のファイルにアクセスできます。

2. SDK をインストールする

お使いの言語用の Agent SDK パッケージをインストールします：

[tab] TypeScript（新規プロジェクト）

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 はインストールが成功すると added N packages と出力します。

[tab] 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 を使用してください。

[tab] Python（uv）

uv をインストールしてください。これは仮想環境を自動的に処理する高速な Python パッケージマネージャーです。その後、プロジェクトを初期化して SDK を追加します：

uv init
uv add claude-agent-sdk

[tab] Python（pip）

仮想環境を作成してアクティベートしてから、パッケージをインストールします。

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 を実行してください。

[!NOTE]

TypeScript SDK と Python SDK の両方は、ネイティブ Claude Code バイナリをバンドルしているため、ほとんどのインストールでは Claude Code を別途インストールする必要がありません。一部のインストールではバンドルされたバイナリがありません：

  • pip が Python SDK のソース配布をプラットフォームホイールの代わりにインストールする場合（たとえば ARM64 Windows）、バイナリはバンドルされません。Claude Code をネイティブにインストールしてください。Python SDK は PATH 上でそれを見つけます。
  • TypeScript SDK は npm オプション依存関係を通じてバイナリをインストールするため、それらをスキップするインストール（たとえば npm ci --omit=optional）は、サポートされているプラットフォームでもバイナリを取得しません。オプション依存関係をスキップせずに再インストールするか、Claude Code をネイティブにインストールして pathToClaudeCodeExecutable をそのパスに設定してください。

3. API キーを設定する

Claude Console から API キーを取得し、エージェントを実行するシェルで環境変数として設定します：

[tab] macOS / Linux

export ANTHROPIC_API_KEY=your-api-key

[tab] Windows（PowerShell）

$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 Cloud の Agent Platform：CLAUDE_CODE_USE_VERTEX=1 環境変数を設定し、Google Cloud 認証情報を構成します
  • Microsoft Foundry：CLAUDE_CODE_USE_FOUNDRY=1 環境変数を設定し、Azure 認証情報を構成します

詳細については、Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、または Microsoft Foundry のセットアップガイドを参照してください。

[!NOTE]

事前に承認されていない限り、Anthropic は、Claude Agent SDK で構築されたエージェントを含む、サードパーティ開発者が claude.ai ログインまたはレート制限を提供することを許可していません。代わりに、このドキュメントで説明されている API キー認証方法を使用してください。

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

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

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

[!NOTE]

この例はストリーミングを使用してリアルタイムで進行状況を表示します。ライブ出力が不要な場合（バックグラウンドジョブや CI パイプラインなど）、すべてのメッセージを一度に収集できます。詳細については、ストリーミング対単一ターンモード を参照してください。

エージェントを実行する

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

[tab] TypeScript

npx tsx agent.ts

スクリプトを agent.mts という名前にした場合は、代わりに npx tsx agent.mts を実行してください。

[tab] Python（uv）

uv run agent.py

[tab] Python（pip）

仮想環境がまだアクティブな状態で：

python agent.py

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

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

これが Agent SDK を異なるものにする理由です：Claude は、実装するよう求める代わりに、ツールを直接実行します。

[!NOTE]

Not logged in や Invalid API key などの認証エラーが表示される場合は、エージェントを実行するシェルで ANTHROPIC_API_KEY 環境変数を設定していることを確認してください。SDK は .env ファイルを自動的に読み込みません。

これらおよび他の認証エラーの原因と修正については、エラーリファレンスの 認証エラー を参照してください。

他のプロンプトを試す

エージェントがセットアップされたので、いくつかの異なるプロンプトを試してください：

  • "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 完全な自動化

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

次のステップ

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

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