初始化项目版本
This commit is contained in:
Axhub Make
101
.agents/skills/claude-api/shared/agent-design.md
Normal file
101
.agents/skills/claude-api/shared/agent-design.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# Agent Design Patterns
|
||||
|
||||
This file covers decision heuristics for building agents on the Claude API: which primitives to reach for, how to design your tool surface, and how to manage context and cost over long runs. For per-tool mechanics and code examples, see `tool-use-concepts.md` and the language-specific folders.
|
||||
|
||||
---
|
||||
|
||||
## Model Parameters
|
||||
|
||||
| Parameter | When to use it | What to expect |
|
||||
| --- | --- | --- |
|
||||
| **Adaptive thinking** (`thinking: {type: "adaptive"}`) | When you want Claude to control when and how much to think. | Claude determines thinking depth per request and automatically interleaves thinking between tool calls. No token budget to tune. |
|
||||
| **Effort** (`output_config: {effort: ...}`) | When adjusting the tradeoff between thoroughness and token efficiency. | Lower effort → fewer and more-consolidated tool calls, less preamble, terser confirmations. `medium` is often a favorable balance. Use `max` when correctness matters more than cost. |
|
||||
|
||||
See `SKILL.md` §Thinking & Effort for model support and parameter details.
|
||||
|
||||
---
|
||||
|
||||
## Designing Your Tool Surface
|
||||
|
||||
### Bash vs. dedicated tools
|
||||
|
||||
Claude doesn't know your application's security boundary, approval policy, or UX surface. Claude emits tool calls; your harness handles them. The shape of those tool calls determines what the harness can do.
|
||||
|
||||
A **bash tool** gives Claude broad programmatic leverage — it can perform almost any action. But it gives the harness only an opaque command string, the same shape for every action. Promoting an action to a **dedicated tool** gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit.
|
||||
|
||||
**When to promote an action to a dedicated tool:**
|
||||
|
||||
- **Security boundary.** Actions that require gating are natural candidates. Reversibility is a useful criterion: hard-to-reverse actions (external API calls, sending messages, deleting data) can be gated behind user confirmation. A `send_email` tool is easy to gate; `bash -c "curl -X POST ..."` is not.
|
||||
- **Staleness checks.** A dedicated `edit` tool can reject writes if the file changed since Claude last read it. Bash can't enforce that invariant.
|
||||
- **Rendering.** Some actions benefit from custom UI. Claude Code promotes question-asking to a tool so it can render as a modal, present options, and block the agent loop until answered.
|
||||
- **Scheduling.** Read-only tools like `glob` and `grep` can be marked parallel-safe. When the same actions run through bash, the harness can't tell a parallel-safe `grep` from a parallel-unsafe `git push`, so it must serialize.
|
||||
|
||||
**Rule of thumb:** Start with bash for breadth. Promote to dedicated tools when you need to gate, render, audit, or parallelize the action.
|
||||
|
||||
---
|
||||
|
||||
## Anthropic-Provided Tools
|
||||
|
||||
| Tool | Side | When to use it | What to expect |
|
||||
| --- | --- | --- | --- |
|
||||
| **Bash** | Client | Claude needs to execute shell commands. | Claude emits commands; your harness executes them. Reference implementation provided. |
|
||||
| **Text editor** | Client | Claude needs to read or edit files. | Claude views, creates, and edits files via your implementation. Reference implementation provided. |
|
||||
| **Computer use** | Client or Server | Claude needs to interact with GUIs, web apps, or visual interfaces. | Claude takes screenshots and issues mouse/keyboard commands. Can be self-hosted (you run the environment) or Anthropic-hosted. |
|
||||
| **Code execution** | Server | Claude needs to run code in a sandbox you don't want to manage. | Anthropic-hosted container with built-in file and bash sub-tools. No client-side execution. |
|
||||
| **Web search / fetch** | Server | Claude needs information past its training cutoff (news, current events, recent docs) or the content of a specific URL. | Claude issues a query or URL; Anthropic executes it and returns results with citations. |
|
||||
| **Memory** | Client | Claude needs to save context across sessions. | Claude reads/writes a `/memories` directory. You implement the storage backend. |
|
||||
|
||||
**Client-side** tools are defined by Anthropic (name, schema, Claude's usage pattern) but executed by your harness. Anthropic provides reference implementations. **Server-side** tools run entirely on Anthropic infrastructure — declare them in `tools` and Claude handles the rest.
|
||||
|
||||
---
|
||||
|
||||
## Composing Tool Calls: Programmatic Tool Calling
|
||||
|
||||
With standard tool use, each tool call is a round trip: Claude calls the tool, the result lands in Claude's context, Claude reasons about it, then calls the next tool. Three sequential actions (read profile → look up orders → check inventory) means three round trips. Each adds latency and tokens, and most of the intermediate data is never needed again.
|
||||
|
||||
**Programmatic tool calling (PTC)** lets Claude compose those calls into a script instead. The script runs in the code execution container. When the script calls a tool, the container pauses, the call is executed (client-side or server-side), and the result returns to the running code — not to Claude's context. The script processes it with normal control flow (loops, filters, branches). Only the script's final output returns to Claude.
|
||||
|
||||
| When to use it | What to expect |
|
||||
| --- | --- |
|
||||
| Many sequential tool calls, or large intermediate results you want filtered before they hit the context window. | Claude writes code that invokes tools as functions. Runs in the code execution container. Token cost scales with final output, not intermediate results. |
|
||||
|
||||
---
|
||||
|
||||
## Scaling the Tool and Instruction Set
|
||||
|
||||
| Feature | When to use it | What to expect |
|
||||
| --- | --- | --- |
|
||||
| **Tool search** | Many tools available, but only a few relevant per request. Don't want all schemas in context upfront. | Claude searches the tool set and loads only relevant schemas. Tool definitions are appended, not swapped — preserves cache (see Caching below). |
|
||||
| **Skills** | Task-specific instructions Claude should load only when relevant. | Each skill is a folder with a `SKILL.md`. The skill's description sits in context by default; Claude reads the full file when the task calls for it. |
|
||||
|
||||
Both patterns keep the fixed context small and load detail on demand.
|
||||
|
||||
---
|
||||
|
||||
## Long-Running Agents: Managing Context
|
||||
|
||||
| Pattern | When to use it | What to expect |
|
||||
| --- | --- | --- |
|
||||
| **Context editing** | Context grows stale over many turns (old tool results, completed thinking). | Tool results and thinking blocks are cleared based on configurable thresholds. Keeps the transcript lean without summarizing. |
|
||||
| **Compaction** | Conversation likely to reach or exceed the context window limit. | Earlier context is summarized into a compaction block server-side. See `SKILL.md` §Compaction for the critical `response.content` handling. |
|
||||
| **Memory** | State must persist across sessions (not just within one conversation). | Claude reads/writes files in a memory directory. Survives process restarts. |
|
||||
|
||||
**Choosing between them:** Context editing and compaction operate within a session — editing prunes stale turns, compaction summarizes when you're near the limit. Memory is for cross-session persistence. Many long-running agents use all three.
|
||||
|
||||
---
|
||||
|
||||
## Caching for Agents
|
||||
|
||||
**Read `prompt-caching.md` first.** It covers the prefix-match invariant, breakpoint placement, the silent-invalidator audit, and why changing tools or models mid-session breaks the cache. This section covers only the agent-specific workarounds for those constraints.
|
||||
|
||||
| Constraint (from `prompt-caching.md`) | Agent-specific workaround |
|
||||
| --- | --- |
|
||||
| Editing the system prompt mid-session invalidates the cache. | Append a `{"role": "system", ...}` message to `messages[]` instead (no beta header; on supporting models — see `prompt-caching.md` § Mid-conversation system messages). The cached prefix stays intact, and the model treats it as an operator-authority instruction rather than user text. On models that don't support it, fall back to a `<system-reminder>` text block in the user turn. |
|
||||
| Switching models mid-session invalidates the cache. | Spawn a **subagent** with the cheaper model for the sub-task; keep the main loop on one model. |
|
||||
| Adding/removing tools mid-session invalidates the cache. | Use **tool search** for dynamic discovery — it appends tool schemas rather than swapping them, so the existing prefix is preserved. |
|
||||
|
||||
For multi-turn breakpoint placement, use top-level auto-caching — see `prompt-caching.md` §Placement patterns.
|
||||
|
||||
---
|
||||
|
||||
For live documentation on any of these features, see `live-sources.md`.
|
||||
246
.agents/skills/claude-api/shared/anthropic-cli.md
Normal file
246
.agents/skills/claude-api/shared/anthropic-cli.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# Anthropic CLI (`ant`)
|
||||
|
||||
The `ant` CLI exposes every Claude API resource as a shell subcommand. Compared to `curl`: request bodies are built from typed flags or piped YAML instead of hand-written JSON, `@path` inlines file contents into any string field, `--transform` extracts fields with a GJSON path (no `jq`), list endpoints auto-paginate (cap total results with `--max-items N`; `--limit` only sets the server page size), and the `beta:` prefix auto-sets the right `anthropic-beta` header.
|
||||
|
||||
## When to use the CLI vs the SDK
|
||||
|
||||
**CLI for the control plane, SDK for the data plane.** Agents and environments are relatively static resources you define, configure, and debug with `ant` — check the YAML into your repo, apply from CI, inspect from a terminal. Sessions are dynamic and driven by your application through the SDK — create per task, stream events, react to tool calls, integrate into your product. Both hit the same API; the split is about where the call lives, not what's possible.
|
||||
|
||||
| | Control plane → `ant` | Data plane → SDK |
|
||||
|---|---|---|
|
||||
| Resources | agents, environments, skills, vaults, files | sessions, events |
|
||||
| Cadence | Once per deploy / ad-hoc | Every task / every turn |
|
||||
| Lives in | `*.yaml` in your repo + CI + terminal | Application code |
|
||||
| Typical calls | `create < agent.yaml`, `update --version N`, `list`, `retrieve`, `archive`, `--debug` | `sessions.create()`, `events.stream()`, `events.send()` |
|
||||
|
||||
## Install and auth
|
||||
|
||||
```sh
|
||||
# macOS
|
||||
brew install anthropics/tap/ant
|
||||
xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant"
|
||||
|
||||
# Linux / WSL — pick the release from github.com/anthropics/anthropic-cli/releases
|
||||
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_$(uname -s | tr A-Z a-z)_$(uname -m | sed -e s/x86_64/amd64/ -e s/aarch64/arm64/).tar.gz" \
|
||||
| sudo tar -xz -C /usr/local/bin ant
|
||||
|
||||
# Or from source (Go 1.22+)
|
||||
go install github.com/anthropics/anthropic-cli/cmd/ant@latest
|
||||
```
|
||||
|
||||
**Auth** — the CLI resolves credentials the same way the SDKs do (first match wins): explicit flags, then `ANTHROPIC_API_KEY`, then `ANTHROPIC_AUTH_TOKEN`, then the `ANTHROPIC_PROFILE`-selected or active profile, then Workload Identity Federation env vars, then the default profile on disk. Override the host with `ANTHROPIC_BASE_URL` or `--base-url`.
|
||||
|
||||
- **API key**: set `ANTHROPIC_API_KEY` in the environment.
|
||||
- **OAuth profile** (no static key to manage): `ant auth login` opens a browser, exchanges for a short-lived token, and stores a profile under `$ANTHROPIC_CONFIG_DIR` (default `~/.config/anthropic/` on Linux/macOS, `%APPDATA%\Anthropic` on Windows — `configs/<profile>.json` for settings, `credentials/<profile>.json` for tokens). Subsequent `ant` (and SDK) calls pick it up automatically — a bare `Anthropic()` client works after login, but scripts that read `ANTHROPIC_API_KEY` directly do not. Claude Code and the Claude Agent SDK honor the same profile resolution. `ant auth status` shows which credential source and profile won (it reports status only — don't script against its exit code as a health check); `ant auth logout` clears the active profile (`--all` for every profile). On a remote host without a browser, `ant auth login --no-browser` prints the authorize URL and accepts the code back in the terminal.
|
||||
- **Non-interactive workloads** (CI, servers, containers): interactive login is for development on your own machine — use Workload Identity Federation instead (see the authentication docs via `shared/live-sources.md`).
|
||||
|
||||
> **The #1 auth trap:** profiles are only consulted when no API key is set. A stale exported `ANTHROPIC_API_KEY` silently overrides every profile — requests hit whatever org/workspace that key is scoped to. `ant auth status` shows which source won; unset the key (or per-command: `env -u ANTHROPIC_API_KEY ant …`) before relying on a profile. Truly **unset** it — an empty `ANTHROPIC_API_KEY=""` still wins its precedence slot and authenticates with an empty key. The same shadowing applies in reverse to Claude Code: after `ant auth login`, Claude Code may warn about an auth conflict between the profile and its own `/login` credential — keep one (use the profile and `/logout` in Claude Code, or `ant auth logout` to keep Claude Code's own login).
|
||||
|
||||
**Named profiles** — an interactive-login token is bound to a single org+workspace, and the API only shows resources belonging to that workspace. If an agent, session, or file you created "disappears", the usual cause is a token scoped to a different workspace than the one that created it (`ant auth status` shows the active workspace). Multi-workspace work means one profile per workspace:
|
||||
|
||||
```sh
|
||||
ant auth login --profile <name> # creates the profile if it doesn't exist; org/workspace picker in browser
|
||||
ant auth login --profile <name> --workspace-id wrkspc_01... # bind directly, skip the picker
|
||||
ant profile activate <name> # switch the default profile
|
||||
ant --profile <name> models list # one-off; equivalent: ANTHROPIC_PROFILE=<name> ant models list
|
||||
ant profile list # inspect
|
||||
ant profile set workspace_id wrkspc_01... --profile <name> # edit config keys (workspace_id, base_url, organization_id, …)
|
||||
```
|
||||
|
||||
`ant profile set` edits an existing profile's config — it never creates one, and it does **not** rebind already-issued credentials; run `ant auth login` again under that profile to mint a token for the new target. Pointing `ANTHROPIC_PROFILE` at a profile that doesn't exist is an error, not a fall-through. Refresh tokens eventually hard-expire (they don't slide with use) — when a previously working profile starts failing auth, re-run `ant auth login` before debugging anything else.
|
||||
|
||||
**Scopes** — a profile's OAuth scope set is requested at login (`--scope`) and persists on the profile (`scope` is also a `profile set` config key; like other config edits, changing it requires a fresh `ant auth login` to take effect). Privileged scopes — e.g. `org:admin` for organization-administration endpoints — are **not** in the default scope set: pass the full set you want explicitly (`ant auth login --profile admin --scope "... org:admin"`), and the server grants a privileged scope only if your role actually has it. Because the scope set rides on every token the profile mints, keep privileged work on a dedicated profile (`admin` vs `default`) and do day-to-day inference on the unprivileged one, switching with `--profile`/`ANTHROPIC_PROFILE`. Check `ant auth login --help` for the current scope list, and `ant auth status` to see what the active token carries.
|
||||
|
||||
To hand the active credential to a subprocess or raw-HTTP script:
|
||||
|
||||
```sh
|
||||
# Bare access token — for curl's Authorization header
|
||||
curl https://api.anthropic.com/v1/messages \
|
||||
-H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-H "anthropic-beta: oauth-2025-04-20" \
|
||||
-H "content-type: application/json" \
|
||||
-d '{"model": "claude-opus-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'
|
||||
|
||||
# .env format — sets ANTHROPIC_AUTH_TOKEN (and ANTHROPIC_BASE_URL if the profile has one).
|
||||
# Output is bare KEY=value (no `export`), so use `set -a` to auto-export for child processes:
|
||||
set -a; eval "$(ant auth print-credentials --env)"; set +a
|
||||
python my_script.py # SDK picks up ANTHROPIC_AUTH_TOKEN
|
||||
```
|
||||
|
||||
OAuth tokens go on `Authorization: Bearer` (not `x-api-key:`) **plus the `anthropic-beta: oauth-2025-04-20` header** — converting a raw curl/httpx script from an API key is a header change, not a key swap. The beta header requirement is endpoint-dependent (some endpoints happen to work without it; `/v1/messages` does not) — always send it so requests don't break when you switch endpoints. The token is short-lived and not auto-refreshed when passed via env var, so re-run `print-credentials` before it expires for long-running scripts (`print-credentials` itself refreshes the token if needed). If both `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` are set, the SDKs send both and the API rejects the request — unset `ANTHROPIC_API_KEY` before `eval`ing the `--env` output.
|
||||
|
||||
**Foot-gun:** `ant auth print-credentials` with **no flags** prints the entire credentials JSON, not the bare token — putting that in an `Authorization` header yields an empty response or HTTP/2 protocol error. Always use `--access-token` for headers (it always reads the named/active profile; a set `ANTHROPIC_API_KEY` doesn't override credential printing).
|
||||
|
||||
## Command structure
|
||||
|
||||
```
|
||||
ant <resource>[:<subresource>] <action> [flags]
|
||||
```
|
||||
|
||||
Beta resources (agents, sessions, environments, deployments, skills, vaults, memory stores) live under `beta:` — the CLI auto-sends the right `anthropic-beta` header, so don't pass it yourself unless overriding with `--beta <header>`. For self-hosted environments, `ant beta:worker poll/run` and `ant beta:environments:work stats/stop` drive and monitor the work queue — see `shared/managed-agents-self-hosted-sandboxes.md`.
|
||||
|
||||
```sh
|
||||
ant models list
|
||||
ant messages create --model claude-opus-5 --max-tokens 1024 --message '{role: user, content: "Hello"}'
|
||||
ant beta:agents retrieve --agent-id agent_01...
|
||||
ant beta:sessions:events list --session-id session_01...
|
||||
```
|
||||
|
||||
`ant --help` lists resources; append `--help` to any subcommand for its flags.
|
||||
|
||||
## Global flags
|
||||
|
||||
| Flag | Purpose |
|
||||
| --- | --- |
|
||||
| `--format` | `auto` (default: pretty if TTY, compact if piped), `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore` (interactive TUI) |
|
||||
| `--transform` | GJSON path applied to the response (per-item on list endpoints). Not applied when `--format raw`. |
|
||||
| `-r`, `--raw-output` | If the transformed result is a string, print it without quotes (jq semantics). Pair with `--transform` for scalar capture. |
|
||||
| `--max-items` | Cap total results returned from auto-paginating list endpoints (distinct from `--limit`, which is the server page size). |
|
||||
| `--format-error` / `--transform-error` | Same as `--format`/`--transform`, applied to error responses. `-r` does not apply to the error path — use `--format-error yaml` for unquoted error scalars. |
|
||||
| `--base-url` | Override API host |
|
||||
| `--debug` | Print full HTTP request + response to stderr (API key redacted) |
|
||||
|
||||
## Output — `--transform` + `--format`
|
||||
|
||||
`--transform` takes a [GJSON path](https://github.com/tidwall/gjson/blob/master/SYNTAX.md). On list endpoints it runs **per item**, not on the envelope.
|
||||
|
||||
```sh
|
||||
ant beta:agents list --transform '{id,name,model}' --format jsonl
|
||||
```
|
||||
|
||||
**Extract a scalar for shell use:** pair `--transform` with `-r` (`--raw-output` — prints strings unquoted, jq-style):
|
||||
|
||||
```sh
|
||||
AGENT_ID=$(ant beta:agents create --name "My Agent" --model '{id: claude-sonnet-5}' \
|
||||
--transform id -r)
|
||||
```
|
||||
|
||||
## Input — flags, stdin, `@file`
|
||||
|
||||
**Flags** — scalar fields map directly. Structured fields accept relaxed-YAML syntax (unquoted keys) or strict JSON. Repeatable flags build arrays (each `--tool`, `--event`, `--message` appends one element):
|
||||
|
||||
```sh
|
||||
ant beta:agents create \
|
||||
--name "Research Agent" \
|
||||
--model '{id: claude-opus-5}' \
|
||||
--tool '{type: agent_toolset_20260401}' \
|
||||
--tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'
|
||||
```
|
||||
|
||||
**Stdin** — pipe a full JSON or YAML body. Merged with flags; flags win on conflict (for array fields, any flag **replaces** the stdin array entirely — it does not append). Quote the heredoc delimiter (`<<'YAML'`) to disable shell expansion inside the body:
|
||||
|
||||
```sh
|
||||
ant beta:agents create <<'YAML'
|
||||
name: Research Agent
|
||||
model: claude-opus-5
|
||||
system: |
|
||||
You are a research assistant. Cite sources for every claim.
|
||||
tools:
|
||||
- type: agent_toolset_20260401
|
||||
YAML
|
||||
```
|
||||
|
||||
**`@file` references** — inline a file's contents into any string-valued field. Inside structured flag values, quote the path. Binary files are auto-base64'd; force with `@file://` (text) or `@data://` (base64). Escape a literal leading `@` as `\@`.
|
||||
|
||||
```sh
|
||||
ant beta:agents create --name "Researcher" --model '{id: claude-sonnet-5}' --system @./prompts/researcher.txt
|
||||
|
||||
ant messages create --model claude-opus-5 --max-tokens 1024 \
|
||||
--message '{role: user, content: [
|
||||
{type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
|
||||
{type: text, text: "Extract the text from this scanned document."}
|
||||
]}' \
|
||||
--transform 'content.0.text' -r
|
||||
```
|
||||
|
||||
Flags that natively take a file path (e.g. `--file` on `beta:files upload`) accept a bare path without `@`.
|
||||
|
||||
## Version-controlled Managed Agents resources
|
||||
|
||||
This is the recommended flow for defining agents and environments — check the YAML into your repo and sync via `create` (first time) / `update` (thereafter). See `shared/managed-agents-core.md` for the field reference.
|
||||
|
||||
```yaml
|
||||
# summarizer.agent.yaml
|
||||
name: Summarizer
|
||||
model: claude-sonnet-5
|
||||
system: |
|
||||
You are a helpful assistant that writes concise summaries.
|
||||
tools:
|
||||
- type: agent_toolset_20260401
|
||||
```
|
||||
|
||||
```sh
|
||||
# Create (once) — capture the ID
|
||||
AGENT_ID=$(ant beta:agents create < summarizer.agent.yaml --transform id -r)
|
||||
|
||||
# Update (CI) — needs ID + current version (optimistic lock)
|
||||
ant beta:agents update --agent-id "$AGENT_ID" --version 1 < summarizer.agent.yaml
|
||||
```
|
||||
|
||||
Same pattern for environments (`ant beta:environments create|update < env.yaml`), then start a session with both IDs:
|
||||
|
||||
```sh
|
||||
ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENV_ID" --title "Task"
|
||||
ant beta:sessions:events send --session-id "$SID" \
|
||||
--event '{type: user.message, content: [{type: text, text: "Summarize X"}]}'
|
||||
ant beta:sessions:events list --session-id "$SID" --transform 'content.0.text' -r
|
||||
ant beta:sessions:events stream --session-id "$SID" # live event stream
|
||||
```
|
||||
|
||||
### Interactive session loop (stream-before-send)
|
||||
|
||||
`ant beta:sessions:events stream` only delivers events emitted *after* the stream opens — so open it **before** sending the kickoff to avoid missing early events. Use process substitution to hold the stream on a file descriptor, send, then read:
|
||||
|
||||
```sh
|
||||
exec {stream}< <(ant beta:sessions:events stream --session-id "$SID" \
|
||||
--transform '{type,text:content.#(type=="text").text,err:error.message}' --format yaml)
|
||||
|
||||
ant beta:sessions:events send --session-id "$SID" > /dev/null <<'YAML'
|
||||
events:
|
||||
- type: user.message
|
||||
content:
|
||||
- type: text
|
||||
text: Summarize the repo README
|
||||
YAML
|
||||
|
||||
type=
|
||||
while IFS= read -r -u "$stream" line; do
|
||||
case "$line" in
|
||||
type:\ session.status_idle) break ;;
|
||||
type:\ session.error)
|
||||
IFS= read -r -u "$stream" next || next=
|
||||
case "$next" in err:\ *) msg=${next#err: } ;; *) msg=unknown ;; esac
|
||||
printf '\n[Error: %s]\n' "$msg"; break ;;
|
||||
type:\ *) type=${line#type: } ;;
|
||||
text:*)
|
||||
[[ $type == agent.message ]] || continue
|
||||
val=${line#text: }
|
||||
case "$val" in '|-'|'|') ;; *) printf '%s' "$val" ;; esac ;;
|
||||
\ \ *)
|
||||
if [[ $type == agent.message ]]; then printf '%s\n' "${line# }"; fi ;;
|
||||
esac
|
||||
done
|
||||
exec {stream}<&-
|
||||
```
|
||||
|
||||
This works for interactive exploration and demos. For application code that needs to react to `agent.tool_use` / `agent.custom_tool_use` events, reconnect after drops, or dedup against `events.list`, use the SDK — see `shared/managed-agents-client-patterns.md`.
|
||||
|
||||
## Scripting patterns
|
||||
|
||||
`--transform id -r` on a list endpoint emits one bare ID per line — compose with `xargs`, or use `--max-items N` to bound the result set without piping through `head`:
|
||||
|
||||
```sh
|
||||
FIRST=$(ant beta:agents list --transform id -r --max-items 1)
|
||||
ant beta:agents:versions list --agent-id "$FIRST" --transform '{version,created_at}' --format jsonl
|
||||
```
|
||||
|
||||
Error shaping mirrors the success path (note: `-r` does not apply to error output — use `--format-error yaml` for an unquoted scalar here):
|
||||
|
||||
```sh
|
||||
ant beta:agents retrieve --agent-id bogus --transform-error error.message --format-error yaml 2>&1
|
||||
```
|
||||
|
||||
Shell completion: `ant @completion {zsh|bash|fish|powershell}`.
|
||||
|
||||
For the full, always-current reference (including per-endpoint flags), WebFetch the **Anthropic CLI** URL in `shared/live-sources.md`.
|
||||
59
.agents/skills/claude-api/shared/claude-platform-on-aws.md
Normal file
59
.agents/skills/claude-api/shared/claude-platform-on-aws.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Claude Platform on AWS
|
||||
|
||||
**Anthropic-operated** access to the Claude Developer Platform through AWS infrastructure — SigV4 authentication, AWS IAM access control, and AWS Marketplace billing. Because Anthropic operates it, **the API surface matches first-party with same-day parity** — for per-feature exceptions, see `shared/platform-availability.md` (the single source of truth; do not rely on an inline exception list here). Model IDs are the bare first-party strings (`claude-opus-5`, `claude-sonnet-5`) — **no provider prefix**.
|
||||
|
||||
> **Not the same as Amazon Bedrock.** Bedrock is partner-operated (AWS runs the service; release schedules vary, feature subset, `anthropic.`-prefixed model IDs). Claude Platform on AWS and Bedrock coexist; pick by whether you need AWS-native IAM/billing with full Anthropic API parity (this page) vs. Bedrock's own ecosystem.
|
||||
|
||||
---
|
||||
|
||||
## Client & install
|
||||
|
||||
| Language | Install | Client |
|
||||
|---|---|---|
|
||||
| Python | `pip install -U "anthropic[aws]"` | `from anthropic import AnthropicAWS` → `AnthropicAWS()` |
|
||||
| TypeScript | `npm install @anthropic-ai/aws-sdk` | `import AnthropicAws from "@anthropic-ai/aws-sdk"` → `new AnthropicAws()` |
|
||||
| Go | `go get github.com/anthropics/anthropic-sdk-go` | `import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws"` → `anthropicaws.NewClient(ctx, anthropicaws.ClientConfig{})` |
|
||||
| C# | `dotnet add package Anthropic.Aws` | `new AnthropicAwsClient()` |
|
||||
| Java | See SDK repo in `shared/live-sources.md` | See SDK repo in `shared/live-sources.md` |
|
||||
| Ruby | `gem install anthropic aws-sdk-core` | See SDK repo in `shared/live-sources.md` |
|
||||
| PHP | `composer require anthropic-ai/sdk aws/aws-sdk-php` | See SDK repo in `shared/live-sources.md` |
|
||||
|
||||
After construction, **use the client exactly as you would `Anthropic()`** — `client.messages.create(...)`, `client.beta.sessions.*`, etc., with bare model IDs.
|
||||
|
||||
```python
|
||||
from anthropic import AnthropicAWS
|
||||
|
||||
client = AnthropicAWS() # region + workspace_id from env; see below
|
||||
client.messages.create(
|
||||
model="claude-opus-5",
|
||||
max_tokens=1024,
|
||||
messages=[{"role": "user", "content": "Hello"}],
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Required configuration
|
||||
|
||||
Two values must be available (constructor args or environment) — **there is no default fallback** for either:
|
||||
|
||||
| Value | Env var | Notes |
|
||||
|---|---|---|
|
||||
| AWS region | `AWS_REGION` | Required. Unlike `AnthropicBedrock`, there is no `us-east-1` fallback. |
|
||||
| Workspace ID | `ANTHROPIC_AWS_WORKSPACE_ID` | Required. Routes requests to your Claude workspace. |
|
||||
|
||||
Endpoint pattern: `https://aws-external-anthropic.{region}.api.aws/v1/...`. Requests are SigV4-signed with service name `aws-external-anthropic`.
|
||||
|
||||
## Authentication
|
||||
|
||||
The client resolves AWS credentials via the standard precedence chain: explicit constructor args → environment (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`/`AWS_SESSION_TOKEN`) → shared profile → assumed role / instance metadata.
|
||||
|
||||
**Short-term API keys** are also supported for cases where SigV4 isn't practical (e.g., browser, simple scripts). Mint one with the per-language token-generator package; pass it as `api_key` on the client. Lifetime is the **lesser of** the requested duration, the underlying credential's expiry, and **12 hours**. For package names and IAM details, WebFetch the Claude Platform on AWS page in `shared/live-sources.md`.
|
||||
|
||||
---
|
||||
|
||||
## What to tell users
|
||||
|
||||
- Treat it as first-party: every section of this skill applies unchanged. Do **not** apply Bedrock's feature-availability mask.
|
||||
- Model IDs are bare (`claude-opus-5`). Do **not** add an `anthropic.` prefix.
|
||||
- A missing region or `workspace_id` throws at client-construction time (no request is sent). A **403** means the request reached the server — check for a **wrong** `workspace_id` or a missing IAM action on the principal. See the IAM actions reference in `shared/live-sources.md`.
|
||||
257
.agents/skills/claude-api/shared/error-codes.md
Normal file
257
.agents/skills/claude-api/shared/error-codes.md
Normal file
@@ -0,0 +1,257 @@
|
||||
# HTTP Error Codes Reference
|
||||
|
||||
This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the `python/` or `typescript/` folders.
|
||||
|
||||
## Error Code Summary
|
||||
|
||||
| Code | Error Type | Retryable | Common Cause |
|
||||
| ---- | ----------------------- | --------- | ------------------------------------ |
|
||||
| 400 | `invalid_request_error` | No | Invalid request format or parameters |
|
||||
| 401 | `authentication_error` | No | Invalid or missing API key |
|
||||
| 403 | `permission_error` | No | API key lacks permission |
|
||||
| 404 | `not_found_error` | No | Invalid endpoint or model ID |
|
||||
| 413 | `request_too_large` | No | Request exceeds size limits |
|
||||
| 429 | `rate_limit_error` | Yes | Too many requests |
|
||||
| 500 | `api_error` | Yes | Anthropic service issue |
|
||||
| 529 | `overloaded_error` | Yes | API is temporarily overloaded |
|
||||
|
||||
## Detailed Error Information
|
||||
|
||||
### 400 Bad Request
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Malformed JSON in request body
|
||||
- Missing required parameters (`model`, `max_tokens`, `messages`)
|
||||
- Invalid parameter types (e.g., string where integer expected)
|
||||
- Empty messages array
|
||||
- Messages not alternating user/assistant
|
||||
|
||||
**Example error:**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "error",
|
||||
"error": {
|
||||
"type": "invalid_request_error",
|
||||
"message": "messages: roles must alternate between \"user\" and \"assistant\""
|
||||
},
|
||||
"request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
|
||||
}
|
||||
```
|
||||
|
||||
**Fix:** Validate request structure before sending. Check that:
|
||||
|
||||
- `model` is a valid model ID
|
||||
- `max_tokens` is a positive integer
|
||||
- `messages` array is non-empty and alternates correctly
|
||||
|
||||
---
|
||||
|
||||
### 401 Unauthorized
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Missing `x-api-key` header or `Authorization` header
|
||||
- Invalid API key format
|
||||
- Revoked or deleted API key
|
||||
- OAuth bearer token sent via `x-api-key` instead of `Authorization: Bearer`
|
||||
- Both `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` set — the SDK sends both headers and the API rejects the request
|
||||
|
||||
**Fix:** Set `ANTHROPIC_API_KEY`, or run `ant auth login` and leave the client constructor empty. For raw HTTP with an OAuth token, use `Authorization: Bearer <token>` (not `x-api-key:`).
|
||||
|
||||
---
|
||||
|
||||
### 403 Forbidden
|
||||
|
||||
**Causes:**
|
||||
|
||||
- API key doesn't have access to the requested model
|
||||
- Organization-level restrictions
|
||||
- Attempting to access beta features without beta access
|
||||
|
||||
**Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features.
|
||||
|
||||
---
|
||||
|
||||
### 404 Not Found
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Typo in model ID (e.g., `claude-sonnet-4.6` instead of `claude-sonnet-4-6`)
|
||||
- Using deprecated model ID
|
||||
- Invalid API endpoint
|
||||
|
||||
**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-5`).
|
||||
|
||||
---
|
||||
|
||||
### 413 Request Too Large
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Request body exceeds maximum size
|
||||
- Too many tokens in input
|
||||
- Image data too large
|
||||
|
||||
**Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.
|
||||
|
||||
---
|
||||
|
||||
### 400 Validation Errors
|
||||
|
||||
Some 400 errors are specifically related to parameter validation:
|
||||
|
||||
- `max_tokens` exceeds model's limit
|
||||
- Invalid `temperature` value (must be 0.0-1.0)
|
||||
- `budget_tokens` >= `max_tokens` in extended thinking
|
||||
- Invalid tool definition schema
|
||||
|
||||
**Model-specific 400s on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7:**
|
||||
|
||||
- `temperature`, `top_p`, `top_k` are removed — sending any of them returns 400. Delete the parameter; see `shared/model-migration.md` → Per-SDK Syntax Reference.
|
||||
- `thinking: {type: "enabled", budget_tokens: N}` is removed — sending it returns 400. Use `thinking: {type: "adaptive"}` instead.
|
||||
- **Claude Opus 5:** `thinking: {type: "disabled"}` returns 400 when `effort` is `xhigh` or `max` — it is accepted at `high` or below. Thinking is on by default, so omitting the param runs adaptive rather than disabling it.
|
||||
- **Fable 5 only:** an explicit `thinking: {type: "disabled"}` returns 400 at any effort (it is accepted on Opus 4.8/4.7). Omit the `thinking` param entirely instead.
|
||||
- **Fable 5 only:** if the organization is set to zero data retention (ZDR) — or any retention below the required 30 days — then **all** Fable 5 requests return `400 invalid_request_error`, even with a perfectly valid payload. Check the org's retention configuration before debugging the request body.
|
||||
|
||||
**Common mistake with extended thinking on older models (Opus 4.6 and earlier):**
|
||||
|
||||
```
|
||||
# Wrong: budget_tokens must be < max_tokens
|
||||
thinking: budget_tokens=10000, max_tokens=1000 → Error!
|
||||
|
||||
# Correct
|
||||
thinking: budget_tokens=10000, max_tokens=16000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 429 Rate Limited
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Exceeded requests per minute (RPM)
|
||||
- Exceeded tokens per minute (TPM)
|
||||
- Exceeded tokens per day (TPD)
|
||||
|
||||
**Headers to check:**
|
||||
|
||||
- `retry-after`: Seconds to wait before retrying
|
||||
- `x-ratelimit-limit-*`: Your limits
|
||||
- `x-ratelimit-remaining-*`: Remaining quota
|
||||
|
||||
**Fix:** The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: `max_retries=2`). For custom retry behavior, see the language-specific error handling examples.
|
||||
|
||||
---
|
||||
|
||||
### 500 Internal Server Error
|
||||
|
||||
**Causes:**
|
||||
|
||||
- Temporary Anthropic service issue
|
||||
- Bug in API processing
|
||||
|
||||
**Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com).
|
||||
|
||||
---
|
||||
|
||||
### 529 Overloaded
|
||||
|
||||
**Causes:**
|
||||
|
||||
- High API demand
|
||||
- Service capacity reached
|
||||
|
||||
**Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes and Fixes
|
||||
|
||||
| Mistake | Error | Fix |
|
||||
| ------------------------------- | ---------------- | ------------------------------------------------------- |
|
||||
| `temperature`/`top_p`/`top_k` on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7 | 400 | Remove the parameter (see `shared/model-migration.md`) |
|
||||
| `budget_tokens` on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7 | 400 | Use `thinking: {type: "adaptive"}` |
|
||||
| `thinking: {type: "disabled"}` on Fable 5 | 400 | Omit the `thinking` param entirely (accepted on Opus 4.8/4.7) |
|
||||
| Org set to ZDR / retention below 30 days (Fable 5) | 400 on every request | Fix the org's data-retention configuration — the payload isn't the problem |
|
||||
| `budget_tokens` >= `max_tokens` (older models) | 400 | Ensure `budget_tokens` < `max_tokens` |
|
||||
| Typo in model ID | 404 | Use valid model ID like `claude-opus-5` |
|
||||
| First message is `assistant` | 400 | First message must be `user` |
|
||||
| Consecutive same-role messages | 400 | Alternate `user` and `assistant` |
|
||||
| API key in code | 401 (leaked key) | Use environment variable |
|
||||
| Custom retry needs | 429/5xx | SDK retries automatically; customize with `max_retries` |
|
||||
|
||||
## Typed Exceptions in SDKs
|
||||
|
||||
**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP status code maps to a specific exception class per SDK.
|
||||
|
||||
### Exception class names by language
|
||||
|
||||
| HTTP | Python (`anthropic.*`) / TypeScript (`Anthropic.*`) | Ruby (`Anthropic::Errors::*`) | Java (`com.anthropic.errors.*`) | C# | PHP (`Anthropic\Core\Exceptions\*`) |
|
||||
|---|---|---|---|---|---|
|
||||
| 400 | `BadRequestError` | `BadRequestError` | `BadRequestException` | `AnthropicBadRequestException` | `BadRequestException` |
|
||||
| 401 | `AuthenticationError` | `AuthenticationError` | `UnauthorizedException` | `AnthropicUnauthorizedException` | `AuthenticationException` |
|
||||
| 403 | `PermissionDeniedError` | `PermissionDeniedError` | `PermissionDeniedException` | `AnthropicForbiddenException` | `PermissionDeniedException` |
|
||||
| 404 | `NotFoundError` | `NotFoundError` | `NotFoundException` | `AnthropicNotFoundException` | `NotFoundException` |
|
||||
| 422 | `UnprocessableEntityError` | `UnprocessableEntityError` | `UnprocessableEntityException` | `AnthropicUnprocessableEntityException` | `UnprocessableEntityException` |
|
||||
| 429 | `RateLimitError` | `RateLimitError` | `RateLimitException` | `AnthropicRateLimitException` | `RateLimitException` |
|
||||
| ≥500 | `InternalServerError` | `InternalServerError` | `InternalServerException` | `Anthropic5xxException` | `InternalServerException` |
|
||||
| net | `APIConnectionError` | `APIConnectionError` | `AnthropicIoException` | `AnthropicIOException` | `APIConnectionException` |
|
||||
| base | `APIError` (both); `APIStatusError` (Python only) | `APIStatusError` / `APIError` | `AnthropicServiceException` | `AnthropicApiException` | `APIStatusException` / `APIException` |
|
||||
|
||||
The Ruby and PHP classes live in a dedicated errors namespace — write `Anthropic::Errors::RateLimitError` and `Anthropic\Core\Exceptions\RateLimitException` (not bare `Anthropic::RateLimitError`). All 4xx C# exceptions also inherit from `Anthropic4xxException`.
|
||||
|
||||
### Catch most-specific first, in a chain
|
||||
|
||||
Order `catch`/`except`/`rescue` clauses from the most specific subclass to the base class, with a separate clause for each category you handle differently — retryable (429, ≥500, network) vs. non-retryable (4xx). The SDK defines a distinct class per status for exactly this reason; a single broad catch-all discards that information.
|
||||
|
||||
```python
|
||||
try:
|
||||
msg = client.messages.create(...)
|
||||
except anthropic.NotFoundError as e: # 404 — e.g. bad model ID
|
||||
...
|
||||
except anthropic.RateLimitError as e: # 429 — back off and retry
|
||||
...
|
||||
except anthropic.APIStatusError as e: # any other non-2xx HTTP response
|
||||
print(e.status_code, e.message)
|
||||
except anthropic.APIConnectionError as e: # network failure before a response
|
||||
...
|
||||
```
|
||||
|
||||
The same chain shape applies in every SDK: TypeScript `instanceof Anthropic.NotFoundError` → `RateLimitError` → `APIConnectionError` → `APIError` (check `APIConnectionError` before `APIError` — in the TypeScript SDK it's a subclass of `APIError`, unlike Python where it's a sibling); Ruby `rescue Anthropic::Errors::NotFoundError` → `…::RateLimitError` → `…::APIStatusError`; Java `catch (NotFoundException) … catch (RateLimitException) … catch (AnthropicServiceException)`; C# `catch (AnthropicNotFoundException) … catch (AnthropicRateLimitException) … catch (AnthropicApiException)`; PHP `catch (NotFoundException) … catch (RateLimitException) … catch (APIStatusException)`.
|
||||
|
||||
### Go — `errors.As` then branch on status
|
||||
|
||||
The Go SDK returns a single `*anthropic.Error` for all non-2xx responses. Unwrap it with `errors.As`, then branch on `StatusCode`:
|
||||
|
||||
```go
|
||||
_, err := client.Messages.New(ctx, params)
|
||||
if err != nil {
|
||||
var apierr *anthropic.Error
|
||||
if errors.As(err, &apierr) {
|
||||
switch apierr.StatusCode {
|
||||
case 404:
|
||||
// bad model ID / resource
|
||||
case 429:
|
||||
// back off and retry
|
||||
default:
|
||||
// other API error — apierr.StatusCode, apierr.RequestID
|
||||
}
|
||||
} else {
|
||||
// transport-level error (*url.Error wrapping *net.OpError, etc.)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error `.type` Field
|
||||
|
||||
All `APIStatusError` subclasses now expose a `.type` property (Python: `.type`, TypeScript: `.type`, Java: `.errorType()`, Go: `.Type()`, Ruby: `.type`, PHP: `.type`) that returns the API error type string (e.g., `"invalid_request_error"`, `"authentication_error"`, `"rate_limit_error"`, `"overloaded_error"`). Use this for programmatic error classification when you need finer granularity than the HTTP status code — for example, distinguishing `"billing_error"` from `"permission_error"` (both map to 403).
|
||||
|
||||
```python
|
||||
except anthropic.APIStatusError as e:
|
||||
if e.type == "rate_limit_error":
|
||||
# handle rate limiting
|
||||
elif e.type == "overloaded_error":
|
||||
# handle overload
|
||||
```
|
||||
143
.agents/skills/claude-api/shared/live-sources.md
Normal file
143
.agents/skills/claude-api/shared/live-sources.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# Live Documentation Sources
|
||||
|
||||
This file contains WebFetch URLs for fetching current information from platform.claude.com and Agent SDK repositories. Use these when users need the latest data that may have changed since the cached content was last updated.
|
||||
|
||||
## When to Use WebFetch
|
||||
|
||||
- User explicitly asks for "latest" or "current" information
|
||||
- Cached data seems incorrect
|
||||
- User asks about features not covered in cached content
|
||||
- User needs specific API details or examples
|
||||
|
||||
## Claude API Documentation URLs
|
||||
|
||||
### Models & Pricing
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| --------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
||||
| Models Overview | `https://platform.claude.com/docs/en/about-claude/models/overview.md` | "Extract current model IDs, context windows, and pricing for all Claude models" |
|
||||
| Migration Guide | `https://platform.claude.com/docs/en/about-claude/models/migration-guide.md` | "Extract breaking changes, deprecated parameters, and per-model migration steps when moving to a newer Claude model" |
|
||||
| Introducing Claude Fable 5 | `https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5.md` | "Extract capabilities, API changes, and availability stages for Claude Fable 5 and Claude Mythos 5" |
|
||||
| Pricing | `https://platform.claude.com/docs/en/pricing.md` | "Extract current pricing per million tokens for input and output" |
|
||||
|
||||
### Core Features
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
||||
| Extended Thinking | `https://platform.claude.com/docs/en/build-with-claude/extended-thinking.md` | "Extract extended thinking parameters, budget_tokens requirements, and usage examples" |
|
||||
| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 5 usage examples" |
|
||||
| Effort Parameter | `https://platform.claude.com/docs/en/build-with-claude/effort.md` | "Extract effort levels, cost-quality tradeoffs, and interaction with thinking" |
|
||||
| Tool Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md` | "Extract tool definition schema, tool_choice options, and handling tool results" |
|
||||
| Streaming | `https://platform.claude.com/docs/en/build-with-claude/streaming.md` | "Extract streaming event types, SDK examples, and best practices" |
|
||||
| Prompt Caching | `https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md` | "Extract cache_control usage, pricing benefits, and implementation examples" |
|
||||
|
||||
### Media & Files
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| ----------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| Vision | `https://platform.claude.com/docs/en/build-with-claude/vision.md` | "Extract supported image formats, size limits, and code examples" |
|
||||
| PDF Support | `https://platform.claude.com/docs/en/build-with-claude/pdf-support.md` | "Extract PDF handling capabilities, limits, and examples" |
|
||||
|
||||
### API Operations
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| Batch Processing | `https://platform.claude.com/docs/en/build-with-claude/batch-processing.md` | "Extract batch API endpoints, request format, and polling for results" |
|
||||
| Files API | `https://platform.claude.com/docs/en/build-with-claude/files.md` | "Extract file upload, download, and referencing in messages, including supported types and beta header" |
|
||||
| Token Counting | `https://platform.claude.com/docs/en/build-with-claude/token-counting.md` | "Extract token counting API usage and examples" |
|
||||
| Rate Limits | `https://platform.claude.com/docs/en/api/rate-limits.md` | "Extract current rate limits by tier and model" |
|
||||
| Errors | `https://platform.claude.com/docs/en/api/errors.md` | "Extract HTTP error codes, meanings, and retry guidance" |
|
||||
| Amazon Bedrock | `https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock.md` | "Extract the AnthropicBedrockMantle client per language, `anthropic.`-prefixed model IDs, auth paths, feature availability, and regions" |
|
||||
| Claude Platform on AWS | `https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws.md` | "Extract the AnthropicAWS client per language, SigV4 auth, credential precedence, short-term API keys, workspace_id, and region requirements" |
|
||||
| Claude Platform on AWS — IAM actions | `https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions.md` | "Extract the IAM action names, resource ARNs, and policy examples required for each API capability" |
|
||||
|
||||
### Tools
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| -------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| Code Execution | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool.md` | "Extract code execution tool setup, file upload, container reuse, and response handling" |
|
||||
| Computer Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use.md` | "Extract computer use tool setup, capabilities, and implementation examples" |
|
||||
| Bash Tool | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool.md` | "Extract bash tool schema, reference implementation, and security considerations" |
|
||||
| Text Editor | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool.md` | "Extract text editor tool commands, schema, and reference implementation" |
|
||||
| Memory Tool | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md` | "Extract memory tool commands, directory structure, and implementation patterns" |
|
||||
| Tool Search | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool.md` | "Extract tool search setup, when to use, and cache interaction" |
|
||||
| Programmatic Tool Calling | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling.md` | "Extract PTC setup, script execution model, and tool invocation from code" |
|
||||
| Skills | `https://platform.claude.com/docs/en/agents-and-tools/skills.md` | "Extract skill folder structure, SKILL.md format, and loading behavior" |
|
||||
|
||||
### Advanced Features
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| Structured Outputs | `https://platform.claude.com/docs/en/build-with-claude/structured-outputs.md` | "Extract output_config.format usage and schema enforcement" |
|
||||
| Compaction | `https://platform.claude.com/docs/en/build-with-claude/compaction.md` | "Extract compaction setup, trigger config, and streaming with compaction" |
|
||||
| Context Editing | `https://platform.claude.com/docs/en/build-with-claude/context-editing.md` | "Extract context editing thresholds, what gets cleared, and configuration" |
|
||||
| Citations | `https://platform.claude.com/docs/en/build-with-claude/citations.md` | "Extract citation format and implementation" |
|
||||
| Context Windows | `https://platform.claude.com/docs/en/build-with-claude/context-windows.md` | "Extract context window sizes and token management" |
|
||||
|
||||
### Managed Agents
|
||||
|
||||
Use these when a managed-agents binding, behavior, or wire-level detail isn't covered in the cached `shared/managed-agents-*.md` concept files or in `{lang}/managed-agents/README.md`.
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| --------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| Overview | `https://platform.claude.com/docs/en/managed-agents/overview.md` | "Extract the high-level architecture and how agents/sessions/environments/vaults fit together" |
|
||||
| Quickstart | `https://platform.claude.com/docs/en/managed-agents/quickstart.md` | "Extract the minimal end-to-end agent → environment → session → stream code path" |
|
||||
| Agent Setup | `https://platform.claude.com/docs/en/managed-agents/agent-setup.md` | "Extract agent create/update/list-versions/archive lifecycle and parameters" |
|
||||
| Define Outcomes | `https://platform.claude.com/docs/en/managed-agents/define-outcomes.md` | "Extract outcome definitions, evaluation hooks, and success criteria configuration" |
|
||||
| Sessions | `https://platform.claude.com/docs/en/managed-agents/sessions.md` | "Extract session lifecycle, status transitions, idle/terminated semantics, and resume rules" |
|
||||
| Environments | `https://platform.claude.com/docs/en/managed-agents/environments.md` | "Extract environment config (cloud/networking), management endpoints, and reuse model" |
|
||||
| Self-Hosted Sandboxes | `https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes.md` | "Extract config:{type:self_hosted}, ANTHROPIC_ENVIRONMENT_KEY, EnvironmentWorker.run/run_one, beta_agent_toolset, ant beta:worker poll/run, webhook-driven wake" |
|
||||
| Self-Hosted Sandboxes — Security | `https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-security.md` | "Extract what the customer owns (hardening, egress, key custody, trust boundaries) vs what Anthropic cannot do" |
|
||||
| Events and Streaming | `https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md` | "Extract event stream types, stream-first ordering, reconnect/dedupe, and steering patterns" |
|
||||
| Tools | `https://platform.claude.com/docs/en/managed-agents/tools.md` | "Extract built-in toolset, custom tool definitions, and tool result wire format" |
|
||||
| Files | `https://platform.claude.com/docs/en/managed-agents/files.md` | "Extract file upload, mount paths, session resources, and listing/downloading session outputs" |
|
||||
| Permission Policies | `https://platform.claude.com/docs/en/managed-agents/permission-policies.md` | "Extract permission policy types (allow/deny/confirm) and per-tool config" |
|
||||
| Multi-Agent | `https://platform.claude.com/docs/en/managed-agents/multi-agent.md` | "Extract multi-agent composition patterns, sub-agent invocation, and result handoff" |
|
||||
| Observability | `https://platform.claude.com/docs/en/managed-agents/observability.md` | "Extract logging, tracing, and usage telemetry exposed by managed agents" |
|
||||
| Webhooks | `https://platform.claude.com/docs/en/managed-agents/webhooks.md` | "Extract webhook endpoint registration, HMAC signature verification, supported event types, and delivery semantics" |
|
||||
| GitHub | `https://platform.claude.com/docs/en/managed-agents/github.md` | "Extract github_repository resource shape, multi-repo mounting, and token rotation" |
|
||||
| MCP Connector | `https://platform.claude.com/docs/en/managed-agents/mcp-connector.md` | "Extract MCP server declaration on agents and vault-based credential injection at session" |
|
||||
| Vaults | `https://platform.claude.com/docs/en/managed-agents/vaults.md` | "Extract vault create, credential add/rotate, OAuth refresh shape, and archive" |
|
||||
| Skills | `https://platform.claude.com/docs/en/managed-agents/skills.md` | "Extract skill packaging and loading model for managed agents" |
|
||||
| Memory | `https://platform.claude.com/docs/en/managed-agents/memory.md` | "Extract memory resource shape, scoping, and lifecycle" |
|
||||
| Onboarding | `https://platform.claude.com/docs/en/managed-agents/onboarding.md` | "Extract first-run setup, prerequisites, and account/region requirements" |
|
||||
| Cloud Containers | `https://platform.claude.com/docs/en/managed-agents/cloud-containers.md` | "Extract cloud container runtime, image config, and network/storage knobs" |
|
||||
| Migration | `https://platform.claude.com/docs/en/managed-agents/migration.md` | "Extract migration paths from earlier APIs/preview shapes to GA managed agents" |
|
||||
|
||||
### Anthropic CLI
|
||||
|
||||
The `ant` CLI provides terminal access to the Claude API. Every API resource is exposed as a subcommand. It is the recommended way to create agents and environments from version-controlled YAML (`ant beta:agents create < agent.yaml` — see `shared/anthropic-cli.md`), and also exposes sessions and every other API resource for scripting and interactive inspection.
|
||||
|
||||
| Topic | URL | Extraction Prompt |
|
||||
| ------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| Anthropic CLI | `https://platform.claude.com/docs/en/api/sdks/cli.md` | "Extract CLI install, authentication, command structure, and the beta:agents/environments/sessions commands" |
|
||||
| Authentication overview | `https://platform.claude.com/docs/en/manage-claude/authentication.md` | "Extract the credential options (API keys, interactive OAuth login, Workload Identity Federation) and when to use each" |
|
||||
| WIF reference | `https://platform.claude.com/docs/en/manage-claude/wif-reference.md` | "Extract credential precedence order, the profile configuration file schema, and the configuration directory layout" |
|
||||
|
||||
---
|
||||
|
||||
## Claude API SDK Repositories
|
||||
|
||||
WebFetch these when a binding (class, method, namespace, field) isn't covered in the cached `{lang}/` skill files or in the managed-agents docs above. The SDKs include beta managed-agents support for `/v1/agents`, `/v1/sessions`, `/v1/environments`, and related resources — search the repo for `BetaManagedAgents`, `beta.agents`, `beta.sessions`, or the equivalent namespace for that language.
|
||||
|
||||
| SDK | URL | Extraction Prompt |
|
||||
| ---------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
||||
| Python | `https://github.com/anthropics/anthropic-sdk-python` | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" |
|
||||
| TypeScript | `https://github.com/anthropics/anthropic-sdk-typescript` | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" |
|
||||
| Java | `https://github.com/anthropics/anthropic-sdk-java` | "Extract beta managed-agents classes, builders, and method signatures (`client.beta().agents()`, `BetaManagedAgents*`)" |
|
||||
| Go | `https://github.com/anthropics/anthropic-sdk-go` | "Extract beta managed-agents types and method signatures (`client.Beta.Agents`, `BetaManagedAgents*` event types)" |
|
||||
| Ruby | `https://github.com/anthropics/anthropic-sdk-ruby` | "Extract beta managed-agents methods and parameter shapes (`client.beta.agents`, `client.beta.sessions`)" |
|
||||
| C# | `https://github.com/anthropics/anthropic-sdk-csharp` | "Extract beta managed-agents classes and method signatures (NuGet package, `BetaManagedAgents*` types)" |
|
||||
| PHP | `https://github.com/anthropics/anthropic-sdk-php` | "Extract beta managed-agents classes and method signatures (`$client->beta->agents`, `BetaManagedAgents*` params)" |
|
||||
|
||||
Each SDK repo also ships runnable programs under `examples/` — including the refusal-fallback / `fallbacks` examples (client-side middleware registration, fallback state, server-side `fallbacks` param). Fetch those for exact per-language syntax instead of translating another language's example.
|
||||
|
||||
---
|
||||
|
||||
## Fallback Strategy
|
||||
|
||||
If WebFetch fails (network issues, URL changed):
|
||||
|
||||
1. Use cached content from the language-specific files (note the cache date)
|
||||
2. Inform user the data may be outdated
|
||||
3. Suggest they check platform.claude.com or the GitHub repos directly
|
||||
448
.agents/skills/claude-api/shared/managed-agents-api-reference.md
Normal file
448
.agents/skills/claude-api/shared/managed-agents-api-reference.md
Normal file
@@ -0,0 +1,448 @@
|
||||
# Managed Agents — Endpoint Reference
|
||||
|
||||
All endpoints require `x-api-key` and `anthropic-version: 2023-06-01` headers. Managed Agents endpoints additionally require the `anthropic-beta` header.
|
||||
|
||||
> Most users should define agents and environments as version-controlled YAML applied with the `ant` CLI — see `shared/anthropic-cli.md`. The endpoints below are the underlying API that the CLI and SDKs drive.
|
||||
|
||||
## Beta Headers
|
||||
|
||||
```
|
||||
anthropic-beta: managed-agents-2026-04-01
|
||||
```
|
||||
|
||||
The SDK adds this header automatically for all `client.beta.{agents,environments,sessions,vaults,memory_stores,deployments,deployment_runs}.*` calls. Skills endpoints use `skills-2025-10-02`; Files endpoints use `files-api-2025-04-14`.
|
||||
|
||||
---
|
||||
|
||||
## SDK Method Reference
|
||||
|
||||
All resources are under the `beta` namespace. Python and TypeScript share identical method names.
|
||||
|
||||
| Resource | Python / TypeScript (`client.beta.*`) | Go (`client.Beta.*`) |
|
||||
| --- | --- | --- |
|
||||
| Agents | `agents.create` / `retrieve` / `update` / `list` / `archive` | `Agents.New` / `Get` / `Update` / `List` / `Archive` |
|
||||
| Agent Versions | `agents.versions.list` | `Agents.Versions.List` |
|
||||
| Environments | `environments.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Environments.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
|
||||
| Environment Work (self-hosted) | `environments.work.poller` / `stats` / `stop` | See `shared/managed-agents-self-hosted-sandboxes.md` |
|
||||
| Sessions | `sessions.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Sessions.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
|
||||
| Session Events | `sessions.events.list` / `send` / `stream` | `Sessions.Events.List` / `Send` / `StreamEvents` |
|
||||
| Session Threads | `sessions.threads.list` / `retrieve` / `archive`; `sessions.threads.events.list` / `stream` | `Sessions.Threads.List` / `Get` / `Archive`; `Sessions.Threads.Events.List` / `StreamEvents` |
|
||||
| Session Resources | `sessions.resources.add` / `retrieve` / `update` / `list` / `delete` | `Sessions.Resources.Add` / `Get` / `Update` / `List` / `Delete` |
|
||||
| Deployments | `deployments.create` / `pause` / `unpause` / `archive` / `run` | Not yet documented — WebFetch the SDK repo (`shared/live-sources.md`) |
|
||||
| Deployment Runs | `deployment_runs.list` / `retrieve` (TS: `deploymentRuns.*`) | Not yet documented — WebFetch the SDK repo (`shared/live-sources.md`) |
|
||||
| Vaults | `vaults.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
|
||||
| Credentials | `vaults.credentials.create` / `retrieve` / `update` / `list` / `delete` / `archive` / `mcp_oauth_validate` | `Vaults.Credentials.New` / `Get` / `Update` / `List` / `Delete` / `Archive` / `McpOauthValidate` |
|
||||
| Memory Stores | `memory_stores.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `MemoryStores.New` / `Get` / `Update` / `List` / `Delete` / `Archive` |
|
||||
| Memories | `memory_stores.memories.create` / `retrieve` / `update` / `list` / `delete` | `MemoryStores.Memories.New` / `Get` / `Update` / `List` / `Delete` |
|
||||
| Memory Versions | `memory_stores.memory_versions.list` / `retrieve` / `redact` | `MemoryStores.MemoryVersions.List` / `Get` / `Redact` |
|
||||
|
||||
**Naming quirks to watch for:**
|
||||
- Agents and Session Threads have **no delete** — only `archive`. Archive is **permanent**: the agent becomes read-only, new sessions cannot reference it, and there is no unarchive. Confirm with the user before archiving a production agent. Environments, Sessions, Vaults, Credentials, and Memory Stores have both `delete` and `archive`; Session Resources, Files, Skills, and Memories are `delete`-only; Memory Versions have neither — only `redact`.
|
||||
- Session resources use `add` (not `create`).
|
||||
- Go's event stream is `StreamEvents` (not `Stream`).
|
||||
- The self-hosted worker is **not** under `client.beta.*` — it's `EnvironmentWorker` from `anthropic.lib.environments` / `@anthropic-ai/sdk/helpers/beta/environments`; only `environments.work.poller/stats/stop` are client methods.
|
||||
|
||||
**Agent shorthand:** `agent` on session create accepts three forms — a bare string (`agent="agent_abc123"`, latest version), a pinned reference `{type: "agent", id, version}`, or `{type: "agent_with_overrides", id, version?, model?, system?, tools?, mcp_servers?, skills?}` to override those fields for this session only (see `shared/managed-agents-core.md` → Override agent configuration for a session).
|
||||
|
||||
**Model shorthand:** `model` on agent create accepts either a bare string (`model="claude-opus-5"` — uses `standard` speed) or the full config object, which takes `speed` and `effort` alongside `id`: `{id: "claude-opus-5", speed: "fast"}`, `{id: "claude-opus-5", effort: "high"}`. `effort` accepts a level string (`low`/`medium`/`high`/`xhigh`/`max`) or `{type: "<level>"}`, and is **agent-configuration only** — an `effort` inside a per-session `model` override is ignored. See `shared/managed-agents-core.md` → Effort on the agent model. Note: `speed: "fast"` is supported on Claude Opus 5 and Opus 4.8 — on the Claude API only, which includes Managed Agents but not Amazon Bedrock, Google Cloud, or Microsoft Foundry. Opus 4.7 fast mode has been removed; `speed: "fast"` on Opus 4.7 returns an error.
|
||||
|
||||
---
|
||||
|
||||
## Agents
|
||||
|
||||
**Step one of every flow.** Sessions require a pre-created agent — there is no inline agent config under `managed-agents-2026-04-01`.
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/agents` | ListAgents | List agents |
|
||||
| `POST` | `/v1/agents` | CreateAgent | Create a saved agent configuration |
|
||||
| `GET` | `/v1/agents/{agent_id}` | GetAgent | Get agent details |
|
||||
| `POST` | `/v1/agents/{agent_id}` | UpdateAgent | Update agent configuration. `version` is **optional**: supply it (≥ 1) for optimistic concurrency — a mismatch returns 409 — or omit it for an unconditional last-write-wins update. |
|
||||
| `POST` | `/v1/agents/{agent_id}/archive` | ArchiveAgent | Archive an agent. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. |
|
||||
| `GET` | `/v1/agents/{agent_id}/versions` | ListAgentVersions | List agent versions |
|
||||
|
||||
## Sessions
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/sessions` | ListSessions | List sessions (paginated) |
|
||||
| `POST` | `/v1/sessions` | CreateSession | Create a new session |
|
||||
| `GET` | `/v1/sessions/{session_id}` | GetSession | Get session details |
|
||||
| `POST` | `/v1/sessions/{session_id}` | UpdateSession | Update session `metadata`/`title`, or `agent.tools`/`agent.mcp_servers`/`vault_ids` (session-local override; session must be `idle`). See `shared/managed-agents-core.md` → Updating the agent configuration mid-session. |
|
||||
| `DELETE` | `/v1/sessions/{session_id}` | DeleteSession | Delete a session |
|
||||
| `POST` | `/v1/sessions/{session_id}/archive` | ArchiveSession | Archive a session |
|
||||
|
||||
## Events
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/sessions/{session_id}/events` | ListEvents | List events (polling, paginated) |
|
||||
| `POST` | `/v1/sessions/{session_id}/events` | SendEvents | Send events (user message, tool result) |
|
||||
| `GET` | `/v1/sessions/{session_id}/events/stream` | StreamEvents | Stream events via SSE. Optional `event_deltas[]=agent.message` / `agent.thinking` opts in to live-preview `event_start`/`event_delta` events — see `shared/managed-agents-events.md` § Live previews. |
|
||||
|
||||
## Session Threads
|
||||
|
||||
Per-subagent event streams in multiagent sessions. See `shared/managed-agents-multiagent.md`.
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/sessions/{session_id}/threads` | ListThreads | List threads (paginated) |
|
||||
| `GET` | `/v1/sessions/{session_id}/threads/{thread_id}` | GetThread | Retrieve one thread (carries `agent` snapshot, `status`, `parent_thread_id`, `stats`, `usage`) |
|
||||
| `POST` | `/v1/sessions/{session_id}/threads/{thread_id}/archive` | ArchiveThread | Archive a thread |
|
||||
| `GET` | `/v1/sessions/{session_id}/threads/{thread_id}/events` | ListThreadEvents | List past events for one thread (paginated) |
|
||||
| `GET` | `/v1/sessions/{session_id}/threads/{thread_id}/stream` | StreamThreadEvents | Stream one thread via SSE (SDK: `threads.events.stream`) |
|
||||
|
||||
## Session Resources
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------------- | ---------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/sessions/{session_id}/resources` | ListResources | List resources attached to session |
|
||||
| `POST` | `/v1/sessions/{session_id}/resources` | AddResource | Attach `file` or `github_repository` resource (SDK method: `add`, not `create`). `memory_store` resources attach at session-create time only. |
|
||||
| `GET` | `/v1/sessions/{session_id}/resources/{resource_id}` | GetResource | Get a single resource |
|
||||
| `POST` | `/v1/sessions/{session_id}/resources/{resource_id}` | UpdateResource | Update resource |
|
||||
| `DELETE` | `/v1/sessions/{session_id}/resources/{resource_id}` | DeleteResource | Remove resource from session |
|
||||
|
||||
## Environments
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ---------------------------------------------------------------- | -------------------- | ----------------------------------- |
|
||||
| `POST` | `/v1/environments` | CreateEnvironment | Create environment |
|
||||
| `GET` | `/v1/environments` | ListEnvironments | List environments |
|
||||
| `GET` | `/v1/environments/{environment_id}` | GetEnvironment | Get environment details |
|
||||
| `POST` | `/v1/environments/{environment_id}` | UpdateEnvironment | Update environment |
|
||||
| `DELETE` | `/v1/environments/{environment_id}` | DeleteEnvironment | Delete environment. Returns 204. |
|
||||
| `POST` | `/v1/environments/{environment_id}/archive` | ArchiveEnvironment | Archive environment. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — this is the terminal state. |
|
||||
| `GET` | `/v1/environments/{environment_id}/work/stats` | WorkQueueStats | Self-hosted work-queue depth/pending/workers. `x-api-key` auth. See `shared/managed-agents-self-hosted-sandboxes.md`. |
|
||||
| `POST` | `/v1/environments/{environment_id}/work/{work_id}/stop` | StopWork | Self-hosted: stop a claimed work item. `x-api-key` auth. |
|
||||
|
||||
For `type: "self_hosted"`, `config` is the bare `{"type": "self_hosted"}` — `networking` and `packages` do not apply.
|
||||
|
||||
## Deployments
|
||||
|
||||
Scheduled deployments (`depl_` IDs) run an agent on a recurring cron schedule — each firing creates a session. See `shared/managed-agents-scheduled-deployments.md` for the conceptual guide (cron/DST semantics, failure behavior, lifecycle).
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `POST` | `/v1/deployments` | CreateDeployment | Create a scheduled deployment |
|
||||
| `POST` | `/v1/deployments/{deployment_id}/pause` | PauseDeployment | Suppress scheduled triggers (reversible; manual runs still allowed) |
|
||||
| `POST` | `/v1/deployments/{deployment_id}/unpause` | UnpauseDeployment | Resume from the next occurrence (no backfill) |
|
||||
| `POST` | `/v1/deployments/{deployment_id}/archive` | ArchiveDeployment | **Terminal** — schedule stops, deployment becomes immutable |
|
||||
| `POST` | `/v1/deployments/{deployment_id}/run` | RunDeployment | Trigger a manual run immediately (`trigger_context.type: "manual"`); works while paused |
|
||||
|
||||
## Deployment Runs
|
||||
|
||||
Each trigger attempt (scheduled or manual) writes a `deployment_run` record (`drun_` IDs) carrying either the created `session_id` or an `error.type` (`environment_archived`, `agent_archived`, `vault_not_found`, `session_rate_limited`, `service_unavailable`).
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/deployment_runs?deployment_id=...` | ListDeploymentRuns | List runs for a deployment (paginated; filter failures with `has_error=true`) |
|
||||
| `GET` | `/v1/deployment_runs/{deployment_run_id}` | GetDeploymentRun | Retrieve a single run by ID (a `deployment_run.*` webhook event carries this as `data.id`) |
|
||||
|
||||
## Vaults
|
||||
|
||||
Vaults store credentials that Anthropic manages on your behalf — MCP credentials (OAuth with auto-refresh, or static bearer tokens) and `environment_variable` credentials substituted into outbound requests at egress. Attach to sessions via `vault_ids`. See `managed-agents-tools.md` §Vaults for the conceptual guide and credential shapes.
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `POST` | `/v1/vaults` | CreateVault | Create a vault |
|
||||
| `GET` | `/v1/vaults` | ListVaults | List vaults |
|
||||
| `GET` | `/v1/vaults/{vault_id}` | GetVault | Get vault details |
|
||||
| `POST` | `/v1/vaults/{vault_id}` | UpdateVault | Update vault |
|
||||
| `DELETE` | `/v1/vaults/{vault_id}` | DeleteVault | Delete vault |
|
||||
| `POST` | `/v1/vaults/{vault_id}/archive` | ArchiveVault | Archive vault |
|
||||
|
||||
## Credentials
|
||||
|
||||
Credentials are individual secrets stored inside a vault.
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ----------------------------------------------------------------- | ------------------ | ---------------------------- |
|
||||
| `POST` | `/v1/vaults/{vault_id}/credentials` | CreateCredential | Create a credential |
|
||||
| `GET` | `/v1/vaults/{vault_id}/credentials` | ListCredentials | List credentials in vault |
|
||||
| `GET` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | GetCredential | Get credential metadata |
|
||||
| `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | UpdateCredential | Update credential |
|
||||
| `DELETE` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | DeleteCredential | Delete credential |
|
||||
| `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` | ArchiveCredential | Archive credential |
|
||||
| `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate` | McpOauthValidate | Validate an MCP OAuth credential |
|
||||
|
||||
## Memory Stores
|
||||
|
||||
Workspace-scoped persistent memory that survives across sessions. Attach to a session via a `{"type": "memory_store", "memory_store_id": ...}` entry in `resources[]` (session-create time only). See `shared/managed-agents-memory.md` for the conceptual guide, the FUSE-mount agent interface, preconditions, and versioning.
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ------------------ | ---------------------------------------- |
|
||||
| `POST` | `/v1/memory_stores` | CreateMemoryStore | Create a store (`name`, `description`, `metadata`) |
|
||||
| `GET` | `/v1/memory_stores` | ListMemoryStores | List stores (`include_archived`, `created_at_{gte,lte}`) |
|
||||
| `GET` | `/v1/memory_stores/{memory_store_id}` | GetMemoryStore | Get store details |
|
||||
| `POST` | `/v1/memory_stores/{memory_store_id}` | UpdateMemoryStore | Update store |
|
||||
| `DELETE` | `/v1/memory_stores/{memory_store_id}` | DeleteMemoryStore | Delete store |
|
||||
| `POST` | `/v1/memory_stores/{memory_store_id}/archive` | ArchiveMemoryStore | Archive store. Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive. |
|
||||
|
||||
## Memories
|
||||
|
||||
Individual text documents inside a store (≤ 100KB each). `create` creates at a `path` and returns `409` (`memory_path_conflict_error`, with `conflicting_memory_id`) if the path is occupied; `update` mutates by `mem_...` ID (rename and/or content). Only `update` accepts a `precondition` (`{"type": "content_sha256", "content_sha256": ...}`) — on mismatch returns `409` (`memory_precondition_failed_error`). List endpoints accept `view: "basic"|"full"` (controls whether `content` is populated; `retrieve` defaults to `full`).
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ----------------------------------------------------------------- | -------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/memory_stores/{memory_store_id}/memories` | ListMemories | Returns `Memory \| MemoryPrefix`; filter by `path_prefix`, `depth` |
|
||||
| `POST` | `/v1/memory_stores/{memory_store_id}/memories` | CreateMemory | Create at `path` (SDK: `memories.create`); `409 memory_path_conflict_error` if occupied |
|
||||
| `GET` | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` | GetMemory | Read one memory (defaults to `view="full"`) |
|
||||
| `PATCH` | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` | UpdateMemory | Change `content`, `path`, or both by ID; optional `precondition` |
|
||||
| `DELETE` | `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` | DeleteMemory | Delete (optional `expected_content_sha256`) |
|
||||
|
||||
## Memory Versions
|
||||
|
||||
Immutable per-mutation snapshots (`memver_...`) — the audit and rollback surface. `operation` ∈ `created` / `modified` / `deleted`.
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ----------------------------------------------------------------------------- | --------------------- | ---------------------------------------- |
|
||||
| `GET` | `/v1/memory_stores/{memory_store_id}/memory_versions` | ListMemoryVersions | Newest-first; filter by `memory_id`, `operation`, `session_id`, `api_key_id`, `created_at_{gte,lte}` |
|
||||
| `GET` | `/v1/memory_stores/{memory_store_id}/memory_versions/{version_id}` | GetMemoryVersion | List fields + full `content` |
|
||||
| `POST` | `/v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact` | RedactMemoryVersion | Clear `content`/`content_sha256`/`content_size_bytes`/`path`; preserve actor + timestamps |
|
||||
|
||||
## Files
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `POST` | `/v1/files` | UploadFile | Upload a file |
|
||||
| `GET` | `/v1/files` | ListFiles | List files |
|
||||
| `GET` | `/v1/files/{file_id}` | GetFile | Get file metadata (SDK method: `retrieve_metadata`) |
|
||||
| `GET` | `/v1/files/{file_id}/content` | DownloadFile | Download file content |
|
||||
| `DELETE` | `/v1/files/{file_id}` | DeleteFile | Delete a file |
|
||||
|
||||
## Skills
|
||||
|
||||
| Method | Path | Operation | Description |
|
||||
| -------- | --------------------------------------------------------------- | ------------------ | ---------------------------- |
|
||||
| `POST` | `/v1/skills` | CreateSkill | Create a skill |
|
||||
| `GET` | `/v1/skills` | ListSkills | List skills |
|
||||
| `GET` | `/v1/skills/{skill_id}` | GetSkill | Get skill details |
|
||||
| `DELETE` | `/v1/skills/{skill_id}` | DeleteSkill | Delete a skill |
|
||||
| `POST` | `/v1/skills/{skill_id}/versions` | CreateVersion | Create skill version |
|
||||
| `GET` | `/v1/skills/{skill_id}/versions` | ListVersions | List skill versions |
|
||||
| `GET` | `/v1/skills/{skill_id}/versions/{version}` | GetVersion | Get skill version |
|
||||
| `DELETE` | `/v1/skills/{skill_id}/versions/{version}` | DeleteVersion | Delete skill version |
|
||||
|
||||
---
|
||||
|
||||
## Request/Response Schema Quick Reference
|
||||
|
||||
### CreateAgent Request Body
|
||||
|
||||
**Always start here.** `model`, `system`, `tools`, `mcp_servers`, `skills` are top-level fields on this object — they do NOT go on the session.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string (required, 1-256 chars)",
|
||||
"model": "claude-opus-5 (required — bare string, or {id, speed?, effort?} object)",
|
||||
"description": "string (optional, up to 2048 chars)",
|
||||
"system": "string (optional, up to 100,000 chars)",
|
||||
"tools": [
|
||||
{ "type": "agent_toolset_20260401" }
|
||||
],
|
||||
"skills": [
|
||||
{ "type": "anthropic", "skill_id": "xlsx" },
|
||||
{ "type": "custom", "skill_id": "skill_abc123", "version": "1" }
|
||||
],
|
||||
"mcp_servers": [
|
||||
{
|
||||
"type": "url",
|
||||
"name": "github",
|
||||
"url": "https://api.githubcopilot.com/mcp/"
|
||||
}
|
||||
],
|
||||
"multiagent": {
|
||||
"type": "coordinator",
|
||||
"agents": [
|
||||
"agent_abc123",
|
||||
{ "type": "agent", "id": "agent_def456", "version": 4 },
|
||||
{ "type": "self" }
|
||||
]
|
||||
},
|
||||
"metadata": {
|
||||
"key": "value (max 16 pairs, keys ≤64 chars, values ≤512 chars)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Limits: `tools` max 128, `skills` max 20, `mcp_servers` max 20 (unique names). `multiagent.agents` 1–20 entries (string ID | `{type:"agent",id,version?}` | `{type:"self"}`) — see `shared/managed-agents-multiagent.md`.
|
||||
|
||||
### CreateSession Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": "agent_abc123 (required — string shorthand for latest version, or {type: \"agent\", id, version} object)",
|
||||
"environment_id": "env_abc123 (required)",
|
||||
"title": "string (optional)",
|
||||
"resources": [
|
||||
{
|
||||
"type": "github_repository",
|
||||
"url": "https://github.com/owner/repo (required)",
|
||||
"authorization_token": "ghp_... (required)",
|
||||
"mount_path": "/workspace/repo (optional — defaults to /workspace/<repo-name>)",
|
||||
"checkout": { "type": "branch", "name": "main" }
|
||||
}
|
||||
],
|
||||
"initial_events": [
|
||||
{ "type": "user.message", "content": [{ "type": "text", "text": "Review the auth module." }] }
|
||||
],
|
||||
"vault_ids": ["vlt_abc123 (optional — vault credentials: MCP auth + environment variables)"],
|
||||
"metadata": {
|
||||
"key": "value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> The `agent` field accepts a string ID, `{type: "agent", id, version}`, or `{type: "agent_with_overrides", id, version?, ...}` for session-local overrides of `model`/`system`/`tools`/`mcp_servers`/`skills`. Outside the overrides form, those fields live on the agent, not here. An `effort` inside a `model` override is ignored — set it on the agent.
|
||||
>
|
||||
> **`initial_events`** (optional, max 50) sends events at creation and starts the agent loop in the same call. Only `user.message` and `user.define_outcome` are accepted — no `system.message`, and none of the tool-result kinds. Validation is all-or-nothing. See `shared/managed-agents-core.md` → Seeding a session with `initial_events`.
|
||||
>
|
||||
> **`checkout`** accepts `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Omit for the repo's default branch.
|
||||
|
||||
### CreateEnvironment Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "string (required)",
|
||||
"description": "string (optional)",
|
||||
"config": {
|
||||
"type": "cloud | self_hosted",
|
||||
"networking": {
|
||||
"type": "unrestricted | limited (union — see SDK types)"
|
||||
},
|
||||
"packages": { }
|
||||
},
|
||||
"metadata": { "key": "value" }
|
||||
}
|
||||
```
|
||||
|
||||
### CreateDeployment Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Weekly compliance scan",
|
||||
"agent": "agent_abc123 (required — same shapes as CreateSession)",
|
||||
"environment_id": "env_abc123 (required)",
|
||||
"initial_events": [
|
||||
{ "type": "user.message", "content": [{ "type": "text", "text": "Run the weekly compliance scan." }] }
|
||||
],
|
||||
"schedule": {
|
||||
"type": "cron",
|
||||
"expression": "0 20 * * 5",
|
||||
"timezone": "America/New_York"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Optional session config (`resources`, `vault_ids`, etc.) is supported the same way as on CreateSession. Response includes `status`, `paused_reason`, and `schedule.upcoming_runs_at` (next fire times). See `shared/managed-agents-scheduled-deployments.md`.
|
||||
|
||||
### SendEvents Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"events": [
|
||||
{
|
||||
"type": "user.message",
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Hello"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
> `system.message` events (append system-level context for this turn and later ones) use the same envelope with `type: "system.message"` — supported on Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, and Claude Mythos 5, checked against the agent's *primary* model only; see `shared/managed-agents-events.md` § Adding system context mid-session.
|
||||
|
||||
### Define Outcome Event
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "user.define_outcome",
|
||||
"description": "Build a DCF model for Costco in .xlsx",
|
||||
"rubric": { "type": "file", "file_id": "file_01..." },
|
||||
"max_iterations": 5
|
||||
}
|
||||
```
|
||||
|
||||
> `rubric` is required: `{type: "text", content}` or `{type: "file", file_id}`. `max_iterations` default 3, max 20. Echoed back with `outcome_id` + `processed_at`. See `shared/managed-agents-outcomes.md`.
|
||||
|
||||
### Tool Result Event
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "user.custom_tool_result",
|
||||
"custom_tool_use_id": "sevt_abc123",
|
||||
"content": [{ "type": "text", "text": "Result data" }],
|
||||
"is_error": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
Managed Agents endpoints use the standard Anthropic API error format. Errors are returned with an HTTP status code and a JSON body containing `type`, `error`, and `request_id`:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "error",
|
||||
"error": {
|
||||
"type": "invalid_request_error",
|
||||
"message": "Description of what went wrong"
|
||||
},
|
||||
"request_id": "req_011CRv1W3XQ8XpFikNYG7RnE"
|
||||
}
|
||||
```
|
||||
|
||||
Include the `request_id` when reporting issues to Anthropic — it lets us trace the request end-to-end. The inner `error.type` is one of the following:
|
||||
|
||||
| Status | Error type | Description |
|
||||
|---|---|---|
|
||||
| 400 | `invalid_request_error` | The request was malformed or missing required parameters |
|
||||
| 401 | `authentication_error` | Invalid or missing API key |
|
||||
| 403 | `permission_error` | The API key doesn't have permission for this operation |
|
||||
| 404 | `not_found_error` | The requested resource doesn't exist |
|
||||
| 409 | `invalid_request_error` | The request conflicts with the resource's current state (e.g., sending to an archived session) |
|
||||
| 413 | `request_too_large` | The request body exceeds the maximum allowed size |
|
||||
| 429 | `rate_limit_error` | Too many requests — check rate limit headers for retry timing |
|
||||
| 500 | `api_error` | An internal server error occurred |
|
||||
| 529 | `overloaded_error` | The service is temporarily overloaded — retry with backoff |
|
||||
|
||||
Note that `409 Conflict` carries `error.type: "invalid_request_error"` (there is no separate `conflict_error` type); inspect both the HTTP status and the `message` to distinguish conflicts from other invalid requests.
|
||||
|
||||
---
|
||||
|
||||
## Pagination
|
||||
|
||||
Most Managed Agents list endpoints use the `page` / `next_page` cursor scheme:
|
||||
|
||||
| Field | Where | Notes |
|
||||
|---|---|---|
|
||||
| `limit` | query | Max items per page |
|
||||
| `page` | query | Opaque cursor from a previous response — pass a `next_page` or `prev_page` value here |
|
||||
| `order` | query | `asc` / `desc` on endpoints that support sorting. A cursor encodes the `order` of the request that produced it — reusing it with a different `order` returns 400. Other params (filters, `limit`) can change between paginated requests. |
|
||||
| `next_page` | response | Cursor for the next page; `null` when there are no more results |
|
||||
| `prev_page` | response | Cursor for the previous page on endpoints that support backward pagination — currently **only `GET /v1/sessions`**. `null` on the first page. On endpoints that don't support it, the field is **absent** (not `null`). |
|
||||
|
||||
Every SDK exposes an auto-paginating iterator that follows `next_page`. In Python and TypeScript, iterate the list result directly; the other SDKs expose the iterator via a separate method (iterating the plain list result returns one page). SDK auto-pagination is **forward-only** — to go back a page, read `prev_page` from the response and pass it back as the `page` parameter yourself.
|
||||
|
||||
> ⚠️ Some endpoints use a **different** cursor scheme: Message Batches, Files, Models, and several Admin API endpoints take `after_id`/`before_id` and return `has_more`/`first_id`/`last_id` instead of `page`/`next_page`. Some `page`-scheme endpoints (e.g. `GET /v1/skills`) also return a `has_more` boolean alongside `next_page`. Check the endpoint's reference page for its exact pagination fields.
|
||||
|
||||
---
|
||||
|
||||
## Rate Limits
|
||||
|
||||
Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your [Messages API token limits](https://platform.claude.com/docs/en/api/rate-limits). Model inference inside a session still draws from your organization's standard ITPM/OTPM limits.
|
||||
|
||||
| Endpoint group | Scope | RPM | Max concurrent |
|
||||
|---|---|---|---|
|
||||
| Create operations (Agents, Sessions, Vaults) | organization | 300 | — |
|
||||
| All other operations (Agents, Sessions, Vaults) | organization | 600 | — |
|
||||
| All operations (Environments) | organization | 60 | 5 |
|
||||
|
||||
Files and Skills endpoints use the standard tier-based [rate limits](https://platform.claude.com/docs/en/api/rate-limits).
|
||||
|
||||
When a limit is exceeded the API returns `429` with a `rate_limit_error` (see [Error Handling](#error-handling) for the response envelope) and a `retry-after` header indicating how many seconds to wait before retrying. The Anthropic SDK reads this header and retries automatically.
|
||||
@@ -0,0 +1,217 @@
|
||||
# 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.
|
||||
319
.agents/skills/claude-api/shared/managed-agents-core.md
Normal file
319
.agents/skills/claude-api/shared/managed-agents-core.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# 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_..."],
|
||||
)
|
||||
```
|
||||
|
||||
219
.agents/skills/claude-api/shared/managed-agents-environments.md
Normal file
219
.agents/skills/claude-api/shared/managed-agents-environments.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# Managed Agents — Environments & Resources
|
||||
|
||||
## Environments
|
||||
|
||||
Creating a session requires an `environment_id`. Environments are **reusable configuration templates** for spinning up containers in Anthropic's infrastructure — you might create different environments for different use cases (e.g. data visualization vs web development, with different package sets). Anthropic handles scaling, container lifecycle, and work orchestration.
|
||||
|
||||
**Environment names must be unique.** Creating an environment with an existing name returns 409.
|
||||
|
||||
### Networking
|
||||
|
||||
| Network Policy | Description |
|
||||
| ---------------- | ------------------------------------------------------------- |
|
||||
| `unrestricted` | Full egress (except legal blocklist) |
|
||||
| `limited` | Deny-by-default; opt in via `allowed_hosts` / `allow_package_managers` / `allow_mcp_servers` |
|
||||
|
||||
```json
|
||||
{
|
||||
"networking": {
|
||||
"type": "limited",
|
||||
"allow_package_managers": true,
|
||||
"allow_mcp_servers": true,
|
||||
"allowed_hosts": ["api.example.com"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
All three `limited` fields are optional. `allow_package_managers` (default `false`) permits PyPI/npm/etc.; `allow_mcp_servers` (default `false`) permits the agent's configured MCP server endpoints without listing them in `allowed_hosts`.
|
||||
|
||||
**MCP caveat:** Under `limited` networking, either set `allow_mcp_servers: true` or add each MCP server domain to `allowed_hosts`. Otherwise the container can't reach them and tools silently fail.
|
||||
|
||||
### Creating an environment
|
||||
|
||||
The SDK adds `managed-agents-2026-04-01` automatically. TypeScript:
|
||||
|
||||
```ts
|
||||
const env = await client.beta.environments.create({
|
||||
name: "my_env",
|
||||
config: {
|
||||
type: "cloud",
|
||||
networking: { type: "unrestricted" },
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Self-hosted sandboxes
|
||||
|
||||
To run tool execution in **your own infrastructure** instead of Anthropic's, set `config: {type: "self_hosted"}` — the agent loop stays on Anthropic's side, but `bash` / file ops / code execute in a container you control via an outbound-polling worker. The `networking` block does not apply (you control egress). Resource mounting (`file`, `github_repository`) and memory stores behave differently — see `shared/managed-agents-self-hosted-sandboxes.md` for the worker, credentials, and cloud-vs-self-hosted comparison.
|
||||
|
||||
### Environment CRUD
|
||||
|
||||
| Operation | Method | Path | Notes |
|
||||
| ---------------- | -------- | ------------------------------------------ | ----- |
|
||||
| Create | `POST` | `/v1/environments` | |
|
||||
| List | `GET` | `/v1/environments` | Paginated (`limit`, `after_id`, `before_id`) |
|
||||
| Get | `GET` | `/v1/environments/{id}` | |
|
||||
| Update | `POST` | `/v1/environments/{id}` | Changes apply only to **new** containers; existing sessions keep their original config |
|
||||
| Delete | `DELETE` | `/v1/environments/{id}` | Returns 204. |
|
||||
| Archive | `POST` | `/v1/environments/{id}/archive` | Makes it **read-only**; existing sessions continue, new sessions cannot reference it. No unarchive — terminal state. |
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
Attach files, GitHub repositories, and memory stores to a session. Resources are resolved during session creation, so a bad `file_id` or an unreachable repo surfaces on the create call rather than mid-run. Creating a session does **not** by itself start work or provision the sandbox — without `initial_events` the session is only registered, and the sandbox comes up when the session first needs it (see `shared/managed-agents-core.md` → Seeding a session with `initial_events`). Max **999 file resources** per session. Multiple GitHub repositories per session are supported. For `type: "memory_store"` resources (persistent cross-session memory — max 8 per session), see `shared/managed-agents-memory.md`.
|
||||
|
||||
### File Uploads (input — host → agent)
|
||||
|
||||
Upload a file first via the Files API, then reference by `file_id` + `mount_path`:
|
||||
|
||||
```ts
|
||||
// 1. Upload
|
||||
const file = await client.beta.files.upload({
|
||||
file: fs.createReadStream("data.csv"),
|
||||
});
|
||||
|
||||
// 2. Attach as a session resource
|
||||
const session = await client.beta.sessions.create({
|
||||
agent: agent.id,
|
||||
environment_id: envId,
|
||||
resources: [
|
||||
{ type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
**`mount_path` is required** and must be absolute. Parent directories are created automatically. Agent working directory defaults to `/workspace`. Files are mounted read-only — the agent writes modified versions to new paths.
|
||||
|
||||
### Session outputs (output — agent → host)
|
||||
|
||||
The agent can write files to `/mnt/session/outputs/` during a session. These are automatically captured by the Files API and can be listed and downloaded afterwards:
|
||||
|
||||
```ts
|
||||
// After the turn completes, list output files scoped to this session:
|
||||
for await (const f of client.beta.files.list({
|
||||
scope_id: session.id,
|
||||
betas: ["managed-agents-2026-04-01"],
|
||||
})) {
|
||||
console.log(f.filename, f.size_bytes);
|
||||
const resp = await client.beta.files.download(f.id);
|
||||
const text = await resp.text();
|
||||
}
|
||||
```
|
||||
|
||||
**Requirements:**
|
||||
- The `write` tool (or `bash`) must be enabled for the agent to create output files.
|
||||
- Session-scoped `files.list` / `files.download` captures outputs written to `/mnt/session/outputs/`.
|
||||
- The filter parameter is **`scope_id`** (REST query param `?scope_id=<session_id>`). The SDK's files resource auto-adds only the `files-api-2025-04-14` header, so pass `betas: ["managed-agents-2026-04-01"]` explicitly (or both headers on raw HTTP) — without it the API may reject `scope_id` as an unknown field. Requires `@anthropic-ai/sdk` ≥ 0.88.0 / `anthropic` (Python) ≥ 0.92.0 — older versions don't type `scope_id`. The `ant` CLI does **not** expose this flag yet; use the SDK or curl.
|
||||
- Pass the session ID returned by `sessions.create()` verbatim (e.g. `sesn_011CZx...`) — the API validates the prefix.
|
||||
- There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if empty.
|
||||
|
||||
> **Fallback when `scope_id` filtering is unavailable** (older SDK, or endpoint returns an error): send a follow-up `user.message` asking the agent to `read` each file under `/mnt/session/outputs/` and return the contents. The agent streams the file bodies back as `agent.message` text. This works for text files only and costs output tokens — use it to unblock, not as the primary path.
|
||||
|
||||
This gives you a bidirectional file bridge: upload reference data in, download agent artifacts out.
|
||||
|
||||
### GitHub Repositories
|
||||
|
||||
Clones a GitHub repository into the session container during initialization, before the agent begins execution. The agent can read, edit, commit, and push via `bash` (`git`). Multiple repositories per session are supported — add one `resources` entry per repo. Repositories are cached, so future sessions that use the same repository start faster.
|
||||
|
||||
Repositories are attached for the lifetime of the session — to change which repositories are mounted, create a new session. You **can** rotate a repository's `authorization_token` on a running session via `client.beta.sessions.resources.update(resource_id, {session_id, authorization_token})`; the resource `id` is returned at session creation and by `resources.list()`.
|
||||
|
||||
**Fields:**
|
||||
|
||||
| Field | Required | Notes |
|
||||
|---|---|---|
|
||||
| `type` | ✅ | `"github_repository"` |
|
||||
| `url` | ✅ | The GitHub repository URL |
|
||||
| `authorization_token` | ✅ | GitHub Personal Access Token with repository access. **Never echoed in API responses.** |
|
||||
| `mount_path` | ❌ | Path where the repository will be cloned. Defaults to `/workspace/<repo-name>`. |
|
||||
| `checkout` | ❌ | `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Defaults to the repo's default branch. |
|
||||
|
||||
**Token permission levels** (fine-grained PATs):
|
||||
- `Contents: Read` — clone only
|
||||
- `Contents: Read and write` — push changes and create pull requests
|
||||
|
||||
**How auth works:** `authorization_token` is never placed inside the container. `git pull` / `git push` and GitHub REST calls against the attached repository are routed through an Anthropic-side git proxy that injects the token after the request leaves the sandbox. Code running in the container — including anything the agent writes — cannot read or exfiltrate it.
|
||||
|
||||
> ‼️ **To generate pull requests** you also need GitHub **MCP server** access — the `github_repository` resource gives filesystem + git access only. See `shared/managed-agents-tools.md` → MCP Servers. The PR workflow is: edit files in the mounted repo → push branch via `bash` (authenticated via the git proxy using `authorization_token`) → create PR via the MCP `create_pull_request` tool (authenticated via the vault).
|
||||
|
||||
**TypeScript:**
|
||||
|
||||
```ts
|
||||
// 1. Create the agent — declare GitHub MCP (no auth here)
|
||||
const agent = await client.beta.agents.create(
|
||||
{
|
||||
name: 'GitHub Agent',
|
||||
model: 'claude-opus-5',
|
||||
mcp_servers: [
|
||||
{ type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' },
|
||||
],
|
||||
tools: [
|
||||
{ type: 'agent_toolset_20260401', default_config: { enabled: true } },
|
||||
{ type: 'mcp_toolset', mcp_server_name: 'github' },
|
||||
],
|
||||
},
|
||||
);
|
||||
|
||||
// 2. Start a session — attach vault for MCP auth + mount the repo
|
||||
const session = await client.beta.sessions.create({
|
||||
agent: agent.id,
|
||||
environment_id: envId,
|
||||
vault_ids: [vaultId], // vault contains the GitHub MCP OAuth credential
|
||||
resources: [
|
||||
{
|
||||
type: 'github_repository',
|
||||
url: 'https://github.com/owner/repo',
|
||||
authorization_token: process.env.GITHUB_TOKEN, // repo clone token (≠ MCP auth)
|
||||
checkout: { type: 'branch', name: 'main' },
|
||||
},
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
**Python:**
|
||||
|
||||
```python
|
||||
import os
|
||||
|
||||
agent = client.beta.agents.create(
|
||||
name="GitHub Agent",
|
||||
model="claude-opus-5",
|
||||
mcp_servers=[{
|
||||
"type": "url",
|
||||
"name": "github",
|
||||
"url": "https://api.githubcopilot.com/mcp/",
|
||||
}],
|
||||
tools=[
|
||||
{"type": "agent_toolset_20260401", "default_config": {"enabled": True}},
|
||||
{"type": "mcp_toolset", "mcp_server_name": "github"},
|
||||
],
|
||||
)
|
||||
|
||||
session = client.beta.sessions.create(
|
||||
agent=agent.id,
|
||||
environment_id=env_id,
|
||||
vault_ids=[vault_id], # vault contains the GitHub MCP OAuth credential
|
||||
resources=[{
|
||||
"type": "github_repository",
|
||||
"url": "https://github.com/owner/repo",
|
||||
"authorization_token": os.environ["GITHUB_TOKEN"], # repo clone token (≠ MCP auth)
|
||||
"checkout": {"type": "branch", "name": "main"},
|
||||
}],
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files API
|
||||
|
||||
Upload and manage files for use as session resources, and download files the agent wrote to `/mnt/session/outputs/`.
|
||||
|
||||
| Operation | Method | Path | SDK |
|
||||
| ---------------- | -------- | ------------------------------------- | --- |
|
||||
| Upload | `POST` | `/v1/files` | `client.beta.files.upload({ file })` |
|
||||
| List | `GET` | `/v1/files?scope_id=...` | `client.beta.files.list({ scope_id, betas: ["managed-agents-2026-04-01"] })` |
|
||||
| Get Metadata | `GET` | `/v1/files/{id}` | `client.beta.files.retrieveMetadata(id)` |
|
||||
| Download | `GET` | `/v1/files/{id}/content` | `client.beta.files.download(id)` → `Response` |
|
||||
| Delete | `DELETE` | `/v1/files/{id}` | `client.beta.files.delete(id)` |
|
||||
|
||||
The `scope_id` filter on List scopes the results to files written to `/mnt/session/outputs/` by that session. Without the filter, you get all files uploaded to your account.
|
||||
270
.agents/skills/claude-api/shared/managed-agents-events.md
Normal file
270
.agents/skills/claude-api/shared/managed-agents-events.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# Managed Agents — Events & Steering
|
||||
|
||||
## Events
|
||||
|
||||
### Sending Events
|
||||
|
||||
Send events to a session via `POST /v1/sessions/{id}/events`.
|
||||
|
||||
| Event Type | When to Send |
|
||||
| ------------------------- | --------------------------------------------------- |
|
||||
| `user.message` | Send a user message |
|
||||
| `user.interrupt` | Interrupt the agent while it's running |
|
||||
| `user.tool_confirmation` | Approve/deny a tool call (when `always_ask` policy) |
|
||||
| `user.custom_tool_result` | Provide result for a custom tool call |
|
||||
| `user.define_outcome` | Start a rubric-graded iterate loop — see `shared/managed-agents-outcomes.md` |
|
||||
| `system.message` | Append privileged system-level context for this turn and every turn after it; see § Adding system context mid-session |
|
||||
|
||||
#### Adding system context mid-session (`system.message`)
|
||||
|
||||
The `system` field on the agent definition sets the top-level system prompt and is fixed for the session's lifetime. A `system.message` event **appends** to the session's system context as a `role: "system"` turn — it does not replace that prompt. The content applies to the accompanying turn and all subsequent turns. Use it for a different persona, revised constraints, or runtime-fetched context that should shape behavior going forward:
|
||||
|
||||
```python
|
||||
client.beta.sessions.events.send(
|
||||
session.id,
|
||||
events=[
|
||||
{
|
||||
"type": "system.message",
|
||||
"content": [
|
||||
{"type": "text", "text": "The user's current timezone is America/New_York."},
|
||||
],
|
||||
},
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
Constraints:
|
||||
|
||||
- **Model-gated: Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5, and Claude Mythos 5.** Only the agent's **primary** model is checked — `system.message` lands on the primary thread only, so subagent models are not considered. On an unsupported primary model the event is rejected with a `model_does_not_support_mid_conversation_system` validation error.
|
||||
- **While the session is idle with `stop_reason: requires_action`** (blocked on `user.custom_tool_result` / `user.tool_confirmation`), a `system.message` is accepted **only when it trails a tool result event in the same request**. Sent on its own — or alongside a `user.message` — it is rejected until the pending tool events are resolved.
|
||||
- `content` accepts 1–1000 text items.
|
||||
|
||||
### Receiving Events
|
||||
|
||||
Three methods:
|
||||
|
||||
1. **Streaming (SSE)**: `GET /v1/sessions/{id}/events/stream` — real-time Server-Sent Events. **Long-lived** — the server sends periodic heartbeats to keep the connection alive.
|
||||
2. **Polling**: `GET /v1/sessions/{id}/events` — paginated event list (query params: `limit` default 1000, `page`). **Returns immediately** — this is a plain paginated GET, not a long-poll.
|
||||
3. **Webhooks**: Anthropic POSTs session state transitions to your HTTPS endpoint — thin payloads (IDs only), HMAC-signed, Console-registered. See `shared/managed-agents-webhooks.md`.
|
||||
|
||||
All **persisted** events carry `id`, `type`, and `processed_at` (ISO 8601), set when the event finishes processing. On events you send, `processed_at` is `null` while the event is still queued behind earlier ones — **except** `user.define_outcome`, `user.custom_tool_result`, and `user.tool_result`, which are processed on receipt and echoed back with `processed_at` already populated. The stream-only `event_start` / `event_delta` preview events (see § Live previews) carry only the `id` of the event they preview.
|
||||
|
||||
> ⚠️ **Robust polling (raw HTTP).** If you bypass the SDK and roll your own poll loop, don't rely on `requests` or `httpx` timeouts as wall-clock caps — they're **per-chunk** read timeouts, reset every time a byte arrives. A trickling response (heartbeats, a wedged chunked-encoding body, a misbehaving proxy) can keep the call blocked indefinitely even with `timeout=(5, 60)` or `httpx.Timeout(120)`. Neither library has a "total wall-clock" timeout built in. For a hard deadline: track `time.monotonic()` at the loop level and break/cancel if a single request exceeds your budget (e.g. via a watchdog thread, or `asyncio.wait_for()` around async httpx). **Prefer the SDK** — `client.beta.sessions.events.stream()` and `client.beta.sessions.events.list()` handle timeout + retry sanely.
|
||||
>
|
||||
> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events/stream` by mistake or a server-side stall — report it; don't treat it as a client-config problem.
|
||||
|
||||
### Event Types (Received)
|
||||
|
||||
Event types use dot notation, grouped by namespace:
|
||||
|
||||
| Event Type | Description |
|
||||
| --- | --- |
|
||||
| `agent.message` | Agent text output |
|
||||
| `agent.thinking` | Progress signal that the agent is thinking — it does **not** carry the thinking content |
|
||||
| `agent.tool_use` | Agent used a built-in tool (`agent_toolset_20260401`) |
|
||||
| `agent.tool_result` | Result from a built-in tool |
|
||||
| `agent.mcp_tool_use` | Agent used an MCP tool |
|
||||
| `agent.mcp_tool_result` | Result from an MCP tool |
|
||||
| `agent.custom_tool_use` | Agent invoked a custom tool — session goes idle, you respond with `user.custom_tool_result` |
|
||||
| `agent.thread_context_compacted` | Conversation context was compacted |
|
||||
| `session.status_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. |
|
||||
| `session.status_running` | Session has starting running, and the Agent is actively doing work. |
|
||||
| `session.status_rescheduled` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. |
|
||||
| `session.status_terminated` | Session ended and is irreversibly unusable — **on completion or on error**, not error-only. |
|
||||
| `session.error` | Error occurred during processing |
|
||||
| `span.model_request_start` | Model inference started |
|
||||
| `span.model_request_end` | Model inference completed |
|
||||
| `span.outcome_evaluation_start` / `_ongoing` / `_end` | Grader progress for outcome-oriented sessions — see `shared/managed-agents-outcomes.md` |
|
||||
| `session.thread_created` | Subagent thread spawned (multiagent) — see `shared/managed-agents-multiagent.md` |
|
||||
| `session.thread_status_running` / `_idle` / `_rescheduled` / `_terminated` | Subagent thread status transitions (multiagent). `_idle` carries `stop_reason`. |
|
||||
| `agent.thread_message_sent` / `_received` | Cross-thread message, carries `to_session_thread_id` / `from_session_thread_id` (multiagent) |
|
||||
|
||||
The stream also echoes back user-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`, `user.define_outcome`).
|
||||
|
||||
Stream-only delta preview events (`event_start`, `event_delta`) are the one exception to the `{domain}.{action}` naming convention — see § Live previews below; they never appear in `GET /v1/sessions/{id}/events`.
|
||||
|
||||
---
|
||||
|
||||
## Live previews
|
||||
|
||||
By default, assistant text reaches the stream as buffered `agent.message` events — emitted only after the model request that produced them finishes. **Live previews** let you render that text incrementally while the model is still generating. The buffered `agent.message` is always the authoritative record; a client that ignores previews still receives a complete, correct stream. The wire format is **not** Messages-API streaming: the delta type is `content_delta`, not `content_block_delta`, so Messages-API accumulator code does not carry over unchanged.
|
||||
|
||||
**Opt in per stream connection** by adding the `event_deltas[]` query parameter, repeated once per event type to preview. Accepted values: `agent.message`, `agent.thinking` — any other value returns a 400, as does a request with more than 100 values. **Both stream endpoints accept it:** the session-level stream (`GET /v1/sessions/{id}/events/stream`) and each session thread's own stream (`GET /v1/sessions/{sid}/threads/{tid}/stream`). In a shell, quote the URL or percent-encode the brackets as `%5B%5D` — bare `[]` is a glob pattern.
|
||||
|
||||
**Previews are thread-scoped.** A connection previews only the thread it is reading. A child thread's previews are delivered on that child's stream and are *never* cross-posted to the session-level stream, whose previews stay scoped to the primary thread. To watch a subagent's text as the model generates it, open that subagent's thread stream — see `shared/managed-agents-multiagent.md`. Run one accumulator instance per connection.
|
||||
|
||||
```python
|
||||
stream = client.beta.sessions.events.stream(
|
||||
session_id=session.id,
|
||||
event_deltas=["agent.message"],
|
||||
)
|
||||
```
|
||||
|
||||
When a previewed event begins, the stream emits an `event_start` carrying the upcoming event's `type` and `id`; for `agent.message` it's followed by `event_delta` events carrying incremental text:
|
||||
|
||||
```json
|
||||
{"type": "event_start", "event": {"type": "agent.message", "id": "sevt_01abc..."}}
|
||||
{"type": "event_delta", "event_id": "sevt_01abc...", "delta": {"type": "content_delta", "index": 0, "content": {"type": "text", "text": "Here is the summary"}}}
|
||||
```
|
||||
|
||||
`event_start` and `event_delta` have no `id` or `processed_at` of their own — the only identifier they carry is the `id` of the event they preview. For `agent.thinking`, **only** the `event_start` is emitted (a "thinking has started" signal) — no deltas follow, and the buffered `agent.thinking` that concludes the preview carries no thinking content either. It is a progress signal, not a content carrier; there is nothing to read out of it.
|
||||
|
||||
**Accumulate-and-reconcile pattern.** Treat the preview as a scratch buffer keyed by `(event_id, index)`. On `event_start`, create an empty entry for the announced `id`. On each `event_delta`, append `delta.content.text` to `(event_id, delta.index)` and render the running text. When the buffered `agent.message` arrives, match it by `id`, **discard the accumulated preview**, and render the message's content instead. The identifiers always line up: `event_start.event.id`, every `event_delta.event_id`, and the buffered event's `id` are the same value. On a normal turn the order is fixed: `session.status_running` → `span.model_request_start` → `event_start` → `event_delta`* → buffered `agent.message` → `span.model_request_end`. If the turn errors or is interrupted the buffered event may never arrive, but `span.model_request_end` still does — close any unreconciled preview when you see it. Python/TypeScript/Go SDKs ship an accumulator helper that implements this; in other SDKs apply the manual pattern to the generated event types.
|
||||
|
||||
**Two guarantees the pattern relies on:** concatenating a preview's deltas in arrival order, keyed by `(event_id, index)`, yields a *prefix* of `content[index].text` in the buffered event (a prefix, not necessarily the whole text — deltas may be shed under load); and a connection emits at most one `event_start` per `event_id`, with the buffered event as the last thing that connection delivers for that `id`.
|
||||
|
||||
**Limitations:**
|
||||
- **Best effort** — under load the server may shed deltas for an event; you receive a contiguous prefix and then no further deltas for that event. The buffered `agent.message` still arrives complete. Never treat an accumulated preview as final.
|
||||
- **No replay on reconnect** — deltas are delivered only to the connection that opted in, while it's open; this holds for the session-level stream and each thread stream alike. A connection opened after a model request started receives no deltas for that in-flight event. After a drop, follow the consolidation pattern in § Reconnecting after a dropped stream — the history fetch returns any buffered events emitted during the gap; missed deltas cannot be re-requested.
|
||||
- **One thread, text only** — previews cover assistant text on the thread the connection is reading. Tool use, tool results, MCP results, and activity on any *other* thread are never previewed on that connection.
|
||||
- **Never persisted** — `event_start` / `event_delta` exist only on the live SSE stream, never in `GET /v1/sessions/{id}/events` or any thread's event history.
|
||||
|
||||
**Troubleshooting:**
|
||||
|
||||
| You see | What it means |
|
||||
| --- | --- |
|
||||
| Buffered events but no `event_start` / `event_delta` | This connection didn't opt in (`event_deltas[]` is per connection, not per session), or the turn ran on a different thread. List `GET /v1/sessions/{sid}/threads` to find which one ran. |
|
||||
| 404 on the stream URL | Wrong path or ID, or the request carries no managed-agents beta header — the thread endpoints are beta-gated, so without it they don't exist. The thread path is `/threads/{tid}/stream`, **not** `/threads/{tid}/events/stream` (which doesn't exist) and not `/events/stream` (session level only). |
|
||||
| 400 naming `event_deltas` | Only `agent.message` and `agent.thinking` are accepted, max 100 values. |
|
||||
|
||||
---
|
||||
|
||||
## Steering Patterns
|
||||
|
||||
Practical patterns for driving a session via the events surface.
|
||||
|
||||
### Stream-first ordering
|
||||
|
||||
**Open the stream before sending events.** The stream only delivers events that occur *after* it's opened — it does not replay current state or historical events. If you send a message first and open the stream second, early events (including fast status transitions) arrive buffered in a single batch and you lose the ability to react to them in real time.
|
||||
|
||||
```ts
|
||||
// ✅ Correct — stream and send concurrently
|
||||
const [response] = await Promise.all([
|
||||
streamEvents(sessionId), // opens SSE connection
|
||||
sendMessage(sessionId, text),
|
||||
]);
|
||||
|
||||
// ❌ Wrong — events before stream opens arrive as a single buffered batch
|
||||
await sendMessage(sessionId, text);
|
||||
const response = await streamEvents(sessionId);
|
||||
```
|
||||
|
||||
**For full history,** use `GET /v1/sessions/{id}/events` (paginated list) — the stream only gives you live events from connection onward.
|
||||
|
||||
### Reconnecting after a dropped stream
|
||||
|
||||
**The SSE stream has no replay.** If your connection drops (httpx read timeout, network blip) and you reconnect, you only get events emitted *after* reconnection. Any events emitted during the gap are lost from the stream.
|
||||
|
||||
**The consolidation pattern:** on every (re)connect, overlap the stream with a history fetch and dedupe by event ID:
|
||||
|
||||
```python
|
||||
def connect_with_consolidation(client, session_id):
|
||||
# 1. Open the SSE stream first
|
||||
stream = client.beta.sessions.events.stream(session_id=session_id)
|
||||
|
||||
# 2. Fetch history to cover any gap
|
||||
history = client.beta.sessions.events.list(
|
||||
session_id=session_id,
|
||||
)
|
||||
|
||||
# 3. Yield history first, then stream — dedupe by event.id
|
||||
seen = set()
|
||||
for ev in history.data:
|
||||
seen.add(ev.id)
|
||||
yield ev
|
||||
for ev in stream:
|
||||
if ev.id not in seen:
|
||||
seen.add(ev.id)
|
||||
yield ev
|
||||
```
|
||||
|
||||
### Message queuing
|
||||
|
||||
**You don't have to wait for a response before sending the next message.** User events are queued server-side and processed in order. This is useful for chat bridges where the user sends rapid follow-ups:
|
||||
|
||||
```ts
|
||||
// All three go into one session; agent processes them in order
|
||||
await sendMessage(sessionId, "Summarize the README");
|
||||
await sendMessage(sessionId, "Actually also check the CONTRIBUTING guide");
|
||||
await sendMessage(sessionId, "And compare the two");
|
||||
// Stream once — agent responds to all three as a coherent turn
|
||||
```
|
||||
|
||||
Events can be sent up to the Session at any time. There is no need to wait on a specific session status to enqueue new events via `client.beta.sessions.events.send()`
|
||||
|
||||
### Interrupt
|
||||
|
||||
A `user.interrupt` event **jumps the queue** (ahead of any pending user messages) and forces the session into `idle`. Use this for "stop" / "nevermind" / "cancel" commands:
|
||||
|
||||
```ts
|
||||
await client.beta.sessions.events.send(sessionId, {
|
||||
events: [{ type: 'user.interrupt' }],
|
||||
});
|
||||
```
|
||||
|
||||
The agent stops mid-task. It does not see the interrupt as a message — it just halts. Send a follow-up `user` event to explain what to do instead. If an outcome is active, the interrupt also marks `span.outcome_evaluation_end.result: "interrupted"` (see `shared/managed-agents-outcomes.md`).
|
||||
|
||||
**The interrupted turn ends with `stop_reason: end_turn`** — the same value a turn that finishes on its own carries. There is no interruption-specific stop reason, so a drain loop can't distinguish the two from `stop_reason` alone; track that you sent the interrupt.
|
||||
|
||||
**In a multiagent session, omitting `session_thread_id` interrupts every non-archived thread, including the primary** — it is not primary-only. Pass `session_thread_id` to stop one thread. See `shared/managed-agents-multiagent.md`.
|
||||
|
||||
> **Note**: Interrupt events may have empty IDs in the current implementation. When troubleshooting, use the `processed_at` timestamp along with surrounding event IDs.
|
||||
|
||||
### Event payloads
|
||||
|
||||
some events carry useful metadata beyond the status change itself:
|
||||
|
||||
`session.status_idle` — includes a `stop_reason` field which elaborates on why the session stopped and what type of further action is required by the user.
|
||||
```json
|
||||
{
|
||||
"id": "sevt_456",
|
||||
"processed_at": "2026-04-07T04:27:43.197Z",
|
||||
"stop_reason": {
|
||||
"event_ids": [
|
||||
"sevt_123"
|
||||
],
|
||||
"type": "requires_action"
|
||||
},
|
||||
"type": "status_idle"
|
||||
}
|
||||
```
|
||||
|
||||
`span.model_request_end` contains a `model_usage` field for cost tracking and efficiency analysis:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "span.model_request_end",
|
||||
"id": "sevt_456",
|
||||
"is_error": false,
|
||||
"model_request_start_id": "sevt_123",
|
||||
"model_usage": {
|
||||
"cache_creation_input_tokens": 0,
|
||||
"cache_read_input_tokens": 6656,
|
||||
"input_tokens": 3571,
|
||||
"output_tokens": 727
|
||||
},
|
||||
"processed_at": "2026-04-07T04:11:32.189Z"
|
||||
}
|
||||
```
|
||||
|
||||
**`agent.thread_context_compacted`** — emitted when the conversation history was summarized to fit context. Includes `pre_compaction_tokens` so you know how much was squeezed:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "sevt_abc123",
|
||||
"processed_at": "2026-03-24T14:05:15.787Z",
|
||||
"type": "agent.thread_context_compacted"
|
||||
}
|
||||
```
|
||||
|
||||
### Archive
|
||||
|
||||
When done with a session, archive it to free resources:
|
||||
|
||||
```ts
|
||||
await client.beta.sessions.archive(sessionId);
|
||||
```
|
||||
|
||||
> Archiving a **session** is routine cleanup — sessions are per-run and disposable. **Do not generalize this to agents or environments**: those are persistent, reusable resources, and archiving them is permanent (no unarchive; new sessions cannot reference them). See `shared/managed-agents-overview.md` → Common Pitfalls.
|
||||
|
||||
|
||||
199
.agents/skills/claude-api/shared/managed-agents-memory.md
Normal file
199
.agents/skills/claude-api/shared/managed-agents-memory.md
Normal file
@@ -0,0 +1,199 @@
|
||||
# Managed Agents — Memory Stores
|
||||
|
||||
> **Public beta.** Memory stores ship under the `managed-agents-2026-04-01` beta header; the SDK sets it automatically on all `client.beta.memory_stores.*` calls. If `client.beta.memory_stores` is missing, upgrade to the latest SDK release.
|
||||
|
||||
Sessions are ephemeral by default — when one ends, anything the agent learned is gone. A **memory store** is a workspace-scoped collection of small text documents that persists across sessions. When a store is attached to a session (via `resources[]`), it is mounted into the container as a filesystem directory; the agent reads and writes it with the ordinary file tools, and a system-prompt note tells it the mount is there.
|
||||
|
||||
Every mutation to a memory produces an immutable **memory version** (`memver_...`), giving you an audit trail and point-in-time rollback/redact.
|
||||
|
||||
> ⚠️ **Never store credentials, API keys, or tokens in memory stores.** Memories persist across sessions and are returned verbatim into future contexts — a key written once is replayed into every later session that mounts the store. Use vault `environment_variable` credentials instead (`shared/managed-agents-tools.md` → Vaults). If a secret has already been written, delete the memory and redact the affected versions (see "Redact a version" below).
|
||||
|
||||
## Object model
|
||||
|
||||
| Object | ID prefix | Scope | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| Memory store | `memstore_...` | Workspace | Attach to sessions via `resources[]` |
|
||||
| Memory | `mem_...` | Store | One text file, addressed by `path` (≤ 100KB each — prefer many small files) |
|
||||
| Memory version | `memver_...` | Memory | Immutable snapshot per mutation; `operation` ∈ `created` / `modified` / `deleted` |
|
||||
|
||||
## Create a store
|
||||
|
||||
`description` is passed to the agent so it knows what the store contains — write it for the model, not for humans.
|
||||
|
||||
```python
|
||||
store = client.beta.memory_stores.create(
|
||||
name="User Preferences",
|
||||
description="Per-user preferences and project context.",
|
||||
)
|
||||
print(store.id) # memstore_01Hx...
|
||||
```
|
||||
|
||||
Other SDKs: TypeScript `client.beta.memoryStores.create({...})`; Go `client.Beta.MemoryStores.New(ctx, ...)`. See `shared/managed-agents-api-reference.md` → SDK Method Reference for the full per-language table.
|
||||
|
||||
Stores support `retrieve` / `update` / `list` (with `include_archived`, `created_at_{gte,lte}` filters) / `delete` / **`archive`**. Archive makes the store read-only — existing session attachments continue, new sessions cannot reference it; no unarchive.
|
||||
|
||||
### Seed with content (optional)
|
||||
|
||||
Pre-load reference material before any session runs. `memories.create` creates a memory at the given `path`; if a memory already exists there the call returns `409` (`memory_path_conflict_error`, with the `conflicting_memory_id`). The store ID is the first positional argument.
|
||||
|
||||
```python
|
||||
client.beta.memory_stores.memories.create(
|
||||
store.id,
|
||||
path="/formatting_standards.md",
|
||||
content="All reports use GAAP formatting. Dates are ISO-8601...",
|
||||
)
|
||||
```
|
||||
|
||||
## Attach to a session
|
||||
|
||||
Memory stores go in the session's `resources[]` array alongside `file` and `github_repository` resources (see `shared/managed-agents-environments.md` → Resources). Memory stores attach at **session create time only** — `sessions.resources.add()` does not accept `memory_store`.
|
||||
|
||||
```python
|
||||
session = client.beta.sessions.create(
|
||||
agent=agent.id,
|
||||
environment_id=environment.id,
|
||||
resources=[
|
||||
{
|
||||
"type": "memory_store",
|
||||
"memory_store_id": store.id,
|
||||
"access": "read_write", # or "read_only"; default is "read_write"
|
||||
"instructions": "User preferences and project context. Check before starting any task.",
|
||||
}
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
| Field | Required | Notes |
|
||||
| --- | --- | --- |
|
||||
| `type` | ✅ | `"memory_store"` |
|
||||
| `memory_store_id` | ✅ | `memstore_...` |
|
||||
| `access` | — | `"read_write"` (default) or `"read_only"` — enforced at the filesystem level on the mount |
|
||||
| `instructions` | — | Session-specific guidance for this store, in addition to the store's `name`/`description`. ≤ 4,096 chars. |
|
||||
|
||||
**Max 8 memory stores per session.** Attach multiple when different slices of memory have different owners or lifecycles — e.g. one read-only shared-reference store plus one read-write per-user store, or one store per end-user/team/project sharing a single agent config.
|
||||
|
||||
### How the agent sees it (FUSE mount)
|
||||
|
||||
Each attached store is mounted in the session container at `/mnt/memory/<store-name>/`. The agent interacts with it using the standard file tools (`bash`, `read`, `write`, `edit`, `glob`, `grep`) — there are no dedicated memory tools. `access: "read_only"` makes the mount read-only at the filesystem level; `"read_write"` allows the agent to create, edit, and delete files under it. A short description of each mount (name, path, `instructions`, access) is automatically injected into the system prompt so the agent knows the store exists without you having to mention it.
|
||||
|
||||
Writes the agent makes under the mount are persisted back to the store and produce memory versions just like host-side `memories.update` calls.
|
||||
|
||||
## Manage memories directly (host-side)
|
||||
|
||||
Use these for review workflows, correcting bad memories, or seeding stores out-of-band.
|
||||
|
||||
### List
|
||||
|
||||
Returns `Memory | MemoryPrefix` entries — a `MemoryPrefix` (`type: "memory_prefix"`, just a `path`) is a directory-like node when listing hierarchically. Use `path_prefix` to scope (include a trailing slash: `"/notes/"` matches `/notes/a.md` but not `/notes_backup/old.md`) and `depth` to bound the tree walk. Pass `view="full"` to include `content` in each item; the default `"basic"` returns metadata only.
|
||||
|
||||
```python
|
||||
for m in client.beta.memory_stores.memories.list(store.id, path_prefix="/"):
|
||||
if m.type == "memory":
|
||||
print(f"{m.path} ({m.content_size_bytes} bytes, sha={m.content_sha256[:8]})")
|
||||
else: # "memory_prefix"
|
||||
print(f"{m.path}/")
|
||||
```
|
||||
|
||||
### Read
|
||||
|
||||
```python
|
||||
mem = client.beta.memory_stores.memories.retrieve(memory_id, memory_store_id=store.id)
|
||||
print(mem.content)
|
||||
```
|
||||
|
||||
`retrieve` defaults to `view="full"` (content included); `view` matters mainly on list endpoints.
|
||||
|
||||
### Create vs. update
|
||||
|
||||
| Operation | Addressed by | Semantics |
|
||||
| --- | --- | --- |
|
||||
| `memories.create(store_id, path=..., content=...)` | **Path** | Create at `path`. `409` (`memory_path_conflict_error`, includes `conflicting_memory_id`) if the path is already occupied. |
|
||||
| `memories.update(mem_id, memory_store_id=..., path=..., content=...)` | **`mem_...` ID** | Mutate existing memory. Change `content`, `path` (rename), or both. Renaming onto an occupied path returns the same `409 memory_path_conflict_error`. |
|
||||
|
||||
```python
|
||||
mem = client.beta.memory_stores.memories.create(
|
||||
store.id,
|
||||
path="/preferences/formatting.md",
|
||||
content="Always use tabs, not spaces.",
|
||||
)
|
||||
|
||||
client.beta.memory_stores.memories.update(
|
||||
mem.id,
|
||||
memory_store_id=store.id,
|
||||
path="/archive/2026_q1_formatting.md", # rename
|
||||
)
|
||||
```
|
||||
|
||||
### Optimistic concurrency (precondition on `update`)
|
||||
|
||||
`memories.update` accepts a `precondition` so you can read → modify → write back without clobbering a concurrent writer. The only supported type is `content_sha256`. On mismatch the API returns `409` (`memory_precondition_failed_error`) — re-read and retry against fresh state.
|
||||
|
||||
```python
|
||||
client.beta.memory_stores.memories.update(
|
||||
mem.id,
|
||||
memory_store_id=store.id,
|
||||
content="CORRECTED: Always use 2-space indentation.",
|
||||
precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
|
||||
)
|
||||
```
|
||||
|
||||
### Delete
|
||||
|
||||
```python
|
||||
client.beta.memory_stores.memories.delete(mem.id, memory_store_id=store.id)
|
||||
```
|
||||
|
||||
Pass `expected_content_sha256` for a conditional delete.
|
||||
|
||||
## Audit and rollback — memory versions
|
||||
|
||||
Every mutation creates an immutable `memver_...` snapshot. Versions accumulate for the lifetime of the parent memory; `memories.retrieve` always returns the current head, the version endpoints give you history.
|
||||
|
||||
| Operation that triggers it | `operation` field on the version |
|
||||
| --- | --- |
|
||||
| `memories.create` at a new path | `"created"` |
|
||||
| `memories.update` changing `content`, `path`, or both (or an agent-side write to the mount) | `"modified"` |
|
||||
| `memories.delete` | `"deleted"` |
|
||||
|
||||
Each version also records `created_by` — an actor object with `type` ∈ `session_actor` / `api_actor` / `user_actor` — and, after redaction, `redacted_at` + `redacted_by`.
|
||||
|
||||
### List versions
|
||||
|
||||
Newest-first, paginated. Filter by `memory_id`, `operation`, `session_id`, `api_key_id`, or `created_at_gte` / `created_at_lte`. Pass `view="full"` to include `content`; default is metadata-only.
|
||||
|
||||
```python
|
||||
for v in client.beta.memory_stores.memory_versions.list(store.id, memory_id=mem.id):
|
||||
print(f"{v.id}: {v.operation}")
|
||||
```
|
||||
|
||||
### Retrieve a version
|
||||
|
||||
```python
|
||||
version = client.beta.memory_stores.memory_versions.retrieve(
|
||||
version_id, memory_store_id=store.id
|
||||
)
|
||||
print(version.content)
|
||||
```
|
||||
|
||||
### Redact a version
|
||||
|
||||
Scrubs content from a historical version while preserving the audit trail (actor + timestamps). Clears `content`, `content_sha256`, `content_size_bytes`, and `path`; everything else stays. Use for leaked secrets, PII, or user-deletion requests.
|
||||
|
||||
```python
|
||||
client.beta.memory_stores.memory_versions.redact(version_id, memory_store_id=store.id)
|
||||
```
|
||||
|
||||
## Endpoint reference
|
||||
|
||||
See `shared/managed-agents-api-reference.md` → Memory Stores / Memories / Memory Versions for the full HTTP method/path tables. Raw HTTP base path:
|
||||
|
||||
```
|
||||
POST /v1/memory_stores
|
||||
POST /v1/memory_stores/{memory_store_id}/archive
|
||||
GET /v1/memory_stores/{memory_store_id}/memories
|
||||
PATCH /v1/memory_stores/{memory_store_id}/memories/{memory_id}
|
||||
GET /v1/memory_stores/{memory_store_id}/memory_versions
|
||||
POST /v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact
|
||||
```
|
||||
|
||||
For cURL examples and the CLI (`ant beta:memory-stores ...`), WebFetch the Memory URL in `shared/live-sources.md` → Managed Agents.
|
||||
125
.agents/skills/claude-api/shared/managed-agents-multiagent.md
Normal file
125
.agents/skills/claude-api/shared/managed-agents-multiagent.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# 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`).
|
||||
@@ -0,0 +1,82 @@
|
||||
# Managed Agents — Onboarding Flow
|
||||
|
||||
> **Invoked via `/claude-api managed-agents-onboard`?** You're in the right place. Run the interview below — don't summarize it back to the user, ask the questions.
|
||||
|
||||
Claude Managed Agents is a hosted agent: Anthropic runs the agent loop and provisions a sandboxed container per session where the agent's tools execute (or your own worker, with a `self_hosted` environment — see `shared/managed-agents-self-hosted-sandboxes.md`). You supply an **agent config** (tools, skills, model, system prompt — reusable, versioned) and an **environment config** (the sandbox — reusable across agents). Each run is a **session**.
|
||||
|
||||
The flow is four beats — **describe → agent → environment → session** — the same arc as the Console quickstart, and the same philosophy: **value before credentials**. The user goes from idea to a runnable session before any auth ask; each credential is *flagged* at the moment the design makes it relevant (§2) and *collected* once, at session setup (§4), where it binds (`sessions.create()`) and gets exercised (smoke-test). Read `shared/managed-agents-core.md` alongside this — it has full detail for each knob; this doc is the interview script.
|
||||
|
||||
---
|
||||
|
||||
## 1. Describe the task
|
||||
|
||||
**Open with a one-breath signpost and a single open prompt — don't guess, don't questionnaire.** In your own words:
|
||||
|
||||
> Managed Agents is hosted — Anthropic runs the agent loop, the sandbox, and the infrastructure; you just define the agent. We'll do this in three moves: the agent, the environment it runs in, then a live test session. So: describe the agent you want — what should it do, and what kicks it off (a person, an event, a schedule)?
|
||||
|
||||
Let them answer in full before configuring anything.
|
||||
|
||||
## 2. Configure the agent — propose, don't interrogate
|
||||
|
||||
Their description does the interview's work. Draft the agent config from it and **present it as a proposal with your suggestions inline** — the user reacts to a concrete config instead of answering a question list. At most one batched follow-up for true gaps. Suggest where the description gives you an opening:
|
||||
|
||||
- **Tools** — enable the full prebuilt toolset by default (`agent_toolset_20260401`: `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`). **Suggest MCP servers** for any third-party service the job names (GitHub, Linear, Slack, …) — and flag the credential each one implies as you suggest it ("Linear MCP → you'll need a Linear API token at kickoff"), so §4's auth step is a formality, not a surprise. Collection itself waits for §4. Custom tools only if the user's own app must answer calls (name, description, input schema — their handler code is theirs; don't generate it).
|
||||
- **Skills** — **suggest** prebuilt `xlsx`/`docx`/`pptx`/`pdf` when the job produces those artifacts; custom by `skill_id` (max 20 total per agent, prebuilt + custom combined).
|
||||
- **Outcome** — if the description implies checkable "done" criteria (or you can elicit them in the follow-up: not "a good report" but "a CSV with a numeric `price` column per SKU"), **suggest an Outcome kickoff** — the harness grades and iterates against a rubric (`shared/managed-agents-outcomes.md`).
|
||||
- **On-hand resources** — repos on disk (`github_repository`: URL, optional `mount_path`/`checkout`; token comes in §4), files to seed (Files API upload → `{type: "file", file_id, mount_path}`; read-only), if the job references them.
|
||||
- **Model** — default `claude-opus-5`; `claude-fable-5` for the hardest long-horizon work (`shared/model-migration.md` → Migrating to Claude Fable 5).
|
||||
|
||||
> ‼️ **PR creation needs the GitHub MCP server too** — a `github_repository` mount is filesystem-only. Edit in the mount → push branch via `bash` → open the PR via the MCP `create_pull_request` tool.
|
||||
|
||||
Full detail per knob: `shared/managed-agents-tools.md` (toolset, MCP, custom tools, skills), `shared/managed-agents-environments.md` (repos, files).
|
||||
|
||||
## 3. Environment
|
||||
|
||||
Usually zero or one question:
|
||||
|
||||
- **Reuse or create?** Environments are shared across agents — check for an existing one first.
|
||||
- **Networking** — default unrestricted egress. Switch to `limited` only if the user wants egress control — then set `allow_mcp_servers: true` or list every MCP server domain in `allowed_hosts`, or those tools fail silently.
|
||||
- **Suggest `self_hosted`** when the signals are there: tools must run on their own infra, secrets can't leave it, or they need binaries/data the cloud container won't have (`shared/managed-agents-self-hosted-sandboxes.md`; not available on Claude Platform on AWS). Otherwise `cloud` — don't raise it unprompted for simple jobs.
|
||||
|
||||
## 4. Session — auth, then test run
|
||||
|
||||
**Auth happens here — collect the credentials flagged in §2, now that the config is settled:** a vault (existing or `vaults.create()`) + `vaults.credentials.create()` for each MCP server declared in §2, `environment_variable` credentials for API keys the job uses (substituted at egress; the sandbox sees a placeholder), and the `authorization_token` for each repo mount. Credentials are write-only; MCP credentials match servers by URL and auto-refresh. See `shared/managed-agents-tools.md` → Vaults.
|
||||
|
||||
**Silent viability gate — run this yourself before emitting anything; surface only the gaps.** Walk the job clause by clause: every verb maps to an enabled tool or MCP server ("open a PR" → GitHub MCP, not just the mount); every MCP server and repo mount has its credential from the auth step; every external host is reachable under the networking choice; every file/repo/dataset the job references is mounted; "done" is checkable. If something's missing, say so and resolve it — don't emit a config you already know is under-resourced.
|
||||
|
||||
**Kickoff — pick one, never both:**
|
||||
- `user.message` — conversational.
|
||||
- `user.define_outcome` + rubric — when §2 settled on an Outcome; the harness iterates and grades until the rubric passes.
|
||||
- **Scheduled shape?** Skip per-session kickoff entirely — create a **deployment** (`deployments.create()` with `schedule` + `initial_events`); each firing creates the session autonomously. See `shared/managed-agents-scheduled-deployments.md`.
|
||||
|
||||
Mechanics to bake into the runtime code: session creation resolves resources (a bad mount surfaces there, before tokens) but does not itself provision the sandbox; open the event stream *before* sending the kickoff; break on `session.status_terminated`, or `session.status_idle` with a terminal `stop_reason` — anything except `requires_action` (`shared/managed-agents-client-patterns.md` Pattern 5); usage lands on `span.model_request_end`; artifacts land in `/mnt/session/outputs/` (`files.list({scope_id: session.id, ...})`).
|
||||
|
||||
## 5. Integrate — emit the code
|
||||
|
||||
Go straight from the last answer to the code — no preamble, no lecture about setup-vs-runtime; the two-block structure shows it. Generate **two clearly-separated blocks**:
|
||||
|
||||
**Block 1 — Setup (run once, store the IDs).** Prefer **YAML files + `ant` CLI** — agents and environments are version-controlled definitions users should check in and apply from CI:
|
||||
|
||||
1. `<name>.agent.yaml` (flat: `name`, `model`, `system`, `tools`, `mcp_servers`, `skills`) and `<name>.environment.yaml`
|
||||
2. ```sh
|
||||
AGENT_ID=$(ant beta:agents create < <name>.agent.yaml --transform id -r)
|
||||
ENV_ID=$(ant beta:environments create < <name>.environment.yaml --transform id -r)
|
||||
# CI sync: ant beta:agents update --agent-id "$AGENT_ID" --version N < <name>.agent.yaml
|
||||
```
|
||||
|
||||
SDK fallback if the user asks — and **required on Claude Platform on AWS**, where auth is SigV4 and the `ant` CLI has no SigV4 mode (use the platform client from `shared/claude-platform-on-aws.md`): label it `# ONE-TIME SETUP — run once, save the IDs` and call `environments.create()` → `agents.create()`.
|
||||
|
||||
> ⚠️ **Deployments are newer than the rest of the MA surface.** Before emitting `ant beta:deployments …` or `client.beta.deployments` / `client.beta.deployment_runs` calls, verify the user's installed CLI/SDK exposes them (`ant beta:deployments --help`; `hasattr(client.beta, "deployments")`). If not, emit raw HTTP against `POST /v1/deployments` with the `managed-agents-2026-04-01` beta header (plus `oauth-2025-04-20` when authenticating with a Bearer token from `ant auth print-credentials`), and leave an upgrade note marking what simplifies to SDK calls.
|
||||
|
||||
**Scheduled shape? The deployment is setup, not runtime.** Create it in Block 1, after the agent/environment IDs exist (`deployments.create()` with `schedule` + `initial_events`). Block 2 is then **not** a session loop — there is no per-run kickoff to send. Emit instead: a manual-run trigger (`POST /v1/deployments/{id}/run`) so the user can test now rather than wait for the first firing — the manual run doubles as the smoke test — plus a fetch helper (latest `deployment_runs` entry → `session_id` → Console URL + `files.list(scope_id=session_id)` for the artifacts).
|
||||
|
||||
**Block 2 — Runtime (every invocation; conversational and Outcome shapes).** SDK code in the detected language (Python/TS/cURL — SKILL.md → Language Detection); don't emit shell loops here:
|
||||
|
||||
1. Load `agent_id` + `env_id` from config/env
|
||||
2. `sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...])`, then print the Console URL so the user can watch live: `https://platform.claude.com/workspaces/default/sessions/{session.id}` (swap `default` for their workspace slug)
|
||||
3. **Smoke-test when the job depends on MCP servers, credentials, or locked-down hosts** — those failures don't surface at `sessions.create()`, only on first use. One cheap probe turn ("Confirm you can reach <service> and list 1–2 items; don't start the task"), verify, then send the real kickoff. Skip when there are no external dependencies.
|
||||
4. Open stream → send the §4 kickoff → loop with the terminal gate from §4.
|
||||
|
||||
> ⚠️ **Never emit `agents.create()` and `sessions.create()` in the same unguarded block** — that teaches creating a new agent per run, the #1 anti-pattern. Single-script requests: wrap creation in `if not os.getenv("AGENT_ID"):`.
|
||||
|
||||
Pull exact syntax from `{lang}/managed-agents/README.md` for your detected language (cURL and C#: use `curl/managed-agents.md` as the wire-level reference). Don't invent field names.
|
||||
108
.agents/skills/claude-api/shared/managed-agents-outcomes.md
Normal file
108
.agents/skills/claude-api/shared/managed-agents-outcomes.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# Managed Agents — Outcomes
|
||||
|
||||
An **outcome** elevates a session from *conversation* to *work*: you state what "done" looks like, and the harness runs an iterate → grade → revise loop until the artifact meets the rubric, hits `max_iterations`, or is interrupted. A separate **grader** (independent context window) scores each iteration against your rubric and feeds per-criterion gaps back to the agent.
|
||||
|
||||
The SDK sets the `managed-agents-2026-04-01` beta header automatically on all `client.beta.sessions.*` calls; no additional header is required for outcomes.
|
||||
|
||||
---
|
||||
|
||||
## The `user.define_outcome` event
|
||||
|
||||
Outcomes are not a field on `sessions.create()`. You create a normal session, then send a `user.define_outcome` event. The agent starts working on receipt — **do not also send a `user.message`** to kick it off.
|
||||
|
||||
You can collapse both calls into one by passing a single `user.define_outcome` in the session's `initial_events` array — same event, same rules, one round trip (see `shared/managed-agents-core.md` → Seeding a session with `initial_events`). More than one `user.define_outcome` in that array, or one without a `rubric`, rejects the whole create with a 400.
|
||||
|
||||
```python
|
||||
session = client.beta.sessions.create(
|
||||
agent=AGENT_ID,
|
||||
environment_id=ENVIRONMENT_ID,
|
||||
title="Financial analysis on Costco",
|
||||
)
|
||||
|
||||
client.beta.sessions.events.send(
|
||||
session_id=session.id,
|
||||
events=[
|
||||
{
|
||||
"type": "user.define_outcome",
|
||||
"description": "Build a DCF model for Costco in .xlsx",
|
||||
"rubric": {"type": "text", "content": RUBRIC_MD},
|
||||
# or: "rubric": {"type": "file", "file_id": rubric.id}
|
||||
"max_iterations": 5, # optional; default 3, max 20
|
||||
}
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
| Field | Type | Notes |
|
||||
|---|---|---|
|
||||
| `type` | `"user.define_outcome"` | |
|
||||
| `description` | string | The task. This is what the agent works toward — no separate `user.message` needed. |
|
||||
| `rubric` | `{type: "text", content}` \| `{type: "file", file_id}` | **Required.** Markdown with explicit, independently gradeable criteria. Upload once via `client.beta.files.upload(...)` (beta `files-api-2025-04-14`) to reuse across sessions. |
|
||||
| `max_iterations` | int | Optional. Default **3**, max **20**. |
|
||||
|
||||
The event is echoed back on the stream with a server-assigned `outcome_id` and `processed_at`.
|
||||
|
||||
> **Writing rubrics.** Use explicit, gradeable criteria ("CSV has a numeric `price` column"), not vibes ("data looks good") — the grader scores each criterion independently, so vague criteria produce noisy loops. If you don't have a rubric, have Claude analyze a known-good artifact and turn that analysis into one.
|
||||
|
||||
---
|
||||
|
||||
## Outcome-specific events
|
||||
|
||||
These appear on the standard event stream (`sessions.events.stream` / `.list`) alongside the usual `agent.*` / `session.*` events.
|
||||
|
||||
| Event | Payload highlights | Meaning |
|
||||
|---|---|---|
|
||||
| `span.outcome_evaluation_start` | `outcome_id`, `iteration` (0-indexed) | Grader began scoring iteration *N*. |
|
||||
| `span.outcome_evaluation_ongoing` | `outcome_id` | Heartbeat while the grader runs. Grader reasoning is opaque — you see *that* it's working, not *what* it's thinking. |
|
||||
| `span.outcome_evaluation_end` | `outcome_evaluation_start_id`, `outcome_id`, `iteration`, `result`, `explanation`, `usage` | Grader finished one iteration. `result` drives what happens next (table below). |
|
||||
|
||||
### `span.outcome_evaluation_end.result`
|
||||
|
||||
| `result` | Next |
|
||||
|---|---|
|
||||
| `satisfied` | Session → `idle`. Terminal for this outcome. |
|
||||
| `needs_revision` | Agent starts another iteration. |
|
||||
| `max_iterations_reached` | No further grader cycles. Agent may run one final revision, then session → `idle`. |
|
||||
| `failed` | Session → `idle`. Rubric fundamentally doesn't match the task (e.g. description and rubric contradict). |
|
||||
| `interrupted` | Emitted whenever a `user.interrupt` arrives while an outcome is active — **even if evaluation hadn't started**. In that case `outcome_evaluation_start_id` is an empty string rather than an event ID, so don't use it as a lookup key without checking. |
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "span.outcome_evaluation_end",
|
||||
"id": "sevt_01jkl...",
|
||||
"outcome_evaluation_start_id": "sevt_01def...",
|
||||
"outcome_id": "outc_01a...",
|
||||
"result": "satisfied",
|
||||
"explanation": "All 12 criteria met: revenue projections use 5 years of historical data, ...",
|
||||
"iteration": 0,
|
||||
"usage": { "input_tokens": 2400, "output_tokens": 350, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 1800 },
|
||||
"processed_at": "2026-03-25T14:03:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checking status & retrieving deliverables
|
||||
|
||||
**Status** — either watch the stream for `span.outcome_evaluation_end`, or poll the session and read `outcome_evaluations`:
|
||||
|
||||
```python
|
||||
session = client.beta.sessions.retrieve(session.id)
|
||||
for ev in session.outcome_evaluations:
|
||||
print(f"{ev.outcome_id}: {ev.result}") # outc_01a...: satisfied
|
||||
```
|
||||
|
||||
**Deliverables** — the agent writes to `/mnt/session/outputs/`. Once idle, fetch via the Files API with `scope_id=session.id`. This is the same session-outputs mechanism documented in `shared/managed-agents-environments.md` → Session outputs (including the dual-beta-header requirement on `files.list`).
|
||||
|
||||
---
|
||||
|
||||
## Interaction rules & pitfalls
|
||||
|
||||
- **One outcome at a time.** Chain by sending the next `user.define_outcome` only after the previous one's terminal `span.outcome_evaluation_end` (`satisfied` / `max_iterations_reached` / `failed` / `interrupted`). The session retains history across chained outcomes.
|
||||
- **Steering is allowed but optional.** You *may* send `user.message` events mid-outcome to nudge direction, but the agent already knows to keep working until terminal — don't send "keep going" prompts.
|
||||
- **`user.interrupt` pauses the current outcome** — it marks `result: "interrupted"` and leaves the session `idle`, ready for a new outcome or conversational turn.
|
||||
- **After terminal, the session is reusable** — continue conversationally or define a new outcome.
|
||||
- **Outcome ≠ session-create field.** Don't put `outcome`, `rubric`, or `description` on `sessions.create()` — outcomes are always sent as a `user.define_outcome` event.
|
||||
- **Idle-break gate is unchanged.** In your drain loop, keep using `event.type === 'session.status_idle' && event.stop_reason?.type !== 'requires_action'` — do **not** gate on `span.outcome_evaluation_end` alone (on `needs_revision` the session keeps running). See `shared/managed-agents-client-patterns.md` Pattern 5.
|
||||
|
||||
For the raw HTTP shapes and per-language SDK bindings beyond Python, WebFetch `https://platform.claude.com/docs/en/managed-agents/define-outcomes.md` (see `shared/live-sources.md`).
|
||||
71
.agents/skills/claude-api/shared/managed-agents-overview.md
Normal file
71
.agents/skills/claude-api/shared/managed-agents-overview.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Managed Agents — Overview
|
||||
|
||||
Managed Agents provisions a container per session as the agent's workspace. The agent loop runs on Anthropic's orchestration layer; the container is where the agent's *tools* execute — bash commands, file operations, code. You create a persisted **Agent** config (model, system prompt, tools, MCP servers, skills), then start **Sessions** that reference it. The session streams events back to you; you send user messages and tool results in.
|
||||
|
||||
## ⚠️ THE MANDATORY FLOW: Agent (once) → Session (every run)
|
||||
|
||||
**Why agents are separate objects: versioning.** An agent is a persisted, versioned config — every update creates a new immutable version, and sessions pin to a version at creation time. This lets you iterate on the agent (tweak the prompt, add a tool) without breaking sessions already running, roll back if a change regresses, and A/B test versions side-by-side. None of that works if you `agents.create()` fresh on every run.
|
||||
|
||||
Every session references a pre-created `/v1/agents` object. Create the agent once, store the ID, and reuse it across runs.
|
||||
|
||||
| Step | Call | Frequency |
|
||||
|---|---|---|
|
||||
| 1 | `POST /v1/agents` — `model`, `system`, `tools`, `mcp_servers`, `skills` live here | **ONCE.** Store `agent.id` **and** `agent.version`. |
|
||||
| 2 | `POST /v1/sessions` — `agent: "agent_abc123"` or `{type: "agent", id, version}` | **Every run.** String shorthand uses latest version. |
|
||||
|
||||
If you're about to write `sessions.create()` with `model`, `system`, or `tools` on the session body — **stop**. Those fields live on `agents.create()`. The session takes a *pointer* only.
|
||||
|
||||
**When generating code, separate setup from runtime.** `agents.create()` belongs in a setup script (or a guarded `if agent_id is None:` block), not at the top of the hot path. If the user's code calls `agents.create()` on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: define the agent as a version-controlled YAML manifest, apply it once with `ant beta:agents create < agent.yaml` (or a guarded setup script — see `shared/anthropic-cli.md`), persist the returned ID (config file, env var, secrets manager), and have every run load the ID and call `sessions.create()`.
|
||||
|
||||
**To change the agent's behavior, use `POST /v1/agents/{id}` — don't create a new one.** Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via `{type: "agent", id, version}`). See `shared/managed-agents-core.md` → Agents → Versioning. To change `tools`/`mcp_servers`/`vault_ids` on **one running session** without touching the agent object, use `sessions.update()` — see `shared/managed-agents-core.md` → Updating the agent configuration mid-session.
|
||||
|
||||
## Beta Headers
|
||||
|
||||
Managed Agents is in beta. The SDK sets required beta headers automatically:
|
||||
|
||||
| Beta Header | What it enables |
|
||||
| ------------------------------ | ---------------------------------------------------- |
|
||||
| `managed-agents-2026-04-01` | Agents, Environments, Sessions, Events, Session Resources, Session Threads, Outcomes, Multiagent, Vaults, Credentials, Memory Stores, Deployments |
|
||||
| `skills-2025-10-02` | Skills API (for managing custom skill definitions) |
|
||||
| `files-api-2025-04-14` | Files API for file uploads |
|
||||
|
||||
**Which beta header goes where:** The SDK sets `managed-agents-2026-04-01` automatically on `client.beta.{agents,environments,sessions,vaults,memory_stores,deployments,deployment_runs}.*` calls, and `files-api-2025-04-14` / `skills-2025-10-02` automatically on `client.beta.files.*` / `client.beta.skills.*` calls. You do NOT need to add the Skills or Files beta header when calling Managed Agents endpoints. On raw HTTP the Managed Agents header **grants Files API access on its own**, so uploading a file for use as a session resource does not need `files-api-2025-04-14` alongside it. (Direct Skills API calls over cURL do still need `skills-2025-10-02`; the `ant` CLI and the SDKs send it for you.) **Exception — session-scoped file listing:** `client.beta.files.list({scope_id: session.id})` is a Files endpoint that takes a Managed Agents parameter, so it needs **both** headers. Pass `betas: ["managed-agents-2026-04-01"]` explicitly on that call (the SDK adds the Files header; you add the Managed Agents one). See `shared/managed-agents-environments.md` → Session outputs.
|
||||
|
||||
|
||||
## Reading Guide
|
||||
|
||||
| User wants to... | Read these files |
|
||||
| -------------------------------------- | ------------------------------------------------------- |
|
||||
| **Get started from scratch / "help me set up an agent"** | `shared/managed-agents-onboarding.md` — guided interview (WHERE→WHO→WHAT→WATCH), then emit code |
|
||||
| Understand how the API works | `shared/managed-agents-core.md` |
|
||||
| See the full endpoint reference | `shared/managed-agents-api-reference.md` |
|
||||
| **Create an agent** (required first step) | `shared/managed-agents-core.md` (Agents section) + language file |
|
||||
| Update/version an agent | `shared/managed-agents-core.md` (Agents → Versioning) — update, don't re-create |
|
||||
| Create a session | `shared/managed-agents-core.md` + `{lang}/managed-agents/README.md` (cURL/C#: `curl/managed-agents.md`) |
|
||||
| Configure tools and permissions | `shared/managed-agents-tools.md` |
|
||||
| Set up MCP servers | `shared/managed-agents-tools.md` (MCP Servers section) |
|
||||
| Stream events / handle tool_use | `shared/managed-agents-events.md` + language file |
|
||||
| Get notified of session state changes via webhook (no polling) | `shared/managed-agents-webhooks.md` — Console-registered endpoint, HMAC verify, thin payload + fetch |
|
||||
| Define an outcome / rubric-graded iterate loop | `shared/managed-agents-outcomes.md` — `user.define_outcome` event, grader, `span.outcome_evaluation_*` events |
|
||||
| Coordinate multiple agents / subagents / threads | `shared/managed-agents-multiagent.md` — `multiagent: {type: "coordinator", agents: [...]}` on the agent, session threads, cross-posted tool confirmations |
|
||||
| Set up environments | `shared/managed-agents-environments.md` + language file |
|
||||
| Run tool execution in your own infra / VPC (self-hosted sandbox) | `shared/managed-agents-self-hosted-sandboxes.md` — `config:{type:"self_hosted"}`, `ANTHROPIC_ENVIRONMENT_KEY`, `EnvironmentWorker.run()` / `ant beta:worker poll` |
|
||||
| Upload files / attach repos | `shared/managed-agents-environments.md` (Resources) |
|
||||
| Give agents persistent memory across sessions | `shared/managed-agents-memory.md` — memory stores, `memory_store` session resource, preconditions, versions/redact |
|
||||
| Define agents/environments as version-controlled YAML; drive the API from the shell | `shared/anthropic-cli.md` — `ant beta:agents create < agent.yaml`, `--transform`, `@file` inlining |
|
||||
| Store credentials (MCP auth, API keys for CLIs/SDKs) | `shared/managed-agents-tools.md` (Vaults section) — `mcp_oauth` / `static_bearer` / `environment_variable` |
|
||||
| Call a non-MCP API / CLI that needs a secret | `shared/managed-agents-tools.md` (Vaults section) — `environment_variable` credential, substituted at egress. If that doesn't fit (e.g. self-hosted sandboxes), `shared/managed-agents-client-patterns.md` Pattern 9 keeps the secret host-side via a custom tool |
|
||||
| Run an agent on a recurring cron schedule | `shared/managed-agents-scheduled-deployments.md` — deployments, deployment runs, pause/auto-pause |
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Agent FIRST, then session — NO EXCEPTIONS** — the session's `agent` field accepts **only** a string ID or `{type: "agent", id, version}`. `model`, `system`, `tools`, `mcp_servers`, `skills` are **top-level fields on `POST /v1/agents`**, never on `sessions.create()`. If the user hasn't created an agent, that is step zero of every example.
|
||||
- **Agent ONCE, not every run** — `agents.create()` is a setup step. Store the returned `agent_id` and reuse it; don't call `agents.create()` at the top of your hot path. If the agent's config needs to change, `POST /v1/agents/{id}` — each update creates a new version, and sessions can pin to a specific version for reproducibility.
|
||||
- **MCP auth goes through vaults** — the agent's `mcp_servers` array declares `{type, name, url}` only (no auth). Credentials live in vaults (`client.beta.vaults.credentials.create`) and attach to sessions via `vault_ids`. Anthropic auto-refreshes OAuth tokens using the stored refresh token. Vaults also hold `environment_variable` credentials for non-MCP services (CLIs, SDKs, direct API calls) — substituted at egress, never visible in the sandbox.
|
||||
- **Reconcile resources before the first run** — a session with a clear ask but a missing tool, credential, data mount, or context will discover the gap mid-run, then flail and give up. Before creating the session, check that every action in the task maps to a configured tool/MCP server, every MCP server has a vault credential, and every referenced file/host is mounted/reachable. When helping a user set one up, run the reconciliation in `shared/managed-agents-onboarding.md` → §3 Pre-flight viability check.
|
||||
- **Stream to get events** — `GET /v1/sessions/{id}/events/stream` is the primary way to receive agent output in real-time.
|
||||
- **SSE stream has no replay — reconnect with consolidation** — if the stream drops while a `agent.tool_use`, `agent.mcp_tool_use`, or `agent.custom_tool_use` is pending resolution (`user.tool_confirmation` for the first two, `user.custom_tool_result` for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with `GET /v1/sessions/{id}/events/stream` , fetch `GET /v1/sessions/{id}/events`, dedupe by event ID, then proceed. See `shared/managed-agents-events.md` → Reconnecting after a dropped stream.
|
||||
- **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `sessions.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events.
|
||||
- **Messages queue** — you can send events while the session is `running` or `idle`; they're processed in order. No need to wait for a response before sending the next message.
|
||||
- **Environment `config.type` is `"cloud"` or `"self_hosted"`** — `cloud` runs the container on Anthropic's infrastructure; `self_hosted` moves tool execution to your own (see `shared/managed-agents-self-hosted-sandboxes.md`).
|
||||
- **Archive is permanent on every resource** — archiving an agent, environment, session, vault, credential, or memory store makes it read-only with no unarchive. For agents, environments, and memory stores specifically, archived resources cannot be referenced by new sessions (existing sessions continue). Do not call `.archive()` on a production agent, environment, or memory store as cleanup — **always confirm with the user before archiving**.
|
||||
@@ -0,0 +1,146 @@
|
||||
# Managed Agents — Scheduled Deployments
|
||||
|
||||
A **scheduled deployment** runs an agent on a recurring cron schedule — each firing creates a session autonomously. Use it for predictable-cadence work: nightly triage, weekly compliance scans, hourly monitors.
|
||||
|
||||
Requires the `managed-agents-2026-04-01` beta header (the SDK sets it automatically for `client.beta.deployments.*` / `client.beta.deployment_runs.*` calls).
|
||||
|
||||
## Create a deployment
|
||||
|
||||
A deployment bundles everything a session needs (agent, environment, optional files / GitHub / memory stores / vaults) plus a `schedule` and the `initial_events` that kick off each run:
|
||||
|
||||
- `agent` and `environment_id` are required — same shapes as `sessions.create` (see `shared/managed-agents-core.md`).
|
||||
- `initial_events` must contain at least one starting event — a `user.message` **or** a `user.define_outcome`. (A deployment's `initial_events` also accepts `system.message`, which a session's does not.)
|
||||
- `schedule` takes a cron `expression` and an IANA `timezone`. Minute-level granularity is the maximum.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://api.anthropic.com/v1/deployments \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-H "anthropic-beta: managed-agents-2026-04-01" \
|
||||
-H "content-type: application/json" \
|
||||
-d @- <<EOF
|
||||
{
|
||||
"name": "Weekly compliance scan",
|
||||
"agent": "$AGENT_ID",
|
||||
"environment_id": "$ENVIRONMENT_ID",
|
||||
"initial_events": [
|
||||
{"type": "user.message", "content": [{"type": "text", "text": "Run the weekly compliance scan."}]}
|
||||
],
|
||||
"schedule": {
|
||||
"type": "cron",
|
||||
"expression": "0 20 * * 5",
|
||||
"timezone": "America/New_York"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
```python
|
||||
deployment = client.beta.deployments.create(
|
||||
name="Weekly compliance scan",
|
||||
agent=agent.id,
|
||||
environment_id=environment.id,
|
||||
initial_events=[
|
||||
{
|
||||
"type": "user.message",
|
||||
"content": [{"type": "text", "text": "Run the weekly compliance scan."}],
|
||||
},
|
||||
],
|
||||
schedule={
|
||||
"type": "cron",
|
||||
"expression": "0 20 * * 5",
|
||||
"timezone": "America/New_York",
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
The response is a deployment object (`depl_` ID prefix). Check `schedule.upcoming_runs_at` — the next fire times — to confirm the schedule parses the way you intended:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "depl_01xyz",
|
||||
"status": "active",
|
||||
"paused_reason": null,
|
||||
"schedule": {
|
||||
"type": "cron",
|
||||
"expression": "0 20 * * 5",
|
||||
"timezone": "America/New_York",
|
||||
"last_run_at": null,
|
||||
"upcoming_runs_at": ["2026-05-09T00:00:00Z", "2026-05-16T00:00:00Z", "2026-05-23T00:00:00Z"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`upcoming_runs_at` reflects the exact configured schedule, but **execution is jittered to distribute load: up to 15% of the interval between runs, floored at 5 seconds and capped at 9 minutes.** An hourly deployment can therefore fire up to 9 minutes late; don't build a downstream deadline that assumes the listed timestamp. Maximum **1000 scheduled deployments per organization** (contact Anthropic support for more).
|
||||
|
||||
### Cron and timezone semantics
|
||||
|
||||
- **Expression:** standard POSIX cron (`minute hour day-of-month month day-of-week`).
|
||||
- **Timezone:** IANA identifier (e.g. `"America/Los_Angeles"`).
|
||||
- **DST:** literal wall-clock matching — `"0 20 * * *"` in `America/New_York` fires at 8:00 PM local regardless of EST/EDT.
|
||||
|
||||
> ⚠️ **DST edge:** wall-clock times that don't exist on a spring-forward day (e.g. 2AM) are **skipped**; times that occur twice on a fall-back day **fire twice**. Schedule outside the 1–3AM local window, or use UTC, when missed or duplicate executions are unacceptable.
|
||||
|
||||
## Deployment runs
|
||||
|
||||
Every trigger attempt — successful or not — writes a **deployment run** record (`drun_` prefix), so you can audit failures independent of the session lifecycle. A successful run carries the created `session_id`; follow that session via the event stream (`shared/managed-agents-events.md`) or webhooks (`shared/managed-agents-webhooks.md`) as usual. A failed run carries an `error` whose `type` explains why session creation was rejected.
|
||||
|
||||
```python
|
||||
# All runs for a deployment
|
||||
for run in client.beta.deployment_runs.list(deployment_id=deployment.id):
|
||||
print(run.created_at, run.session_id or run.error.type)
|
||||
|
||||
# Failures only
|
||||
for run in client.beta.deployment_runs.list(deployment_id=deployment.id, has_error=True):
|
||||
print(run.created_at, run.error.type, run.error.message)
|
||||
```
|
||||
|
||||
```typescript
|
||||
for await (const run of client.beta.deploymentRuns.list({
|
||||
deployment_id: deployment.id,
|
||||
has_error: true,
|
||||
})) {
|
||||
console.log(run.created_at, run.error?.type, run.error?.message);
|
||||
}
|
||||
```
|
||||
|
||||
Raw HTTP: `GET /v1/deployment_runs?deployment_id=...&has_error=true`. To retrieve a single run by ID, `GET /v1/deployment_runs/{deployment_run_id}` (SDK: `client.beta.deployment_runs.retrieve(run_id)`) — a `deployment_run.*` webhook event carries the run ID as its `data.id`.
|
||||
|
||||
A failed run looks like:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "deployment_run",
|
||||
"id": "drun_01abc124",
|
||||
"deployment_id": "depl_01xyz",
|
||||
"trigger_context": { "type": "schedule", "scheduled_at": "2026-05-09T00:00:00Z" },
|
||||
"session_id": null,
|
||||
"error": { "type": "environment_archived", "message": "environment `env_01abc` is archived" },
|
||||
"agent": { "type": "agent", "id": "agent_01ghi789", "version": 3 },
|
||||
"created_at": "2026-05-09T00:00:01Z"
|
||||
}
|
||||
```
|
||||
|
||||
Error types include `environment_archived`, `agent_archived`, `vault_not_found`, `session_rate_limited`, and `service_unavailable`.
|
||||
|
||||
The outcome of each **scheduled** run (started/succeeded/failed) and each deployment lifecycle change (created/updated/paused/unpaused/archived/deleted) is also delivered as a webhook event — see `shared/managed-agents-webhooks.md` for the `deployment.*` and `deployment_run.*` event types — so you can react without polling. Manual runs do **not** emit `deployment_run.*` webhook events.
|
||||
|
||||
## Lifecycle: pause / unpause / archive
|
||||
|
||||
| Operation | SDK | Effect |
|
||||
|---|---|---|
|
||||
| Pause | `client.beta.deployments.pause(id)` | Suppresses scheduled triggers go-forward. Sessions already running continue. **Manual runs are still permitted while paused.** Sets `paused_reason: {"type": "manual"}`. |
|
||||
| Unpause | `client.beta.deployments.unpause(id)` | Resumes from the next scheduled occurrence. **Missed triggers are not backfilled.** Clears `paused_reason`. |
|
||||
| Archive | `client.beta.deployments.archive(id)` | **Terminal** — the schedule stops and the deployment can no longer be modified. Use pause for anything reversible. |
|
||||
|
||||
Raw HTTP: `POST /v1/deployments/{deployment_id}/pause` (likewise `/unpause`, `/archive`).
|
||||
|
||||
### Failure behavior
|
||||
|
||||
- **Rate-limited:** recorded immediately as a `session_rate_limited` run, **no retry** — the schedule simply tries again at the next occurrence. (Rate limits on API calls *inside* a session are handled by the session itself.)
|
||||
- **Other failed runs** (e.g. `environment_archived`, `vault_not_found`, `service_unavailable`): the run records the `error.type` — monitor runs and fix the referenced resource, or pause the deployment.
|
||||
- **Agent archived:** the deployment is automatically **archived** (terminal) in the same operation. **Agent deleted:** the next scheduled trigger detects the missing agent and archives the deployment then. Either way no deployment run is recorded, and no further sessions are created.
|
||||
|
||||
## Manual runs
|
||||
|
||||
`POST /v1/deployments/{deployment_id}/run` (SDK: `client.beta.deployments.run(id)`) creates a session immediately and writes a run with `trigger_context.type: "manual"`. Use it to **test a deployment before committing to the schedule** — and remember it works even while the deployment is paused.
|
||||
@@ -0,0 +1,174 @@
|
||||
# Managed Agents — Self-Hosted Sandboxes
|
||||
|
||||
With `config.type: "self_hosted"`, the **agent loop stays on Anthropic's orchestration layer** but **tool execution moves to infrastructure you control** — bash, file ops, and code run inside your container, so filesystem contents and network egress never leave your environment. Contrast with `config.type: "cloud"`, where Anthropic runs the container. Connectivity is **outbound-only**: your worker long-polls Anthropic's work queue; Anthropic never dials into your network.
|
||||
|
||||
## Flow
|
||||
|
||||
```
|
||||
1. Create environment: config: {type: "self_hosted"} → env_...
|
||||
2. Generate environment key (Console, on the environment page) → sk-ant-oat01-... as ANTHROPIC_ENVIRONMENT_KEY
|
||||
3. Run a worker: EnvironmentWorker.run() or ant beta:worker poll
|
||||
4. Sessions reference environment_id=env_... exactly as for cloud
|
||||
```
|
||||
|
||||
## Create the environment
|
||||
|
||||
```python
|
||||
client = anthropic.Anthropic()
|
||||
|
||||
environment = client.beta.environments.create(
|
||||
name="self-hosted", config={"type": "self_hosted"}
|
||||
)
|
||||
```
|
||||
|
||||
`{"type": "self_hosted"}` is the entire config — there are no pool, capacity, or networking sub-fields; you control those on your side.
|
||||
|
||||
## Run a worker — SDK (primary path)
|
||||
|
||||
`EnvironmentWorker` wraps the poll → dispatch → tool-execute loop. `.run()` is the always-on loop; `.run_one()` / `.runOne()` handles one work item (for webhook-driven wake).
|
||||
|
||||
**Python — always-on:**
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import os
|
||||
from anthropic import AsyncAnthropic
|
||||
from anthropic.lib.environments import EnvironmentWorker
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
|
||||
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
|
||||
async with AsyncAnthropic(auth_token=environment_key) as client:
|
||||
await EnvironmentWorker(
|
||||
client,
|
||||
environment_id=environment_id,
|
||||
environment_key=environment_key,
|
||||
workdir="/workspace",
|
||||
).run()
|
||||
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
**TypeScript — always-on:**
|
||||
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";
|
||||
|
||||
const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
|
||||
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
|
||||
const client = new Anthropic({ authToken: environmentKey });
|
||||
const ctrl = new AbortController();
|
||||
process.once("SIGTERM", () => ctrl.abort());
|
||||
|
||||
await new EnvironmentWorker({
|
||||
client,
|
||||
environmentId,
|
||||
environmentKey,
|
||||
workdir: "/workspace",
|
||||
signal: ctrl.signal
|
||||
}).run();
|
||||
```
|
||||
|
||||
**Customizing tools.** `EnvironmentWorker` runs the built-in toolset by default. To add or replace tools, use `AgentToolContext(workdir=, client=, session_id=)` with `beta_agent_toolset(env)` / `betaAgentToolset(env)` and pass the resulting tools to the lower-level `tool_runner()`. Skills attached to the agent are downloaded into `{workdir}/skills/<name>/` before tool calls begin (`AgentToolContext` handles this when given `client` and `session_id`). Downloaded skill files are marked executable automatically by the CLI and SDK; if you implement skills download yourself, you set permissions.
|
||||
|
||||
> **Runtime deps:** the SDK helpers require `/bin/bash` at that exact path. The TypeScript SDK additionally requires `unzip`, `tar`, and Node.js 22+. These are resolved at fixed paths and do **not** respect `PATH` overrides.
|
||||
|
||||
## Run a worker — `ant` CLI (fixed tools)
|
||||
|
||||
The `ant` CLI ships a worker with the fixed built-in toolset (`bash`, `read`, `write`, `edit`, `glob`, `grep`). Install per `shared/anthropic-cli.md`, then:
|
||||
|
||||
```sh
|
||||
export ANTHROPIC_ENVIRONMENT_KEY=sk-ant-oat01-...
|
||||
ant beta:worker poll --environment-id env_... --workdir /workspace
|
||||
```
|
||||
|
||||
- `--workdir` is the directory tools operate in (default `.`); tool calls are sandboxed to it.
|
||||
- `--environment-key` overrides the env var.
|
||||
- `--on-work <script>` runs your script per work item (e.g. to spin a fresh container per session — see Container orchestration below).
|
||||
- `--unrestricted-paths`, `--max-idle` (default `60s`), `--log-format` — see `ant beta:worker poll --help`.
|
||||
- Flags fall back to env vars (`ANTHROPIC_ENVIRONMENT_ID`, `ANTHROPIC_ENVIRONMENT_KEY`).
|
||||
- Exits cleanly on SIGTERM/SIGINT after draining in-flight work.
|
||||
- **Fixed toolset** — for custom tools, use the SDK worker above.
|
||||
|
||||
Inside an `--on-work` container, run `ant beta:worker run --workdir <dir>` as the entrypoint.
|
||||
|
||||
## Webhook-driven wake (instead of always-on)
|
||||
|
||||
Register a webhook for `session.status_run_started` (see `shared/managed-agents-webhooks.md`), verify the delivery, then drain one work item with `.run_one()`:
|
||||
|
||||
```python
|
||||
import os
|
||||
import anthropic
|
||||
from anthropic.lib.environments import EnvironmentWorker
|
||||
|
||||
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
|
||||
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
|
||||
client = anthropic.AsyncAnthropic(
|
||||
auth_token=environment_key,
|
||||
) # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env for webhooks.unwrap()
|
||||
|
||||
|
||||
async def handle(raw: bytes, headers: dict[str, str]) -> dict:
|
||||
event = client.beta.webhooks.unwrap(raw.decode(), headers=headers)
|
||||
if event.data.type != "session.status_run_started":
|
||||
return {"status": "ignored"}
|
||||
await EnvironmentWorker(
|
||||
client,
|
||||
environment_id=environment_id,
|
||||
environment_key=environment_key,
|
||||
workdir="/workspace",
|
||||
).run_one()
|
||||
return {"status": "ok"}
|
||||
```
|
||||
|
||||
TypeScript: same shape with `client.beta.webhooks.unwrap(body, {headers})` and `new EnvironmentWorker({...}).runOne()`.
|
||||
|
||||
## Container orchestration (mid-level)
|
||||
|
||||
`EnvironmentWorker.run()` polls and executes tools in the same process. To run each session in its **own** container, use the mid-level poller in a thin orchestrator — Python `client.beta.environments.work.poller(environment_id=, environment_key=, drain=, block_ms=, reclaim_older_than_ms=, auto_stop=)`; TypeScript `new WorkPoller({client, environmentId, environmentKey, autoStop})` from `@anthropic-ai/sdk/helpers/beta/environments` — and, for each yielded `work` item, start a fresh container with these env vars injected, whose entrypoint runs `ant beta:worker run` or an `EnvironmentWorker(...).run_one()`. `block_ms` is 1–999 (or `None` for non-blocking); `reclaim_older_than_ms` re-claims items leased to a dead worker; `drain` stops once the queue is empty; `auto_stop` posts a stop signal after the iterator exits (set `False` when the launched container owns the stop call). **Go's poller has no `auto_stop` opt-out** — it calls `work.Stop` when the handler returns, so block in the handler until the session completes rather than detaching.
|
||||
|
||||
| Env var | Value |
|
||||
|---|---|
|
||||
| `ANTHROPIC_SESSION_ID` | `work.data.id` |
|
||||
| `ANTHROPIC_WORK_ID` | `work.id` |
|
||||
| `ANTHROPIC_ENVIRONMENT_ID` | `work.environment_id` |
|
||||
| `ANTHROPIC_ENVIRONMENT_KEY` | pass through |
|
||||
| `ANTHROPIC_BASE_URL` | pass through |
|
||||
|
||||
Skip items where `work.data.type != "session"`.
|
||||
|
||||
## Monitoring & control
|
||||
|
||||
These are **control-plane** calls — authenticate with `x-api-key` (not the environment key); `managed-agents-2026-04-01` beta header. **Call them from outside the worker host** — setting `ANTHROPIC_API_KEY` on the worker host exposes an organization-scoped credential to agent tool calls.
|
||||
|
||||
| SDK (`client.beta.environments.work.*`) | REST | CLI | Returns |
|
||||
|---|---|---|---|
|
||||
| `stats(environment_id)` | `GET /v1/environments/{id}/work/stats` | `ant beta:environments:work stats` | `{type:"work_queue_stats", depth, pending, oldest_queued_at, workers_polling}` |
|
||||
| `stop(work_id, environment_id=)` | `POST /v1/environments/{id}/work/{work_id}/stop` | `ant beta:environments:work stop` | `work.state` |
|
||||
|
||||
## What changes vs `cloud`
|
||||
|
||||
| Concern | `cloud` | `self_hosted` |
|
||||
|---|---|---|
|
||||
| Container lifecycle, hardening, networking | Anthropic | **You** — run non-root, read-only rootfs, drop caps; egress is whatever your VPC/firewall allows |
|
||||
| `file` / `github_repository` resource mounting | Anthropic mounts into the container | **You** — pass pointers via `sessions.create(metadata={...})` and have your orchestrator fetch/clone before dispatch |
|
||||
| `memory_store` resources | Supported | **Not yet supported** |
|
||||
| Vault `environment_variable` credentials | Supported (substituted at Anthropic-managed egress) | **Not yet supported** — egress is yours, so there's nowhere to substitute the secret. Use MCP credentials or a host-side custom tool (`shared/managed-agents-client-patterns.md` Pattern 9) |
|
||||
| Built-in tools | Via `agent_toolset_20260401` | Supplied by your worker (`EnvironmentWorker` default / `beta_agent_toolset(env)` / `ant` CLI fixed set) |
|
||||
| Skills download | Automatic | `EnvironmentWorker` / `AgentToolContext` fetch into `{workdir}/skills/` (needs `client` + `session_id`) |
|
||||
| Claude Platform on AWS | Supported | **Not available** |
|
||||
| SDK worker helpers | All SDKs | **Python, TypeScript, Go only** (`EnvironmentWorker` / poller not in Java, Ruby, PHP, or C#) — use one of those three or the `ant` CLI |
|
||||
|
||||
## Credentials
|
||||
|
||||
| Credential | Format | Scope |
|
||||
|---|---|---|
|
||||
| `ANTHROPIC_ENVIRONMENT_KEY` | `sk-ant-oat01-...` | One environment's work queue. Generate in Console ("Generate environment key"). Pass as `auth_token=` / `authToken` on the client **and** as `environment_key=` / `environmentKey` on `EnvironmentWorker`. Store in a secrets manager; rotate on exposure. |
|
||||
| `ANTHROPIC_WEBHOOK_SIGNING_KEY` | `whsec_...` | Webhook signature verification (if using webhook-driven wake). The SDK reads this env var automatically for `client.beta.webhooks.unwrap()`. |
|
||||
|
||||
## Security — what you own
|
||||
|
||||
Container hardening; egress restriction (there is no default); `ANTHROPIC_ENVIRONMENT_KEY` custody and rotation; one workspace + environment per trust boundary when running untrusted code; least-privilege for the tool process; log retention and redaction. **Anthropic cannot**: fast-revoke a leaked environment key, verify your image or supply chain, sandbox tool execution inside your container, or enforce retention after tool output reaches your infrastructure. See the Self-Hosted Sandboxes Security page in `shared/live-sources.md` for the full checklist.
|
||||
371
.agents/skills/claude-api/shared/managed-agents-tools.md
Normal file
371
.agents/skills/claude-api/shared/managed-agents-tools.md
Normal file
@@ -0,0 +1,371 @@
|
||||
# Managed Agents — Tools & Skills
|
||||
|
||||
## Tools
|
||||
|
||||
### Server tools vs client tools
|
||||
|
||||
| Type | Who runs it | How it works |
|
||||
|---|---|---|
|
||||
| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Anthropic, on the session's container (for `cloud` envs; for `self_hosted`, **your** worker supplies and runs them — see `shared/managed-agents-self-hosted-sandboxes.md`) | File ops, bash, web search, etc. Enable all at once or configure individually with `enabled: true/false`. |
|
||||
| **MCP tools** (`mcp_toolset`) | Anthropic's orchestration layer | Capabilities exposed by connected MCP servers. Grant access per-server via the toolset. |
|
||||
| **Custom tools** | **You** — your application handles the call and returns results | Agent emits a `agent.custom_tool_use` event, session goes `idle`, you send back a `user.custom_tool_result` event. |
|
||||
|
||||
**Recommendation:** Enable all prebuilt tools via `agent_toolset_20260401`, then disable individually as needed.
|
||||
|
||||
**Versioning:** The toolset is a versioned, static resource. When underlying tools change, a new toolset version is created (hence `_20260401`) so you always know exactly what you're getting.
|
||||
|
||||
### Agent Toolset
|
||||
|
||||
The `agent_toolset_20260401` provides these built-in tools:
|
||||
|
||||
| Tool | Description |
|
||||
| ---------------------- | ---------------------------------------- |
|
||||
| `bash` | Execute bash commands in a shell session |
|
||||
| `read` | Read a file from the local filesystem, including text, images, PDFs, and Jupyter notebooks |
|
||||
| `write` | Write a file to the local filesystem |
|
||||
| `edit` | Perform string replacement in a file |
|
||||
| `glob` | Fast file pattern matching using glob patterns |
|
||||
| `grep` | Text search using regex patterns |
|
||||
| `web_fetch` | Fetch content from a URL |
|
||||
| `web_search` | Search the web for information |
|
||||
|
||||
Enable the full toolset:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{ "type": "agent_toolset_20260401" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Per-Tool Configuration
|
||||
|
||||
Override defaults for individual tools. This example enables everything except bash:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"type": "agent_toolset_20260401",
|
||||
"default_config": { "enabled": true },
|
||||
"configs": [
|
||||
{ "name": "bash", "enabled": false }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Required | Description |
|
||||
|---|---|---|
|
||||
| `type` | ✅ | `"agent_toolset_20260401"` |
|
||||
| `default_config` | ❌ | Applied to all tools. `{ "enabled": bool, "permission_policy": {...} }` |
|
||||
| `configs` | ❌ | Per-tool overrides: `[{ "name": "...", "enabled": bool, "permission_policy": {...} }]` |
|
||||
|
||||
### Permission Policies
|
||||
|
||||
Control when server-executed tools (agent toolset + MCP) run automatically vs wait for approval. Does not apply to custom tools.
|
||||
|
||||
| Policy | Behavior |
|
||||
|---|---|
|
||||
| `always_allow` | Tool executes automatically (default) |
|
||||
| `always_ask` | Session emits `session.status_idle` and pauses until you send a `user.tool_confirmation` event |
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "agent_toolset_20260401",
|
||||
"default_config": {
|
||||
"enabled": true,
|
||||
"permission_policy": { "type": "always_allow" }
|
||||
},
|
||||
"configs": [
|
||||
{ "name": "bash", "permission_policy": { "type": "always_ask" } }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Responding to `always_ask`:** Send a `user.tool_confirmation` event with `tool_use_id` from the triggering `agent_tool_use`/`mcp_tool_use` event:
|
||||
|
||||
```json
|
||||
{ "type": "user.tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" }
|
||||
{ "type": "user.tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "message": "Read .env.example instead" }
|
||||
```
|
||||
|
||||
The optional `message` on a deny is delivered to the agent so it can adjust its approach.
|
||||
|
||||
To enable only specific tools, flip the default off and opt-in per tool:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"type": "agent_toolset_20260401",
|
||||
"default_config": { "enabled": false },
|
||||
"configs": [
|
||||
{ "name": "bash", "enabled": true },
|
||||
{ "name": "read", "enabled": true }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Tools (Client-Side)
|
||||
|
||||
Custom tools are executed by **your application**, not Anthropic. The flow:
|
||||
|
||||
1. Agent decides to use the tool → session emits a `agent.custom_tool_use` event with inputs
|
||||
2. Session goes `idle` waiting for you
|
||||
3. Your application executes the tool
|
||||
4. You send back a `user.custom_tool_result` event with the output
|
||||
5. Session resumes `running`
|
||||
|
||||
No permission policy needed — you're the one executing.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"type": "custom",
|
||||
"name": "get_weather",
|
||||
"description": "Fetch current weather for a city.",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"city": { "type": "string", "description": "City name" }
|
||||
},
|
||||
"required": ["city"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### MCP Servers
|
||||
|
||||
MCP (Model Context Protocol) servers expose standardized third-party capabilities (e.g. Asana, GitHub, Linear). **Configuration is split across agent and vault:**
|
||||
|
||||
1. **Agent creation** declares which servers to connect to (`type`, `name`, `url` — no auth). The agent's `mcp_servers` array has no auth field.
|
||||
2. **Vault** stores the OAuth credentials. Attach via `vault_ids` on session create.
|
||||
|
||||
This keeps secrets out of reusable agent definitions. Each vault credential is tied to one MCP server URL; Anthropic matches credentials to servers by URL.
|
||||
|
||||
**Agent side — declare servers (no auth):**
|
||||
|
||||
| Field | Required | Description |
|
||||
|---|---|---|
|
||||
| `type` | ✅ | `"url"` |
|
||||
| `name` | ✅ | Unique name — referenced by `mcp_toolset.mcp_server_name` |
|
||||
| `url` | ✅ | The MCP server's endpoint URL (Streamable HTTP transport) |
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp_servers": [
|
||||
{ "type": "url", "name": "linear", "url": "https://mcp.linear.app/mcp" }
|
||||
],
|
||||
"tools": [
|
||||
{ "type": "mcp_toolset", "mcp_server_name": "linear" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Session side — attach vault:**
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": "agent_abc123",
|
||||
"environment_id": "env_abc123",
|
||||
"vault_ids": ["vlt_abc123"]
|
||||
}
|
||||
```
|
||||
|
||||
> 💡 **Per-tool enablement (empirical):** `mcp_toolset` has been observed accepting `default_config: {enabled: false}` + `configs: [{name, enabled: true}]` for an allowlist pattern. The API ref shows only the minimal `{type, mcp_server_name}` form.
|
||||
|
||||
> 💡 **Changing tools/MCP servers on a running session:** `sessions.update()` can replace `agent.tools`, `agent.mcp_servers`, and `vault_ids` while the session is `idle` — a session-local override that doesn't touch the agent object. See `shared/managed-agents-core.md` → Updating the agent configuration mid-session.
|
||||
|
||||
**Large tool outputs.** If a tool returns more than **100,000 characters (roughly 25,000 tokens)**, the output is automatically offloaded to a file in the sandbox — the agent receives a truncated preview plus the file path and can `read` the full content. No configuration required. The threshold is in *characters*, not tokens, and applies to built-in agent tools as well as MCP tools.
|
||||
|
||||
**Invalid vault credentials don't block session creation.** If a vault credential is invalid for a declared MCP server, the session still creates successfully; a `session.error` event describes the MCP auth failure, and auth retries on the next `session.status_idle` → `session.status_running` transition.
|
||||
|
||||
> ⚠️ **MCP auth tokens ≠ REST API tokens.** Hosted MCP servers (`mcp.notion.com`, `mcp.linear.app`, etc.) typically require **OAuth bearer tokens**, not the service's native API keys. A Notion `ntn_` integration token authenticates against Notion's REST API but will **not** work as a vault credential for the Notion MCP server. These are different auth systems.
|
||||
|
||||
### Vaults — the credential store
|
||||
|
||||
**Vaults** store credentials that Anthropic manages on your behalf. Two credential categories:
|
||||
|
||||
- **MCP credentials** (`mcp_oauth`, `static_bearer`) — keyed by `mcp_server_url`. When the agent connects to a server at that URL, the token is injected automatically. **Matching is normalized, not byte-exact:** scheme and host are lowercased, and default ports and trailing slashes are stripped, so host casing, an explicit default port, or a trailing slash won't break the match. A different path, subdomain, or *non-default* port will. If nothing matches, the connection is attempted unauthenticated. `mcp_oauth` tokens are auto-refreshed via the standard OAuth 2.0 `refresh_token` grant. This is the only way to authenticate MCP servers.
|
||||
- **Environment variables** (`environment_variable`) — keyed by `secret_name` (the env var name). The sandbox sees only an **opaque placeholder**; the real secret is substituted into the outbound request **at egress**. Use this for any service that authenticates through an environment variable: CLIs (`aws`, `gcloud`, `stripe`), SDKs, or direct `curl` calls from the `bash` tool.
|
||||
|
||||
Secret fields you supply (`token`, `access_token`, `refresh_token`, `client_secret`, `secret_value`) are write-only — never returned in API responses.
|
||||
|
||||
#### Credentials and the sandbox
|
||||
|
||||
Vaults store credentials; those credentials **never enter the sandbox**. This is a deliberate security boundary — code running in the sandbox (including anything the agent writes) cannot read or exfiltrate a vaulted credential, even under prompt injection. Instead, credentials are injected by Anthropic-side proxies **after** a request leaves the sandbox:
|
||||
|
||||
- **MCP tool calls** are routed through an Anthropic-side proxy that fetches the credential from the vault and adds it to the outbound request.
|
||||
- **Git operations on attached GitHub repositories** (`git pull`, `git push`, GitHub REST calls) are routed through a git proxy that injects the `github_repository` resource's `authorization_token` the same way.
|
||||
- **Environment-variable credentials** appear in the sandbox as an opaque placeholder; the real value replaces the placeholder at egress, on requests to the credential's allowed hosts only. Substitution covers request **headers and body only** — a secret embedded in the **URL path** is never substituted, so path-secret endpoints (e.g. Slack incoming-webhook URLs) can't be vaulted; use header-based auth instead (for Slack: a bot token in `Authorization` via `chat.postMessage`).
|
||||
|
||||
**When vault credentials don't fit** (e.g. self-hosted sandboxes — `environment_variable` is not yet supported there), **register a custom tool:** the agent emits `agent.custom_tool_use`, your orchestrator (which already holds the credential) executes the call and returns `user.custom_tool_result` over the same authenticated event stream. No public endpoint is exposed; the sandbox never sees the secret. See `shared/managed-agents-client-patterns.md` → Pattern 9.
|
||||
|
||||
**Do not put API keys in the system prompt or user messages as a workaround** — they persist in the session's event history.
|
||||
|
||||
> Formerly known internally as TATs (Tool/Tenant Access Tokens).
|
||||
|
||||
**Flow:**
|
||||
|
||||
1. Create a vault (`client.beta.vaults.create(...)`) — one per tenant/user, or one shared, depending on your model
|
||||
2. Add credentials to it (`client.beta.vaults.credentials.create(...)`) — MCP credentials are keyed by MCP server URL; environment-variable credentials by `secret_name`
|
||||
3. Reference the vault on session create via `vault_ids: ["vlt_..."]`
|
||||
4. Anthropic auto-refreshes OAuth tokens before they expire and substitutes secrets at runtime
|
||||
|
||||
**MCP OAuth credential shape**:
|
||||
|
||||
```json
|
||||
{
|
||||
"display_name": "Notion (workspace-foo)",
|
||||
"auth": {
|
||||
"type": "mcp_oauth",
|
||||
"mcp_server_url": "https://mcp.notion.com/mcp",
|
||||
"access_token": "<current access token>",
|
||||
"expires_at": "2026-04-02T14:00:00Z",
|
||||
"refresh": {
|
||||
"refresh_token": "<refresh token>",
|
||||
"client_id": "<your OAuth client_id>",
|
||||
"token_endpoint": "https://api.notion.com/v1/oauth/token",
|
||||
"token_endpoint_auth": { "type": "none" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `refresh` block is what enables auto-refresh — `token_endpoint` is where Anthropic posts the `refresh_token` grant. `token_endpoint_auth` is a discriminated union:
|
||||
|
||||
| `type` | Shape | Use when |
|
||||
|---|---|---|
|
||||
| `"none"` | `{type: "none"}` | Public OAuth client (no secret) |
|
||||
| `"client_secret_basic"` | `{type: "client_secret_basic", client_secret: "..."}` | Confidential client, secret via HTTP Basic auth |
|
||||
| `"client_secret_post"` | `{type: "client_secret_post", client_secret: "..."}` | Confidential client, secret in request body |
|
||||
|
||||
Omit `refresh` entirely if you only have an access token with no refresh capability — it'll work until it expires, then the agent loses access.
|
||||
|
||||
> 💡 **Getting an OAuth token.** How you obtain the initial access and refresh tokens depends on the MCP server — consult its documentation. Once you have them, store them in a vault credential using the shape above; Anthropic auto-refreshes via the `refresh.token_endpoint` from there.
|
||||
|
||||
**Environment-variable credential shape**:
|
||||
|
||||
```json
|
||||
{
|
||||
"display_name": "Twilio API key for sandbox",
|
||||
"auth": {
|
||||
"type": "environment_variable",
|
||||
"secret_name": "TWILIO_API_KEY",
|
||||
"secret_value": "sk-your-secret-here",
|
||||
"networking": {
|
||||
"type": "limited",
|
||||
"allowed_hosts": ["api.twilio.com", "*.twilio.com"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`networking.allowed_hosts` controls which outbound hosts the secret can be substituted for — `{"type": "limited", "allowed_hosts": [...]}` or `{"type": "unrestricted"}` if you can't enumerate the domains in advance. Limiting is strongly recommended: it prevents the key from ever being sent to unauthorized hosts.
|
||||
|
||||
**`injection_location`** (optional, sibling of `networking`) controls **where** in the outbound request the secret is substituted — `{header: bool, body: bool}`. The two are independent: `allowed_hosts` scopes *which hosts* a substituted request can target; `injection_location` scopes *which parts of the request* the secret is substituted into across all of those hosts. Most services read an API key from a request header, so `{"header": true}` is the narrower configuration — request bodies are often assembled from content the agent is working with, making the body the broader exposure surface. A placeholder in a disabled location is **neither substituted nor stripped** — the literal opaque placeholder string is sent to the third party in that location.
|
||||
|
||||
| Operation | `injection_location` semantics |
|
||||
|---|---|
|
||||
| Create credential | Omit the field entirely → both locations enabled. Provide the object → any field you omit defaults to `false` (`{"header": true}` creates a header-only credential). |
|
||||
| Update credential | Fields **merge individually** — `{"body": false}` disables body substitution and leaves `header` unchanged. For a running session, the update takes effect on the session's next operation. |
|
||||
|
||||
A credential must have at least one location enabled; a create or update that would disable both returns 400, as does explicit `null` for the object or either field (omit instead). The response always returns both fields with their resolved values.
|
||||
|
||||
> ⚠️ **Credentials created in the Console are header-only by default** — unlike the API, where omitting the field enables both. If your client sends the secret in the request body (a form-encoded token request, for example), the placeholder passes through literally and the service rejects it with its own authentication error. Tick body injection in the Console form, or `POST` the credential with `{"injection_location": {"body": true}}`.
|
||||
|
||||
> ⚠️ **Two networking layers, both required.** `networking.allowed_hosts` on the credential controls which requests *use the secret*, not which requests are *allowed*. The agent must also be able to reach the domain at the **environment level** (`unrestricted`, or the host listed in the environment's `allowed_hosts` — see `shared/managed-agents-environments.md`). A domain missing from either layer means the secret-substituted request fails.
|
||||
|
||||
> ⚠️ **Client-side validation caveat.** Substitution happens at egress, not inside the sandbox — clients that validate the credential *format* locally before making a network request (e.g. a CLI that checks the key starts with `sk-`) will see the opaque placeholder and may fail at startup. If a client rejects the credential before any network call, that's why.
|
||||
|
||||
> 💡 **Scope the key minimally.** The agent can do anything the key allows; a key with broader permissions than the task needs increases the blast radius if the agent behaves unexpectedly.
|
||||
|
||||
**Not supported with self-hosted sandboxes** — `environment_variable` credentials require Anthropic-managed egress. See `shared/managed-agents-self-hosted-sandboxes.md`.
|
||||
|
||||
**Constraints (all credential types):**
|
||||
|
||||
- **Unique key per vault.** `mcp_server_url` (MCP credentials) and `secret_name` (environment-variable credentials) must be unique among active credentials in a vault; duplicates return a 409.
|
||||
- **Keys are immutable.** Secret values, `display_name`, and (on environment-variable credentials) `injection_location` can be updated; to change `mcp_server_url`, `secret_name`, `token_endpoint`, or `client_id`, archive the credential and create a new one. Archiving purges the secret and frees the key for a replacement.
|
||||
- **Maximum 20 credentials per vault.**
|
||||
- Credentials are stored as provided and **not validated until session runtime** — an invalid credential surfaces as an authentication or downstream error during the session, which is emitted but does not block the session from continuing.
|
||||
|
||||
**Scoping:** Vaults are workspace-scoped. Anyone with developer+ role in the API workspace can create, read (metadata only — secrets are write-only), and attach vaults. `vault_ids` can be set at session **create** time but not via session update (the SDK docstring says "Not yet supported; requests setting this field are rejected").
|
||||
|
||||
---
|
||||
|
||||
## Skills
|
||||
|
||||
Skills are reusable, filesystem-based resources that provide your agent with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations.
|
||||
|
||||
Two types — both work the same way; the agent automatically uses them when relevant to the task at hand:
|
||||
|
||||
| Type | What it is |
|
||||
|---|---|
|
||||
| **Pre-built Anthropic skills** | Common document tasks (PowerPoint, Excel, Word, PDF). Reference by name (e.g. `xlsx`). |
|
||||
| **Custom skills** | Skills you've created in your organization via the Skills API. Reference by `skill_id` + optional `version`. |
|
||||
|
||||
**Max 20 skills per agent.** Agent creation uses `managed-agents-2026-04-01`; the separate Skills API (for managing custom skill definitions) uses `skills-2025-10-02`.
|
||||
|
||||
### Enabling skills on a session
|
||||
|
||||
Skills are attached to the **agent** definition via `agents.create()`:
|
||||
|
||||
```ts
|
||||
const agent = await client.beta.agents.create(
|
||||
{
|
||||
name: "Financial Agent",
|
||||
model: "claude-opus-5",
|
||||
system: "You are a financial analysis agent.",
|
||||
skills: [
|
||||
{ type: "anthropic", skill_id: "xlsx" },
|
||||
{ type: "custom", skill_id: "skill_abc123", version: "latest" },
|
||||
],
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
Python:
|
||||
|
||||
```python
|
||||
agent = client.beta.agents.create(
|
||||
name="Financial Agent",
|
||||
model="claude-opus-5",
|
||||
system="You are a financial analysis agent.",
|
||||
skills=[
|
||||
{"type": "anthropic", "skill_id": "xlsx"},
|
||||
{"type": "custom", "skill_id": "skill_abc123", "version": "latest"},
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
**Skill reference fields:**
|
||||
|
||||
| Field | Anthropic skill | Custom skill |
|
||||
|---|---|---|
|
||||
| `type` | `"anthropic"` | `"custom"` |
|
||||
| `skill_id` | Skill name (e.g. `"xlsx"`, `"docx"`, `"pptx"`, `"pdf"`) | Skill ID from Skills API (e.g. `"skill_abc123"`) |
|
||||
| `version` | `"latest"` or a specific version number | `"latest"` or a specific version number |
|
||||
|
||||
`version` is optional on **both** kinds and defaults to `"latest"` — it is not custom-skill-only.
|
||||
|
||||
### Skills API
|
||||
|
||||
| Operation | Method | Path |
|
||||
| --------------------- | -------- | ----------------------------------------------- |
|
||||
| Create Skill | `POST` | `/v1/skills` |
|
||||
| List Skills | `GET` | `/v1/skills` |
|
||||
| Get Skill | `GET` | `/v1/skills/{id}` |
|
||||
| Delete Skill | `DELETE` | `/v1/skills/{id}` |
|
||||
| Create Version | `POST` | `/v1/skills/{id}/versions` |
|
||||
| List Versions | `GET` | `/v1/skills/{id}/versions` |
|
||||
| Get Version | `GET` | `/v1/skills/{id}/versions/{version}` |
|
||||
| Delete Version | `DELETE` | `/v1/skills/{id}/versions/{version}` |
|
||||
|
||||
143
.agents/skills/claude-api/shared/managed-agents-webhooks.md
Normal file
143
.agents/skills/claude-api/shared/managed-agents-webhooks.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# Managed Agents — Webhooks
|
||||
|
||||
Anthropic can POST to your HTTPS endpoint when a Managed Agents resource changes state — an alternative to holding an SSE stream or polling. Payloads are **thin** (event type + resource IDs only); on receipt, fetch the resource for current state. Every delivery is HMAC-signed.
|
||||
|
||||
> **Direction matters.** This page covers *Anthropic → you* notifications about session/vault state. It does **not** cover *third-party → you* webhooks that *trigger* a session (e.g. a GitHub push handler that calls `sessions.create()`) — that's ordinary application code on your side with no Anthropic-specific wire format.
|
||||
|
||||
---
|
||||
|
||||
## Register an endpoint (Console only)
|
||||
|
||||
Console → **Manage → Webhooks**. There is no programmatic endpoint-management API yet. Secret rotation is supported from the same page.
|
||||
|
||||
| Field | Constraint |
|
||||
|---|---|
|
||||
| URL | HTTPS on port 443, publicly resolvable hostname |
|
||||
| Event types | Subscribe per `data.type` — an endpoint receives only the types it is subscribed to |
|
||||
| Signing secret | `whsec_`-prefixed, 32 bytes, **shown once at creation** — store it |
|
||||
|
||||
---
|
||||
|
||||
## Verify the signature
|
||||
|
||||
Every delivery carries the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. **Use the SDK's `client.beta.webhooks.unwrap()`** — it verifies the signature, rejects payloads more than ~5 minutes old, and returns the parsed event. It reads the `whsec_` secret from `ANTHROPIC_WEBHOOK_SIGNING_KEY`. Pass the headers through untouched; don't hand-roll verification against a single `X-Webhook-Signature` header, which is not the wire format.
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
from flask import Flask, request
|
||||
|
||||
client = anthropic.Anthropic() # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
|
||||
app = Flask(__name__)
|
||||
|
||||
|
||||
@app.route("/webhook", methods=["POST"])
|
||||
def webhook():
|
||||
try:
|
||||
event = client.beta.webhooks.unwrap(
|
||||
request.get_data(as_text=True),
|
||||
headers=dict(request.headers),
|
||||
)
|
||||
except Exception:
|
||||
return "invalid signature", 400
|
||||
|
||||
if event.id in seen_event_ids: # dedupe retries — id is per-event, not per-delivery
|
||||
return "", 204
|
||||
seen_event_ids.add(event.id)
|
||||
|
||||
match event.data.type:
|
||||
case "session.status_idled":
|
||||
session = client.beta.sessions.retrieve(event.data.id)
|
||||
notify_user(session)
|
||||
case "vault_credential.refresh_failed":
|
||||
alert_oncall(event.data.id)
|
||||
|
||||
return "", 204
|
||||
```
|
||||
|
||||
Pass the **raw request body** to `unwrap()` — frameworks that re-serialize JSON (Express `.json()`, Flask `.get_json()`) change the bytes and break the MAC. For other languages, look up the `beta.webhooks.unwrap` binding in the SDK repo (`shared/live-sources.md`); don't hand-roll verification.
|
||||
|
||||
---
|
||||
|
||||
## Payload envelope
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "event",
|
||||
"id": "whe_9d5c1f7e...",
|
||||
"created_at": "2026-03-18T14:05:22Z",
|
||||
"data": {
|
||||
"type": "session.status_idled",
|
||||
"id": "session_01XYZ...",
|
||||
"organization_id": "8a3d2f1e-...",
|
||||
"workspace_id": "c7b0e4d9-..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Switch on `data.type`, fetch the resource by `data.id`, return any **2xx** to acknowledge. `created_at` is when the *event occurred*, not when the delivery was attempted — the `webhook-timestamp` header is the clock for the attempt (see Delivery behavior).
|
||||
|
||||
The top-level `id` is the same value as the `webhook-id` header, and it is per *event*, not per delivery — every retry carries it unchanged. Dedupe on it.
|
||||
|
||||
---
|
||||
|
||||
## Supported `data.type` values
|
||||
|
||||
| `data.type` | Fires when |
|
||||
|---|---|
|
||||
| `session.status_scheduled` | Session created and ready to accept events |
|
||||
| `session.status_run_started` | Agent execution kicked off (every transition to `running`) |
|
||||
| `session.status_idled` | Agent awaiting input (tool approval, custom tool result, or next message) |
|
||||
| `session.status_rescheduled` | A transient error occurred; the session is retrying automatically |
|
||||
| `session.status_terminated` | Session ended — **on completion or on error**, not error-only |
|
||||
| `session.thread_created` | Multiagent: coordinator opened a new subagent thread |
|
||||
| `session.thread_idled` | Multiagent: a subagent thread is waiting for input |
|
||||
| `session.thread_terminated` | A thread ended — child completed its work, or the thread was archived. **Child threads only**; the primary thread's end surfaces as `session.status_terminated` |
|
||||
| `session.outcome_evaluation_ended` | Outcome grader finished one iteration |
|
||||
| `session.updated` | Session properties changed (name, configuration) |
|
||||
| `session.deleted` | Session permanently deleted — no object left to fetch; treat the event itself as final |
|
||||
| `vault.archived` | Vault was archived |
|
||||
| `vault.created` | Vault was created |
|
||||
| `vault.deleted` | Vault was deleted — a `vault_credential.deleted` also fires per underlying credential. No object left to fetch; treat the event itself as final |
|
||||
| `vault_credential.archived` | Credential archived, directly or via vault archival |
|
||||
| `vault_credential.created` | Vault credential was created |
|
||||
| `vault_credential.deleted` | Credential deleted, directly or via vault deletion. No object left to fetch; treat the event itself as final |
|
||||
| `vault_credential.refresh_failed` | MCP OAuth vault credential failed to refresh |
|
||||
| `agent.created` | Agent created |
|
||||
| `agent.updated` | A new agent version was published. Updates that do not create a new version do **not** fire this. |
|
||||
| `agent.archived` | Agent archived |
|
||||
| `agent.deleted` | Agent permanently deleted — no object left to fetch; treat the event itself as final |
|
||||
| `deployment.created` | Scheduled deployment created |
|
||||
| `deployment.updated` | Deployment properties changed (e.g. schedule edited) |
|
||||
| `deployment.paused` | Deployment paused — by request, or automatically when a scheduled run fails with a **non-recoverable** error (archived agent, missing environment). Recoverable failures, including rate limits, do **not** auto-pause. |
|
||||
| `deployment.unpaused` | Deployment unpaused; schedule resumes |
|
||||
| `deployment.archived` | Deployment archived — directly, or as a result of agent archival/deletion |
|
||||
| `deployment.deleted` | Deployment permanently deleted — no object left to fetch; treat the event itself as final |
|
||||
| `deployment_run.started` | A **scheduled** run started. Manual runs do **not** emit `deployment_run.*` events. |
|
||||
| `deployment_run.succeeded` | Scheduled run created its session. Same `data.id` (the run ID) as the run's `.started` event — fetch the deployment run for its `session_id`, then subscribe to the session events to follow the work. |
|
||||
| `deployment_run.failed` | Scheduled run did not create a session. Same `data.id` as the run's `.started` event — fetch the deployment run for `error.type` / `error.message`. |
|
||||
| `environment.created` | Environment created |
|
||||
| `environment.updated` | Environment updated with at least one changed field. A no-op update emits nothing. |
|
||||
| `environment.archived` | Environment archived. Re-archiving an already-archived environment emits nothing. |
|
||||
| `environment.deleted` | Environment deleted, including delete of an already-archived one. No object left to fetch; treat the event itself as final |
|
||||
| `memory_store.created` | Memory store created — by you, or by an Anthropic-operated process that clones one of your stores |
|
||||
| `memory_store.archived` | Memory store archived. Re-archiving an already-archived store emits nothing. |
|
||||
| `memory_store.deleted` | Memory store deleted, including delete of an already-archived one. Cascades to its memories and versions **without** per-memory events — this single event is the signal. No object left to fetch; treat it as final |
|
||||
|
||||
> **There is deliberately no `memory_store.updated`.** Individual memories and memory versions emit no webhook events at all, and neither do an environment's self-hosted work items. If you need per-memory change tracking, poll the memory-versions endpoints (`shared/managed-agents-memory.md`).
|
||||
|
||||
> These are **webhook** `data.type` values — a separate namespace from SSE event types (`session.status_idle`, `span.outcome_evaluation_end`, etc. in `shared/managed-agents-events.md`). Don't reuse SSE constants in webhook handlers.
|
||||
|
||||
---
|
||||
|
||||
## Delivery behavior & pitfalls
|
||||
|
||||
- **Duplicates.** An endpoint can receive the same event more than once; every attempt carries the same top-level `event.id` (= the `webhook-id` header). Dedupe on it.
|
||||
- **Subscription scope.** An event reaches only endpoints subscribed to its type **at the moment it is emitted**. An event emitted while nothing was subscribed is never delivered, and subscribing later does not backfill — subscribe before you need the type.
|
||||
- **No ordering guarantee.** Events are not delivered in occurrence order: `session.status_idled` may arrive before `session.outcome_evaluation_ended`, and a `.deleted` can arrive before the `.archived` for the same resource. **Drive state from the resource you fetch, not from arrival order.**
|
||||
- **Retries: up to three attempts** per endpoint per event, with jittered exponential backoff between 5 and 120 seconds. A response that triggers auto-disable is never retried. **After the last attempt fails the event is dropped** — not queued, and with no signal that it was lost. Webhooks are not a durable log: if you must observe every transition, reconcile by listing or fetching the resource.
|
||||
- **`webhook-timestamp` is re-stamped on every attempt**, so retries don't fail the SDK's five-minute freshness check. It times the *delivery attempt*; use the payload's `created_at` for when the event occurred.
|
||||
- **Auto-disable — three triggers**, each setting `disabled_reason`, all reversible from Console (events emitted while disabled are **not** replayed):
|
||||
- A `3xx` response. Redirects are never followed; disables immediately, on the first attempt. Reason: `auto-disabled: endpoint URL returned a redirect (3xx)`.
|
||||
- The URL resolves to a non-public IP at connect time. Disables immediately. Reason: `auto-disabled: endpoint URL resolved to an invalid address`.
|
||||
- Continuous failure for a sustained period. Reason: `auto-disabled after sustained delivery failures`. **The trigger is duration, not a delivery count** — a single `2xx` resets the window, so one flaky event can't disable the endpoint.
|
||||
- **Thin payload is intentional.** Don't expect `stop_reason`, `outcome_evaluations`, credential secrets, etc. on the webhook body — fetch the resource.
|
||||
1548
.agents/skills/claude-api/shared/model-migration.md
Normal file
1548
.agents/skills/claude-api/shared/model-migration.md
Normal file
File diff suppressed because it is too large
Load Diff
138
.agents/skills/claude-api/shared/models.md
Normal file
138
.agents/skills/claude-api/shared/models.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# Claude Model Catalog
|
||||
|
||||
**Only use exact model IDs listed in this file.** Never guess or construct model IDs — incorrect IDs will cause API errors. Use aliases wherever available. For the latest information, WebFetch the Models Overview URL in `shared/live-sources.md`, or query the Models API directly (see Programmatic Model Discovery below).
|
||||
|
||||
## Programmatic Model Discovery
|
||||
|
||||
For **live** capability data — context window, max output tokens, feature support (thinking, vision, effort, structured outputs, etc.) — query the Models API instead of relying on the cached tables below. Use this when the user asks "what's the context window for X", "does model X support vision/thinking/effort", "which models support feature Y", or wants to select a model by capability at runtime.
|
||||
|
||||
```python
|
||||
m = client.models.retrieve("claude-opus-4-8")
|
||||
m.id # "claude-opus-4-8"
|
||||
m.display_name # "Claude Opus 4.8"
|
||||
m.max_input_tokens # context window (int)
|
||||
m.max_tokens # max output tokens (int)
|
||||
|
||||
# capabilities is an untyped nested dict — bracket access, check ["supported"] at the leaf
|
||||
caps = m.capabilities
|
||||
caps["image_input"]["supported"] # vision
|
||||
caps["thinking"]["types"]["adaptive"]["supported"] # adaptive thinking
|
||||
caps["effort"]["max"]["supported"] # effort: max (also low/medium/high)
|
||||
caps["structured_outputs"]["supported"]
|
||||
caps["context_management"]["compact_20260112"]["supported"]
|
||||
|
||||
# filter across all models — iterate the page object directly (auto-paginates); do NOT use .data
|
||||
[m for m in client.models.list()
|
||||
if m.capabilities["thinking"]["types"]["adaptive"]["supported"]
|
||||
and m.max_input_tokens >= 200_000]
|
||||
```
|
||||
|
||||
Top-level fields (`id`, `display_name`, `max_input_tokens`, `max_tokens`) are typed attributes. `capabilities` is a dict — use bracket access, not attribute access. The API returns the full capability tree for every model with `supported: true/false` at each leaf, so bracket chains are safe without `.get()` guards. TypeScript SDK: same method names, also auto-paginates on iteration.
|
||||
|
||||
### Raw HTTP
|
||||
|
||||
```bash
|
||||
curl https://api.anthropic.com/v1/models/claude-opus-4-8 \
|
||||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||
-H "anthropic-version: 2023-06-01"
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "claude-opus-4-8",
|
||||
"display_name": "Claude Opus 4.8",
|
||||
"max_input_tokens": 1000000,
|
||||
"max_tokens": 128000,
|
||||
"capabilities": {
|
||||
"image_input": {"supported": true},
|
||||
"structured_outputs": {"supported": true},
|
||||
"thinking": {"supported": true, "types": {"enabled": {"supported": false}, "adaptive": {"supported": true}}},
|
||||
"effort": {"supported": true, "low": {"supported": true}, …, "max": {"supported": true}},
|
||||
…
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Current Models (recommended)
|
||||
|
||||
| Friendly Name | Alias (use this) | Full ID | Context | Max Output | Status |
|
||||
|-------------------|---------------------|-------------------------------|----------------|------------|--------|
|
||||
| Claude Fable 5 | `claude-fable-5` | — | 1M | 128K | Active |
|
||||
| Claude Mythos 5 | `claude-mythos-5` | — | 1M | 128K | Active (Project Glasswing only) |
|
||||
| Claude Opus 5 | `claude-opus-5` | — | 1M | 128K | Active |
|
||||
| Claude Opus 4.8 | `claude-opus-4-8` | — | 1M | 128K | Active |
|
||||
| Claude Opus 4.7 | `claude-opus-4-7` | — | 1M | 128K | Active |
|
||||
| Claude Opus 4.6 | `claude-opus-4-6` | — | 1M | 128K | Active |
|
||||
| Claude Sonnet 5 | `claude-sonnet-5` | — | 1M | 128K | Active |
|
||||
| Claude Sonnet 4.6 | `claude-sonnet-4-6` | - | 1M | 128K | Active |
|
||||
| Claude Haiku 4.5 | `claude-haiku-4-5` | `claude-haiku-4-5-20251001` | 200K | 64K | Active |
|
||||
|
||||
### Model Descriptions
|
||||
- **Claude Fable 5** — Anthropic's most capable widely released model, for the most demanding reasoning and long-horizon agentic work. Same API surface as Opus 4.7/4.8 with one new breaking change: an explicit `thinking: {type: "disabled"}` returns a 400 — omit the `thinking` parameter instead (thinking is always on; the raw chain of thought is never returned — summaries via `display: "summarized"`). Same tokenizer as Opus 4.8 (token counts roughly unchanged vs Opus 4.7/4.8). Safety classifiers may return `stop_reason: "refusal"`. No assistant prefill. Requires 30-day data retention (not available under ZDR). $10/$50 per MTok; 1M context window (default), 128K max output. See `shared/model-migration.md` → Migrating to Claude Fable 5.
|
||||
- **Claude Mythos 5** — Same capabilities, pricing, limits, and API behavior as Claude Fable 5; only the model ID differs. Available exclusively through Project Glasswing, where it joins (and succeeds) the invitation-only Claude Mythos Preview (`claude-mythos-preview`). Use it only when the org participates in Project Glasswing; otherwise use claude-fable-5.
|
||||
- **Claude Opus 5** — For complex agentic coding and enterprise work; a step-change over Claude Opus 4.8, strongest on deep reasoning, agentic and long-horizon work, and test-time compute scaling, at half the cost of Claude Fable 5 (Claude Fable 5 remains the highest-capability tier). Safety classifiers can return `stop_reason: "refusal"` — handle it before reading `content`. A drop-in upgrade at Opus 4.8's pricing ($5/$25 per MTok) with the same feature set. Thinking is on by default (omitting `thinking` runs adaptive; `{type: "adaptive"}` is equivalent), and `thinking: {type: "disabled"}` is available only at effort `high` or lower — pairing it with `xhigh`/`max` returns a 400. Raw thinking tokens are never returned. Full effort ladder through `max`; 512-token prompt-cache minimum (down from 1024 on Opus 4.8); fast mode on the Claude API only. Elevated cybersecurity safeguards. Separate rate-limit bucket from the combined Opus 4.x pool. 1M context window (default and maximum), 128K max output. See `shared/model-migration.md` → Migrating to Claude Opus 5.
|
||||
- **Claude Opus 4.8** — The most capable model in the Opus 4 series — highly autonomous, state-of-the-art on long-horizon agentic work, knowledge work, and memory; clearer, warmer writing. Same API surface as Opus 4.7 (adaptive thinking only; sampling parameters and `budget_tokens` removed). 1M context window at standard API pricing (no long-context premium). See `shared/model-migration.md` → Migrating to Opus 4.8 — a 4.7 → 4.8 move is a model-ID swap plus prompt re-tuning, no new breaking changes.
|
||||
- **Claude Opus 4.7** — Previous-generation Opus. Highly autonomous; strong on long-horizon agentic work, knowledge work, vision, and memory. Adaptive thinking only; sampling parameters and `budget_tokens` removed. 1M context window. See `shared/model-migration.md` → Migrating to Opus 4.7.
|
||||
- **Claude Opus 4.6** — Older Opus. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window.
|
||||
- **Claude Sonnet 5** — The best combination of speed and intelligence in the Sonnet tier; near-Opus quality on coding and agentic work. Adaptive thinking on by default (omitting `thinking` runs adaptive); manual `budget_tokens` removed; non-default sampling parameters rejected. `effort` supports `low`/`medium`/`high`/`xhigh`/`max`. New tokenizer (~30% more tokens for the same text vs Sonnet 4.6). High-resolution vision (2576px). 1M context window, 128K max output. See `shared/model-migration.md` → Migrating to Claude Sonnet 5.
|
||||
- **Claude Sonnet 4.6** — Previous-generation Sonnet. Supports adaptive thinking (recommended). 1M context window. 128K max output tokens.
|
||||
- **Claude Haiku 4.5** — Fastest and most cost-effective model for simple tasks.
|
||||
|
||||
## Legacy Models (still active)
|
||||
|
||||
| Friendly Name | Alias (use this) | Full ID | Status |
|
||||
|-------------------|---------------------|-------------------------------|--------|
|
||||
| Claude Opus 4.5 | `claude-opus-4-5` | `claude-opus-4-5-20251101` | Active |
|
||||
| Claude Opus 4.1 | `claude-opus-4-1` | `claude-opus-4-1-20250805` | Deprecated (retires 2026-08-05 — migrate to `claude-opus-5`) |
|
||||
| Claude Sonnet 4.5 | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929` | Active |
|
||||
|
||||
## Deprecated Models (retiring soon)
|
||||
|
||||
| Friendly Name | Alias (use this) | Full ID | Status | Retires |
|
||||
|-------------------|---------------------|-------------------------------|------------|--------------|
|
||||
| Claude Sonnet 4 | `claude-sonnet-4-0` | `claude-sonnet-4-20250514` | Deprecated | TBD |
|
||||
| Claude Opus 4 | `claude-opus-4-0` | `claude-opus-4-20250514` | Deprecated | TBD |
|
||||
| Claude Haiku 3 | — | `claude-3-haiku-20240307` | Deprecated | Apr 19, 2026 |
|
||||
|
||||
## Retired Models (no longer available)
|
||||
|
||||
| Friendly Name | Full ID | Retired |
|
||||
|-------------------|-------------------------------|-------------|
|
||||
| Claude Sonnet 3.7 | `claude-3-7-sonnet-20250219` | Feb 19, 2026 |
|
||||
| Claude Haiku 3.5 | `claude-3-5-haiku-20241022` | Feb 19, 2026 |
|
||||
| Claude Opus 3 | `claude-3-opus-20240229` | Jan 5, 2026 |
|
||||
| Claude Sonnet 3.5 | `claude-3-5-sonnet-20241022` | Oct 28, 2025 |
|
||||
| Claude Sonnet 3.5 | `claude-3-5-sonnet-20240620` | Oct 28, 2025 |
|
||||
| Claude Sonnet 3 | `claude-3-sonnet-20240229` | Jul 21, 2025 |
|
||||
| Claude 2.1 | `claude-2.1` | Jul 21, 2025 |
|
||||
| Claude 2.0 | `claude-2.0` | Jul 21, 2025 |
|
||||
|
||||
## Resolving User Requests
|
||||
|
||||
When a user asks for a model by name, use this table to find the correct model ID:
|
||||
|
||||
| User says... | Use this model ID |
|
||||
|-------------------------------------------|--------------------------------|
|
||||
| "fable", "most capable model" | `claude-fable-5` |
|
||||
| "most powerful" | `claude-fable-5` |
|
||||
| "mythos", "mythos 5" | `claude-mythos-5` (Project Glasswing participants only; otherwise use `claude-fable-5`) |
|
||||
| "mythos preview" | `claude-mythos-5` (successor to `claude-mythos-preview` — see migration guide) |
|
||||
| "opus" | `claude-opus-5` |
|
||||
| "opus 5" | `claude-opus-5` |
|
||||
| "opus 4.8" | `claude-opus-4-8` |
|
||||
| "opus 4.7" | `claude-opus-4-7` |
|
||||
| "opus 4.6" | `claude-opus-4-6` |
|
||||
| "opus 4.5" | `claude-opus-4-5` |
|
||||
| "opus 4.1" | `claude-opus-4-1` (deprecated, retires 2026-08-05 — suggest `claude-opus-5`) |
|
||||
| "opus 4", "opus 4.0" | `claude-opus-4-0` (deprecated — suggest `claude-opus-5`) |
|
||||
| "sonnet", "balanced" | `claude-sonnet-5` |
|
||||
| "sonnet 5" | `claude-sonnet-5` |
|
||||
| "sonnet 4.6" | `claude-sonnet-4-6` |
|
||||
| "sonnet 4.5" | `claude-sonnet-4-5` |
|
||||
| "sonnet 4", "sonnet 4.0" | `claude-sonnet-4-0` (deprecated — suggest `claude-sonnet-5`) |
|
||||
| "sonnet 3.7" | Retired — suggest `claude-sonnet-5` |
|
||||
| "sonnet 3.5" | Retired — suggest `claude-sonnet-5` |
|
||||
| "haiku", "fast", "cheap" | `claude-haiku-4-5` |
|
||||
| "haiku 4.5" | `claude-haiku-4-5` |
|
||||
| "haiku 3.5" | Retired — suggest `claude-haiku-4-5` |
|
||||
| "haiku 3" | Deprecated — suggest `claude-haiku-4-5` |
|
||||
97
.agents/skills/claude-api/shared/platform-availability.md
Normal file
97
.agents/skills/claude-api/shared/platform-availability.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# Platform Availability
|
||||
|
||||
Which features work on which provider platform. **This table is the single source of truth in this skill** — per-feature sections elsewhere point here instead of restating availability. When writing code for a third-party platform (Bedrock, Vertex, Foundry) or Claude Platform on AWS, check this table first; a feature not supported there means use the first-party Claude API surface or a different approach.
|
||||
|
||||
Columns: **1P** = first-party Claude API, **P-AWS** = Claude Platform on AWS (Anthropic-operated, same-day parity), **Bedrock** = Amazon Bedrock, **Vertex** = Google Cloud Vertex AI, **Foundry** = Microsoft Foundry. ✅ = GA, β = beta, ❌ = not supported.
|
||||
|
||||
| Feature | 1P | P-AWS | Bedrock | Vertex | Foundry | Notes |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Messages, streaming, tool use | ✅ | ✅ | ✅ | ✅ | ✅ | Core API |
|
||||
| PDF input | ✅ | ✅ | ✅ | ✅ | β | |
|
||||
| Structured outputs / strict tool use | ✅ | ✅ | ✅ | ✅ | β | |
|
||||
| Adaptive thinking / effort | ✅ | ✅ | ✅ | ✅ | β | |
|
||||
| Extended thinking | ✅ | ✅ | ✅ | ✅ | β | |
|
||||
| Prompt caching (5m, 1h) | ✅ | ✅ | ✅ | ✅ | β | |
|
||||
| Automatic prompt caching | ✅ | ✅ | ❌ | ❌ | β | |
|
||||
| Token counting | ✅ | ✅ | ✅ | ✅ | β | |
|
||||
| Citations | ✅ | ✅ | ✅ | ✅ | β | |
|
||||
| Search results content blocks | ✅ | ✅ | ✅ | ✅ | β | |
|
||||
| Fine-grained tool streaming | ✅ | ✅ | ✅ | ✅ | ✅ | |
|
||||
| Compaction | β | β | β | β | β | |
|
||||
| Context editing | β | β | β | β | β | |
|
||||
| Context windows (1M) | ✅ | ✅ | ✅ | ✅ | β | |
|
||||
| `inference_geo` (data residency) | ✅ | ✅ | ❌ | ❌ | ❌ | |
|
||||
| **Server-side tools** | | | | | | |
|
||||
| Web search | ✅ | ✅ | ❌ | ✅ | β | Vertex: basic `web_search_20250305` only (no `_20260209` dynamic filtering) |
|
||||
| Web fetch | ✅ | ✅ | ❌ | ❌ | β | |
|
||||
| Code execution | ✅ | ✅ | ❌ | ❌ | β | |
|
||||
| Tool search | ✅ | ✅ | ✅ | ✅ | β | Bedrock: InvokeModel API only, not Converse |
|
||||
| Advisor tool | β | β | ❌ | ❌ | ❌ | |
|
||||
| **Client-implemented tools** | | | | | | |
|
||||
| Bash, text editor, memory | ✅ | ✅ | ✅ | ✅ | β | |
|
||||
| Computer use | β | β | β | β | β | |
|
||||
| **Agentic / orchestration** | | | | | | |
|
||||
| Agent Skills (Messages API) | β | β | ❌ | ❌ | β | |
|
||||
| Programmatic tool calling | ✅ | ✅ | ❌ | ❌ | β | |
|
||||
| MCP connector | β | β | ❌ | ❌ | β | |
|
||||
| Managed Agents | β | β | ❌ | ❌ | ❌ | Foundry ❌ inferred (not in Foundry docs either way) |
|
||||
| Self-hosted sandboxes | β | β | ❌ | ❌ | ❌ | P-AWS: `GET /v1/environments/{id}/work` list endpoint not supported; other work endpoints OK |
|
||||
| **API endpoints** | | | | | | |
|
||||
| Message Batches | ✅ | ✅ | ❌ | ❌ | ❌ | |
|
||||
| Files API | β | β | ❌ | ❌ | β | |
|
||||
| Models API | ✅ | ✅ | ❌ | ❌ | ❌ | |
|
||||
| **Other** | | | | | | |
|
||||
| Mid-conversation system messages | ✅ | ✅ | ❌ | ❌ | ❌ | Claude Opus 5, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5; not Claude Sonnet 5 |
|
||||
| Server-side `fallbacks` | β | β | ❌ | ❌ | ❌ | `"default"` → beta `server-side-fallback-2026-07-01`; array form → beta `server-side-fallback-2026-06-01` |
|
||||
| Fast mode | β | ❌ | ❌ | ❌ | ❌ | Research preview, beta `fast-mode-2026-02-01`, first-party API only |
|
||||
| Cache diagnostics | β | ❌ | ❌ | ❌ | ❌ | First-party API only |
|
||||
| Task budgets | β | β | ❌ | ❌ | ❌ | Beta header `task-budgets-2026-03-13`; 3P availability not documented — assume unsupported |
|
||||
|
||||
<!--
|
||||
GROUNDING (reviewer-only; stripped at runtime by processSkillMarkdown).
|
||||
All paths are under docker_eval/resources/cdp-skill/public-docs/.
|
||||
|
||||
Primary source: build-with-claude/overview.mdx <PlatformAvailability> props
|
||||
(claudeApi→1P, claudePlatformAws→P-AWS, bedrock→Bedrock, vertexAi→Vertex,
|
||||
azureAi→Foundry; *Beta suffix→β; prop absent→❌). Per-row citations:
|
||||
|
||||
Context windows ov:44
|
||||
Adaptive thinking ov:45
|
||||
Batch / Message Batches ov:46; bed:360; vtx:381; fdy:507
|
||||
Citations ov:47
|
||||
inference_geo ov:48
|
||||
Effort ov:49
|
||||
Extended thinking ov:50
|
||||
PDF input ov:51
|
||||
Search results ov:52
|
||||
Structured outputs ov:53
|
||||
Advisor tool ov:63
|
||||
Code execution ov:64
|
||||
Web fetch ov:65
|
||||
Web search ov:66; agents-and-tools/tool-use/web-search-tool.mdx:41
|
||||
Bash/text-editor/memory ov:72,75,74
|
||||
Computer use ov:73
|
||||
Agent Skills ov:83
|
||||
Fine-grained streaming ov:84
|
||||
MCP connector ov:85; agents-and-tools/mcp-connector.mdx:36
|
||||
Programmatic tool call ov:86
|
||||
Tool search ov:87; agents-and-tools/tool-use/tool-search-tool.mdx:24-30
|
||||
Compaction ov:95
|
||||
Context editing ov:96
|
||||
Automatic caching ov:97
|
||||
Prompt caching 5m/1h ov:98,99
|
||||
Token counting ov:100
|
||||
Files API ov:108; build-with-claude/files.mdx:17
|
||||
Managed Agents managed-agents/overview.mdx:11,70-72; bed:360; vtx:381
|
||||
Self-hosted sandboxes build-with-claude/claude-platform-on-aws.mdx:525,547
|
||||
Mid-convo system msgs build-with-claude/mid-conversation-system-messages.mdx:15
|
||||
Fast mode build-with-claude/fast-mode.mdx:23
|
||||
Cache diagnostics build-with-claude/cache-diagnostics.mdx:15,1379
|
||||
Task budgets build-with-claude/task-budgets.mdx:15
|
||||
Models API bed:360; vtx:381; fdy:506
|
||||
|
||||
ov = build-with-claude/overview.mdx
|
||||
bed = build-with-claude/claude-in-amazon-bedrock.mdx
|
||||
vtx = build-with-claude/claude-on-vertex-ai.mdx
|
||||
fdy = build-with-claude/claude-in-microsoft-foundry.mdx
|
||||
-->
|
||||
235
.agents/skills/claude-api/shared/prompt-caching.md
Normal file
235
.agents/skills/claude-api/shared/prompt-caching.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# Prompt Caching — Design & Optimization
|
||||
|
||||
This file covers how to design prompt-building code for effective caching. For language-specific syntax, see the `## Prompt Caching` section in each language's README or single-file doc.
|
||||
|
||||
## The one invariant everything follows from
|
||||
|
||||
**Prompt caching is a prefix match. Any change anywhere in the prefix invalidates everything after it.**
|
||||
|
||||
The cache key is derived from the exact bytes of the rendered prompt up to each `cache_control` breakpoint. A single byte difference at position N — a timestamp, a reordered JSON key, a different tool in the list — invalidates the cache for all breakpoints at positions ≥ N.
|
||||
|
||||
Render order is: `tools` → `system` → `messages`. A breakpoint on the last system block caches both tools and system together.
|
||||
|
||||
Design the prompt-building path around this constraint. Get the ordering right and most caching works for free. Get it wrong and no amount of `cache_control` markers will help.
|
||||
|
||||
---
|
||||
|
||||
## Workflow for optimizing existing code
|
||||
|
||||
When asked to add or optimize caching:
|
||||
|
||||
1. **Trace the prompt assembly path.** Find where `system`, `tools`, and `messages` are constructed. Identify every input that flows into them.
|
||||
2. **Classify each input by stability:**
|
||||
- Never changes → belongs early in the prompt, before any breakpoint
|
||||
- Changes per-session → belongs after the global prefix, cache per-session
|
||||
- Changes per-turn → belongs at the end, after the last breakpoint
|
||||
- Changes per-request (timestamps, UUIDs, random IDs) → **eliminate or move to the very end**
|
||||
3. **Check rendered order matches stability order.** Stable content must physically precede volatile content. If a timestamp is interpolated into the system prompt header, everything after it is uncacheable regardless of markers.
|
||||
4. **Place breakpoints at stability boundaries.** See placement patterns below.
|
||||
5. **Audit for silent invalidators.** See anti-patterns table.
|
||||
|
||||
---
|
||||
|
||||
## Placement patterns
|
||||
|
||||
### Large system prompt shared across many requests
|
||||
|
||||
Put a breakpoint on the last system text block. If there are tools, they render before system — the marker on the last system block caches tools + system together.
|
||||
|
||||
```json
|
||||
"system": [
|
||||
{"type": "text", "text": "<large shared prompt>", "cache_control": {"type": "ephemeral"}}
|
||||
]
|
||||
```
|
||||
|
||||
### Multi-turn conversations
|
||||
|
||||
Put a breakpoint on the last content block of the most-recently-appended turn. Each subsequent request reuses the entire prior conversation prefix. Earlier breakpoints remain valid read points, so hits accrue incrementally as the conversation grows.
|
||||
|
||||
```json
|
||||
// Last content block of the last user turn
|
||||
messages[-1].content[-1].cache_control = {"type": "ephemeral"}
|
||||
```
|
||||
|
||||
### Shared prefix, varying suffix
|
||||
|
||||
Many requests share a large fixed preamble (few-shot examples, retrieved docs, instructions) but differ in the final question. Put the breakpoint at the end of the **shared** portion, not at the end of the whole prompt — otherwise every request writes a distinct cache entry and nothing is ever read.
|
||||
|
||||
```json
|
||||
"messages": [{"role": "user", "content": [
|
||||
{"type": "text", "text": "<shared context>", "cache_control": {"type": "ephemeral"}},
|
||||
{"type": "text", "text": "<varying question>"} // no marker — differs every time
|
||||
]}]
|
||||
```
|
||||
|
||||
### Mid-conversation system messages
|
||||
|
||||
**Claude Opus 5, Claude Opus 4.8, Claude Fable 5, and Claude Mythos 5; no beta header. Not available on Claude Sonnet 5** — use top-level `system` there. (Sources conflict on Claude Sonnet 5: the model config marks it supported, but every canonical docs page omits it. Treat it as unsupported and catch the 400.) When an operator instruction arrives mid-conversation — a mode switch, updated context, dynamically injected state — send it as `{"role": "system", "content": "..."}` appended to `messages[]`, rather than editing top-level `system`. Editing top-level `system` changes the prefix ahead of the entire conversation history, so every cached turn is re-processed uncached; a `role: "system"` message sits after the history and leaves the cached prefix intact.
|
||||
|
||||
```json
|
||||
// Top-level system stays byte-identical; new instruction goes after the cached history
|
||||
"system": [{"type": "text", "text": "<stable core>", "cache_control": {"type": "ephemeral"}}],
|
||||
"messages": [
|
||||
...history,
|
||||
{"role": "user", "content": "..."},
|
||||
{"role": "system", "content": "Terse mode enabled — keep responses under 40 words."}
|
||||
]
|
||||
```
|
||||
|
||||
This is also the prompt-injection-safe replacement for embedding operator instructions as text inside a user turn (the `<system-reminder>` pattern): both have the same caching profile, but `role: "system"` is the non-spoofable operator channel, whereas text inside user/tool content can be forged by anything that writes to user-visible input.
|
||||
|
||||
Must follow a `role: "user"` message (or an `assistant` message ending in server-tool use), and must be either the last entry in `messages` or be followed by an `assistant` turn; cannot be `messages[0]` — use top-level `system` for the initial prompt. Content is text-only. Unsupported models return a 400 (`BadRequestError`: `role 'system' is not supported on this model`); catch that error and fall back to putting the instruction in a user-turn `<system-reminder>` block.
|
||||
|
||||
### Prompts that change from the beginning every time
|
||||
|
||||
Don't cache. If the first 1K tokens differ per request, there is no reusable prefix. Adding `cache_control` only pays the cache-write premium with zero reads. Leave it off.
|
||||
|
||||
---
|
||||
|
||||
## Architectural guidance
|
||||
|
||||
These are the decisions that matter more than marker placement. Fix these first.
|
||||
|
||||
**Keep the system prompt frozen.** Don't interpolate "current date: X", "mode: Y", "user name: Z" into the system prompt — those sit at the front of the prefix and invalidate everything downstream. Inject dynamic context later in `messages` instead — as a `{"role": "system", ...}` message where supported (see § Mid-conversation system messages above), or as text in a user message otherwise. A message at turn 5 invalidates nothing before turn 5.
|
||||
|
||||
**Don't change tools or model mid-conversation.** Tools render at position 0; adding, removing, or reordering a tool invalidates the entire cache. Same for switching models (caches are model-scoped). If you need "modes", don't swap the tool set — give Claude a tool that records the mode transition, or pass the mode as message content. Serialize tools deterministically (sort by name).
|
||||
|
||||
**Fork operations must reuse the parent's exact prefix.** Side computations (summarization, compaction, sub-agents) often spin up a separate API call. If the fork rebuilds `system` / `tools` / `model` with any difference, it misses the parent's cache entirely. Copy the parent's `system`, `tools`, and `model` verbatim, then append fork-specific content at the end.
|
||||
|
||||
---
|
||||
|
||||
## Silent invalidators
|
||||
|
||||
When reviewing code, grep for these inside anything that feeds the prompt prefix:
|
||||
|
||||
| Pattern | Why it breaks caching |
|
||||
|---|---|
|
||||
| `datetime.now()` / `Date.now()` / `time.time()` in system prompt | Prefix changes every request |
|
||||
| `uuid4()` / `crypto.randomUUID()` / request IDs early in content | Same — every request is unique |
|
||||
| `json.dumps(d)` without `sort_keys=True` / iterating a `set` | Non-deterministic serialization → prefix bytes differ |
|
||||
| f-string interpolating session/user ID into system prompt | Per-user prefix; no cross-user sharing |
|
||||
| Conditional system sections (`if flag: system += ...`) | Every flag combination is a distinct prefix |
|
||||
| `tools=build_tools(user)` where set varies per user | Tools render at position 0; nothing caches across users |
|
||||
|
||||
Fix by moving the dynamic piece after the last breakpoint, making it deterministic, or deleting it if it's not load-bearing.
|
||||
|
||||
---
|
||||
|
||||
## API reference
|
||||
|
||||
```json
|
||||
"cache_control": {"type": "ephemeral"} // 5-minute TTL (default)
|
||||
"cache_control": {"type": "ephemeral", "ttl": "1h"} // 1-hour TTL
|
||||
```
|
||||
|
||||
- Max **4** `cache_control` breakpoints per request.
|
||||
- Goes on any content block: system text blocks, tool definitions, message content blocks (`text`, `image`, `tool_use`, `tool_result`, `document`).
|
||||
- Top-level `cache_control` on `messages.create()` auto-places on the last cacheable block — simplest option when you don't need fine-grained placement.
|
||||
- Minimum cacheable prefix is model-dependent. Shorter prefixes silently won't cache even with a marker — no error, just `cache_creation_input_tokens: 0`:
|
||||
|
||||
| Model | Minimum |
|
||||
|---|---:|
|
||||
| Claude Opus 5, Claude Fable 5, Claude Mythos 5 | 512 tokens |
|
||||
| Opus 4.8, Claude Sonnet 5, Sonnet 4.6, Sonnet 4.5, Opus 4.1, Opus 4, Sonnet 4 | 1024 tokens |
|
||||
| Opus 4.7, Mythos Preview, Haiku 3.5 | 2048 tokens |
|
||||
| Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens |
|
||||
|
||||
**The minimum is not monotonic across generations** — 512 on the newest models, but 4096 on Opus 4.6/4.5 and Haiku 4.5. A 3K-token prompt caches on Claude Opus 5, Opus 4.8, and Sonnet 4.5, and silently won't on Opus 4.6 or Haiku 4.5. Claude Opus 5 halves the Opus 4.8 minimum (1024 → 512), so prompts previously too short to cache now create entries with no code change.
|
||||
|
||||
These minimums apply on **every** platform where the model is available — the old Amazon Bedrock override for Claude Fable 5 was removed, and no per-platform exception remains.
|
||||
|
||||
**Economics:** Cache reads cost ~0.1× base input price. Cache writes cost **1.25× for 5-minute TTL, 2× for 1-hour TTL**. Break-even depends on TTL: with 5-minute TTL, two requests break even (1.25× + 0.1× = 1.35× vs 2× uncached); with 1-hour TTL, you need at least three requests (2× + 0.2× = 2.2× vs 3× uncached). The 1-hour TTL keeps entries alive across gaps in bursty traffic, but the doubled write cost means it needs more reads to pay off.
|
||||
|
||||
---
|
||||
|
||||
## Verifying cache hits
|
||||
|
||||
The response `usage` object reports cache activity:
|
||||
|
||||
| Field | Meaning |
|
||||
|---|---|
|
||||
| `cache_creation_input_tokens` | Tokens written to cache this request (you paid the ~1.25× write premium) |
|
||||
| `cache_read_input_tokens` | Tokens served from cache this request (you paid ~0.1×) |
|
||||
| `input_tokens` | Tokens processed at full price (not cached) |
|
||||
|
||||
If `cache_read_input_tokens` is zero across repeated requests with identical prefixes, a silent invalidator is at work — diff the rendered prompt bytes between two requests to find it.
|
||||
|
||||
**`input_tokens` is the uncached remainder only.** Total prompt size = `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. If your agent ran for hours but `input_tokens` shows 4K, the rest was served from cache — check the sum, not the single field.
|
||||
|
||||
Language-specific access: `response.usage.cache_read_input_tokens` (Python/TS/Ruby), `$message->usage->cacheReadInputTokens` (PHP), `resp.Usage.CacheReadInputTokens` (Go/C#), `.usage().cacheReadInputTokens()` (Java).
|
||||
|
||||
---
|
||||
|
||||
## Invalidation hierarchy
|
||||
|
||||
Not every parameter change invalidates everything. The API has three cache tiers, and changes only invalidate their own tier and below:
|
||||
|
||||
| Change | Tools cache | System cache | Messages cache |
|
||||
|---|:---:|:---:|:---:|
|
||||
| Tool definitions (add/remove/reorder) | ❌ | ❌ | ❌ |
|
||||
| Model switch | ❌ | ❌ | ❌ |
|
||||
| `speed`, web-search, citations toggle | ✅ | ❌ | ❌ |
|
||||
| System prompt content | ✅ | ❌ | ❌ |
|
||||
| `tool_choice`, images, `thinking` enable/disable | ✅ | ✅ | ❌ |
|
||||
| Message content | ✅ | ✅ | ❌ |
|
||||
|
||||
Implication: you can change `tool_choice` per-request or toggle `thinking` without losing the tools+system cache. Don't over-worry about these — only tool-definition and model changes force a full rebuild.
|
||||
|
||||
**Two of these rows have a cache-preserving escape hatch**, each by moving the change out of the top-level request and into a system message inside `messages[]`, after the cached prefix. **Availability differs per row** — the two are not gated together:
|
||||
|
||||
| Top-level change that invalidates | Cache-preserving form | Available on |
|
||||
|---|---|---|
|
||||
| Tool definitions (add/remove) | `tool_addition` / `tool_removal` blocks — see `shared/tool-use-concepts.md` § Mid-conversation tool changes | Claude Opus 5 onward, behind `mid-conversation-tool-changes-2026-07-01` |
|
||||
| System prompt content | A `{"role": "system", "content": "…"}` message — see § Mid-conversation system messages above | Claude Opus 5, Claude Opus 4.8, Claude Fable 5, Claude Mythos 5 — **already available today**, no beta header |
|
||||
|
||||
Model switch has no escape hatch: caches are model-scoped. Keep the main loop on one model and spawn a subagent for cheaper sub-tasks (see `agent-design.md` § Caching for Agents).
|
||||
|
||||
---
|
||||
|
||||
## 20-block lookback window
|
||||
|
||||
Each breakpoint walks backward **at most 20 content blocks** to find a prior cache entry. If a single turn adds more than 20 blocks (common in agentic loops with many tool_use/tool_result pairs), the next request's breakpoint won't find the previous cache and silently misses.
|
||||
|
||||
Fix: place an intermediate breakpoint every ~15 blocks in long turns, or put the marker on a block that's within 20 of the previous turn's last cached block.
|
||||
|
||||
---
|
||||
|
||||
## Concurrent-request timing
|
||||
|
||||
A cache entry becomes readable only after the first response **begins streaming**. N parallel requests with identical prefixes all pay full price — none can read what the others are still writing.
|
||||
|
||||
For fan-out patterns: send 1 request, await the first streamed token (not the full response), then fire the remaining N−1. They'll read the cache the first one just wrote.
|
||||
|
||||
## Pre-warming the cache
|
||||
|
||||
To eliminate the cache-miss latency on the *first* real request, send a **`max_tokens: 0`** request at startup (or on an interval). The API runs prefill — writing the cache at your `cache_control` breakpoint — and returns immediately with `content: []`, `stop_reason: "max_tokens"`, and a populated `usage` block (zero output tokens billed; normal cache-write charge on `cache_creation_input_tokens`).
|
||||
|
||||
**When to pre-warm** — pre-warming trades a cache-write charge *now* for lower TTFT on the *next* real request. It's worth it when all three hold: (a) first-request latency is user-visible (chat/voice/interactive — not background jobs), (b) the shared prefix is large enough that a cold write is noticeably slow, and (c) there's a moment *before* traffic to fire it — app startup, worker boot, post-deploy, start of a scheduled window.
|
||||
|
||||
| Skip pre-warming when… | Because |
|
||||
|---|---|
|
||||
| Traffic is continuous (requests ≤ TTL apart) | The first real request warms the cache and every subsequent one hits it; a separate warm call is a pure extra write |
|
||||
| The prefix is small or below the cacheable minimum | The cold-write penalty is negligible |
|
||||
| The prefix varies per request/user | Nothing shared to pre-warm |
|
||||
| You'd pre-warm many distinct prefixes speculatively | Each is a ~1.25× write; cost can exceed the latency you save |
|
||||
|
||||
**Scheduled re-warms:** only needed when traffic has gaps longer than the TTL. If real requests arrive more often than every 5 minutes, they keep the cache warm on their own — don't add an interval re-warm. For bursty traffic with long idle gaps, either re-warm just under the TTL or switch to `ttl: "1h"` and re-warm less often.
|
||||
|
||||
```python
|
||||
client.messages.create(
|
||||
model="claude-opus-5",
|
||||
max_tokens=0,
|
||||
system=[{
|
||||
"type": "text",
|
||||
"text": SYSTEM_PROMPT,
|
||||
"cache_control": {"type": "ephemeral"},
|
||||
}],
|
||||
messages=[{"role": "user", "content": "warmup"}],
|
||||
)
|
||||
```
|
||||
|
||||
**Breakpoint placement:** put `cache_control` on the **last block shared with the real request** (the system prompt or tool definitions) — **not** on the placeholder user message, and **not** via top-level automatic caching (which would key the cache to the placeholder). The placeholder can be any non-whitespace string; it's read during prefill but never answered.
|
||||
|
||||
**Rejected combinations:** `max_tokens: 0` is an `invalid_request_error` with `stream: true`, `thinking.type: "enabled"`, `output_config.format`, `tool_choice` of `{"type":"tool"}` or `{"type":"any"}`, or inside a Message Batches request.
|
||||
|
||||
**TTL still applies** — re-warm at least every 5 minutes for the default cache, or use the 1-hour TTL. This replaces the older `max_tokens: 1` workaround (no single-token reply to discard, no output tokens billed, intent is unambiguous).
|
||||
56
.agents/skills/claude-api/shared/token-counting.md
Normal file
56
.agents/skills/claude-api/shared/token-counting.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Token Counting
|
||||
|
||||
Use the `count_tokens` endpoint (`POST /v1/messages/count_tokens`) for accurate
|
||||
token counts against Claude models. Token counts are **model-specific** — pass
|
||||
the same model ID you'll use for inference.
|
||||
|
||||
**Do not use `tiktoken`.** It's OpenAI's tokenizer. It undercounts Claude
|
||||
tokens by ~15–20% on typical text, and by much more on code or non-English
|
||||
input. Any estimate from `tiktoken`, `gpt-tokenizer`, or similar is wrong for
|
||||
Claude.
|
||||
|
||||
## Count a file or string
|
||||
|
||||
```python
|
||||
from anthropic import Anthropic
|
||||
|
||||
client = Anthropic()
|
||||
resp = client.messages.count_tokens(
|
||||
model="claude-opus-5",
|
||||
messages=[{"role": "user", "content": open("CLAUDE.md").read()}],
|
||||
)
|
||||
print(resp.input_tokens)
|
||||
```
|
||||
|
||||
TypeScript: `await client.messages.countTokens({model, messages})` →
|
||||
`.input_tokens`. See `{lang}/claude-api/README.md` for other SDKs.
|
||||
|
||||
## CLI
|
||||
|
||||
```sh
|
||||
ant messages count-tokens --model claude-opus-5 \
|
||||
--message '{role: user, content: "@./CLAUDE.md"}' \
|
||||
--transform input_tokens -r
|
||||
```
|
||||
|
||||
## Diffing a file across two versions
|
||||
|
||||
The endpoint is stateless — count each version separately and subtract:
|
||||
|
||||
```python
|
||||
from anthropic import Anthropic
|
||||
import subprocess
|
||||
|
||||
client = Anthropic()
|
||||
def count(text: str) -> int:
|
||||
return client.messages.count_tokens(
|
||||
model="claude-opus-5",
|
||||
messages=[{"role": "user", "content": text}],
|
||||
).input_tokens
|
||||
|
||||
before = subprocess.check_output(["git", "show", "HEAD:CLAUDE.md"], text=True)
|
||||
after = open("CLAUDE.md").read()
|
||||
print(count(after) - count(before))
|
||||
```
|
||||
|
||||
Full docs: see the Token Counting entry in `shared/live-sources.md`.
|
||||
514
.agents/skills/claude-api/shared/tool-use-concepts.md
Normal file
514
.agents/skills/claude-api/shared/tool-use-concepts.md
Normal file
@@ -0,0 +1,514 @@
|
||||
# Tool Use Concepts
|
||||
|
||||
This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the `python/`, `typescript/`, or other language folders. For decision heuristics on which tools to expose, how to manage context in long-running agents, and caching strategy, see `agent-design.md`.
|
||||
|
||||
## User-Defined Tools
|
||||
|
||||
### Tool Definition Structure
|
||||
|
||||
> **Note:** When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java), `jsonschema` struct tags (Go), or `BaseTool` subclasses (Ruby). The raw JSON schema format below is for the manual approach — including PHP's `BetaRunnableTool`, which wraps a run closure around a hand-written schema — or SDKs without tool runner support.
|
||||
|
||||
Each tool requires a name, description, and JSON Schema for its inputs:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "get_weather",
|
||||
"description": "Get current weather for a location",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {
|
||||
"type": "string",
|
||||
"description": "City and state, e.g., San Francisco, CA"
|
||||
},
|
||||
"unit": {
|
||||
"type": "string",
|
||||
"enum": ["celsius", "fahrenheit"],
|
||||
"description": "Temperature unit"
|
||||
}
|
||||
},
|
||||
"required": ["location"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Best practices for tool definitions:**
|
||||
|
||||
- Use clear, descriptive names (e.g., `get_weather`, `search_database`, `send_email`)
|
||||
- Write detailed descriptions — Claude uses these to decide when to use the tool. Be **prescriptive about *when* to call it**, not just what it does (e.g. "Call this when the user asks about current prices or recent events"). On recent Opus models, which reach for tools more conservatively, trigger conditions in the description give measurable lift in should-call rate.
|
||||
- Include descriptions for each property
|
||||
- Use `enum` for parameters with a fixed set of values
|
||||
- Mark truly required parameters in `required`; make others optional with defaults
|
||||
|
||||
---
|
||||
|
||||
### Tool Choice Options
|
||||
|
||||
Control when Claude uses tools:
|
||||
|
||||
| Value | Behavior |
|
||||
| --------------------------------- | --------------------------------------------- |
|
||||
| `{"type": "auto"}` | Claude decides whether to use tools (default) |
|
||||
| `{"type": "any"}` | Claude must use at least one tool |
|
||||
| `{"type": "tool", "name": "..."}` | Claude must use the specified tool |
|
||||
| `{"type": "none"}` | Claude cannot use tools |
|
||||
|
||||
Any `tool_choice` value can also include `"disable_parallel_tool_use": true` to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response.
|
||||
|
||||
---
|
||||
|
||||
### Tool Runner vs Manual Loop
|
||||
|
||||
**Tool Runner (Recommended):** The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, PHP, and C# SDKs (beta). The Python SDK also provides MCP conversion helpers (`anthropic.lib.tools.mcp`) to convert MCP tools, prompts, and resources for use with the tool runner — see `python/claude-api/tool-use.md` for details. **Default to the tool runner** for any custom-tool agent.
|
||||
|
||||
**The tool runner is not a black box — "I need control" is rarely a reason to drop to the manual loop.** Each iteration yields the assistant message *before* the tools run and lets you intervene, so most "fine-grained control" needs are covered without hand-writing the loop:
|
||||
|
||||
- **Human-in-the-loop approval / gating** — gate in the tool's run function (return a "user declined" result instead of executing), or inspect the tool call in the yielded message and override the pending request with `set_messages_params()` / `setMessagesParams()` / `append_messages()` / `pushMessages()` to allow or deny *before* the tool executes. The runner runs your function automatically only if you don't intervene.
|
||||
- **Error interception** — inspect the tool result before it returns to Claude (`generate_tool_call_response()` / `generateToolResponse()`); stop early or handle it yourself.
|
||||
- **Result modification** — mutate the tool result before it goes back (e.g. add `cache_control` for prompt caching, or transform the output).
|
||||
- **Per-turn retries / param changes** — e.g. bump `max_tokens` and re-run a truncated turn; bound the whole loop with `max_iterations`.
|
||||
- **Streaming and automatic compaction** are both supported.
|
||||
|
||||
These hooks are SDK helper features, not separate API parameters — for the exact method names and worked examples, WebFetch the per-language SDK repo listed in `shared/live-sources.md` → *Claude API SDK Repositories* (the tool-runner helpers live in each repo's `tools.md` / `helpers.md`). The bundled `python/claude-api/tool-use.md` and `typescript/claude-api/tool-use.md` show the basic tool-runner setup.
|
||||
|
||||
**Don't drop to a manual loop because of these misconceptions:**
|
||||
|
||||
- The tool runner does not require Zod/Pydantic — `betaTool()` (TS) and `@beta_tool` (Python) accept raw JSON Schema; other SDKs use plain structs/maps/classes.
|
||||
- The runner makes detecting the final turn *easier*, not harder — iteration ends when Claude stops calling tools, and the last yielded message is the final response. Most SDKs also offer a one-shot variant (`runner.until_done()` / `runner.runUntilDone()` / `RunToCompletion()`).
|
||||
- Confirmation/approval gates work with the runner (see Security below).
|
||||
|
||||
**Manual Agentic Loop:** Reach for this only when you want to own the *entire* loop — you need control the runner does not expose (e.g., a custom transport, request shapes the SDK cannot build, per-token streaming on SDKs whose runner does not support it), you'd rather not take the beta dependency, or your control flow doesn't fit the runner's per-turn hooks (e.g. interleaving unrelated work mid-loop). Approval gates, logging, interception, result modification, and conditional execution do **not** require it — the tool runner covers those (above). Loop until `stop_reason == "end_turn"`, always append the full `response.content` to preserve tool_use blocks, and ensure each `tool_result` includes the matching `tool_use_id`.
|
||||
|
||||
**Stop reasons for server-side tools:** When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have `stop_reason: "pause_turn"`. To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing `server_tool_use` block and knows to resume automatically.
|
||||
|
||||
```python
|
||||
# Handle pause_turn in your agentic loop
|
||||
if response.stop_reason == "pause_turn":
|
||||
messages = [
|
||||
{"role": "user", "content": user_query},
|
||||
{"role": "assistant", "content": response.content},
|
||||
]
|
||||
# Make another API request — server resumes automatically
|
||||
response = client.messages.create(
|
||||
model="claude-opus-5", messages=messages, tools=tools
|
||||
)
|
||||
```
|
||||
|
||||
**Note:** the SDK tool runners do not auto-resume `pause_turn` (as of `@anthropic-ai/sdk` 0.110.0 / `anthropic` 0.116.0) — a paused turn ends the runner and is returned as the final message, with no error. In TypeScript you can resume inside the iteration body (push the paused assistant turn back onto the runner); in Python the runner cannot be resumed mid-loop — restart a new runner with the paused turn appended, or handle `pause_turn` in a manual loop. See each language's `tool-use.md` for the pattern.
|
||||
|
||||
Set a `max_continuations` limit (e.g., 5) to prevent infinite loops. For the full guide, see: `https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons`
|
||||
|
||||
> **Security:** The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs and gate destructive operations behind human approval. **Both** the tool runner and the manual loop support this — with the tool runner, gate inside the tool's run function (prompt the user and return a "user declined" result instead of executing), or inspect the tool call in each yielded message and take over message history with `set_messages_params()` / `setMessagesParams()` to allow or deny *before* the tool runs (it executes your function automatically only if you don't intervene); with the manual loop you gate inline before calling the function.
|
||||
|
||||
---
|
||||
|
||||
### Handling Tool Results
|
||||
|
||||
When Claude uses a tool, the response contains a `tool_use` block. You must:
|
||||
|
||||
1. Execute the tool with the provided input
|
||||
2. Send the result back in a `tool_result` message
|
||||
3. Continue the conversation
|
||||
|
||||
**Error handling in tool results:** When a tool execution fails, set `"is_error": true` and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification.
|
||||
|
||||
**Multiple tool calls:** Claude can request multiple tools in a single response. Handle them all before continuing — send all results back in a single `user` message.
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools: Code Execution
|
||||
|
||||
The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure — you don't execute anything client-side. Just include the tool definition and Claude handles the rest.
|
||||
|
||||
### Key Facts
|
||||
|
||||
- Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk)
|
||||
- No internet access (fully sandboxed)
|
||||
- Python 3.11 with data science libraries pre-installed
|
||||
- Containers persist for 30 days and can be reused across requests
|
||||
- Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization
|
||||
|
||||
### Tool Definition
|
||||
|
||||
The tool requires no schema — just declare it in the `tools` array:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "code_execution_20260120",
|
||||
"name": "code_execution"
|
||||
}
|
||||
```
|
||||
|
||||
Claude automatically gains access to `bash_code_execution` (run shell commands) and `text_editor_code_execution` (create/view/edit files).
|
||||
|
||||
### Pre-installed Python Libraries
|
||||
|
||||
- **Data science**: pandas, numpy, scipy, scikit-learn, statsmodels
|
||||
- **Visualization**: matplotlib, seaborn
|
||||
- **File processing**: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx
|
||||
- **Math**: sympy, mpmath
|
||||
- **Utilities**: tqdm, python-dateutil, pytz, sqlite3
|
||||
|
||||
Additional packages can be installed at runtime via `pip install`.
|
||||
|
||||
### Supported File Types for Upload
|
||||
|
||||
| Type | Extensions |
|
||||
| ------ | ---------------------------------- |
|
||||
| Data | CSV, Excel (.xlsx/.xls), JSON, XML |
|
||||
| Images | JPEG, PNG, GIF, WebP |
|
||||
| Text | .txt, .md, .py, .js, etc. |
|
||||
|
||||
### Container Reuse
|
||||
|
||||
Reuse containers across requests to maintain state (files, installed packages, variables). Extract the `container_id` from the first response and pass it to subsequent requests.
|
||||
|
||||
### Response Structure
|
||||
|
||||
The response contains interleaved text and tool result blocks:
|
||||
|
||||
- `text` — Claude's explanation
|
||||
- `server_tool_use` — What Claude is doing
|
||||
- `bash_code_execution_tool_result` — Code execution output (check `return_code` for success/failure)
|
||||
- `text_editor_code_execution_tool_result` — File operation results
|
||||
|
||||
> **Security:** Always sanitize filenames with `os.path.basename()` / `path.basename()` before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory.
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools: Web Search and Web Fetch
|
||||
|
||||
Web search and web fetch let Claude search the web and retrieve page content. They run server-side — just include the tool definitions and Claude handles queries, fetching, and result processing automatically.
|
||||
|
||||
### Tool Definitions
|
||||
|
||||
```json
|
||||
[
|
||||
{ "type": "web_search_20260209", "name": "web_search" },
|
||||
{ "type": "web_fetch_20260209", "name": "web_fetch" }
|
||||
]
|
||||
```
|
||||
|
||||
### Dynamic Filtering (Claude Opus 5 / Fable 5 / Opus 4.8 / Opus 4.7 / Opus 4.6 / Sonnet 5 / Sonnet 4.6)
|
||||
|
||||
The `web_search_20260209` and `web_fetch_20260209` versions support **dynamic filtering** — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the `code_execution` tool or pass any beta header.
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{ "type": "web_search_20260209", "name": "web_search" },
|
||||
{ "type": "web_fetch_20260209", "name": "web_fetch" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Without dynamic filtering, the previous `web_search_20250305` version is also available.
|
||||
|
||||
> **Note:** Only include the standalone `code_execution` tool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside `_20260209` web tools creates a second execution environment that can confuse the model.
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools: Programmatic Tool Calling
|
||||
|
||||
With standard tool use, each tool call is a round trip: Claude calls, the result enters Claude's context, Claude reasons, then calls the next tool. Chained calls accumulate latency and tokens — most of that intermediate data is never needed again.
|
||||
|
||||
Programmatic tool calling lets Claude compose those calls into a script. The script runs in the code execution container; when it invokes a tool, the container pauses, the call executes, and the result returns to the running code (not to Claude's context). The script processes it with normal control flow. Only the final output returns to Claude. Use it when chaining many tool calls or when intermediate results are large and should be filtered before reaching the context window.
|
||||
|
||||
For full documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling`
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools: Tool Search
|
||||
|
||||
The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Use it when you have many tools but only a few are relevant to any given request. Discovered tool schemas are appended to the request, not swapped in — this preserves the prompt cache (see `agent-design.md` §Caching for Agents).
|
||||
|
||||
For full documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool`
|
||||
|
||||
---
|
||||
|
||||
## Mid-conversation tool changes (Beta)
|
||||
|
||||
**Beta header `mid-conversation-tool-changes-2026-07-01`; Claude Opus 5 onward.** Normally `tools` is fixed for a conversation's lifetime — editing it changes the very front of the prompt prefix and invalidates the entire cache (see `prompt-caching.md` § Invalidation hierarchy). This feature lets you add and remove tools between turns while the cached prefix survives.
|
||||
|
||||
Both operations are content blocks on a `{"role": "system", ...}` message appended to `messages[]`, and both reference a tool by name via a `tool_reference`:
|
||||
|
||||
```python
|
||||
# Removal — must sit immediately before an assistant message, or last in messages.
|
||||
{"role": "system", "content": [
|
||||
{"type": "tool_removal", "tool": {"type": "tool_reference", "name": "get_weather"}},
|
||||
]}
|
||||
|
||||
# Addition — surfaces a tool declared up front with defer_loading.
|
||||
{"role": "system", "content": [
|
||||
{"type": "tool_addition", "tool": {"type": "tool_reference", "name": "get_forecast"}},
|
||||
]}
|
||||
```
|
||||
|
||||
**A tool you plan to add must already be declared in `tools[]` with `"defer_loading": True`.** Deferred tools are known to the request but not loaded into the model's context until a `tool_addition` surfaces them:
|
||||
|
||||
```python
|
||||
tools = [
|
||||
{"name": "get_weather", "description": "Get weather",
|
||||
"input_schema": {"type": "object", "properties": {"city": {"type": "string"}}}},
|
||||
{"name": "get_forecast", "description": "Get 5-day forecast",
|
||||
"input_schema": {"type": "object", "properties": {"city": {"type": "string"}}},
|
||||
"defer_loading": True},
|
||||
]
|
||||
```
|
||||
|
||||
**To change a tool's definition**, do it across two requests: send a `tool_removal` for the old definition on the first, then carry the conversation forward with the updated entry in `tools[]` on the next.
|
||||
|
||||
> ⚠️ Earlier previews used a different beta header and different block shapes; both are deprecated. Use `mid-conversation-tool-changes-2026-07-01` with `tool_addition` / `tool_removal` / `tool_reference`.
|
||||
|
||||
SDK typings lag these blocks — pass them as plain dicts in Python, or add a `@ts-expect-error` in TypeScript.
|
||||
|
||||
**Choosing between this and tool search:** tool search is for *discovery* — Claude finds what it needs from a large library on its own. Mid-conversation tool changes are for *control* — your application decides the tool set has changed (a mode switch, a resource that became available, a capability you want to revoke) and says so explicitly.
|
||||
|
||||
---
|
||||
|
||||
## Agent Skills (Messages API)
|
||||
|
||||
Agent Skills package task-specific instructions and files that Claude loads when relevant (e.g., the Anthropic pre-built `pptx`, `xlsx`, `pdf`, `docx` skills). On the **Messages API**, skills are enabled via the `container` parameter alongside the code-execution tool — this is **not** the Managed Agents surface and does **not** use `client.beta.agents` / `sessions` / `environments`. Availability: see `shared/platform-availability.md`.
|
||||
|
||||
Required on each request:
|
||||
|
||||
1. `client.beta.messages.create(...)` with **both** beta flags: `code-execution-2025-08-25` **and** `skills-2025-10-02`.
|
||||
2. `container={"skills": [{"type": "anthropic", "skill_id": "<id>", "version": "latest"}]}` — the skills list selects which skills are available inside the execution container.
|
||||
3. `tools=[{"type": "code_execution_20260521", "name": "code_execution"}]` — skills execute via code execution in the container.
|
||||
|
||||
```python
|
||||
response = client.beta.messages.create(
|
||||
model="claude-opus-5", max_tokens=16000,
|
||||
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
|
||||
container={"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]},
|
||||
tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
|
||||
messages=[{"role": "user", "content": "Create a 3-slide presentation on X"}],
|
||||
)
|
||||
```
|
||||
|
||||
Generated files (`.pptx`, `.xlsx`, …) are written inside the container; the response carries a file ID for each. Download by passing that ID to the Files API (`client.beta.files.download(file_id)` / `GET /v1/files/{id}/content` with `anthropic-beta: files-api-2025-04-14`).
|
||||
|
||||
List available skills via `GET /v1/skills` (requires `anthropic-beta: skills-2025-10-02`).
|
||||
|
||||
---
|
||||
|
||||
## MCP Connector (Beta)
|
||||
|
||||
The MCP connector lets Claude call tools hosted on a remote MCP server directly from the Messages API — Anthropic makes the MCP connection server-side. Requires beta flag `mcp-client-2025-11-20` on `client.beta.messages.create(...)`. Availability: see `shared/platform-availability.md`.
|
||||
|
||||
**Two parameters are required together:**
|
||||
|
||||
- `mcp_servers` — array of server connection definitions: `[{"type": "url", "url": "<server URL>", "name": "<server-name>", "authorization_token": "<optional>"}]`
|
||||
- `tools` — must include an `mcp_toolset` entry that references the server by name: `[{"type": "mcp_toolset", "mcp_server_name": "<server-name>"}]`
|
||||
|
||||
The `mcp_server_name` in the toolset must match a `name` in `mcp_servers`. Omitting the `mcp_toolset` entry is rejected as a validation error — every server in `mcp_servers` must be referenced by exactly one toolset.
|
||||
|
||||
```python
|
||||
client.beta.messages.create(
|
||||
model="claude-opus-5", max_tokens=1024,
|
||||
betas=["mcp-client-2025-11-20"],
|
||||
mcp_servers=[{"type": "url", "url": "https://example/sse", "name": "example-mcp"}],
|
||||
tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
|
||||
messages=[...],
|
||||
)
|
||||
```
|
||||
|
||||
Go uses the typed constant `anthropic.AnthropicBetaMCPClient2025_11_20`; the older `…2025_04_04` constant is deprecated.
|
||||
|
||||
Optional toolset fields: `default_config` (defaults for all tools, e.g. `{"enabled": false}` for allowlist mode) and `configs` (per-tool overrides keyed by tool name).
|
||||
|
||||
---
|
||||
|
||||
## Tool Use Examples
|
||||
|
||||
You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas.
|
||||
|
||||
For full documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use`
|
||||
|
||||
---
|
||||
|
||||
## Client-Side Tools: Computer Use
|
||||
|
||||
Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It is a client-side tool — your application provides the environment and executes the actions Claude requests; Anthropic processes the screenshots and action requests in real time but does not host the environment or retain the data.
|
||||
|
||||
For full documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview`
|
||||
|
||||
---
|
||||
|
||||
## Context Editing
|
||||
|
||||
Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes — the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure.
|
||||
|
||||
**Beta.** Use `client.beta.messages.*` with beta `context-management-2025-06-27`. Configure via `context_management.edits` with a strategy type of `clear_tool_uses_20250919` (clear old tool results; optional `clear_tool_inputs: true` also clears the tool_use params) or `clear_thinking_20251015` (clear thinking blocks). These are **not** the compaction types — `compact_20260112` with beta `compact-2026-01-12` is the separate compaction feature.
|
||||
|
||||
For full documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/build-with-claude/context-editing`
|
||||
|
||||
---
|
||||
|
||||
## Server-Side Tools: Advisor (Beta)
|
||||
|
||||
The advisor tool pairs a faster, lower-cost **executor** model (the top-level `model` on the request) with a higher-intelligence **advisor** model (the `model` field inside the tool definition) that provides strategic guidance mid-generation. The executor does most of the token generation; the advisor is consulted for planning. Availability: see `shared/platform-availability.md`.
|
||||
|
||||
### Tool Definition
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "advisor_20260301",
|
||||
"name": "advisor",
|
||||
"model": "claude-opus-4-8"
|
||||
}
|
||||
```
|
||||
|
||||
**The advisor model must be at least as capable as the executor.** An invalid pairing returns `400 invalid_request_error`. Valid pairs:
|
||||
|
||||
| Executor (request `model`) | Valid advisor (tool `model`) |
|
||||
|---|---|
|
||||
| `claude-haiku-4-5` / `claude-sonnet-4-6` / `claude-sonnet-5` / `claude-opus-4-6` / `claude-opus-4-7` | `claude-opus-5`, `claude-fable-5`, `claude-mythos-5`, `claude-opus-4-8`, or `claude-opus-4-7` |
|
||||
| `claude-opus-4-8` | `claude-opus-5`, `claude-fable-5`, `claude-mythos-5`, or `claude-opus-4-8` |
|
||||
| `claude-opus-5` | `claude-opus-5`, `claude-fable-5`, or `claude-mythos-5` |
|
||||
| `claude-fable-5` | `claude-fable-5` or `claude-opus-5` |
|
||||
| `claude-mythos-5` | `claude-mythos-5` or `claude-opus-5` |
|
||||
|
||||
> ⚠️ **The advisor's payload shape differs by advisor model.** The response block is always `advisor_tool_result`; what varies is its **`content`**, a discriminated union:
|
||||
>
|
||||
> | `content` type | Fields | When |
|
||||
> |---|---|---|
|
||||
> | `advisor_result` | `text`, `stop_reason` | Advisor returns plaintext (e.g. Opus 4.8) |
|
||||
> | `advisor_redacted_result` | `encrypted_content`, `stop_reason` | Advisor returns encrypted output — Claude Opus 5, Claude Fable 5, Claude Mythos 5 |
|
||||
>
|
||||
> So switch on `advisor_tool_result.content` type, not on the block type. Code that reads `.text` unconditionally gets nothing back from an Claude Opus 5 advisor, because the payload is under `encrypted_content` instead — and you cannot read it, only replay it.
|
||||
|
||||
Call via `client.beta.messages.create(...)` with `betas=["advisor-tool-2026-03-01"]` (or the `anthropic-beta: advisor-tool-2026-03-01` header). In multi-turn conversations, append the full `response.content` — including any `advisor_tool_result` blocks — back to `messages` on the next turn. If you remove the advisor tool from `tools` on a later turn while the history still contains `advisor_tool_result` blocks, the API returns a 400.
|
||||
|
||||
---
|
||||
|
||||
## Client-Side Tools: Memory
|
||||
|
||||
The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions.
|
||||
|
||||
### Key Facts
|
||||
|
||||
- Client-side tool — you control storage via your implementation
|
||||
- Supports commands: `view`, `create`, `str_replace`, `insert`, `delete`, `rename`
|
||||
- Operates on files in a `/memories` directory
|
||||
- The Python, TypeScript, and Java SDKs provide helper classes/functions for implementing the memory backend
|
||||
|
||||
> **Security:** Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) — check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers.
|
||||
|
||||
For full implementation examples, use WebFetch:
|
||||
|
||||
- Docs: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md`
|
||||
|
||||
---
|
||||
|
||||
## Client-Side Tools: Bash and Text Editor
|
||||
|
||||
The bash and text editor tools are **Anthropic-defined, schema-less** tools. Declare them by `type` and `name` only — the input schema is built into the model and cannot be modified. **Do not pass an `input_schema`**, and do not define a custom tool that happens to be named `"bash"` — that creates a user-defined tool without the built-in behavior.
|
||||
|
||||
Both are **client-executed**: Claude returns a `tool_use` block, your code performs the action locally, and you send back a `tool_result`. The API is stateless; your application maintains the shell session or filesystem between turns.
|
||||
|
||||
### Bash tool declaration
|
||||
|
||||
```json
|
||||
{"type": "bash_20250124", "name": "bash"}
|
||||
```
|
||||
|
||||
| Language | Declaration |
|
||||
|---|---|
|
||||
| Python / TypeScript / Ruby / cURL | plain object `{"type": "bash_20250124", "name": "bash"}` |
|
||||
| Go | `anthropic.ToolUnionParam{OfBashTool20250124: &anthropic.ToolBash20250124Param{}}` |
|
||||
| Java | `.addTool(ToolBash20250124.builder().build())` from `com.anthropic.models.messages` |
|
||||
| C# | `Tools = [new ToolBash20250124()]` from `Anthropic.Models.Messages` |
|
||||
| PHP | `tools: [new \Anthropic\Messages\ToolBash20250124()]` |
|
||||
|
||||
Claude's `tool_use.input` contains either `{"command": "<string>"}` or `{"restart": true}`. Check for `restart` first (reset the session, return a confirmation string); otherwise run `command` and return combined stdout + stderr.
|
||||
|
||||
> **Security — commands are untrusted model output.** Run in an isolated environment (container, VM, or restricted user); apply an **allowlist** of permitted executables and reject shell operators (`&&`, `|`, `;`, `` ` ``, `$()`); set timeouts and resource limits; log every command. A blocklist is not sufficient.
|
||||
|
||||
### Text editor tool declaration
|
||||
|
||||
```json
|
||||
{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}
|
||||
```
|
||||
|
||||
Optional field: `max_characters` to cap `view` output. Java exposes a typed `ToolTextEditor20250728` builder (`com.anthropic.models.messages`); other statically-typed SDKs follow the same naming pattern — see the Anthropic-Defined Tools section in `{lang}/claude-api/tool-use.md` for the exact class.
|
||||
|
||||
> **Security — `path` is untrusted model output. Confine every file operation to a fixed project root.** Before executing any command, resolve the model-supplied `path` to its canonical form and verify it remains within your project root; reject the request if it escapes (`..`, symlinks, absolute paths outside the root, URL-encoded traversal like `%2e%2e%2f`). Use your language's built-in path utilities (e.g., Python `pathlib.Path.resolve()` then check `.is_relative_to(root)`). Never call `open()` / `writeFile` / `unlink` directly on the raw `path` value.
|
||||
|
||||
`tool_use.input.command` is one of:
|
||||
|
||||
| `command` | Other inputs | Action |
|
||||
|---|---|---|
|
||||
| `view` | `path`, optional `view_range` | Return file contents or directory listing |
|
||||
| `create` | `path`, `file_text` | Create/overwrite file with `file_text`. Create a backup if the file already exists. |
|
||||
| `str_replace` | `path`, `old_str`, `new_str` | Replace exactly one occurrence; error if 0 or >1 matches |
|
||||
| `insert` | `path`, `insert_line`, `insert_text` | Insert `insert_text` after line `insert_line` (0 = beginning of file) |
|
||||
|
||||
For both tools, on error return `{"type": "tool_result", "tool_use_id": "…", "content": "<error text>", "is_error": true}` so Claude can recover.
|
||||
|
||||
---
|
||||
|
||||
## Structured Outputs
|
||||
|
||||
Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation.
|
||||
|
||||
Two features are available:
|
||||
|
||||
- **JSON outputs** (`output_config.format`): Control Claude's response format
|
||||
- **Strict tool use** (`strict: true`): Guarantee valid tool parameter schemas
|
||||
|
||||
**Supported models:** Claude Fable 5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs.
|
||||
|
||||
> **Recommended:** Use `client.messages.parse()` which automatically validates responses against your schema. When using `messages.create()` directly, use `output_config: {format: {...}}`. The `output_format` convenience parameter is also accepted by some SDK methods (e.g., `.parse()`), but `output_config.format` is the canonical API-level parameter.
|
||||
|
||||
### JSON Schema Limitations
|
||||
|
||||
**Supported:**
|
||||
|
||||
- Basic types: object, array, string, integer, number, boolean, null
|
||||
- `enum`, `const`, `anyOf`, `allOf`, `$ref`/`$def`
|
||||
- String formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid`
|
||||
- `additionalProperties: false` (required for all objects)
|
||||
|
||||
**Not supported:**
|
||||
|
||||
- Recursive schemas
|
||||
- Numerical constraints (`minimum`, `maximum`, `multipleOf`)
|
||||
- String constraints (`minLength`, `maxLength`)
|
||||
- Complex array constraints
|
||||
- `additionalProperties` set to anything other than `false`
|
||||
|
||||
The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side.
|
||||
|
||||
### Important Notes
|
||||
|
||||
- **First request latency**: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache.
|
||||
- **Refusals**: If Claude refuses for safety reasons (`stop_reason: "refusal"`), the output may not match your schema.
|
||||
- **Token limits**: If `stop_reason: "max_tokens"`, output may be incomplete. Increase `max_tokens`.
|
||||
- **Incompatible with**: Citations (returns 400 error), message prefilling.
|
||||
- **Works with**: Batches API, streaming, token counting, extended thinking.
|
||||
|
||||
---
|
||||
|
||||
## Tips for Effective Tool Use
|
||||
|
||||
1. **Provide detailed descriptions**: Claude relies heavily on descriptions to understand when and how to use tools
|
||||
2. **Use specific tool names**: `get_current_weather` is better than `weather`
|
||||
3. **Validate inputs**: Always validate tool inputs before execution
|
||||
4. **Handle errors gracefully**: Return informative error messages so Claude can adapt
|
||||
5. **Limit tool count**: Too many tools can confuse the model — keep the set focused
|
||||
6. **Test tool interactions**: Verify Claude uses tools correctly in various scenarios
|
||||
|
||||
For detailed tool use documentation, use WebFetch:
|
||||
|
||||
- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview`
|
||||
Reference in New Issue
Block a user