1# Managed Agents — TypeScript
2 
3> **Bindings not shown here:** This README covers the most common managed-agents flows for TypeScript. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the TypeScript SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK.
4 
5> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path.
6 
7## Installation
8 
9```bash
10npm install @anthropic-ai/sdk
11```
12 
13## Client Initialization
14 
15```typescript
16import Anthropic from "@anthropic-ai/sdk";
17 
18// Default — resolves credentials from the environment:
19// ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN, or an `ant auth login` profile.
20// Prefer this for local dev; don't hardcode a key.
21const client = new Anthropic();
22 
23// Explicit API key (only when you must inject a specific key)
24const client = new Anthropic({ apiKey: "your-api-key" });
25```
26 
27---
28 
29## Create an Environment
30 
31```typescript
32const environment = await client.beta.environments.create(
33  {
34    name: "my-dev-env",
35    config: {
36      type: "cloud",
37      networking: { type: "unrestricted" },
38    },
39  },
40);
41console.log(environment.id); // env_...
42```
43 
44---
45 
46## Create an Agent (required first step)
47 
48> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `agents.create()` — the session only takes `agent: { type: "agent", id: agent.id }`.
49 
50### Minimal
51 
52```typescript
53// 1. Create the agent (reusable, versioned)
54const agent = await client.beta.agents.create(
55  {
56    name: "Coding Assistant",
57    model: "claude-opus-4-8",
58    tools: [{ type: "agent_toolset_20260401", default_config: { enabled: true } }],
59  },
60);
61 
62// 2. Start a session
63const session = await client.beta.sessions.create(
64  {
65    agent: { type: "agent", id: agent.id, version: agent.version },
66    environment_id: environment.id,
67  },
68);
69console.log(session.id, session.status);
70```
71 
72### With system prompt and custom tools
73 
74```typescript
75const agent = await client.beta.agents.create(
76  {
77    name: "Code Reviewer",
78    model: "claude-opus-4-8",
79    system: "You are a senior code reviewer.",
80    tools: [
81      { type: "agent_toolset_20260401", default_config: { enabled: true } },
82      {
83        type: "custom",
84        name: "run_tests",
85        description: "Run the test suite",
86        input_schema: {
87          type: "object",
88          properties: {
89            test_path: { type: "string", description: "Path to test file" },
90          },
91          required: ["test_path"],
92        },
93      },
94    ],
95  },
96);
97 
98const session = await client.beta.sessions.create(
99  {
100    agent: { type: "agent", id: agent.id, version: agent.version },
101    environment_id: environment.id,
102    title: "Code review session",
103    resources: [
104      {
105        type: "github_repository",
106        url: "https://github.com/owner/repo",
107        mount_path: "/workspace/repo",
108        authorization_token: process.env.GITHUB_TOKEN,
109        branch: "main",
110      },
111    ],
112  },
113);
114```
115 
116---
117 
118## Send a User Message
119 
120```typescript
121await client.beta.sessions.events.send(
122  session.id,
123  {
124    events: [
125      {
126        type: "user.message",
127        content: [{ type: "text", text: "Review the auth module" }],
128      },
129    ],
130  },
131);
132```
133 
134> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns).
135 
136---
137 
138## Stream Events (SSE)
139 
140```typescript
141// Stream-first: open stream and send concurrently
142const [events] = await Promise.all([
143  collectStream(session.id),
144  client.beta.sessions.events.send(
145    session.id,
146    { events: [{ type: "user.message", content: [{ type: "text", text: "..." }] }] },
147  ),
148]);
149 
150// Standalone stream iteration:
151const stream = await client.beta.sessions.events.stream(
152  session.id,
153);
154 
155for await (const event of stream) {
156  switch (event.type) {
157    case "agent.message":
158      for (const block of event.content) {
159        if (block.type === "text") {
160          process.stdout.write(block.text);
161        }
162      }
163      break;
164    case "agent.custom_tool_use":
165      // Custom tool invocation — session is now idle
166      console.log(`\nCustom tool call: ${event.name}`);
167      console.log(`Input: ${JSON.stringify(event.input)}`);
168      break;
169    case "session.status_idle":
170      console.log("\n--- Agent idle ---");
171      break;
172    case "session.status_terminated":
173      console.log("\n--- Session terminated ---");
174      break;
175  }
176}
177```
178 
179---
180 
181## Provide Custom Tool Result
182 
183```typescript
184await client.beta.sessions.events.send(
185  session.id,
186  {
187    events: [
188      {
189        type: "user.custom_tool_result",
190        custom_tool_use_id: "sevt_abc123",
191        content: [{ type: "text", text: "All 42 tests passed." }],
192      },
193    ],
194  },
195);
196```
197 
198---
199 
200## Poll Events
201 
202```typescript
203const events = await client.beta.sessions.events.list(
204  session.id,
205);
206for (const event of events.data) {
207  console.log(`${event.type}: ${event.id}`);
208}
209```
210 
211---
212 
213## Full Streaming Loop with Custom Tools
214 
215```typescript
216function runCustomTool(toolName: string, toolInput: unknown): string {
217  if (toolName === "run_tests") {
218    // Your tool implementation here
219    return "All tests passed.";
220  }
221  return `Unknown tool: ${toolName}`;
222}
223 
224async function runSession(client: Anthropic, sessionId: string) {
225  while (true) {
226    const stream = await client.beta.sessions.events.stream(
227      sessionId,
228    );
229 
230    const toolCalls: Anthropic.Beta.Sessions.BetaManagedAgentsAgentCustomToolUseEvent[] = [];
231 
232    for await (const event of stream) {
233      if (event.type === "agent.message") {
234        for (const block of event.content) {
235          if (block.type === "text") {
236            process.stdout.write(block.text);
237          }
238        }
239      } else if (event.type === "agent.custom_tool_use") {
240        toolCalls.push(event);
241      } else if (event.type === "session.status_idle") {
242        break;
243      } else if (event.type === "session.status_terminated") {
244        return;
245      }
246    }
247 
248    if (toolCalls.length === 0) break;
249 
250    // Process custom tool calls
251    const results = toolCalls.map((call) => ({
252      type: "user.custom_tool_result" as const,
253      custom_tool_use_id: call.id,
254      content: [{ type: "text" as const, text: runCustomTool(call.name, call.input) }],
255    }));
256 
257    await client.beta.sessions.events.send(
258      sessionId,
259      { events: results },
260    );
261  }
262}
263```
264 
265---
266 
267## Upload a File
268 
269```typescript
270import fs from "fs";
271 
272const file = await client.beta.files.upload({
273  file: fs.createReadStream("data.csv"),
274});
275 
276// Use in a session
277const session = await client.beta.sessions.create(
278  {
279    agent: { type: "agent", id: agent.id, version: agent.version },
280    environment_id: environment.id,
281    resources: [{ type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }],
282  },
283);
284```
285 
286---
287 
288## List and Download Session Files
289 
290List files the agent wrote to `/mnt/session/outputs/` during a session, then download them.
291 
292```typescript
293import fs from "fs";
294 
295// List files associated with a session
296const files = await client.beta.files.list({
297  scope_id: session.id,
298  betas: ["managed-agents-2026-04-01"],
299});
300for (const f of files.data) {
301  console.log(f.filename, f.size_bytes);
302 
303  // Download and save to disk
304  const resp = await client.beta.files.download(f.id);
305  const buffer = Buffer.from(await resp.arrayBuffer());
306  fs.writeFileSync(f.filename, buffer);
307}
308```
309 
310> 💡 There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if the list is empty.
311 
312---
313 
314## Session Management
315 
316```typescript
317// Get session details
318const session = await client.beta.sessions.retrieve("sesn_011CZxAbc123Def456");
319console.log(session.status, session.usage);
320 
321// List sessions
322const sessions = await client.beta.sessions.list();
323 
324// Delete a session
325await client.beta.sessions.delete("sesn_011CZxAbc123Def456");
326 
327// Archive a session
328await client.beta.sessions.archive("sesn_011CZxAbc123Def456");
329```
330 
331---
332 
333## MCP Server Integration
334 
335```typescript
336// Agent declares MCP server (no auth here — auth goes in a vault)
337const agent = await client.beta.agents.create({
338  name: "MCP Agent",
339  model: "claude-opus-4-8",
340  mcp_servers: [
341    { type: "url", name: "my-tools", url: "https://my-mcp-server.example.com/sse" },
342  ],
343  tools: [
344    { type: "agent_toolset_20260401", default_config: { enabled: true } },
345    { type: "mcp_toolset", mcp_server_name: "my-tools" },
346  ],
347});
348 
349// Session attaches vault(s) containing credentials for those MCP server URLs
350const session = await client.beta.sessions.create({
351  agent: agent.id,
352  environment_id: environment.id,
353  vault_ids: [vault.id],
354});
355```
356 
357See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.
358