mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
235 lines
27 KiB
HTML
235 lines
27 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>managed-agents-overview</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/managed-agents-overview.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/managed-agents-overview">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/managed-agents-overview.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>managed-agents-overview</h1><p class="lede">Managed Agents provisions a container per session as the agent's workspace.</p><h1>Managed Agents — Overview</h1>
|
|
<p>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 <em>tools</em> execute — bash commands, file operations, code. You create a persisted <strong>Agent</strong> config (model, system prompt, tools, MCP servers, skills), then start <strong>Sessions</strong> that reference it. The session streams events back to you; you send user messages and tool results in.</p>
|
|
<h2>⚠️ THE MANDATORY FLOW: Agent (once) → Session (every run)</h2>
|
|
<p><strong>Why agents are separate objects: versioning.</strong> 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 <code>agents.create()</code> fresh on every run.</p>
|
|
<p>Every session references a pre-created <code>/v1/agents</code> object. Create the agent once, store the ID, and reuse it across runs.</p>
|
|
<p>| Step | Call | Frequency | |---|---|---| | 1 | <code>POST /v1/agents</code> — <code>model</code>, <code>system</code>, <code>tools</code>, <code>mcp_servers</code>, <code>skills</code> live here | <strong>ONCE.</strong> Store <code>agent.id</code> <strong>and</strong> <code>agent.version</code>. | | 2 | <code>POST /v1/sessions</code> — <code>agent: "agent_abc123"</code> or <code>{type: "agent", id, version}</code> | <strong>Every run.</strong> String shorthand uses latest version. |</p>
|
|
<p>If you're about to write <code>sessions.create()</code> with <code>model</code>, <code>system</code>, or <code>tools</code> on the session body — <strong>stop</strong>. Those fields live on <code>agents.create()</code>. The session takes a <em>pointer</em> only.</p>
|
|
<p><strong>When generating code, separate setup from runtime.</strong> <code>agents.create()</code> belongs in a setup script (or a guarded <code>if agent_id is None:</code> block), not at the top of the hot path. If the user's code calls <code>agents.create()</code> 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 <code>ant beta:agents create < agent.yaml</code> (or a guarded setup script — see <code>shared/anthropic-cli.md</code>), persist the returned ID (config file, env var, secrets manager), and have every run load the ID and call <code>sessions.create()</code>.</p>
|
|
<p><strong>To change the agent's behavior, use <code>POST /v1/agents/{id}</code> — don't create a new one.</strong> Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via <code>{type: "agent", id, version}</code>). See <code>shared/managed-agents-core.md</code> → Agents → Versioning. To change <code>tools</code>/<code>mcp_servers</code> on <strong>one running session</strong> without touching the agent object, use <code>sessions.update()</code> (<code>vault_ids</code> attaches at session create only) — see <code>shared/managed-agents-core.md</code> → Updating the agent configuration mid-session.</p>
|
|
<h2>Beta Headers</h2>
|
|
<p>Managed Agents is in beta. The SDK sets required beta headers automatically:</p>
|
|
<p>| Beta Header | What it enables | | ------------------------------ | ---------------------------------------------------- | | <code>managed-agents-2026-04-01</code> | Agents, Environments, Sessions, Events, Session Resources, Session Threads, Outcomes, Multiagent, Vaults, Credentials, Memory Stores, Deployments | | <code>skills-2025-10-02</code> | Skills API (for managing custom skill definitions) | | <code>files-api-2025-04-14</code> | Files API for file uploads |</p>
|
|
<p><strong>Which beta header goes where:</strong> The SDK sets <code>managed-agents-2026-04-01</code> automatically on <code>client.beta.{agents,environments,sessions,vaults,memory_stores,deployments,deployment_runs}.<em></code> calls, and <code>files-api-2025-04-14</code> / <code>skills-2025-10-02</code> automatically on <code>client.beta.files.</em></code> / <code>client.beta.skills.*</code> 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 <strong>grants Files API access on its own</strong>, so uploading a file for use as a session resource does not need <code>files-api-2025-04-14</code> alongside it. (Direct Skills API calls over cURL do still need <code>skills-2025-10-02</code>; the <code>ant</code> CLI and the SDKs send it for you.) <strong>Exception — session-scoped file listing:</strong> <code>client.beta.files.list({scope_id: session.id})</code> is a Files endpoint that takes a Managed Agents parameter, so it needs <strong>both</strong> headers. Pass <code>betas: ["managed-agents-2026-04-01"]</code> explicitly on that call (the SDK adds the Files header; you add the Managed Agents one). See <code>shared/managed-agents-environments.md</code> → Session outputs.</p>
|
|
<h2>Reading Guide</h2>
|
|
<p>| User wants to... | Read these files | | -------------------------------------- | ------------------------------------------------------- | | <strong>Get started from scratch / "help me set up an agent"</strong> | <code>shared/managed-agents-onboarding.md</code> — guided interview (WHERE→WHO→WHAT→WATCH), then emit code | | Understand how the API works | <code>shared/managed-agents-core.md</code> | | See the full endpoint reference | <code>shared/managed-agents-api-reference.md</code> | | <strong>Create an agent</strong> (required first step) | <code>shared/managed-agents-core.md</code> (Agents section) + language file | | Update/version an agent | <code>shared/managed-agents-core.md</code> (Agents → Versioning) — update, don't re-create | | Create a session | <code>shared/managed-agents-core.md</code> + <code>{lang}/managed-agents/README.md</code> (cURL/C#: <code>curl/managed-agents.md</code>) | | Configure tools and permissions | <code>shared/managed-agents-tools.md</code> | | Set up MCP servers | <code>shared/managed-agents-tools.md</code> (MCP Servers section) | | Stream events / handle tool_use | <code>shared/managed-agents-events.md</code> + language file | | Get notified of session state changes via webhook (no polling) | <code>shared/managed-agents-webhooks.md</code> — Console-registered endpoint, HMAC verify, thin payload + fetch | | Define an outcome / rubric-graded iterate loop | <code>shared/managed-agents-outcomes.md</code> — <code>user.define_outcome</code> event, grader, <code>span.outcome_evaluation_*</code> events | | Coordinate multiple agents / subagents / threads | <code>shared/managed-agents-multiagent.md</code> — <code>multiagent: {type: "coordinator", agents: [...]}</code> on the agent, session threads, cross-posted tool confirmations | | Set up environments | <code>shared/managed-agents-environments.md</code> + language file | | Run tool execution in your own infra / VPC (self-hosted sandbox) | <code>shared/managed-agents-self-hosted-sandboxes.md</code> — <code>config:{type:"self_hosted"}</code>, <code>ANTHROPIC_ENVIRONMENT_KEY</code>, <code>EnvironmentWorker.run()</code> / <code>ant beta:worker poll</code> | | Upload files / attach repos | <code>shared/managed-agents-environments.md</code> (Resources) | | Give agents persistent memory across sessions | <code>shared/managed-agents-memory.md</code> — memory stores, <code>memory_store</code> session resource, preconditions, versions/redact | | Define agents/environments as version-controlled YAML; drive the API from the shell | <code>shared/anthropic-cli.md</code> — <code>ant beta:agents create < agent.yaml</code>, <code>--transform</code>, <code>@file</code> inlining | | Store credentials (MCP auth, API keys for CLIs/SDKs) | <code>shared/managed-agents-tools.md</code> (Vaults section) — <code>mcp_oauth</code> / <code>static_bearer</code> / <code>environment_variable</code> | | Call a non-MCP API / CLI that needs a secret | <code>shared/managed-agents-tools.md</code> (Vaults section) — <code>environment_variable</code> credential, substituted at egress. If that doesn't fit (e.g. self-hosted sandboxes), <code>shared/managed-agents-client-patterns.md</code> Pattern 9 keeps the secret host-side via a custom tool | | Run an agent on a recurring cron schedule | <code>shared/managed-agents-scheduled-deployments.md</code> — deployments, deployment runs, pause/auto-pause | | Cap a session's spend with a hard dollar budget | <code>shared/managed-agents-core.md</code> (§ Session budgets) — <code>budget</code> at session create, <code>budget_reached</code> pause, change/remove to resume. Deployments: <code>shared/managed-agents-scheduled-deployments.md</code> § Deployment budgets | | Pin where model inference runs (data residency) | <code>shared/managed-agents-core.md</code> (§ Pinning inference geography) — <code>model.inference_geo</code> on the agent, per-session override, roster uniformity | | Load skills from the codebase instead of uploading | <code>shared/managed-agents-tools.md</code> (§ Skills from a GitHub repository) — root <code>.claude/skills</code> discovery at session start | | Give the session an advisor to consult mid-turn | <code>shared/managed-agents-multiagent.md</code> (§ Advisor) — <code>{type: "advisor", model}</code> roster entry, consultation threads, plaintext vs redacted delivery |</p>
|
|
<h2>Common Pitfalls</h2>
|
|
<ul><li><strong>Agent FIRST, then session — NO EXCEPTIONS</strong> — the session's <code>agent</code> field accepts <strong>only</strong> a string ID or <code>{type: "agent", id, version}</code>. <code>model</code>, <code>system</code>, <code>tools</code>, <code>mcp_servers</code>, <code>skills</code> are <strong>top-level fields on <code>POST /v1/agents</code></strong>, never on <code>sessions.create()</code>. If the user hasn't created an agent, that is step zero of every example.</li><li><strong>Agent ONCE, not every run</strong> — <code>agents.create()</code> is a setup step. Store the returned <code>agent_id</code> and reuse it; don't call <code>agents.create()</code> at the top of your hot path. If the agent's config needs to change, <code>POST /v1/agents/{id}</code> — each update creates a new version, and sessions can pin to a specific version for reproducibility.</li><li><strong>MCP auth goes through vaults</strong> — the agent's <code>mcp_servers</code> array declares <code>{type, name, url}</code> only (no auth). Credentials live in vaults (<code>client.beta.vaults.credentials.create</code>) and attach to sessions via <code>vault_ids</code>. Anthropic auto-refreshes OAuth tokens using the stored refresh token. Vaults also hold <code>environment_variable</code> credentials for non-MCP services (CLIs, SDKs, direct API calls) — substituted at egress, never visible in the sandbox.</li><li><strong>Reconcile resources before the first run</strong> — 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 <code>shared/managed-agents-onboarding.md</code> → §3 Pre-flight viability check.</li><li><strong>Stream to get events</strong> — <code>GET /v1/sessions/{id}/events/stream</code> is the primary way to receive agent output in real-time.</li><li><strong>SSE stream has no replay — reconnect with consolidation</strong> — if the stream drops while a <code>agent.tool_use</code>, <code>agent.mcp_tool_use</code>, or <code>agent.custom_tool_use</code> is pending resolution (<code>user.tool_confirmation</code> for the first two, <code>user.custom_tool_result</code> for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with <code>GET /v1/sessions/{id}/events/stream</code> , fetch <code>GET /v1/sessions/{id}/events</code>, dedupe by event ID, then proceed. See <code>shared/managed-agents-events.md</code> → Reconnecting after a dropped stream.</li><li><strong>Don't trust HTTP-library timeouts as wall-clock caps</strong> — <code>requests</code> <code>timeout=(c, r)</code> and <code>httpx.Timeout(n)</code> are <em>per-chunk</em> read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track <code>time.monotonic()</code> at the loop level and bail explicitly. Prefer the SDK's <code>sessions.events.stream()</code> / <code>sessions.events.list()</code> over hand-rolled HTTP. See <code>shared/managed-agents-events.md</code> → Receiving Events.</li><li><strong>Messages queue</strong> — you can send events while the session is <code>running</code> or <code>idle</code>; they're processed in order. No need to wait for a response before sending the next message. Exception: a session paused at its budget (<code>stop_reason: budget_reached</code>) accepts only settle events — change or remove the budget to resume (<code>shared/managed-agents-core.md</code> § Session budgets).</li><li><strong>Environment <code>config.type</code> is <code>"cloud"</code> or <code>"self_hosted"</code></strong> — <code>cloud</code> runs the container on Anthropic's infrastructure; <code>self_hosted</code> moves tool execution to your own (see <code>shared/managed-agents-self-hosted-sandboxes.md</code>).</li><li><strong>Archive is permanent on every resource</strong> — 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 <code>.archive()</code> on a production agent, environment, or memory store as cleanup — <strong>always confirm with the user before archiving</strong>.</li></ul>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/managed-agents-overview.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |