Agent SDK

Agent SDK でカスタムエージェントを作る

約 14 分 · クイズ 4 問 · 演習 1 問

重要キーワード (4 語)

Agent SDK (エージェントSDK) — Claude Code のコアを再利用してカスタムエージェントを構築できる SDK

Loop (ループ) — 計画→ツール実行→観察を繰り返す基本構造

Memory (メモリ) — セッションを跨いで保持する状態

Headless (ヘッドレス) — 対話 UI なしで動かすモード

Claude Agent SDK

Agent SDK は、Claude Code の中核 (計画 → ツール → 観察ループ) を 任意のアプリに組み込める SDK。ターミナルだけでなく、Slack ボット・社内ツール・SaaS の中で動くエージェントが作れます。

なぜ Agent SDK?

ゼロから「ループ + ツール選択 + 安全機構」を書くのは大変
Claude Code が長年磨いてきた仕組みを再利用できる
Hooks / Skills / MCP / Subagents もそのまま動く
セッション再開・メモリ・キャッシュ含む

インストール

pip install claude-agent-sdk
# or
npm install @anthropic-ai/claude-agent-sdk

Hello World (Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        system_prompt="あなたはコード解析の専門家です。",
        allowed_tools=["Read", "Glob", "Grep"],
        cwd="/path/to/repo",
    )
    async for msg in query(
        prompt="このリポジトリの依存関係を要約して",
        options=options,
    ):
        print(msg)

asyncio.run(main())

主要オプション

オプション	用途
`system_prompt`	エージェントの役割
`allowed_tools`	利用可能ツール (Read/Edit/Bash...)
`cwd`	作業ディレクトリ
`mcp_servers`	MCP サーバー設定
`hooks`	フック登録
`permission_mode`	default / acceptEdits / plan
`model`	使用モデル
`max_turns`	自律ループの上限

Streaming で受信

async for msg in query(prompt=user_input, options=options):
    if msg.type == "assistant_message":
        print(msg.content[0].text)
    elif msg.type == "tool_use":
        print(f"[Tool] {msg.name}({msg.input})")
    elif msg.type == "result":
        print(f"[Done] {msg.usage}")

Slack ボット例

from slack_bolt import App
from claude_agent_sdk import query, ClaudeAgentOptions

app = App(token=SLACK_TOKEN)

@app.event("app_mention")
async def handle_mention(event, say):
    options = ClaudeAgentOptions(
        system_prompt="あなたは社内ヘルプデスクです。",
        allowed_tools=["WebFetch", "Read"],
    )
    answer = ""
    async for msg in query(prompt=event["text"], options=options):
        if msg.type == "assistant_message":
            answer += msg.content[0].text
    say(answer)

TypeScript 版

import { query, ClaudeAgentOptions } from "@anthropic-ai/claude-agent-sdk";

const options: ClaudeAgentOptions = {
  systemPrompt: "...",
  allowedTools: ["Read", "Glob"],
};
for await (const msg of query({ prompt: "...", options })) {
  console.log(msg);
}

Hooks との組み合わせ

Agent SDK でも .claude/settings.json の hooks が動きます。ファイル編集 → 自動 lint、危険コマンドブロック、ロギング等が SDK から動く。

Headless モード

-p フラグ的なワンショット呼び出し:

result = await query_oneshot(prompt="..." , options=options)

CI ジョブやバッチ処理向け。

Multi-Agent パターン

複数のエージェントを協調させる: - Researcher: 情報収集 - Writer: 草案作成 - Critic: レビュー - Editor: 仕上げ

各エージェントを Claude Agent SDK の query で動かし、結果を別エージェントに渡す。

セキュリティ

ツール許可リストを最小化
実行ディレクトリを sandbox に
出力を検証してから外部に出す
Hooks で危険コマンドをブロック
max_turns で無限ループを防ぐ

Use Case

社内 Slack ボット: 質問対応・タスク管理
CI に組み込むレビュアー: PR を自動分析
データ整形パイプライン: ETL の中で LLM を呼ぶ
カスタマーサポートのエージェント: チケット解決
コード生成サービス: SaaS の機能としてエージェントを提供

Claude Code との関係

Claude Code = Agent SDK + ターミナル UI + 公式 Hooks/Skills
Agent SDK = 同じコアを 任意の文脈に持ち込める ようにしたもの

試す

カスタムエージェントの設計を Claude に。

▶ Agent 設計依頼

「社内 GitHub の PR を毎晩レビューして翌朝の Slack に要約投稿する」エージェントの設計を Agent SDK 想定で書いてください。必要な ClaudeAgentOptions / 主要ロジックの擬似コード / リスクと緩和策を順に。