1# Managed Agents — Common Client Patterns
2 
3Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples.
4 
5Code samples are TypeScript — Python and cURL follow the same shape; see `python/managed-agents/README.md` and `curl/managed-agents.md` for equivalents.
6 
7---
8 
9## 1. Lossless stream reconnect
10 
11**Problem:** 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.
12 
13**Solution:** on reconnect, fetch the full event history via `events.list()` *before* consuming the live stream, and dedupe on event ID as the live stream catches up.
14 
15```ts
16const seenEventIds = new Set<string>()
17const stream = await client.beta.sessions.events.stream(session.id)
18 
19// Stream is now open and buffering server-side. Read history first.
20for await (const event of client.beta.sessions.events.list(session.id)) {
21  seenEventIds.add(event.id)
22  handle(event)
23}
24 
25// Tail the live stream. Dedupe only gates handle() — terminal checks must run
26// even for already-seen events, or a terminal event that was in the history
27// response gets skipped by `continue` and the loop never exits.
28for await (const event of stream) {
29  if (!seenEventIds.has(event.id)) {
30    seenEventIds.add(event.id)
31    handle(event)
32  }
33  if (event.type === 'session.status_terminated') break
34  if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break
35}
36```
37 
38---
39 
40## 2. `processed_at` — queued vs processed
41 
42Every event on the stream carries `processed_at` (ISO 8601). For client-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`) it's `null` when the event has been queued but not yet picked up by the agent, and populated once the agent processes it. The same event appears on the stream twice — once with `processed_at: null`, once with a timestamp.
43 
44```ts
45for await (const event of stream) {
46  if (event.type === 'user.message') {
47    if (event.processed_at == null) onQueued(event.id)
48    else onProcessed(event.id, event.processed_at)
49  }
50}
51```
52 
53Use this to drive pending → acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned `event.id` is application-specific (typically via the return value of `events.send()` or FIFO ordering).
54 
55---
56 
57## 3. Interrupt a running session
58 
59Send `user.interrupt` as a normal event. The session keeps running until it reaches a safe boundary, then goes idle.
60 
61```ts
62await client.beta.sessions.events.send(session.id, {
63  events: [{ type: 'user.interrupt' }],
64})
65 
66// Drain until the session is truly done — see Pattern 5 for the full gate.
67for await (const event of stream) {
68  if (event.type === 'session.status_terminated') break
69  if (
70    event.type === 'session.status_idle' &&
71    event.stop_reason.type !== 'requires_action'
72  ) break
73}
74```
75 
76Reference: `interrupt.ts` — sends the interrupt the moment it sees `span.model_request_start`, drains to idle, then verifies via `sessions.retrieve()`.
77 
78---
79 
80## 4. `tool_confirmation` round-trip
81 
82When the agent has `permission_policy: { type: 'always_ask' }`, any call to that tool fires an `agent.tool_use` event with `evaluated_permission === 'ask'` and the session goes idle waiting for a decision. Respond with `user.tool_confirmation`.
83 
84```ts
85for await (const event of stream) {
86  if (event.type === 'agent.tool_use' && event.evaluated_permission === 'ask') {
87    await client.beta.sessions.events.send(session.id, {
88      events: [{
89        type: 'user.tool_confirmation',
90        tool_use_id: event.id,         // not a toolu_ id — use event.id
91        result: 'allow',               // or 'deny'
92        // deny_message: '...',        // optional, only with result: 'deny'
93      }],
94    })
95  }
96}
97```
98 
99Key points:
100- `tool_use_id` is `event.id` (typically `sevt_...`), **not** a `toolu_...` ID.
101- `result` is `'allow' | 'deny'`. Use `deny_message` to tell the model *why* you denied — it gets surfaced back to the agent.
102- Multiple pending tools: respond once per `agent.tool_use` event with `evaluated_permission === 'ask'`.
103 
104Reference: `tool-permissions.ts`.
105 
106---
107 
108## 5. Correct idle-break gate
109 
110Do not break on `session.status_idle` alone. The session goes idle transiently — e.g. between parallel tool executions, while waiting for a `user.tool_confirmation`, or while awaiting a `user.custom_tool_result`. Break when idle with a terminal `stop_reason`, or on `session.status_terminated`.
111 
112```ts
113for await (const event of stream) {
114  handle(event)
115  if (event.type === 'session.status_terminated') break
116  if (event.type === 'session.status_idle') {
117    if (event.stop_reason.type === 'requires_action') continue // waiting on you — handle it
118    break // end_turn or retries_exhausted — both terminal
119  }
120}
121```
122 
123`stop_reason.type` values on `session.status_idle`:
124- `requires_action` — agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break.
125- `retries_exhausted` — terminal failure. Break, then check `sessions.retrieve()` for the error state.
126- `end_turn` — normal completion.
127 
128---
129 
130## 6. Post-idle status-write race
131 
132The SSE stream emits `session.status_idle` slightly before the session's queryable status reflects it. Clients that break on idle and immediately call `sessions.delete()` or `sessions.archive()` will intermittently 400 with "cannot delete/archive while running."
133 
134Poll before cleanup:
135 
136```ts
137let s
138for (let i = 0; i < 10; i++) {
139  s = await client.beta.sessions.retrieve(session.id)
140  if (s.status !== 'running') break
141  await new Promise(r => setTimeout(r, 200))
142}
143if (s?.status !== 'running') {
144  await client.beta.sessions.archive(session.id)
145} // else: still running after 2s — don't archive, let it settle or escalate
146```
147 
148---
149 
150## 7. Stream-first, then send
151 
152Always open the stream **before** 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.
153 
154```ts
155const stream = await client.beta.sessions.events.stream(session.id)
156await client.beta.sessions.events.send(session.id, {
157  events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }],
158})
159for await (const event of stream) { /* ... */ }
160```
161 
162The `Promise.all([stream, send])` shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened.
163 
164---
165 
166## 8. File-mount gotchas
167 
168**The mounted resource has a different `file_id` than the file you uploaded.** Session creation makes a session-scoped copy.
169 
170```ts
171const uploaded = await client.beta.files.upload({ file })
172// uploaded.id         → the original file
173const session = await client.beta.sessions.create({
174  /* ... */
175  resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/workspace/data.csv' }],
176})
177// session.resources[0].file_id !== uploaded.id  ← different IDs
178```
179 
180Delete the original via `files.delete(uploaded.id)`; the session-scoped copy is garbage-collected with the session. `mount_path` must be absolute — see `shared/managed-agents-environments.md`.
181 
182---
183 
184## 9. Secrets for non-MCP APIs and CLIs — keep them host-side via custom tools
185 
186**Problem:** 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 there is currently no way to set environment variables inside the session container, and vaults currently hold MCP credentials only — they are not exposed to the container's shell. So `curl`, installed CLIs, or SDK clients running via the `bash` tool have no first-class place to read a secret from.
187 
188**Solution:** move the authenticated call to your side. Declare a custom tool on the agent; when the agent emits `agent.custom_tool_use`, your orchestrator (the process reading the SSE stream) executes the call with its own credentials and responds with `user.custom_tool_result`. The container never sees the key.
189 
190```ts
191// Agent template: declare the tool, no credentials
192tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }]
193 
194// Orchestrator: handle the call with host-side creds
195for await (const event of stream) {
196  if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') {
197    const result = await linear.request(event.input.query, event.input.vars) // host's key
198    await client.beta.sessions.events.send(session.id, {
199      events: [{ type: 'user.custom_tool_result', tool_use_id: event.id, result }],
200    })
201  }
202}
203```
204 
205Same shape works for `gh` CLI, local eval scripts, or anything else that needs host-side auth or binaries.
206 
207**Security note:** this does not expose a public endpoint. `agent.custom_tool_use` arrives on the SSE stream your orchestrator already holds open with your Anthropic API key, and `user.custom_tool_result` goes back via `events.send()` under the same key. Your orchestrator is a client, not a server — nothing unauthenticated is listening.
208 
209**Do not embed API keys in the system prompt or user messages as a workaround.** Prompts and messages are stored in the session's event history, returned by `events.list()`, and included in compaction summaries — a secret placed there is durably persisted and readable via the API for the life of the session.
210