Claude Managed Agents開発編 — Agent SDKでSubagentを呼び出し・再開する

本記事は 2026-04-10 時点で公開されている公式Agent SDKドキュメントを参照しています。

何が“開発編”の難所か

UIでsubagentを使うだけなら簡単ですが、SDK実装では次の3点で躓きます。

Task toolを許可し忘れてsubagentが起動しない
どのsubagentが実際に起動したか追跡できない
resume時にsession_id/agent_idの扱いが曖昧になる

公式サンプルを土台に、状態管理を明示した実装にすると安定します。

最小サンプル（TypeScript）

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

async function run() {
  let sessionId: string | undefined;
  let agentId: string | undefined;

  // 1回目: Explore系subagentで探索
  for await (const message of query({
    prompt: "Use the Explore agent to find all API endpoints in this codebase",
    options: { allowedTools: ["Read", "Grep", "Glob", "Task"] }
  })) {
    if ("session_id" in message) sessionId = message.session_id;

    // 実際にはTask結果メッセージからagentIdを抽出
    const text = JSON.stringify(message);
    const match = text.match(/agent_[a-zA-Z0-9_-]+/);
    if (match) agentId = match[0];
  }

  // 2回目: 同一セッションをresumeして追撃
  if (sessionId && agentId) {
    for await (const message of query({
      prompt: `Resume agent ${agentId} and list top 3 complex endpoints`,
      options: { allowedTools: ["Read", "Grep", "Glob", "Task"], resume: sessionId }
    })) {
      if ("result" in message) {
        console.log(message.result);
      }
    }
  }
}

run();

実装の要点

`Task`が鍵

公式ドキュメントで明示されている通り、subagent委譲にはTask toolが必要です。Read/Grep/Globだけでは呼び出せません。

built-in general-purpose subagent

カスタムsubagent未定義でも、Task許可時はbuilt-inのgeneral-purposeが使われる挙動があります。PoC段階ではまずこれで委譲品質を確認できます。

履歴分離を前提にする

subagent transcriptはメイン会話とは独立して保持されます。つまり、

「主会話が保持する状態」
「subagent会話が保持する状態」

を分けて設計しないと、resume時に意図しない文脈が混ざります。

Managed AgentsとSDKを組み合わせる設計

実務では次の形が安定です。

組織はmanaged-settingsでagent定義を配布
アプリはTask + 必要最小のallowedToolsのみを許可
実行ごとにsession_idを保存
追跡キーとしてagent_idをログ化

こうすると、「どの定義のagentがどのセッションで何をしたか」が監査しやすくなります。

セキュリティとコストの実務ポイント

allowedToolsを広げすぎない（最小権限）
調査系は軽量モデル、実装系は高性能モデルへ分離
長時間セッションはmaxTurnsで暴走を抑制
失敗時にresume再実行できるよう中間IDを永続化

失敗パターン

❌ Taskなしで「subagentが使えない」と誤解
❌ session_id未保存でresume不能
❌ agent_idを取らず、どのagentが応答したか不明
❌ 全agentに同一高権限toolsを付与

まとめ

SDKでManaged Agentsを扱うときは、

Task許可
ID管理（session/agent）
履歴分離を前提にした状態設計

が必須です。ここを固めるだけで、本番運用の安定度が大きく上がります。

参考（公式）

Agent SDK Docs: Subagents
https://docs.anthropic.com/en/docs/claude-code/sdk/subagents
Claude Code Docs: Subagents
https://docs.anthropic.com/en/docs/claude-code/sub-agents

S	公式ソース確認済み
A	成功実績多数・失敗例少数
B	賛否両論
C	動作未確認・セキュリティリスク高
Z	個人所感