claude-api スキルに Managed Agents ガイダンスを追加

2026年04月09日 02:01 JST anthropics/skills

https://github.com/anthropics/skills/pull/891

claude-api スキルが大幅に刷新され、旧 Agent SDK ドキュメントが削除されて新しい Managed Agents API の包括的なガイダンスへと置き換えられました。Python・TypeScript・Go・Java・Ruby・PHP・cURL の 7 言語に対応した実装例と、設計パターン・イベントモデル・環境管理などの共有コンセプトファイル群が追加されています。

背景

旧 Agent SDK（claude-agent-sdk / @anthropic-ai/claude-agent-sdk）のドキュメントが削除され、公式 Anthropic SDK（anthropic、@anthropic-ai/sdk 等）を通じてアクセスする Managed Agents API のドキュメントに全面移行しました。旧 SDK は claude_agent_sdk.query() や ClaudeAgentOptions といった独自のインターフェースを持ち、claude-agent-sdk / @anthropic-ai/claude-agent-sdk という別パッケージに依存していました。新 API は既存の各言語向け Anthropic SDK の client.beta.* 名前空間として提供されます。

旧 SDK 向けのドキュメントファイル 4 つが削除の対象です：

python/agent-sdk/README.md（355 行）
python/agent-sdk/patterns.md（359 行）
typescript/agent-sdk/README.md（297 行）
typescript/agent-sdk/patterns.md（209 行）

これらに代わって、7 言語 × 言語別 README と 9 つの共有コンセプトファイルが追加されています。

技術的な変更

Managed Agents の基本アーキテクチャ

Managed Agents は Agent・Session・Environment・Container の 4 要素で構成されます。エージェントループは Anthropic のオーケストレーション層で動作し、ツール（bash、ファイル操作、Web 検索等）はセッションごとにプロビジョニングされるサンドボックスコンテナ上で実行されます。

shared/managed-agents-core.md に記載されたアーキテクチャは以下の通りです：

                       ┌─────────────────────────────────────┐
                       │  Anthropic orchestration layer      │
Agent (config) ───────▶│  (agent loop: Claude + tool calls)  │
                       └──────────────┬──────────────────────┘
                                      │ tool calls
                                      ▼
Environment (template) ──▶ Container (tool execution workspace)
                                 │
                         Session ─┤
                                 ├── Resources
                                 ├── Vault IDs
                                 └── Conversation (event stream in/out)

必須フロー：Agent の事前作成

Managed Agents で最も重要な設計上の制約は、Agent の事前作成が必須である点です。model・system・tools はセッションではなく Agent オブジェクトに定義し、セッションは Agent ID への参照を持つだけです。

変更前（旧 Agent SDK — Python）:

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="Explain this codebase",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"])
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

anyio.run(main)

変更後（Managed Agents — Python）:

import anthropic

client = anthropic.Anthropic()

# Step 1: Create agent ONCE, store the ID
agent = client.beta.agents.create(
    model="claude-opus-4-6",
    name="my-agent",
    # system, tools, etc. live here
)

# Step 2: Create a session per run
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

各言語の SDK メソッド命名は統一されており、Python・TypeScript は client.beta.agents.create / client.beta.sessions.create、Go は client.Beta.Agents.New / client.Beta.Sessions.New という形式になります。

ベータヘッダーと SDK 対応

Managed Agents は anthropic-beta: managed-agents-2026-04-01 ヘッダーが必要ですが、SDK を使用する場合は client.beta.* 配下のメソッドを呼ぶだけで自動付与されます。ファイル操作（files-api-2025-04-14）やスキル（skills-2025-10-02）には別々のベータヘッダーが必要であり、Managed Agents エンドポイントと混在させないよう注意が必要です。

イベントモデルと SSE 再接続

shared/managed-agents-events.md と shared/managed-agents-client-patterns.md には、セッションのイベントストリーム仕様と実装上の注意点が詳述されています。受信イベントはドット記法の型（agent.message・agent.tool_use・session.status_idle・session.status_terminated 等）で区別されます。

SSE 接続断後の ロスレス再接続 パターンが明示されています。ナイーブな実装では接続再開時に中間イベントを消失するため、events.list() で過去イベントを取得してから events.stream() を tail する手順が必要です：

const seenEventIds = new Set<string>()
const stream = await client.beta.sessions.events.stream(session.id)

// Stream is now open and buffering server-side. Read history first.
for await (const event of client.beta.sessions.events.list(session.id)) {
  seenEventIds.add(event.id)
  handle(event)
}

// Tail the live stream. Dedupe only gates handle().
for await (const event of stream) {
  if (!seenEventIds.has(event.id)) {
    seenEventIds.add(event.id)
    handle(event)
  }
  if (event.type === 'session.status_terminated') break
  if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break
}

SKILL.md の更新

SKILL.md にも複数の重要な変更が加えられました。非 Anthropic ファイルの検出ルールが明文化され、import openai や gpt-4 などのマーカーが見つかった場合はユーザーに確認を求めてから編集するよう指示されています。また、Subcommands ディスパッチ機構が追加され、/claude-api managed-agents-onboard のような形式でサブコマンドを呼び出せるようになりました。

プロンプトキャッシュの情報更新

shared/prompt-caching.md に具体的なキャッシュ最小トークン数テーブルが追加されました：

モデル	最小トークン
Opus 4.6, Opus 4.5, Haiku 4.5	4096
Sonnet 4.6, Haiku 3.5, Haiku 3	2048
Sonnet 4.5, Sonnet 4.1, Sonnet 4, Sonnet 3.7	1024

キャッシュ書き込みコストも TTL に応じて詳細化されており、5 分 TTL では 1.25×、1 時間 TTL では 2× という形に更新されています。また、20 ブロックルックバックウィンドウの制約（1 ターンで 20 ブロックを超えるとキャッシュミスが発生する）も新たに文書化されました。

設計判断

Agent と Session の分離は、エージェントのバージョニングを実現するための核心的な設計です。Agent オブジェクトは更新のたびに不変の新バージョンを生成し、実行中のセッションは作成時のバージョンに固定されます。この設計により、エージェントの改善と既存セッションの安定性が両立できます。shared/managed-agents-overview.md では、agents.create() をホットパスで毎回呼ぶことで孤立した Agent オブジェクトが蓄積するアンチパターンを明示的に警告しています。

SDK ファーストの方針も一貫して強調されています。shared/agent-design.md で追加されたツール設計ガイドラインでは、Bash ツールと専用ツールのトレードオフが整理されています。Bash はエージェントに広範な操作能力を与えるが、ハーネス側ではコマンド文字列しか受け取れないため、ゲーティング・監査・並列化が困難になります。セキュリティ境界・変更の可逆性・カスタム UI が必要なアクションは専用ツールに昇格させるという指針が示されています。

言語固有の注意点も各 README に明記されています。たとえば Ruby SDK では Kernel#system と Kernel#send との衝突を避けるために system_: や send_( という末尾アンダースコア形式を使う必要があり、Java SDK では BetaCloudConfigParams.builder() のようなビルダーパターンを用います。こうした言語固有の落とし穴を各 README に集約することで、他言語の SDK から推測して誤った API 呼び出しを生成するリスクを低減しています。

まとめ

本 PR は旧 Agent SDK から Managed Agents API への移行を、スキルドキュメントのレイヤーで完結させた変更です。Agent の事前作成とセッション分離という制約を中心に据え、7 言語の実装例・イベントモデル・再接続パターン・ツール設計指針を体系化することで、スキルを参照する AI が正しい API パターンを生成するための知識基盤が整備されました。