anymous 1.3.0 → 1.3.2

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

@@ -1,371 +0,0 @@
-# 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}`            |
-

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

@@ -1,143 +0,0 @@
-# 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.