mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
Every page now loads /webmcp.js, scripts/webmcp.ts with its types stripped (npm run webmcp). Where the browser has document.modelContext it registers two read-only tools: search_skills over the published skills index, and get_skill, which returns a skill's markdown checked against the index digest. The markdown alternate link moves from build.py to site.py, so CI holds every page to it. The API catalog gains the site itself (llms.txt and the skills index) and hanzo.ai/agents; the live discovery check now fetches every catalog link. tests/site.mjs drives the tools through a recording modelContext, and checks a browser without one loads clean.
360 lines
25 KiB
HTML
360 lines
25 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-client-patterns</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="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/managed-agents-client-patterns">
|
|
<link rel="alternate" type="text/markdown" href="/managed-agents-client-patterns.md">
|
|
<script type="module" src="/webmcp.js"></script>
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/managed-agents-client-patterns.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-client-patterns</h1><p class="lede">Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples.</p><h1>Managed Agents — Common Client Patterns</h1>
|
|
<p>Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples.</p>
|
|
<p>Code samples are TypeScript — other languages follow the same shape; see <code>{lang}/managed-agents/README.md</code> (cURL and C#: <code>curl/managed-agents.md</code>) for equivalents.</p>
|
|
<hr>
|
|
<h2>1. Lossless stream reconnect</h2>
|
|
<p><strong>Problem:</strong> SSE has no replay. If the connection drops mid-session, a naive reconnect re-opens the stream from "now" and you silently miss every event emitted in between.</p>
|
|
<p><strong>Solution:</strong> on reconnect, fetch the full event history via <code>events.list()</code> <em>before</em> consuming the live stream, and dedupe on event ID as the live stream catches up.</p>
|
|
<pre><code class="lang-ts">const seenEventIds = new Set<string>()
|
|
const stream = await client.beta.sessions.events.stream(session.id)
|
|
|
|
// Stream is now open and buffering server-side. Read history first.
|
|
for await (const event of client.beta.sessions.events.list(session.id)) {
|
|
seenEventIds.add(event.id)
|
|
handle(event)
|
|
}
|
|
|
|
// Tail the live stream. Dedupe only gates handle() — terminal checks must run
|
|
// even for already-seen events, or a terminal event that was in the history
|
|
// response gets skipped by `continue` and the loop never exits.
|
|
for await (const event of stream) {
|
|
if (!seenEventIds.has(event.id)) {
|
|
seenEventIds.add(event.id)
|
|
handle(event)
|
|
}
|
|
if (event.type === 'session.status_terminated') break
|
|
if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break
|
|
}</code></pre>
|
|
<hr>
|
|
<h2>2. <code>processed_at</code> — queued vs processed</h2>
|
|
<p>Every event on the stream carries <code>processed_at</code> (ISO 8601), set when the event finishes processing. For client-sent events (<code>user.message</code>, <code>user.interrupt</code>, <code>user.tool_confirmation</code>) it's <code>null</code> while the event is queued behind earlier ones, and populated once the agent processes it — so the same event appears on the stream twice, once with <code>null</code> and once with a timestamp. (Exception: a <code>user.interrupt</code> sent while the session is paused at its budget is accepted and ignored — it never appears at all; see <code>shared/managed-agents-events.md</code> § Reaching a session budget.)</p>
|
|
<p><strong>Three event types skip the queued phase:</strong> <code>user.define_outcome</code>, <code>user.custom_tool_result</code>, and <code>user.tool_result</code> are processed on receipt and echoed back with <code>processed_at</code> already populated. A pending → acknowledged UI that assumes "first sighting is always <code>null</code>" will never clear for these — treat a populated <code>processed_at</code> on first sighting as immediately acknowledged.</p>
|
|
<pre><code class="lang-ts">for await (const event of stream) {
|
|
if (event.type === 'user.message') {
|
|
if (event.processed_at == null) onQueued(event.id)
|
|
else onProcessed(event.id, event.processed_at)
|
|
}
|
|
}</code></pre>
|
|
<p>Use this to drive pending → acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned <code>event.id</code> is application-specific (typically via the return value of <code>events.send()</code> or FIFO ordering).</p>
|
|
<hr>
|
|
<h2>3. Interrupt a running session</h2>
|
|
<p>Send <code>user.interrupt</code> as a normal event. The session keeps running until it reaches a safe boundary, then goes idle.</p>
|
|
<pre><code class="lang-ts">await client.beta.sessions.events.send(session.id, {
|
|
events: [{ type: 'user.interrupt' }],
|
|
})
|
|
|
|
// Drain until the session is truly done — see Pattern 5 for the full gate.
|
|
for await (const event of stream) {
|
|
if (event.type === 'session.status_terminated') break
|
|
if (
|
|
event.type === 'session.status_idle' &&
|
|
event.stop_reason.type !== 'requires_action'
|
|
) break
|
|
}</code></pre>
|
|
<p>Reference: <code>interrupt.ts</code> — sends the interrupt the moment it sees <code>span.model_request_start</code>, drains to idle, then verifies via <code>sessions.retrieve()</code>.</p>
|
|
<hr>
|
|
<h2>4. <code>tool_confirmation</code> round-trip</h2>
|
|
<p>When the agent has <code>permission_policy: { type: 'always_ask' }</code>, any call to that tool fires an <code>agent.tool_use</code> event with <code>evaluated_permission === 'ask'</code> and the session goes idle waiting for a decision. Respond with <code>user.tool_confirmation</code>.</p>
|
|
<pre><code class="lang-ts">for await (const event of stream) {
|
|
if (event.type === 'agent.tool_use' && event.evaluated_permission === 'ask') {
|
|
await client.beta.sessions.events.send(session.id, {
|
|
events: [{
|
|
type: 'user.tool_confirmation',
|
|
tool_use_id: event.id, // not a toolu_ id — use event.id
|
|
result: 'allow', // or 'deny'
|
|
// deny_message: '...', // optional, only with result: 'deny'
|
|
}],
|
|
})
|
|
}
|
|
}</code></pre>
|
|
<p>Key points:</p>
|
|
<ul><li><code>tool_use_id</code> is <code>event.id</code> (typically <code>sevt_...</code>), <strong>not</strong> a <code>toolu_...</code> ID.</li><li><code>result</code> is <code>'allow' | 'deny'</code>. Use <code>deny_message</code> to tell the model <em>why</em> you denied — it gets surfaced back to the agent.</li><li>Multiple pending tools: respond once per <code>agent.tool_use</code> event with <code>evaluated_permission === 'ask'</code>.</li></ul>
|
|
<p>Reference: <code>tool-permissions.ts</code>.</p>
|
|
<hr>
|
|
<h2>5. Correct idle-break gate</h2>
|
|
<p>Do not break on <code>session.status_idle</code> alone. The session goes idle transiently — e.g. between parallel tool executions, while waiting for a <code>user.tool_confirmation</code>, or while awaiting a <code>user.custom_tool_result</code>. Break when idle with a non-<code>requires_action</code> <code>stop_reason</code> (terminal, or <code>budget_reached</code> — resumable only by a budget update, so break unless you intend to change or remove the budget), or on <code>session.status_terminated</code>.</p>
|
|
<pre><code class="lang-ts">for await (const event of stream) {
|
|
handle(event)
|
|
if (event.type === 'session.status_terminated') break
|
|
if (event.type === 'session.status_idle') {
|
|
if (event.stop_reason.type === 'requires_action') continue // waiting on you — handle it
|
|
break // end_turn, retries_exhausted, or budget_reached — see list below
|
|
}
|
|
}</code></pre>
|
|
<p><code>stop_reason.type</code> values on <code>session.status_idle</code>:</p>
|
|
<ul><li><code>requires_action</code> — agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break.</li><li><code>retries_exhausted</code> — terminal failure. Break, then check <code>sessions.retrieve()</code> for the error state.</li><li><code>end_turn</code> — normal completion.</li><li><code>budget_reached</code> — the session hit its spend cap and paused. Not terminal and not resumable by any event: change (typically raise) or remove the session's <code>budget</code> to resume, or treat it as done. A <code>session.usage</code> event with the final cost immediately precedes this idle. See <code>shared/managed-agents-core.md</code> § Session budgets.</li></ul>
|
|
<hr>
|
|
<h2>6. Post-idle status-write race</h2>
|
|
<p>The SSE stream emits <code>session.status_idle</code> slightly before the session's queryable status reflects it. Clients that break on idle and immediately call <code>sessions.delete()</code> or <code>sessions.archive()</code> will intermittently 400 with "cannot delete/archive while running."</p>
|
|
<p>Poll before cleanup:</p>
|
|
<pre><code class="lang-ts">let s
|
|
for (let i = 0; i < 10; i++) {
|
|
s = await client.beta.sessions.retrieve(session.id)
|
|
if (s.status !== 'running') break
|
|
await new Promise(r => setTimeout(r, 200))
|
|
}
|
|
if (s?.status !== 'running') {
|
|
await client.beta.sessions.archive(session.id)
|
|
} // else: still running after 2s — don't archive, let it settle or escalate</code></pre>
|
|
<hr>
|
|
<h2>7. Stream-first, then send</h2>
|
|
<p>Always open the stream <strong>before</strong> sending the kickoff event. Otherwise the agent may process the event and emit the first events before your consumer is attached, and you'll miss them.</p>
|
|
<pre><code class="lang-ts">const stream = await client.beta.sessions.events.stream(session.id)
|
|
await client.beta.sessions.events.send(session.id, {
|
|
events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }],
|
|
})
|
|
for await (const event of stream) { /* ... */ }</code></pre>
|
|
<p>The <code>Promise.all([stream, send])</code> shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened.</p>
|
|
<hr>
|
|
<h2>8. File-mount gotchas</h2>
|
|
<p><strong>The mounted resource has a different <code>file_id</code> than the file you uploaded.</strong> Session creation makes a session-scoped copy.</p>
|
|
<pre><code class="lang-ts">const uploaded = await client.beta.files.upload({ file, purpose: 'agent_resource' })
|
|
// uploaded.id → the original file
|
|
const session = await client.beta.sessions.create({
|
|
/* ... */
|
|
resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/workspace/data.csv' }],
|
|
})
|
|
// session.resources[0].file_id !== uploaded.id ← different IDs</code></pre>
|
|
<p>Delete the original via <code>files.delete(uploaded.id)</code>; the session-scoped copy is garbage-collected with the session. <code>mount_path</code> must be absolute — see <code>shared/managed-agents-environments.md</code>.</p>
|
|
<hr>
|
|
<h2>9. Secrets for non-MCP APIs and CLIs — keep them host-side via custom tools</h2>
|
|
<p><strong>Problem:</strong> you want the agent to call a third-party API or run a CLI that needs a secret (API key, token, service-account credential), but you can't or don't want to hand the secret to a vault.</p>
|
|
<p><strong>First check:</strong> for cloud environments, the first-class answer is now a vault <code>environment_variable</code> credential — the agent's shell sees an opaque placeholder and the real secret is substituted at egress. See <code>shared/managed-agents-tools.md</code> → Vaults. Use this pattern instead when that doesn't fit: <strong>self-hosted sandboxes</strong> (env-var credentials not yet supported there), clients that reject the placeholder via local format validation, secrets that must never leave your infrastructure, or calls that need host-side binaries.</p>
|
|
<p><strong>Solution:</strong> move the authenticated call to your side. Declare a custom tool on the agent; when the agent emits <code>agent.custom_tool_use</code>, your orchestrator (the process reading the SSE stream) executes the call with its own credentials and responds with <code>user.custom_tool_result</code>. The container never sees the key.</p>
|
|
<pre><code class="lang-ts">// Agent template: declare the tool, no credentials
|
|
tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }]
|
|
|
|
// Orchestrator: handle the call with host-side creds
|
|
for await (const event of stream) {
|
|
if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') {
|
|
const result = await linear.request(event.input.query, event.input.vars) // host's key
|
|
await client.beta.sessions.events.send(session.id, {
|
|
events: [{
|
|
type: 'user.custom_tool_result',
|
|
custom_tool_use_id: event.id,
|
|
content: [{ type: 'text', text: JSON.stringify(result) }],
|
|
}],
|
|
})
|
|
}
|
|
}</code></pre>
|
|
<p>Same shape works for <code>gh</code> CLI, local eval scripts, or anything else that needs host-side auth or binaries.</p>
|
|
<p><strong>Security note:</strong> this does not expose a public endpoint. <code>agent.custom_tool_use</code> arrives on the SSE stream your orchestrator already holds open with your Anthropic API key, and <code>user.custom_tool_result</code> goes back via <code>events.send()</code> under the same key. Your orchestrator is a client, not a server — nothing unauthenticated is listening.</p>
|
|
<p><strong>Do not embed API keys in the system prompt or user messages as a workaround.</strong> Prompts and messages are stored in the session's event history, returned by <code>events.list()</code>, and included in compaction summaries — a secret placed there is durably persisted and readable via the API for the life of the session.</p>
|
|
<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-client-patterns.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |