Claude Code Agent SDK：多くの開発者が見落としがちな欠けているケイパビリティ層

Claude Code Agent SDK が提供するのはエージェントループであり、完全なケイパビリティ層ではありません。SDK の仕組み、限界、そして AnyCap がライブ検索・メディア生成・保存・公開をどう補うのかを解説します。

by AnyCap

Claude Code Agent SDK の開発者ワークフロー — 温かみのあるクリーム色の背景にオリーブグリーンのアイコンを配したミニマルなフラット線画ダイアグラム

Claude Code Agent SDK は、プログラム可能なエージェントループを提供します。これは朗報です。

より重要なのは、何を提供しないのかという点です。

この SDK は、実運用の多くのワークフローで必要となる現実世界のケイパビリティ層、つまりライブ検索、画像生成、動画生成、成果物の保存、公開をエージェントに与えてくれるわけではありません。SDK が提供するのはシェルとオーケストレーション層です。より強力なエージェントが必要なら、その背後に動くランタイムが依然として必要です。

この違いが重要なのは、多くの SDK ガイドが「エージェントを起動する方法」で止まってしまうからです。実運用チームが気にするのは次の問いです。そのエージェントは本当に仕事を最後までやり切れるのか。

このガイドでは両方を扱います。Claude Code Agent SDK が得意なこと、そしてファイルを読んで bash を実行する以上のことをエージェントにさせたいとき、AnyCap のようなケイパビリティランタイムがどこに入るのかを説明します。

Claude Code Agent SDK とは？

Claude Code Agent SDK は、Claude Code のようなエージェント動作を自分のアプリケーションに組み込むための Anthropic の Python / TypeScript ツールキットです。

次のように考えると分かりやすいでしょう。

  • Claude モデル = 推論
  • Agent SDK = プログラム可能なエージェントループ
  • ケイパビリティランタイム = メディア、検索、保存、公開のための欠けている実行層

SDK は、本来なら自分で作る必要がある中核のオーケストレーション作業を担います。

  • 計画と反復実行
  • ファイルアクセスと編集
  • シェル実行
  • ツール呼び出し
  • MCP 連携
  • サブエージェントのパターン

これだけでも多くのカスタムなつなぎ込みコードを置き換えられます。ただし、それでもなお実運用スタックの一部にすぎません。

生の Claude API と何が違うのか

機能 Claude API Claude Code Agent SDK
エージェントループ 自分で構築 組み込み
ファイルアクセス なし 含まれる
シェル実行 なし 含まれる
ツールのオーケストレーション 手動 含まれる
MCP サポート 手動 含まれる
サブエージェントのパターン 手動 実装しやすい

コードレビュー用ワーカー、CI 自動化、リポジトリアシスタントを構築するなら、この SDK はループを手作業で実装するより大きな前進です。

ただし境界は理解しておくべきです。ツールインターフェースがあるからといって、自動的に完全なケイパビリティランタイムになるわけではありません。

インストールとセットアップ

前提条件

  • Python 3.10+ または Node.js 20+
  • Anthropic API キー または Claude Code へのアクセス
  • ランタイム面としての Claude Code CLI のインストール

Claude Code CLI をインストール

npm install -g @anthropic-ai/claude-code

Agent SDK をインストール

Python

pip install claude-agent-sdk

TypeScript

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

認証

claude login

最初のエージェント

from claude_agent_sdk import Agent, tool

@tool
def read_file(path: str) -> str:
    with open(path, "r") as f:
        return f.read()

@tool
def list_files(directory: str = ".") -> list:
    import os
    return os.listdir(directory)

agent = Agent(
    system_prompt="You are a careful code reviewer.",
    tools=[read_file, list_files],
    model="claude-sonnet-4-20250514"
)

result = agent.run("Review ./src for security issues")
print(result.output)

ここがこの SDK の強みです。ツールを定義し、タスクを渡せば、探索と反復はエージェントループに任せられます。

コアコンセプト

1. エージェントループ

タスク → 計画 → ツール呼び出し → 観察 → 再計画 → 最終回答

このループこそが SDK の本当の価値です。各ターンを手作業で配線する必要をなくしてくれます。

2. サブエージェント

サブエージェントを使うと、すべてを長い 1 つのコンテキストに詰め込むのではなく、作業を分解できます。

agent = Agent(
    system_prompt="You are a tech lead reviewing a codebase.",
    tools=["task"]
)

並列のディレクトリレビュー、分割した調査、大規模コードベースで活用してください。

3. MCP サポート

SDK は MCP 対応ツールと連携できます。これは社内 API、データベース、特化型サービスで役立ちます。

agent = Agent(
    mcp_servers=[
        {
            "command": "npx",
            "args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
            "env": {"ALLOWED_DIRECTORIES": "/project"}
        }
    ]
)

ただし、多くのガイドが見落とすニュアンスがあります。MCP はプロトコル層であって、ケイパビリティ戦略の全体ではありません。 エージェントにより広い横断的なツール面が必要なら、多くの場合ほしいのは 5 つのバラバラな個別連携ではなく、ケイパビリティランタイムです。

本番運用での考慮点

コスト管理

日常的な作業には低コストモデルを使い、max_turns を設定し、広範な並列作業は肥大化した 1 セッションではなくサブエージェントに振り分けましょう。

コンテキスト管理

プロンプトは簡潔に保ち、不要なファイル読み込みを避け、セッションが長くなったら中間結果を要約しましょう。

権限

エージェントのファイルアクセスと外部連携は、必要最小限の範囲に制限してください。

よくあるエラーと対処法

OverloadedError

指数バックオフで再試行します。

import time
from claude_agent_sdk import OverloadedError

def run_with_retry(agent, prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return agent.run(prompt)
        except OverloadedError:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

ContextLengthExceededError

作業をサブタスクに分け、1 回の巨大な実行ではなくサブエージェントを使いましょう。

MaxTurnsReached

max_turns を増やすのは、タスクの範囲が明確に限定されている場合だけにしてください。そうでなければワークフローを分解しましょう。

権限エラー

エージェントが実際に必要とするディレクトリと連携だけを広げてください。

それでも Agent SDK が提供しないもの

ここが本番ワークフローでもっとも重要な部分です。

Claude Code Agent SDK にできることは次のとおりです。

  • ファイルの読み取りと編集
  • シェルコマンドの実行
  • ツール呼び出しのオーケストレーション
  • 反復的なエージェントループの管理

一方で、単体では 提供されない 欠けているケイパビリティ層は次のとおりです。

  • ライブ Web 検索
  • 画像生成
  • 動画生成
  • クラウドストレージと共有
  • Web 公開

このため、多くのチームはデモでは印象的でも、実務では不完全なエージェントに行き着きます。エージェントはローンチページについて見事に考えられても、追加のインフラがなければヒーロー画像を生成したり、最終成果物を保存したり、納品物を公開したりはできません。

AnyCap が入る場所

ここでの AnyCap は、Claude ベースのエージェントが実行に使えるケイパビリティランタイムとして理解するのが最適です。

レイヤーを分離すると、アーキテクチャはより明快になります。

  • Claude モデル → 考える
  • Claude Code Agent SDK → オーケストレーションする
  • AnyCap CLI → 横断的なケイパビリティを実行する
  • AnyCap スキル → その CLI を効果的に使う方法をエージェントに教える

ケイパビリティランタイムをインストール

curl -fsSL https://anycap.ai/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
anycap login

スキル層を追加

npx -y skills add anycap-ai/anycap -a claude-code

その後、エージェントは次の用途で一貫したケイパビリティ面を使えるようになります。

anycap search "latest competitor pricing"
anycap image generate "product hero image"
anycap video generate "10-second launch teaser"
anycap drive upload ./report.pdf
anycap page publish ./launch-brief.md

これが「エージェントループを作った」と「実際に仕事を完了できるエージェントを作った」の違いです。

Agent SDK を使うべき場面

次のような場合は Agent SDK を使いましょう。

  • プロダクトや自動化の中で動くプログラム可能なエージェントが必要なとき
  • 再現可能なコードレビュー用ワーカーが必要なとき
  • CI/CD 内で動くリポジトリアシスタントが必要なとき
  • 反復型のエージェントループを必要とするバックグラウンドタスクがあるとき

エージェントに調査、メディア生成、ファイル配布、出力公開まで求めるなら、これと併せてケイパビリティランタイムも使いましょう。

まとめ

Claude Code Agent SDK が強力なのは、オーケストレーションの問題を解決してくれるからです。開発者に、Claude Code のループをゼロから作らせる代わりに、そのプログラム可能版を提供してくれます。

しかし、それでもなおシェルと調整の層にすぎません。

エージェントが現実世界とやり取りする必要があるなら、つまり最新情報を検索し、クリエイティブ資産を生成し、出力を保存し、結果を公開する必要があるなら、欠けているケイパビリティ層も必要です。

この考え方が、SDK 単体でできることをチームが過大評価しないための土台になります。

SDK はエージェントをプログラム可能にします。

ケイパビリティランタイムは、エージェントをコード以外でも役立つ存在にします。