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