Claude Agent SDKでカスタムAIエージェントを構築する実践ガイド

はじめに

Claude Agent SDK（旧Claude Code SDK）は、Claude Codeと同じエージェントループ・ツール・コンテキスト管理をプログラマブルに利用できるSDKです。自社のワークフローに合わせたカスタムAIエージェントを構築でき、Python / TypeScriptの両方で提供されています。本記事では、Agent SDKの概要と実践的な構築方法を解説します。

Agent SDKとは

Agent SDKは、Claude Codeの内部で使われているのと同じ技術基盤を開発者に公開するものです。Claude Code以外のアプリケーション（ディープリサーチ、動画作成、ノート管理など）にも利用されていることから、「Claude Code SDK」から「Claude Agent SDK」に改名されました。

Client SDKとの違い

観点	Client SDK	Agent SDK
ツールループ	自分で実装する必要がある	Claudeが自律的に処理
ツール実行	自分で実装する必要がある	組み込みツール（Read, Write, Bash等）が即動作
ファイル操作	非対応	ローカルファイルの読み書き・編集が可能
用途	直接API呼び出し	自律型エージェントの構築

インストール

TypeScript

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

Python

pip install claude-agent-sdk

Claude Code CLIが自動バンドルされるため、別途インストールする必要はありません。

基本的な使い方（TypeScript）

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

async function main() {
  // エージェントにタスクを依頼
  const messages = query({
    prompt: "src/lib/auth.ts のバグを見つけて修正してください",
    options: {
      allowedTools: ["Read", "Edit", "Bash"],
      model: "claude-sonnet-4-5-20250929",
    } as ClaudeAgentOptions
  });

  // ストリーミングでメッセージを受信
  for await (const message of messages) {
    if (message.type === "assistant") {
      console.log(message.content);
    }
  }
}

main();

基本的な使い方（Python）

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="auth.pyのバグを見つけて修正してください",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash"]
        )
    ):
        print(message)

asyncio.run(main())

組み込みツール一覧

ツール	機能
Read	ファイルの読み取り（PDF、画像対応）
Write	新規ファイルの作成
Edit	既存ファイルの精密な編集
Bash	ターミナルコマンドの実行
Glob	パターンによるファイル検索
Grep	正規表現による内容検索
WebSearch	Web検索
WebFetch	Webページの取得・解析
Task	サブエージェントの起動

実践例: 自動コードレビューエージェント

Pull Requestの差分を分析し、問題点をレポートするエージェントの例です。

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

async function reviewPR(prNumber: number) {
  const messages = query({
    prompt: `GitHub PR #${prNumber} をレビューしてください。
      以下の観点でチェックしてください:
      1. セキュリティ脆弱性
      2. パフォーマンス問題
      3. コーディング規約違反
      結果をMarkdown形式でreview-report.mdに出力してください。`,
    options: {
      allowedTools: ["Read", "Bash", "Write", "Grep"],
    }
  });

  for await (const msg of messages) {
    // 処理結果をストリーミング
  }
}

Hooks — ライフサイクルの制御

Hooksを使うと、エージェントの動作をきめ細かく制御できます。

フック	タイミング	用途
PreToolUse	ツール実行前	操作のバリデーション・ブロック
PostToolUse	ツール実行後	ログ記録・後処理
Stop	エージェント停止時	リソース解放・レポート生成
SessionStart	セッション開始時	初期化処理

認証方式

Agent SDKは以下の認証方式に対応しています。

Anthropic API: 環境変数ANTHROPIC_API_KEYを設定
Amazon Bedrock: CLAUDE_CODE_USE_BEDROCK=1
Google Vertex AI: CLAUDE_CODE_USE_VERTEX=1
Azure Foundry: CLAUDE_CODE_USE_FOUNDRY=1

MCP連携

Model Context Protocol（MCP）を通じて、外部サービスとの接続も可能です。データベース、ブラウザ、外部API等をMCPサーバーとして構築し、エージェントのツールとして利用できます。

まとめ

Claude Agent SDKにより、Claude Codeの強力なエージェント機能を自社のワークフローに組み込むことが可能になりました。自動コードレビュー、データ処理パイプライン、カスタムCIツールなど、開発プロセスの様々な場面でAIエージェントを活用できます。Python / TypeScriptの両方で利用でき、既存のインフラに容易に統合できる点も大きなメリットです。