anymous 1.3.0 → 1.3.2

package/skills/claude-api/shared/managed-agents-scheduled-deployments.md

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

package/skills/claude-api/shared/managed-agents-self-hosted-sandboxes.md

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