anymous 1.3.0 → 1.3.2

package/skills/claude-api/shared/managed-agents-client-patterns.md

@@ -1,217 +0,0 @@
-# Managed Agents — Common Client Patterns
-
-Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples.
-
-Code samples are TypeScript — other languages follow the same shape; see `{lang}/managed-agents/README.md` (cURL and C#: `curl/managed-agents.md`) for equivalents.
-
----
-
-## 1. Lossless stream reconnect
-
-**Problem:** SSE has no replay. If the connection drops mid-session, a naive reconnect re-opens the stream from "now" and you silently miss every event emitted in between.
-
-**Solution:** on reconnect, fetch the full event history via `events.list()` *before* consuming the live stream, and dedupe on event ID as the live stream catches up.
-
-```ts
-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() — terminal checks must run
-// even for already-seen events, or a terminal event that was in the history
-// response gets skipped by `continue` and the loop never exits.
-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
-}
-```
-
----
-
-## 2. `processed_at` — queued vs processed
-
-Every event on the stream carries `processed_at` (ISO 8601), set when the event finishes processing. For client-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`) it's `null` while the event is queued behind earlier ones, and populated once the agent processes it — so the same event appears on the stream twice, once with `null` and once with a timestamp.
-
-**Three event types skip the queued phase:** `user.define_outcome`, `user.custom_tool_result`, and `user.tool_result` are processed on receipt and echoed back with `processed_at` already populated. A pending → acknowledged UI that assumes "first sighting is always `null`" will never clear for these — treat a populated `processed_at` on first sighting as immediately acknowledged.
-
-```ts
-for await (const event of stream) {
-  if (event.type === 'user.message') {
-    if (event.processed_at == null) onQueued(event.id)
-    else onProcessed(event.id, event.processed_at)
-  }
-}
-```
-
-Use this to drive pending → acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned `event.id` is application-specific (typically via the return value of `events.send()` or FIFO ordering).
-
----
-
-## 3. Interrupt a running session
-
-Send `user.interrupt` as a normal event. The session keeps running until it reaches a safe boundary, then goes idle.
-
-```ts
-await client.beta.sessions.events.send(session.id, {
-  events: [{ type: 'user.interrupt' }],
-})
-
-// Drain until the session is truly done — see Pattern 5 for the full gate.
-for await (const event of stream) {
-  if (event.type === 'session.status_terminated') break
-  if (
-    event.type === 'session.status_idle' &&
-    event.stop_reason.type !== 'requires_action'
-  ) break
-}
-```
-
-Reference: `interrupt.ts` — sends the interrupt the moment it sees `span.model_request_start`, drains to idle, then verifies via `sessions.retrieve()`.
-
----
-
-## 4. `tool_confirmation` round-trip
-
-When the agent has `permission_policy: { type: 'always_ask' }`, any call to that tool fires an `agent.tool_use` event with `evaluated_permission === 'ask'` and the session goes idle waiting for a decision. Respond with `user.tool_confirmation`.
-
-```ts
-for await (const event of stream) {
-  if (event.type === 'agent.tool_use' && event.evaluated_permission === 'ask') {
-    await client.beta.sessions.events.send(session.id, {
-      events: [{
-        type: 'user.tool_confirmation',
-        tool_use_id: event.id,         // not a toolu_ id — use event.id
-        result: 'allow',               // or 'deny'
-        // deny_message: '...',        // optional, only with result: 'deny'
-      }],
-    })
-  }
-}
-```
-
-Key points:
-- `tool_use_id` is `event.id` (typically `sevt_...`), **not** a `toolu_...` ID.
-- `result` is `'allow' | 'deny'`. Use `deny_message` to tell the model *why* you denied — it gets surfaced back to the agent.
-- Multiple pending tools: respond once per `agent.tool_use` event with `evaluated_permission === 'ask'`.
-
-Reference: `tool-permissions.ts`.
-
----
-
-## 5. Correct idle-break gate
-
-Do not break on `session.status_idle` alone. The session goes idle transiently — e.g. between parallel tool executions, while waiting for a `user.tool_confirmation`, or while awaiting a `user.custom_tool_result`. Break when idle with a terminal `stop_reason`, or on `session.status_terminated`.
-
-```ts
-for await (const event of stream) {
-  handle(event)
-  if (event.type === 'session.status_terminated') break
-  if (event.type === 'session.status_idle') {
-    if (event.stop_reason.type === 'requires_action') continue // waiting on you — handle it
-    break // end_turn or retries_exhausted — both terminal
-  }
-}
-```
-
-`stop_reason.type` values on `session.status_idle`:
-- `requires_action` — agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break.
-- `retries_exhausted` — terminal failure. Break, then check `sessions.retrieve()` for the error state.
-- `end_turn` — normal completion.
-
----
-
-## 6. Post-idle status-write race
-
-The SSE stream emits `session.status_idle` slightly before the session's queryable status reflects it. Clients that break on idle and immediately call `sessions.delete()` or `sessions.archive()` will intermittently 400 with "cannot delete/archive while running."
-
-Poll before cleanup:
-
-```ts
-let s
-for (let i = 0; i < 10; i++) {
-  s = await client.beta.sessions.retrieve(session.id)
-  if (s.status !== 'running') break
-  await new Promise(r => setTimeout(r, 200))
-}
-if (s?.status !== 'running') {
-  await client.beta.sessions.archive(session.id)
-} // else: still running after 2s — don't archive, let it settle or escalate
-```
-
----
-
-## 7. Stream-first, then send
-
-Always open the stream **before** sending the kickoff event. Otherwise the agent may process the event and emit the first events before your consumer is attached, and you'll miss them.
-
-```ts
-const stream = await client.beta.sessions.events.stream(session.id)
-await client.beta.sessions.events.send(session.id, {
-  events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }],
-})
-for await (const event of stream) { /* ... */ }
-```
-
-The `Promise.all([stream, send])` shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened.
-
----
-
-## 8. File-mount gotchas
-
-**The mounted resource has a different `file_id` than the file you uploaded.** Session creation makes a session-scoped copy.
-
-```ts
-const uploaded = await client.beta.files.upload({ file })
-// uploaded.id         → the original file
-const session = await client.beta.sessions.create({
-  /* ... */
-  resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/workspace/data.csv' }],
-})
-// session.resources[0].file_id !== uploaded.id  ← different IDs
-```
-
-Delete the original via `files.delete(uploaded.id)`; the session-scoped copy is garbage-collected with the session. `mount_path` must be absolute — see `shared/managed-agents-environments.md`.
-
----
-
-## 9. Secrets for non-MCP APIs and CLIs — keep them host-side via custom tools
-
-**Problem:** you want the agent to call a third-party API or run a CLI that needs a secret (API key, token, service-account credential), but you can't or don't want to hand the secret to a vault.
-
-**First check:** for cloud environments, the first-class answer is now a vault `environment_variable` credential — the agent's shell sees an opaque placeholder and the real secret is substituted at egress. See `shared/managed-agents-tools.md` → Vaults. Use this pattern instead when that doesn't fit: **self-hosted sandboxes** (env-var credentials not yet supported there), clients that reject the placeholder via local format validation, secrets that must never leave your infrastructure, or calls that need host-side binaries.
-
-**Solution:** move the authenticated call to your side. Declare a custom tool on the agent; when the agent emits `agent.custom_tool_use`, your orchestrator (the process reading the SSE stream) executes the call with its own credentials and responds with `user.custom_tool_result`. The container never sees the key.
-
-```ts
-// Agent template: declare the tool, no credentials
-tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }]
-
-// Orchestrator: handle the call with host-side creds
-for await (const event of stream) {
-  if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') {
-    const result = await linear.request(event.input.query, event.input.vars) // host's key
-    await client.beta.sessions.events.send(session.id, {
-      events: [{
-        type: 'user.custom_tool_result',
-        custom_tool_use_id: event.id,
-        content: [{ type: 'text', text: JSON.stringify(result) }],
-      }],
-    })
-  }
-}
-```
-
-Same shape works for `gh` CLI, local eval scripts, or anything else that needs host-side auth or binaries.
-
-**Security note:** this does not expose a public endpoint. `agent.custom_tool_use` arrives on the SSE stream your orchestrator already holds open with your Anthropic API key, and `user.custom_tool_result` goes back via `events.send()` under the same key. Your orchestrator is a client, not a server — nothing unauthenticated is listening.
-
-**Do not embed API keys in the system prompt or user messages as a workaround.** Prompts and messages are stored in the session's event history, returned by `events.list()`, and included in compaction summaries — a secret placed there is durably persisted and readable via the API for the life of the session.

package/skills/claude-api/shared/managed-agents-core.md

@@ -1,319 +0,0 @@
-# Managed Agents — Core Concepts
-
-## Architecture
-
-Managed Agents is built around four core concepts:
-
-| Concept | Endpoint | What it is |
-|---|---|---|
-| **Agent** | `/v1/agents` | A persisted, versioned object defining the agent's capabilities and persona: model, system prompt, tools, MCP servers, skills. **Must be created before starting a session.** See the Agents section below. |
-| **Session** | `/v1/sessions` | A stateful interaction with an agent. References a pre-created agent by ID + an environment + initial instructions. Produces an event stream. |
-| **Environment** | `/v1/environments` | A template defining the configuration for container provisioning. |
-| **Container** | N/A | An isolated compute instance where the agent's **tools** execute (bash, file ops, code). The agent loop does not run here — it runs on Anthropic's orchestration layer and acts on the container via tool calls. |
-
-```
-                       ┌─────────────────────────────────────┐
-                       │  Anthropic orchestration layer      │
-Agent (config) ───────▶│  (agent loop: Claude + tool calls)  │
-                       └──────────────┬──────────────────────┘
-                                      │ tool calls
-                                      ▼
-Environment (template) ──▶ Container (tool execution workspace)
-                                 │
-                         Session ─┤
-                                 ├── Resources (files, repos, memory stores — attached at startup)
-                                 ├── Vault IDs (MCP credential references)
-                                 └── Conversation (event stream in/out)
-```
-
-> **Agent creation is a prerequisite.** Sessions reference a pre-created agent by ID — `model`/`system`/`tools` live on the agent object, never on the session. Every flow starts with `POST /v1/agents`.
-
----
-
-## Session Lifecycle
-
-```
-rescheduling → running ↔ idle → terminated
-```
-
-| Status         | Description                                                        |
-| -------------- | ------------------------------------------------------------------ |
-| `idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. |
-| `running` | Session has starting running, and the Agent is actively doing work. |
-| `rescheduling` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
-| `terminated` | Session has ended and is in an irreversible, unusable state — **either on completion or because of an unrecoverable error**. Terminated does not by itself mean failure; fetch the session to tell the two apart. |
-
-- Events can be sent when the session is `running` or `idle`. Messages are queued and processed in order.
-- The agent transitions `idle → running` when it receives a new event, then back to `idle` when done.
-- Errors surface as `session.error` events in the stream, not as a status value.
-
-Every session has a live trace view in the Anthropic Console at `https://platform.claude.com/workspaces/{workspace}/sessions/{session_id}`. Print this URL immediately after creating a session so the user can watch tool calls and messages stream in real time. **`{workspace}` is the workspace the API key belongs to** — use `default` only when that's the org's Default workspace. The session response does **not** include a workspace field and the Console has no workspace-agnostic session route, so for non-default workspaces substitute the workspace's ID (visible in the Console URL bar, or expose it as a config value alongside the API key). A `default` link to a session that lives in another workspace lands on a **"Session not found"** page — the **Search workspaces** button there will locate it, but it is not an automatic redirect.
-
-### Built-in session features
-
-- **Context compaction** — if you approach max context, the API automatically condenses session history to keep the interaction going
-- **Prompt caching** — historical repeated tokens are cached, reducing processing time and cost
-- **Extended thinking** — on by default; `agent.thinking` events signal thinking progress and carry no thinking content
-
-### Session operations
-
-| Operation | Notes |
-|---|---|
-| List / fetch | Paginated list or single resource by ID |
-| Update | Only `title` is updatable |
-| Archive | Session becomes **read-only**. Not reversible. |
-| Delete | Permanently deletes session, event history, container, and checkpoints. |
-
-These are ops/inspection calls — typically made from a terminal, not application code. From the shell (see `shared/anthropic-cli.md`):
-
-```sh
-ant beta:sessions list --transform '{id,title,status,created_at}' --format jsonl
-ant beta:sessions retrieve --session-id "$SID"
-ant beta:sessions:events stream --session-id "$SID"   # watch events live
-ant beta:sessions archive  --session-id "$SID"
-ant beta:sessions delete   --session-id "$SID"
-```
-
----
-
-## Sessions
-
-A session is a running agent instance inside an environment.
-
-### Session Object
-
-Key fields returned by the API:
-
-| Field           | Type     | Description                                         |
-| --------------- | -------- | --------------------------------------------------- |
-| `type` | string | Always `"session"` |
-| `id` | string | Unique session ID |
-| `title` | string | Human-readable title |
-| `status` | string | `idle`, `running`, `rescheduling`, `terminated` |
-| `created_at` | string | ISO 8601 timestamp |
-| `updated_at` | string | ISO 8601 timestamp |
-| `archived_at` | string | ISO 8601 timestamp (nullable) |
-| `environment_id` | string | Environment ID |
-| `agent` | object | Agent configuration |
-| `resources` | array | Attached files, repos, and memory stores |
-| `metadata` | object | User-provided key-value pairs (max 8 keys) |
-| `usage` | object | Token usage statistics |
-
-### Creating a session
-
-**A session is meaningless without an agent.** Sessions reference a pre-created agent by ID. Create the agent first via `agents.create()`, then reference it:
-
-```ts
-// 1. Create the agent (reusable, versioned)
-const agent = await client.beta.agents.create(
-  {
-    name: "Coding Assistant",
-    model: "claude-opus-5",
-    system: "You are a helpful coding agent.",
-    tools: [{ type: "agent_toolset_20260401"}],
-  },
-);
-
-// 2. Start a session that references it
-const session = await client.beta.sessions.create(
-  {
-    agent: agent.id,  // string shorthand → latest version. Or: { type: "agent", id: agent.id, version: agent.version }
-    environment_id: environmentId,
-    title: "Hello World Session",
-  },
-);
-```
-
-> 💡 **Watch it live in Console.** While developing, print a link so you can click through to the session UI instead of parsing the event stream: `https://platform.claude.com/workspaces/{workspace}/sessions/{session.id}`. Use `default` for `{workspace}` only when the API key belongs to the org's Default workspace; otherwise substitute the workspace's ID (the session response does not carry it — read it from the Console URL bar or make it a config value). Include this `print`/`console.log` in code you generate for users who are iterating locally.
-
-**Session creation parameters:**
-
-| Field           | Type     | Required | Description                                    |
-| --------------- | -------- | -------- | ---------------------------------------------- |
-| `agent`         | string or object | **Yes** | Three forms: string shorthand `"agent_abc123"` (latest version); pinned `{type: "agent", id, version}`; or `{type: "agent_with_overrides", id, version?, ...}` to override `model`/`system`/`tools`/`mcp_servers`/`skills` for this session only — see § Override agent configuration for a session |
-| `environment_id`| string   | **Yes**  | Environment ID                                 |
-| `title`         | string   | No       | Human-readable name (appears in logs/dashboards) |
-| `resources`     | array    | No       | Files, GitHub repos, or memory stores, attached to the container at startup. Memory stores are session-create-only (not addable via `resources.add()`). |
-| `initial_events`| array    | No       | Events to send at creation, processed in order — collapses create + first send into one call. See § Seeding a session with `initial_events` below. |
-| `vault_ids`     | array    | No       | Vault IDs (`vlt_*`) — MCP credentials with auto-refresh + `environment_variable` secrets substituted at egress. See `shared/managed-agents-tools.md` → Vaults. |
-| `metadata`      | object   | No       | User-provided key-value pairs                  |
-
-#### Seeding a session with `initial_events`
-
-Creating a session without `initial_events` registers the session in `idle` and starts no work; the sandbox is provisioned when the session first needs it. Passing a **non-empty** `initial_events` array starts the agent loop in the same call — the session is **created directly in `running`**, never passing through `idle`. A client that waits for an `idle → running` transition to know work began will wait forever; check `status` on the create response instead.
-
-```python
-session = client.beta.sessions.create(
-    agent=AGENT_ID,
-    environment_id=ENVIRONMENT_ID,
-    initial_events=[
-        {"type": "user.message", "content": [{"type": "text", "text": "Review the auth module."}]},
-    ],
-)
-```
-
-- **Only `user.message` and `user.define_outcome` are accepted**, max **50** events. The tool-result kinds (`user.tool_confirmation`, `user.tool_result`, `user.custom_tool_result`) are rejected because no agent turn exists yet, and `user.interrupt` because there is no turn to stop. Unlike a scheduled deployment's `initial_events`, a session's does **not** accept `system.message`.
-- Each event is validated and persisted before the create response returns, in list order, with a server-assigned ID — exactly as if you had posted it to the send-events endpoint immediately after creation. Per-event content rules are the same as on that endpoint.
-- **The events are not echoed on the create response.** Read them back with `sessions.events.list(session.id)` if you need their server-assigned IDs.
-- **Validation is all-or-nothing:** if any event fails, the whole request is rejected and no session is created. An empty list is equivalent to omitting the field.
-- Rejections: more than one `user.define_outcome` → 400; a `user.define_outcome` without a `rubric` → 400; more than 100 file-sourced `document` content blocks across the whole list → 400; a request body over 32 MB → 413.
-
-An outcome-driven session is therefore a single call — pass one `user.define_outcome` in `initial_events` instead of creating the session and then sending the event (see `shared/managed-agents-outcomes.md`).
-
-**Agent configuration fields** (passed to `agents.create()`, not `sessions.create()`):
-
-| Field         | Type     | Required | Description                                    |
-| ------------- | -------- | -------- | ---------------------------------------------- |
-| `name`        | string   | **Yes**  | Human-readable name (1-256 chars)              |
-| `model`       | string or object | **Yes** | Claude model ID (bare string, or an object taking `id`, `speed`, and `effort`). All Claude 4.5+ models supported. See § Effort on the agent model below. |
-| `system`      | string   | No       | System prompt — defines the agent's behavior (up to 100K chars) |
-| `tools`       | array    | No       | Encompasses three kinds: (1) pre-built Claude Agent tools (`agent_toolset_20260401`), (2) MCP tools (`mcp_toolset`), and (3) custom client-side tools. Max 128. |
-| `mcp_servers` | array    | No       | MCP server connections — standardized third-party capabilities (e.g. GitHub, Asana). Max 20, unique names. See `shared/managed-agents-tools.md` → MCP Servers. |
-| `skills`      | array    | No       | Customized "best-practices" context with progressive disclosure. Max 20. See `shared/managed-agents-tools.md` → Skills. |
-| `description` | string   | No       | Description of the agent (up to 2048 chars)    |
-| `multiagent`  | object   | No       | `{type: "coordinator", agents: [...]}` — roster this agent may delegate to. See `shared/managed-agents-multiagent.md`. |
-| `metadata`    | object   | No       | Arbitrary key-value pairs (max 16, keys ≤64 chars, values ≤512 chars) |
-
----
-
-## Agents
-
-**This is where every Managed Agents flow begins.** The agent object is a persisted, versioned configuration — you create it once, then reference it by ID every time you start a session. No agent → no session.
-
-### Agent Object
-
-The API is **flat** — `model`, `system`, `tools` etc. are top-level fields, not wrapped in an `agent:{}` sub-object.
-
-| Field              | Type     | Required | Description                                        |
-| ------------------ | -------- | -------- | -------------------------------------------------- |
-| `name`             | string   | Yes      | Human-readable name                                |
-| `model`            | string or object | Yes | Claude model ID — bare string, or `{id, speed?, effort?}` |
-| `system`           | string   | No       | System prompt                                      |
-| `tools`            | array    | No       | Agent toolset / MCP toolset / custom tools         |
-| `mcp_servers`      | array    | No       | MCP server connections                             |
-| `skills`           | array    | No       | Skill references (max 20)                          |
-| `description`      | string   | No       | Description of the agent                           |
-| `multiagent`       | object   | No       | Coordinator roster — see `shared/managed-agents-multiagent.md` |
-| `metadata`         | object   | No       | Arbitrary key-value pairs                          |
-
-### Lifecycle: create once, run many, update in place
-
-The agent is a **persistent resource**, not a per-run parameter. The intended pattern:
-
-```
-┌─ setup (once) ─────────┐     ┌─ runtime (every invocation) ─┐
-│ agents.create()        │     │ sessions.create(             │
-│   → store agent_id     │ ──→ │   agent={type:..., id: ID}   │
-│     in config/env/db   │     │ )                            │
-└────────────────────────┘     └──────────────────────────────┘
-```
-
-**Anti-pattern:** calling `agents.create()` at the top of every script run. This accumulates orphaned agent objects, pays create latency on every invocation, and defeats the versioning model. If you see `agents.create()` in a function that's called per-request or per-cron-tick, that's wrong — hoist it to one-time setup and persist the ID.
-
-> **Recommended — define agents and environments as YAML + apply via the `ant` CLI.** The split is **CLI for the control plane, SDK for the data plane**: agents and environments are relatively static resources you manage with `ant` (version-controlled YAML, applied from CI); sessions are dynamic and driven by your application through the SDK. See `shared/anthropic-cli.md` → *Version-controlled Managed Agents resources* for the `ant beta:agents create < agent.yaml` / `update --version N` flow. The SDK `agents.create()` call shown elsewhere in this doc is the in-code equivalent — use it when you need to provision programmatically, but prefer the YAML flow for anything a human maintains.
-
-### Effort on the agent model
-
-Pass `model` as an object to set the effort level: `{"id": "claude-opus-5", "effort": "high"}`. `effort` accepts a level string (`low`, `medium`, `high`, `xhigh`, `max`) or an object such as `{"type": "high"}`. The create/update response echoes it in object form and fills in omitted `model` fields with their defaults.
-
-> ⚠️ **Effort is agent configuration only.** An `effort` set inside a per-session `model` override is **not applied** — the session runs at the agent's effort. To change effort you must update the agent (or point the session at a different agent). This is the one field where the override form silently does nothing rather than erroring.
-
-The same object form carries `speed` for fast mode: `{"id": "claude-opus-5", "speed": "fast"}`.
-
-### Versioning
-
-Each `POST /v1/agents/{id}` (update) creates a new immutable version (numeric timestamp, e.g. `1772585501101368014`). The agent's history is append-only — you can't edit a past version.
-
-**`version` on update is optional.** Supply it for optimistic concurrency, or omit it to apply the update unconditionally:
-
-| `version` | Behavior | Fits |
-|---|---|---|
-| Supplied (must be ≥ 1) | 409 if it doesn't match the agent's current version — **even when the fields you send already equal the stored values**. Re-read and retry. | Interactive callers; the recommended default |
-| Omitted | Applies unconditionally. The most recent update silently replaces any concurrent one, with no error to either caller. | Declarative apply loops — e.g. a CI job syncing checked-in agent definitions, where the loop owns the agent |
-
-**Update semantics.** Omitted fields are preserved. Scalar fields (`model`, `system`, `name`, `description`) are replaced; `system` and `description` can be cleared with `null`, while `model` and `name` cannot. Array fields (`tools`, `mcp_servers`, `skills`) are replaced wholesale — `null` or `[]` clears them. **`effort` is the exception inside a `model` object you supply:** if the model `id` is unchanged, omitting `effort` leaves the stored level alone; if you change the `id`, an omitted `effort` resets to the new model's default.
-
-**Why version:**
-- **Reproducibility** — pin a session to a known-good config: `{type: "agent", id, version: 3}`
-- **Safe iteration** — update the agent without breaking sessions already running on the old version
-- **Rollback** — if a new system prompt regresses, pin new sessions back to the prior version while you debug
-
-**`version` is optional.** Omit it (or use the string shorthand `agent="agent_abc123"`) to get the latest version at session-creation time. Pass it explicitly (`{type: "agent", id, version: N}`) to pin for reproducibility.
-
-**Getting the version to pin:** `agents.create()` and `agents.update()` both return `version` in the response. Store it alongside `agent_id`. To fetch the current latest for an existing agent: `GET /v1/agents/{id}` → `.version`.
-
-**When to update vs create new:** Update (`POST /v1/agents/{id}`) when it's conceptually the same agent with tweaked behavior (better prompt, extra tool). Create a new agent when it's a different persona/purpose. Rule of thumb: if you'd give it the same `name`, update.
-
-### Agent Endpoints
-
-| Operation        | Method   | Path                                  |
-| ---------------- | -------- | ------------------------------------- |
-| Create           | `POST`   | `/v1/agents`                          |
-| List             | `GET`    | `/v1/agents`                          |
-| Get              | `GET`    | `/v1/agents/{id}`                     |
-| Update           | `POST`   | `/v1/agents/{id}`                     |
-| Archive          | `POST`   | `/v1/agents/{id}/archive`             |
-
-> ⚠️ **Archive is permanent.** Archiving makes the agent read-only: existing sessions continue to run, but **new sessions cannot reference it**, and there is no unarchive. Since agents have no `delete`, this is the terminal lifecycle state. Never archive a production agent as routine cleanup — confirm with the user first.
-
-### Using an Agent in a Session
-
-Reference the agent by string ID (latest version) or by object with an explicit version:
-
-```python
-# String shorthand — uses the agent's latest version
-session = client.beta.sessions.create(
-    agent=agent.id,
-    environment_id=environment_id,
-)
-
-# Or pin to a specific version (int)
-session = client.beta.sessions.create(
-    agent={"type": "agent", "id": agent.id, "version": agent.version},
-    environment_id=environment_id,
-)
-```
-
-### Override agent configuration for a session
-
-The third `agent` form, `agent_with_overrides`, replaces parts of the agent's configuration for **a single session** — try a different model or grant an extra tool without versioning the agent. Pass `id` (and optionally `version`; omitted = latest, same default as the other two forms) plus any of `model`, `system`, `tools`, `mcp_servers`, `skills`:
-
-```python
-session = client.beta.sessions.create(
-    agent={
-        "type": "agent_with_overrides",
-        "id": agent.id,
-        "model": "claude-opus-5",   # replace the agent's model for this session
-        "system": None,           # clear the system prompt for this session
-    },
-    environment_id=environment_id,
-)
-```
-
-Each overridable field follows tri-state rules:
-- **Omit** → the session inherits the value from the referenced agent version.
-- **`null` (or `[]` for list fields)** → the session runs with that field cleared. Applies in full to `system` and `skills`. Three exceptions: `model` is never clearable (`model: null` → 400 `agent_model_required`); clearing `tools` returns 400 when the session's effective `skills` is non-empty (skills require the `read` tool); and clearing `mcp_servers` returns 400 when the effective `tools` still contains an `mcp_toolset` referencing one of the agent's servers — override `tools` in the same request to drop those entries, then clear `mcp_servers`.
-- **A value** → replaces the agent's value **in full**. Overrides never merge — a `tools` override must list every tool the session should have. One exception: an `effort` level inside a `model` override is **not applied** (set it on the agent instead — see § Effort on the agent model).
-
-Overrides are session-local: they do **not** modify the agent resource or create a new agent version. The response's `agent` object reflects the post-override configuration, while its `id` and `version` still identify the base agent — so you can trace a session back to its base. In multiagent sessions, overrides apply to the coordinator and its `{type: "self"}` copies; roster agents referenced by ID always use their own as-created configuration (see `shared/managed-agents-multiagent.md`).
-
-### Updating the agent configuration mid-session
-
-`sessions.update()` can change `agent.tools`, `agent.mcp_servers` (including permission policies), and `vault_ids` on an **existing** session. This is a **session-local override** — it does not create a new agent version and does not propagate back to the agent object. The provided arrays are **full replacements**; to append one tool, `GET` the session, modify, and `POST` back. The session must be `idle` — interrupt first if running.
-
-Only `tools` and `mcp_servers` can change after a session is created — to run with a `model`, `system`, or `skills` other than the agent's values, use `agent_with_overrides` at create time (above). The agent's configured `system` field is fixed for the session's lifetime; you can still **append system-level context between turns** by sending a `system.message` event (see `shared/managed-agents-events.md` § Adding system context mid-session).
-
-```python
-client.beta.sessions.update(
-    session.id,
-    agent={
-        "tools": [
-            {"type": "agent_toolset_20260401"},
-            {"type": "mcp_toolset", "mcp_server_name": "linear"},
-        ],
-        "mcp_servers": [{"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}],
-    },
-    vault_ids=["vlt_..."],
-)
-```
-