mirror of
https://github.com/anthropics/skills.git
synced 2026-08-02 13:05:28 +08:00
Lance Martin
b29e7cf65e
* Update claude-api skill: Claude Opus 5 - Add Claude Opus 5 (`claude-opus-5`) as the default model across all SDK examples, model tables, pricing, and migration guidance. - Add an Opus 5 migration section covering the API changes that come with it, and move Opus 4.8 into the previous-generation slot. - Drop the Opus 4.7 fast-mode guidance, which no longer applies. - Scope the server-side fallbacks beta header to the current version. * Update claude-api skill: Opus 5 fast-follow corrections - Server-side refusal fallbacks are available on Claude Platform on AWS, not just the Claude API. Correct the availability statements in SKILL.md, the migration guide, and the platform-availability table. - Simplify the effort guidance: start at `high` (the API default) and sweep down, rather than starting at `xhigh` for coding work. - Add a time-to-first-token section with the prompt instruction that reduces pre-answer thinking on latency-sensitive routes. - Replace the two separate thinking-disabled mitigations with the single combined instruction that covers both failure modes.
126 lines
9.4 KiB
Markdown
126 lines
9.4 KiB
Markdown
# Managed Agents — Multiagent Sessions
|
||
|
||
A coordinator agent can delegate to other agents within one session. All agents **share the container and filesystem**; each runs in its own **thread** — a context-isolated event stream with its own conversation history, model, system prompt, tools, MCP servers, and skills (from that agent's own config). Threads are persistent: the coordinator can send a follow-up to a subagent it called earlier and that subagent retains its prior turns.
|
||
|
||
The SDK sets the `managed-agents-2026-04-01` beta header automatically on all `client.beta.{agents,sessions}.*` calls; no additional header is required for multiagent.
|
||
|
||
---
|
||
|
||
## Declare the roster on the coordinator
|
||
|
||
`multiagent` is a **top-level field** on `agents.create()` / `agents.update()` — **not** a `tools[]` entry. `agents` lists 1–20 roster entries. Nothing changes on `sessions.create()` — the roster is resolved from the coordinator's config.
|
||
|
||
```python
|
||
orchestrator = client.beta.agents.create(
|
||
name="Engineering Lead",
|
||
model="claude-opus-5",
|
||
system="You coordinate engineering work. Delegate code review to the reviewer and test writing to the test agent.",
|
||
tools=[{"type": "agent_toolset_20260401"}],
|
||
multiagent={
|
||
"type": "coordinator",
|
||
"agents": [
|
||
reviewer.id, # bare string — latest version
|
||
{"type": "agent", "id": test_writer.id, "version": 4}, # pinned version
|
||
{"type": "self"}, # the coordinator itself
|
||
],
|
||
},
|
||
)
|
||
|
||
session = client.beta.sessions.create(agent=orchestrator.id, environment_id=env.id)
|
||
```
|
||
|
||
| Roster entry | Shape | Notes |
|
||
|---|---|---|
|
||
| String shorthand | `"agent_abc123"` | References the latest version of a stored agent. |
|
||
| Agent reference | `{type: "agent", id, version?}` | Omit `version` to pin the latest at coordinator save time. |
|
||
| Self | `{type: "self"}` | The coordinator can spawn copies of itself. |
|
||
|
||
If the session was created with `agent_with_overrides` (see `shared/managed-agents-core.md` → Override agent configuration for a session), those overrides apply to the **coordinator and its `self` copies**. Roster agents referenced by ID always use their own as-created configuration — overrides do not propagate to them.
|
||
|
||
Up to **20 unique agents** in the roster; the coordinator may spawn **multiple copies** of each. **One level of delegation only** — and it is enforced rather than silently flattened: rostering an agent that itself carries a `multiagent.agents` roster fails the create or update with a validation error.
|
||
|
||
---
|
||
|
||
## Threads
|
||
|
||
The session-level event stream is the **primary thread** — it shows the coordinator's trace plus a condensed view of subagent activity (thread status transitions and cross-thread messages, not every subagent tool call). Drill into a specific subagent via the per-thread endpoints:
|
||
|
||
| Operation | HTTP | SDK (`client.beta.sessions.threads.*`) |
|
||
|---|---|---|
|
||
| List threads | `GET /v1/sessions/{sid}/threads` | `.list(session_id)` |
|
||
| Retrieve one | `GET /v1/sessions/{sid}/threads/{tid}` | `.retrieve(thread_id, session_id=...)` |
|
||
| Archive | `POST /v1/sessions/{sid}/threads/{tid}/archive` | `.archive(thread_id, session_id=...)` |
|
||
| List thread events | `GET /v1/sessions/{sid}/threads/{tid}/events` | `.events.list(thread_id, session_id=...)` |
|
||
| Stream thread events | `GET /v1/sessions/{sid}/threads/{tid}/stream` | `.events.stream(thread_id, session_id=...)` |
|
||
|
||
Each `SessionThread` carries `id`, `status` (`running` | `idle` | `rescheduling` | `terminated`), `agent` (a resolved snapshot of the agent config — `id`, `name`, `model`, `system`, `tools`, `skills`, `mcp_servers`, `version`), `parent_thread_id` (null for the primary thread, which is included in the list), `archived_at`, and optional `stats`/`usage`. **Session status aggregates thread statuses** — if any thread is `running`, `session.status` is `running`. Max **25 concurrent threads**. When draining a per-thread stream, break on `session.thread_status_idle` (and check its `stop_reason` as you would for the session-level idle).
|
||
|
||
---
|
||
|
||
## Multiagent events (on the session stream)
|
||
|
||
| Event | Payload highlights | Meaning |
|
||
|---|---|---|
|
||
| `session.thread_created` | `session_thread_id`, `agent_name` | A new thread was created. |
|
||
| `session.thread_status_running` | `session_thread_id`, `agent_name` | Thread started activity. |
|
||
| `session.thread_status_idle` | `session_thread_id`, `agent_name`, **`stop_reason`** | Thread is awaiting input. Inspect `stop_reason` (same shape as `session.status_idle.stop_reason`). |
|
||
| `session.thread_status_rescheduled` | `session_thread_id`, `agent_name` | Thread is rescheduling after a retryable error. |
|
||
| `session.thread_status_terminated` | `session_thread_id`, `agent_name` | Thread was archived or hit a terminal error. |
|
||
| `agent.thread_message_sent` | `to_session_thread_id`, `to_agent_name`, `content` | *This* thread sent a message to another thread. On the primary stream: the coordinator sent a task or follow-up to an agent. |
|
||
| `agent.thread_message_received` | `from_session_thread_id`, `from_agent_name`, `content` | A message arrived on *this* thread from another. On the primary stream: an agent sent a report or question to the coordinator. |
|
||
|
||
> **Direction is relative to the thread whose stream carries the event**, not to the coordinator. The same delegated task is an `agent.thread_message_sent` on the primary stream and an `agent.thread_message_received` on the child's own stream. Reading `_received` as "a subagent finished" is wrong once you're reading a child stream.
|
||
|
||
---
|
||
|
||
## Previewing a subagent's text
|
||
|
||
Each thread's stream accepts the same `event_deltas[]` parameter as the session-level stream, so you can watch a subagent's text as the model generates it:
|
||
|
||
```
|
||
GET /v1/sessions/{sid}/threads/{tid}/stream?event_deltas%5B%5D=agent.message
|
||
```
|
||
|
||
**Previews are thread-scoped.** A child's previews are delivered only on that child's stream and never cross-posted to the session-level stream, whose previews stay scoped to the primary thread. So watching a subagent live means opening its thread stream — the session stream will not show it, no matter what you pass.
|
||
|
||
> ⚠️ **Only plain assistant text previews.** A subagent's *reply to its coordinator* rides `agent.thread_message_sent` and is never previewed. A worker that does nothing but report back therefore streams no deltas at all, even with a correct opt-in on the right thread. To get a live preview out of a subagent, its prompt has to make it write the answer as a plain assistant message in its own thread first, and only then report to the coordinator. Run one accumulator per connection, and exit the read loop on `session.thread_status_idle`. Opt-in, accumulate, and reconcile details: `shared/managed-agents-events.md` → Live previews.
|
||
|
||
---
|
||
|
||
## Tool permissions and custom tools from subagent threads
|
||
|
||
When a subagent needs your client (an `always_ask` confirmation, or a custom tool result), the request is **cross-posted to the primary thread** with `session_thread_id` identifying the originating thread — so you only need to watch the session stream. Reply with `user.tool_confirmation` (carrying `tool_use_id`) or `user.custom_tool_result` (carrying `custom_tool_use_id`), and **echo the `session_thread_id` from the originating event** (the SDK param type and docstring expect it). The server also routes by the tool-use ID, so the echo is belt-and-suspenders rather than load-bearing — but include it.
|
||
|
||
```python
|
||
for event_id in stop.event_ids:
|
||
pending = events_by_id[event_id]
|
||
confirmation = {
|
||
"type": "user.tool_confirmation",
|
||
"tool_use_id": event_id,
|
||
"result": "allow",
|
||
}
|
||
if pending.session_thread_id is not None:
|
||
confirmation["session_thread_id"] = pending.session_thread_id
|
||
client.beta.sessions.events.send(session.id, events=[confirmation])
|
||
```
|
||
|
||
The same pattern applies to `user.custom_tool_result`.
|
||
|
||
---
|
||
|
||
## Interrupting and archiving threads
|
||
|
||
- **`user.interrupt` without `session_thread_id` interrupts every non-archived thread in the session, including the primary** — it is not a primary-only stop. Pass `session_thread_id` to target one thread.
|
||
- **Against a child thread blocked on `requires_action`**, the interrupt closes each pending tool call with an *error* tool result (`"Tool execution was interrupted before completion. Please retry."`) and re-emits `session.thread_status_idle` with `stop_reason: end_turn` directly — the model is not sampled. Against a thread already `idle`, the interrupt is a no-op.
|
||
- **Archive requires the thread to be idle, and `requires_action` counts as idle** — a thread parked on a pending tool call can be archived directly. Only a *running* thread must be interrupted first.
|
||
|
||
---
|
||
|
||
## Pitfalls
|
||
|
||
- **Don't put the roster on `sessions.create()` or in `tools[]`.** `multiagent` is a top-level agent field; update the coordinator, then start a session that references it.
|
||
- **Don't assume shared context.** Threads share the filesystem but not conversation history or tools. If the coordinator needs a subagent to act on something, it must say so in the delegated message (or write it to disk).
|
||
- **Depth > 1 is a validation error.** Rostering an agent that itself carries a `multiagent.agents` roster fails the create or update — only the session's coordinator delegates.
|
||
|
||
For per-language bindings beyond Python, WebFetch `https://platform.claude.com/docs/en/managed-agents/multi-agent.md` (see `shared/live-sources.md`).
|