mirror of
https://github.com/anthropics/skills
synced 2026-09-20 10:38:25 +00:00
Update claude-api skill: Claude Fable 5.1 / Mythos 5.1, Managed Agents updates, cost-optimize (#1704)
* Update claude-api skill: Managed Agents self-hosted memory stores and web tool domain settings, cost-optimize subcommand, Admin API reference, ASCII-only text Managed Agents: self-hosted sandboxes can now attach memory stores via the SDK worker (handle_item, ANTHROPIC_WORK_SECRET, sync options, troubleshooting); web_search/web_fetch accept allowed_domains/blocked_domains/user_location/max_content_tokens on the toolset configs entry and are not governed by environment networking; typed per-tool config unions; Console session viewer notes; packages caveat under limited networking; Claude Platform on AWS self-hosted worker auth. New shared/cost-optimization.md backing a cost-optimize subcommand, and new shared/admin-api.md covering client.beta.organization in all SDKs and the CLI. Prompt caching gains TTL selection, automatic vs explicit breakpoint guidance, workspace isolation, and verification guidance. Sonnet 5 pricing is the permanent $2/$10 list price. Advisor pairing no longer excludes Claude Fable 5 for Managed Agents. Reviewer-only HTML comments are stripped from the published files. All files are now plain ASCII in prose (em dashes, arrows, emoji callouts, and box-drawing replaced with ASCII equivalents), matching the source so future syncs diff cleanly. No-Verification-Needed: documentation-only change to skill reference content * Update claude-api skill: Claude Fable 5.1 / Mythos 5.1 catalog rows, Files and Skills APIs out of beta Claude Fable 5.1 (claude-fable-5-1) and Claude Mythos 5.1 (claude-mythos-5-1) become the default Fable-tier models throughout the skill; Claude Fable 5 and Mythos 5 stay selectable by id with their own catalog rows. Feature-support lists that named Fable 5 now read Fable 5/5.1. The Files API and Skills API are out of beta: examples use client.files.* / client.skills.* with no beta header, and the API-drift table points at the beta-to-GA migration docs. No-Verification-Needed: documentation-only change to skill reference content * Update claude-api skill: Claude Fable 5.1 / Mythos 5.1 migration section and API changes Adds a "Migrating to Claude Fable 5.1 from Claude Fable 5" section to shared/model-migration.md: three breaking changes (forced tool_choice any/tool returns 400; thinking blocks are preserved only for the model that produced them or a newer one; and only in the conversation that produced them, so edited history replayed with thinking blocks is rejected), what carries over from Fable 5, the Opus 5 path, Mythos 5.1 notes, capability improvements, prompt-tunable behavioral shifts, and a migration checklist. New API features documented: per-message effort (mid-conversation-output-config beta), turn-scoped mid-conversation system messages with clear_at, progress updates between tool calls via thinking.display "updates", thinking block_binding controls, and the 0.025x cache-read rate on Fable 5.1 with a max_tokens: 0 keep-alive that usually beats the 1-hour TTL. Error catalog, prompt-caching, tool-use, platform-availability, cost-optimization, and prompt-audit are updated to match; SKILL.md routes migration and prompting questions to the new section. No-Verification-Needed: documentation-only change to skill reference content * Update claude-api skill: Claude Fable 5.1 launch-day hedges and migration-path table rows Adds claude-fable-5 -> claude-fable-5-1 and claude-mythos-5 -> claude-mythos-5-1 rows to the migration-path and model-ID mapping tables (including the Bedrock IDs), and updates the refusal-fallback example to the 5.1 model id. Hedges three claims until the launch docs confirm them: Task Budgets support on Claude Fable 5.1, whether Claude Mythos 5.1 shares the 0.025x cache-read rate, and the fallback-credit wording. The block_binding error row now says to send the controls beta header only where that beta is offered and to fall back to strip-and-retry elsewhere. Cross-references within the migration section point at the history-editing check directly. No-Verification-Needed: documentation-only change to skill reference content
This commit is contained in:
Lance Martin
@@ -1,8 +1,8 @@
|
||||
# Managed Agents — Environments & Resources
|
||||
# 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.
|
||||
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.
|
||||
|
||||
@@ -28,6 +28,10 @@ All three `limited` fields are optional. `allow_package_managers` (default `fals
|
||||
|
||||
**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.
|
||||
|
||||
**Packages caveat:** Under `limited` networking, `packages` requires `allow_package_managers: true`; otherwise the request fails with a 400. Listing the registry in `allowed_hosts` is not enough.
|
||||
|
||||
**`networking` does not govern `web_search` / `web_fetch`.** Those tools run on Anthropic's servers (in cloud *and* self-hosted environments), so `limited` egress and `allowed_hosts` don't restrict them. To restrict the sites they can reach, set `allowed_domains` / `blocked_domains` on the tool's `configs` entry in the agent toolset - see `shared/managed-agents-tools.md` § Web search & web fetch settings.
|
||||
|
||||
### Creating an environment
|
||||
|
||||
The SDK adds `managed-agents-2026-04-01` automatically. TypeScript:
|
||||
@@ -44,7 +48,7 @@ const env = await client.beta.environments.create({
|
||||
|
||||
### 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.
|
||||
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
|
||||
|
||||
@@ -55,15 +59,15 @@ To run tool execution in **your own infrastructure** instead of Anthropic's, set
|
||||
| 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. |
|
||||
| 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`.
|
||||
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)
|
||||
### File Uploads (input - host -> agent)
|
||||
|
||||
Upload a file first via the Files API, then reference by `file_id` + `mount_path`:
|
||||
|
||||
@@ -84,9 +88,9 @@ const session = await client.beta.sessions.create({
|
||||
});
|
||||
```
|
||||
|
||||
**`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.
|
||||
**`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)
|
||||
### 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:
|
||||
|
||||
@@ -105,44 +109,44 @@ for await (const f of client.beta.files.list({
|
||||
**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.
|
||||
- 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.
|
||||
> **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.
|
||||
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.
|
||||
|
||||
Mounting a repository also loads any skills stored in its root `.claude/skills` directory — discovered once per session, from the repository state checked out at session start (cloud sandboxes only). See `shared/managed-agents-tools.md` → Skills from a GitHub repository.
|
||||
Mounting a repository also loads any skills stored in its root `.claude/skills` directory - discovered once per session, from the repository state checked out at session start (cloud sandboxes only). See `shared/managed-agents-tools.md` -> Skills from a GitHub repository.
|
||||
|
||||
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()`.
|
||||
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. |
|
||||
| `type` | Yes | `"github_repository"` |
|
||||
| `url` | Yes | The GitHub repository URL |
|
||||
| `authorization_token` | Yes | GitHub Personal Access Token with repository access. **Never echoed in API responses.** |
|
||||
| `mount_path` | No | Path where the repository will be cloned. Defaults to `/workspace/<repo-name>`. |
|
||||
| `checkout` | No | `{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
|
||||
- `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.
|
||||
**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).
|
||||
> Important: **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)
|
||||
// 1. Create the agent - declare GitHub MCP (no auth here)
|
||||
const agent = await client.beta.agents.create(
|
||||
{
|
||||
name: 'GitHub Agent',
|
||||
@@ -157,7 +161,7 @@ const agent = await client.beta.agents.create(
|
||||
},
|
||||
);
|
||||
|
||||
// 2. Start a session — attach vault for MCP auth + mount the repo
|
||||
// 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,
|
||||
@@ -166,7 +170,7 @@ const session = await client.beta.sessions.create({
|
||||
{
|
||||
type: 'github_repository',
|
||||
url: 'https://github.com/owner/repo',
|
||||
authorization_token: process.env.GITHUB_TOKEN, // repo clone token (≠ MCP auth)
|
||||
authorization_token: process.env.GITHUB_TOKEN, // repo clone token (!= MCP auth)
|
||||
checkout: { type: 'branch', name: 'main' },
|
||||
},
|
||||
],
|
||||
@@ -199,7 +203,7 @@ session = client.beta.sessions.create(
|
||||
resources=[{
|
||||
"type": "github_repository",
|
||||
"url": "https://github.com/owner/repo",
|
||||
"authorization_token": os.environ["GITHUB_TOKEN"], # repo clone token (≠ MCP auth)
|
||||
"authorization_token": os.environ["GITHUB_TOKEN"], # repo clone token (!= MCP auth)
|
||||
"checkout": {"type": "branch", "name": "main"},
|
||||
}],
|
||||
)
|
||||
@@ -216,7 +220,7 @@ Upload and manage files for use as session resources, and download files the age
|
||||
| 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` |
|
||||
| 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.
|
||||
|
||||
Reference in New Issue
Block a user