Claude Agent SDK で自分専用エージェントを作る — Python と TypeScript 最短ガイド

Claude Code を自分の Python / TypeScript アプリに組み込むなら Claude Agent SDK が答えになる。ただし紛らわしい選択肢が 3 つ隣にある。Tool Runner、Managed Agents、そして API 直叩き。何がどこまで面倒を見てくれるのかを整理したうえで、Agent SDK を最短で動かす手順と本番運用の注意点をまとめる。

まず「誰がハーネスを持ち、誰がデプロイを持つか」

エージェントの作り方は 4 通りあり、混同されやすい。分ける軸は 2 つだけだ。エージェントループとコンテキスト管理（ハーネス）を誰が用意するか、そしてそれを動かすインフラ（デプロイ）を誰が持つか。

| 選択肢 | 自分で書くもの | ハーネス／デプロイ | 使えるツール | |---|---|---|---| | API 直叩き（手動ループ） | `stop_reason` を見るループ本体 | 両方とも自分 | 自分で定義したものだけ | | Tool Runner | ツール関数だけ | ハーネスは SDK、デプロイは自分 | 自分で定義したものだけ | | Claude Agent SDK | プロンプトとオプション | ハーネスは SDK、デプロイは自分 | 組み込みの Read/Write/Edit/Bash 等 + MCP + サブエージェント | | Managed Agents | エージェント設定とツール結果 | **両方とも Anthropic** | ホスト型サンドボックス + Skills/MCP + 自分のツール |

要点はこうだ。API 直叩き・Tool Runner・Agent SDK の 3 つは、いずれもデプロイが自分持ちになる。Anthropic 側がループとサンドボックスの両方を持つのは Managed Agents だけ。

Tool Runner と Agent SDK は別物

名前が似ているので取り違えやすいが、パッケージからして違う。

Tool Runner は通常の Anthropic API SDK（`anthropic` / `@anthropic-ai/sdk`）の一部で、`client.beta.messages.tool_runner` から使う。「リクエスト → ツール実行 → ループ」を自動化してくれるが、組み込みツールもファイルアクセスもサンドボックスも無い。ツールは全部自分で用意し、計算資源も自分で持つ。

```python from anthropic import Anthropic, beta_tool

client = Anthropic()

@beta_tool def get_weather(location: str) -> str: """指定した地点の現在の天気を返す。""" return f"{location} は晴れ、22 度"

runner = client.beta.messages.tool_runner( model="claude-opus-5", max_tokens=4096, tools=[get_weather], messages=[{"role": "user", "content": "東京の天気は？"}], ) final = runner.until_done() ```

一方 Claude Agent SDK は Claude Code をライブラリにしたもので、組み込みツール一式、エージェントループ、コンテキスト管理、フック、サブエージェント、権限、セッションが最初から入っている。`query(prompt, options)` を呼べば全部が動く。

「ツールを自分で全部定義するが、ループは書きたくない」なら Tool Runner。「ファイルを読んでコードを直すエージェントが欲しい」なら Agent SDK。この線引きで大体決まる。

Agent SDK の最短セットアップ

SDK が提供されるのは Python と TypeScript のみ。他の言語から同じループを回したいときは、CLI を `-p` と `--output-format json` でサブプロセスとして起動する。

Python

pip install claude-agent-sdk
export ANTHROPIC_API_KEY=sk-ant-...

```python import asyncio from claude_agent_sdk import query, ClaudeAgentOptions

async def main(): async for message in query( prompt="Find and fix the bug in auth.py", options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]), ): print(message)

asyncio.run(main()) ```

TypeScript

npm install @anthropic-ai/claude-agent-sdk

```typescript import { query } from "@anthropic-ai/claude-agent-sdk"

for await (const message of query({ prompt: "Find and fix the bug in auth.ts", options: { allowedTools: ["Read", "Edit", "Bash"] } })) { console.log(message) } ```

プロジェクトの `.claude/` と `~/.claude/` からスキル・コマンド・メモリが自動で読み込まれる。Claude Code で整備した資産がそのまま効く。

Managed Agents に渡すべき場合

サンドボックスやセッション基盤を自分で持ちたくない、長時間・非同期で走らせたい、という要件なら Managed Agents が向く。REST API のホスト型で、Anthropic がエージェントとサンドボックスの両方を運用する。