api/beta/sessions/events/stream / documentation change

The whole hunk

from line 1, old and new numbered

lines

The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.

from line 1

1---

2title: Stream Events

3url: https://platform.claude.com/docs/en/api/beta/sessions/events/stream

4---

16# Stream Events

38**GET** `/v1/sessions/{session_id}/events/stream`

from line 31

2631

2732 - `string`

2833

29 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`

34 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`

3035

3136 - `"message-batches-2024-09-24"`

3237

from line 79

7479

7580 - `"user-profiles-2026-08-18"`

7681

82 - `"user-profiles-2026-09-04"`

7784 - `"advisor-tool-2026-03-01"`

7885

7986 - `"managed-agents-2026-04-01"`

from line 123

116123

117124 - `"mid-conversation-system-clear-at-2026-08-21"`

118125

126- `"anthropic-workspace-id": optional string`

127

119128## Returns

120129

121130- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`

from line 135

126135

127136 A user message event in the session conversation.

128137

138 - `type: "user.message"`

139

129140 - `id: string`

130141

131142 Unique identifier for this event.

from line 149

138149

139150 Regular text content.

140151

152 - `type: "text"`

153

141154 - `text: string`

142155

143156 The text content.

144157

145158 minLength: 1

146159

160 - `BetaManagedAgentsImageBlock object`

161

162 Image content specified directly as base64 data or as a reference via a URL.

163

164 - `type: "image"`

165

166 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

167

168 Union type for image source variants.

169

170 - `BetaManagedAgentsBase64ImageSource object`

171

172 Base64-encoded image data.

173

174 - `type: "base64"`

175

176 - `data: string`

177

178 Base64-encoded image data.

179

180 minLength: 1

181

182 - `media_type: string`

183

184 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

185

186 minLength: 1

187

188 - `BetaManagedAgentsURLImageSource object`

189

190 Image referenced by URL.

191

192 - `type: "url"`

193

194 - `url: string`

195

196 URL of the image to fetch.

197

198 minLength: 1

199

200 - `BetaManagedAgentsFileImageSource object`

201

202 Image referenced by file ID.

203

204 - `type: "file"`

205

206 - `file_id: string`

207

208 ID of a previously uploaded file.

209

210 minLength: 1

211

212 - `BetaManagedAgentsDocumentBlock object`

213

214 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

215

216 - `type: "document"`

217

218 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`

219

220 Union type for document source variants.

221

222 - `BetaManagedAgentsBase64DocumentSource object`

223

224 Base64-encoded document data.

225

226 - `type: "base64"`

227

228 - `data: string`

229

230 Base64-encoded document data.

231

232 minLength: 1

233

234 - `media_type: string`

235

236 MIME type of the document (e.g., "application/pdf").

237

238 minLength: 1

239

240 - `BetaManagedAgentsPlainTextDocumentSource object`

241

242 Plain text document content.

243

244 - `type: "text"`

245

246 - `data: string`

247

248 The plain text content.

249

250 minLength: 1

251

252 - `media_type: "text/plain"`

253

254 MIME type of the text content. Must be "text/plain".

255

256 - `BetaManagedAgentsURLDocumentSource object`

257

258 Document referenced by URL.

259

260 - `type: "url"`

261

262 - `url: string`

263

264 URL of the document to fetch.

265

266 minLength: 1

267

268 - `BetaManagedAgentsFileDocumentSource object`

269

270 Document referenced by file ID.

271

272 - `type: "file"`

273

274 - `file_id: string`

275

276 ID of a previously uploaded file.

277

278 minLength: 1

279

280 - `context: optional string or null`

281

282 Additional context about the document for the model.

283

284 - `title: optional string or null`

285

286 The title of the document.

287

288 - `BetaManagedAgentsRedactedBlock object`

289

290 Placeholder for content withheld by Anthropic model policy.

291

292 - `type: "redacted"`

293

294 - `processed_at: optional string or null`

295

296 A timestamp in RFC 3339 format

297

298 format: date-time

299

300 - `BetaManagedAgentsUserInterruptEvent object`

301

302 An interrupt event that pauses agent execution and returns control to the user.

303

304 - `type: "user.interrupt"`

305

306 - `id: string`

307

308 Unique identifier for this event.

309

310 - `processed_at: optional string or null`

311

312 A timestamp in RFC 3339 format

313

314 format: date-time

315

316 - `session_thread_id: optional string or null`

317

318 If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

319

320 - `BetaManagedAgentsUserToolConfirmationEvent object`

321

322 A tool confirmation event that approves or denies a pending tool execution.

323

324 - `type: "user.tool_confirmation"`

325

326 - `id: string`

327

328 Unique identifier for this event.

329

330 - `result: "allow" or "deny"`

331

332 UserToolConfirmationResult enum

333

334 - `"allow"`

335

336 - `"deny"`

337

338 - `tool_use_id: string`

339

340 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

341

342 - `deny_message: optional string or null`

343

344 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

345

346 maxLength: 10000

347

348 - `processed_at: optional string or null`

349

350 A timestamp in RFC 3339 format

351

352 format: date-time

353

354 - `session_thread_id: optional string or null`

355

356 When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

357

358 - `BetaManagedAgentsUserCustomToolResultEvent object`

359

360 Event sent by the client providing the result of a custom tool execution.

361

362 - `type: "user.custom_tool_result"`

363

364 - `id: string`

365

366 Unique identifier for this event.

367

368 - `custom_tool_use_id: string`

369

370 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

371

372 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

373

374 The result content returned by the tool.

375

376 - `BetaManagedAgentsTextBlock object`

377

378 Regular text content.

379

380 - `BetaManagedAgentsImageBlock object`

381

382 Image content specified directly as base64 data or as a reference via a URL.

383

384 - `BetaManagedAgentsDocumentBlock object`

385

386 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

387

388 - `BetaManagedAgentsSearchResultBlock object`

389

390 A block containing a web search result.

391

392 - `type: "search_result"`

393

394 - `citations: BetaManagedAgentsSearchResultCitations`

395

396 Citation settings for a search result.

397

398 - `enabled: boolean`

399

400 Whether citations are enabled for this search result.

401

402 - `content: array of BetaManagedAgentsSearchResultContent`

403

404 Array of text content blocks from the search result.

405

406 - `type: "text"`

407

408 - `text: string`

409

410 The text content.

411

412 minLength: 1

413

414 - `source: string`

415

416 The URL source of the search result.

417

418 minLength: 1

419

420 - `title: string`

421

422 The title of the search result.

423

424 minLength: 1

425

426 - `is_error: optional boolean or null`

427

428 Whether the tool execution resulted in an error.

429

430 - `processed_at: optional string or null`

431

432 A timestamp in RFC 3339 format

433

434 format: date-time

435

436 - `session_thread_id: optional string or null`

437

438 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

439

440 - `BetaManagedAgentsAgentCustomToolUseEvent object`

441

442 Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.

443

444 - `type: "agent.custom_tool_use"`

445

446 - `id: string`

447

448 Unique identifier for this event.

449

450 - `input: map[unknown]`

451

452 Input parameters for the tool call.

453

454 - `name: string`

455

456 Name of the custom tool being called.

457

458 - `processed_at: string`

459

460 A timestamp in RFC 3339 format

461

462 format: date-time

463

464 - `session_thread_id: optional string or null`

465

466 When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.

467

468 - `BetaManagedAgentsAgentMessageEvent object`

469

470 An agent response event in the session conversation.

471

472 - `type: "agent.message"`

473

474 - `id: string`

475

476 Unique identifier for this event.

477

478 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`

479

480 Array of text blocks comprising the agent response.

481

482 - `BetaManagedAgentsTextBlock object`

483

484 Regular text content.

485

486 - `BetaManagedAgentsRedactedBlock object`

487

488 Placeholder for content withheld by Anthropic model policy.

489

490 - `processed_at: string`

491

492 A timestamp in RFC 3339 format

493

494 format: date-time

495

496 - `BetaManagedAgentsAgentThinkingEvent object`

497

498 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

499

500 - `type: "agent.thinking"`

501

502 - `id: string`

503

504 Unique identifier for this event.

505

506 - `processed_at: string`

507

508 A timestamp in RFC 3339 format

509

510 format: date-time

511

512 - `BetaManagedAgentsAgentMCPToolUseEvent object`

513

514 Event emitted when the agent invokes a tool provided by an MCP server.

515

516 - `type: "agent.mcp_tool_use"`

517

518 - `id: string`

519

520 Unique identifier for this event.

521

522 - `input: map[unknown]`

523

524 Input parameters for the tool call.

525

526 - `mcp_server_name: string`

527

528 Name of the MCP server providing the tool.

529

530 - `name: string`

531

532 Name of the MCP tool being used.

533

534 - `processed_at: string`

535

536 A timestamp in RFC 3339 format

537

538 format: date-time

539

540 - `evaluated_permission: optional "allow" or "ask" or "deny"`

541

542 AgentEvaluatedPermission enum

543

544 - `"allow"`

545

546 - `"ask"`

547

548 - `"deny"`

549

550 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`

551

552 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.

553

554 - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object`

555

556 The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".

557

558 - `type: "always_allow"`

559

560 - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object`

561

562 The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".

563

564 - `type: "always_ask"`

565

566 - `BetaManagedAgentsAgentToolEvaluationAuto object`

567

568 The resolved permission_policy was auto: the server judged this invocation individually.

569

570 - `type: "auto"`

571

572 - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission`

573

574 The server's per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.

575

576 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object`

577

578 The server judged the invocation safe to execute without client approval.

579

580 - `type: "allow"`

581

582 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object`

583

584 The server reached no judgement; the invocation is held for client approval.

585

586 - `type: "ask"`

587

588 - `reason_code: string`

589

590 The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.

591

592 maxLength: 64

593

594 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object`

595

596 The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.

597

598 - `type: "deny"`

599

600 - `reason_code: string`

601

602 The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.

603

604 maxLength: 64

605

606 - `session_thread_id: optional string or null`

607

608 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

609

610 - `BetaManagedAgentsAgentMCPToolResultEvent object`

611

612 Event representing the result of an MCP tool execution.

613

614 - `type: "agent.mcp_tool_result"`

615

616 - `id: string`

617

618 Unique identifier for this event.

619

620 - `mcp_tool_use_id: string`

621

622 The id of the `agent.mcp_tool_use` event this result corresponds to.

623

624 - `processed_at: string`

625

626 A timestamp in RFC 3339 format

627

628 format: date-time

629

630 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

631

632 The result content returned by the tool.

633

634 - `BetaManagedAgentsTextBlock object`

635

636 Regular text content.

637

638 - `BetaManagedAgentsImageBlock object`

639

640 Image content specified directly as base64 data or as a reference via a URL.

641

642 - `BetaManagedAgentsDocumentBlock object`

643

644 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

645

646 - `BetaManagedAgentsSearchResultBlock object`

647

648 A block containing a web search result.

649

650 - `is_error: optional boolean or null`

651

652 Whether the tool execution resulted in an error.

653

654 - `BetaManagedAgentsAgentToolUseEvent object`

655

656 Event emitted when the agent invokes a built-in agent tool.

657

658 - `type: "agent.tool_use"`

659

660 - `id: string`

661

662 Unique identifier for this event.

663

664 - `input: map[unknown]`

665

666 Input parameters for the tool call.

667

668 - `name: string`

669

670 Name of the agent tool being used.

671

672 - `processed_at: string`

673

674 A timestamp in RFC 3339 format

675

676 format: date-time

677

678 - `evaluated_permission: optional "allow" or "ask" or "deny"`

679

680 AgentEvaluatedPermission enum

681

682 - `"allow"`

683

684 - `"ask"`

685

686 - `"deny"`

687

688 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`

689

690 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.

691

692 - `session_thread_id: optional string or null`

693

694 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

695

696 - `BetaManagedAgentsAgentToolResultEvent object`

697

698 Event representing the result of an agent tool execution.

699

700 - `type: "agent.tool_result"`

701

702 - `id: string`

703

704 Unique identifier for this event.

705

706 - `processed_at: string`

707

708 A timestamp in RFC 3339 format

709

710 format: date-time

711

712 - `tool_use_id: string`

713

714 The id of the `agent.tool_use` event this result corresponds to.

715

716 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

717

718 The result content returned by the tool.

719

720 - `BetaManagedAgentsTextBlock object`

721

722 Regular text content.

723

724 - `BetaManagedAgentsImageBlock object`

725

726 Image content specified directly as base64 data or as a reference via a URL.

727

728 - `BetaManagedAgentsDocumentBlock object`

729

730 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

731

732 - `BetaManagedAgentsSearchResultBlock object`

733

734 A block containing a web search result.

735

736 - `is_error: optional boolean or null`

737

738 Whether the tool execution resulted in an error.

739

740 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`

741

742 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

743

744 - `type: "agent.thread_message_received"`

745

746 - `id: string`

747

748 Unique identifier for this event.

749

750 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

751

752 Message content blocks.

753

754 - `BetaManagedAgentsTextBlock object`

755

756 Regular text content.

757

758 - `BetaManagedAgentsImageBlock object`

759

760 Image content specified directly as base64 data or as a reference via a URL.

761

762 - `BetaManagedAgentsDocumentBlock object`

763

764 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

765

766 - `BetaManagedAgentsRedactedBlock object`

767

768 Placeholder for content withheld by Anthropic model policy.

769

770 - `from_session_thread_id: string`

771

772 Public `sthr_` ID of the thread that sent the message.

773

774 - `processed_at: string`

775

776 A timestamp in RFC 3339 format

777

778 format: date-time

779

780 - `from_agent_name: optional string or null`

781

782 Name of the callable agent this message came from. Absent when received from the primary agent.

783

784 - `BetaManagedAgentsAgentThreadMessageSentEvent object`

785

786 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

787

788 - `type: "agent.thread_message_sent"`

789

790 - `id: string`

791

792 Unique identifier for this event.

793

794 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

795

796 Message content blocks.

797

798 - `BetaManagedAgentsTextBlock object`

799

800 Regular text content.

801

802 - `BetaManagedAgentsImageBlock object`

803

804 Image content specified directly as base64 data or as a reference via a URL.

805

806 - `BetaManagedAgentsDocumentBlock object`

807

808 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

809

810 - `BetaManagedAgentsRedactedBlock object`

811

812 Placeholder for content withheld by Anthropic model policy.

813

814 - `processed_at: string`

815

816 A timestamp in RFC 3339 format

817

818 format: date-time

819

820 - `to_session_thread_id: string`

821

822 Public `sthr_` ID of the thread the message was sent to.

823

824 - `to_agent_name: optional string or null`

825

826 Name of the callable agent this message was sent to. Absent when sent to the primary agent.

827

828 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`

829

830 Indicates that context compaction (summarization) occurred during the session.

831

832 - `type: "agent.thread_context_compacted"`

833

834 - `id: string`

835

836 Unique identifier for this event.

837

838 - `processed_at: string`

839

840 A timestamp in RFC 3339 format

841

842 format: date-time

843

844 - `BetaManagedAgentsSessionErrorEvent object`

845

846 An error event indicating a problem occurred during session execution.

847

848 - `type: "session.error"`

849

850 - `id: string`

851

852 Unique identifier for this event.

853

854 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`

855

856 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

857

858 - `BetaManagedAgentsUnknownError object`

859

860 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

861

862 - `type: "unknown_error"`

863

864 - `message: string`

865

866 Human-readable error description.

867

868 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

869

870 What the client should do next in response to this error.

871

872 - `BetaManagedAgentsRetryStatusRetrying object`

873

874 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

875

876 - `type: "retrying"`

877

878 - `BetaManagedAgentsRetryStatusExhausted object`

879

880 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

881

882 - `type: "exhausted"`

883

884 - `BetaManagedAgentsRetryStatusTerminal object`

885

886 The session encountered a terminal error and will transition to `terminated` state.

887

888 - `type: "terminal"`

889

890 - `BetaManagedAgentsModelOverloadedError object`

891

892 The model is currently overloaded. Emitted after automatic retries are exhausted.

893

894 - `type: "model_overloaded_error"`

895

896 - `message: string`

897

898 Human-readable error description.

899

900 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

901

902 What the client should do next in response to this error.

903

904 - `BetaManagedAgentsRetryStatusRetrying object`

905

906 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

907

908 - `BetaManagedAgentsRetryStatusExhausted object`

909

910 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

911

912 - `BetaManagedAgentsRetryStatusTerminal object`

913

914 The session encountered a terminal error and will transition to `terminated` state.

915

916 - `BetaManagedAgentsModelRateLimitedError object`

917

918 The model request was rate-limited.

919

920 - `type: "model_rate_limited_error"`

921

922 - `message: string`

923

924 Human-readable error description.

925

926 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

927

928 What the client should do next in response to this error.

929

930 - `BetaManagedAgentsRetryStatusRetrying object`

931

932 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

933

934 - `BetaManagedAgentsRetryStatusExhausted object`

935

936 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

937

938 - `BetaManagedAgentsRetryStatusTerminal object`

939

940 The session encountered a terminal error and will transition to `terminated` state.

941

942 - `BetaManagedAgentsModelRequestFailedError object`

943

944 A model request failed for a reason other than overload or rate-limiting.

945

946 - `type: "model_request_failed_error"`

947

948 - `message: string`

949

950 Human-readable error description.

951

952 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

953

954 What the client should do next in response to this error.

955

956 - `BetaManagedAgentsRetryStatusRetrying object`

957

958 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

959

960 - `BetaManagedAgentsRetryStatusExhausted object`

961

962 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

963

964 - `BetaManagedAgentsRetryStatusTerminal object`

965

966 The session encountered a terminal error and will transition to `terminated` state.

967

968 - `BetaManagedAgentsMCPConnectionFailedError object`

969

970 Failed to connect to an MCP server.

971

972 - `type: "mcp_connection_failed_error"`

973

974 - `mcp_server_name: string`

975

976 Name of the MCP server that failed to connect.

977

978 - `message: string`

979

980 Human-readable error description.

981

982 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

983

984 What the client should do next in response to this error.

985

986 - `BetaManagedAgentsRetryStatusRetrying object`

987

988 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

989

990 - `BetaManagedAgentsRetryStatusExhausted object`

991

992 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

993

994 - `BetaManagedAgentsRetryStatusTerminal object`

995

996 The session encountered a terminal error and will transition to `terminated` state.

997

998 - `BetaManagedAgentsMCPAuthenticationFailedError object`

999

1000 Authentication to an MCP server failed.

1001

1002 - `type: "mcp_authentication_failed_error"`

1003

1004 - `mcp_server_name: string`

1005

1006 Name of the MCP server that failed authentication.

1007

1008 - `message: string`

1009

1010 Human-readable error description.

1011

1012 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1013

1014 What the client should do next in response to this error.

1015

1016 - `BetaManagedAgentsRetryStatusRetrying object`

1017

1018 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

1019

1020 - `BetaManagedAgentsRetryStatusExhausted object`

1021

1022 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

1023

1024 - `BetaManagedAgentsRetryStatusTerminal object`

1025

1026 The session encountered a terminal error and will transition to `terminated` state.

1027

1028 - `BetaManagedAgentsBillingError object`

1029

1030 The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

1031

1032 - `type: "billing_error"`

1033

1034 - `message: string`

1035

1036 Human-readable error description.

1037

1038 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1039

1040 What the client should do next in response to this error.

1041

1042 - `BetaManagedAgentsRetryStatusRetrying object`

1043

1044 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

1045

1046 - `BetaManagedAgentsRetryStatusExhausted object`

1047

1048 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

1049

1050 - `BetaManagedAgentsRetryStatusTerminal object`

1051

1052 The session encountered a terminal error and will transition to `terminated` state.

1053

1054 - `BetaManagedAgentsCredentialHostUnreachableError object`

1055

1056 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

1057

1058 - `type: "credential_host_unreachable_error"`

1059

1060 - `credential_id: string`

1061

1062 ID of the affected credential.

1063

1064 - `message: string`

1065

1066 Human-readable error description.

1067

1068 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1069

1070 What the client should do next in response to this error.

1071

1072 - `BetaManagedAgentsRetryStatusRetrying object`

1073

1074 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

1075

1076 - `BetaManagedAgentsRetryStatusExhausted object`

1077

1078 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

1079

1080 - `BetaManagedAgentsRetryStatusTerminal object`

1081

1082 The session encountered a terminal error and will transition to `terminated` state.

1083

1084 - `vault_id: string`

1085

1086 ID of the vault containing the affected credential.

1087

1088 - `processed_at: string`

1089

1090 A timestamp in RFC 3339 format

1091

1092 format: date-time

1093

1094 - `BetaManagedAgentsSessionStatusRescheduledEvent object`

1095

1096 Indicates the session is recovering from an error state and is rescheduled for execution.

1097

1098 - `type: "session.status_rescheduled"`

1099

1100 - `id: string`

1101

1102 Unique identifier for this event.

1103

1104 - `processed_at: string`

1105

1106 A timestamp in RFC 3339 format

1107

1108 format: date-time

1109

1110 - `BetaManagedAgentsSessionStatusRunningEvent object`

1111

1112 Indicates the session is actively running and the agent is working.

1113

1114 - `type: "session.status_running"`

1115

1116 - `id: string`

1117

1118 Unique identifier for this event.

1119

1120 - `processed_at: string`

1121

1122 A timestamp in RFC 3339 format

1123

1124 format: date-time

1125

1126 - `BetaManagedAgentsSessionStatusIdleEvent object`

1127

1128 Indicates the agent has paused and is awaiting user input.

1129

1130 - `type: "session.status_idle"`

1131

1132 - `id: string`

1133

1134 Unique identifier for this event.

1135

1136 - `processed_at: string`

1137

1138 A timestamp in RFC 3339 format

1139

1140 format: date-time

1141

1142 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`

1143

1144 The agent completed its turn naturally and is ready for the next user message.

1145

1146 - `BetaManagedAgentsSessionEndTurn object`

1147

1148 The agent completed its turn naturally and is ready for the next user message.

1149

1150 - `type: "end_turn"`

1151

1152 - `BetaManagedAgentsSessionRequiresAction object`

1153

1154 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

1155

1156 - `type: "requires_action"`

1157

1158 - `event_ids: array of string`

1159

1160 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

1161

1162 - `BetaManagedAgentsSessionRetriesExhausted object`

1163

1164 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.

1165

1166 - `type: "retries_exhausted"`

1167

1168 - `BetaManagedAgentsSessionBudgetReached object`

1169

1170 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.

1171

1172 - `type: "budget_reached"`

1173

1174 - `BetaManagedAgentsSessionStatusTerminatedEvent object`

1175

1176 Indicates the session has terminated, either due to an error or completion.

1177

1178 - `type: "session.status_terminated"`

1179

1180 - `id: string`

1181

1182 Unique identifier for this event.

1183

1184 - `processed_at: string`

1185

1186 A timestamp in RFC 3339 format

1187

1188 format: date-time

1189

1190 - `BetaManagedAgentsSessionThreadCreatedEvent object`

1191

1192 Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.

1193

1194 - `type: "session.thread_created"`

1195

1196 - `id: string`

1197

1198 Unique identifier for this event.

1199

1200 - `agent_name: string`

1201

1202 Name of the callable agent the thread runs.

1203

1204 - `processed_at: string`

1205

1206 A timestamp in RFC 3339 format

1207

1208 format: date-time

1209

1210 - `session_thread_id: string`

1211

1212 Public `sthr_` ID of the newly created thread.

1213

1214 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`

1215

1216 Emitted when an outcome evaluation cycle begins.

1217

1218 - `type: "span.outcome_evaluation_start"`

1219

1220 - `id: string`

1221

1222 Unique identifier for this event.

1223

1224 - `iteration: number`

1225

1226 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

1227

1228 format: int32

1229

1230 - `outcome_id: string`

1231

1232 The `outc_` ID of the outcome being evaluated.

1233

1234 - `processed_at: string`

1235

1236 A timestamp in RFC 3339 format

1237

1238 format: date-time

1239

1240 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`

1241

1242 Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.

1243

1244 - `type: "span.outcome_evaluation_end"`

1245

1246 - `id: string`

1247

1248 Unique identifier for this event.

1249

1250 - `explanation: string`

1251

1252 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

1253

1254 - `iteration: number`

1255

1256 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

1257

1258 format: int32

1259

1260 - `outcome_evaluation_start_id: string`

1261

1262 The id of the corresponding `span.outcome_evaluation_start` event.

1263

1264 - `outcome_id: string`

1265

1266 The `outc_` ID of the outcome being evaluated.

1267

1268 - `processed_at: string`

1269

1270 A timestamp in RFC 3339 format

1271

1272 format: date-time

1273

1274 - `result: string`

1275

1276 Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.

1277

1278 - `usage: BetaManagedAgentsSpanModelUsage`

1279

1280 Token usage for a single model request.

1281

1282 - `cache_creation_input_tokens: number`

1283

1284 Tokens used to create prompt cache in this request.

1285

1286 format: int32

1287

1288 - `cache_read_input_tokens: number`

1289

1290 Tokens read from prompt cache in this request.

1291

1292 format: int32

1293

1294 - `input_tokens: number`

1295

1296 Input tokens consumed by this request.

1297

1298 format: int32

1299

1300 - `output_tokens: number`

1301

1302 Output tokens generated by this request.

1303

1304 format: int32

1305

1306 - `speed: optional "standard" or "fast" or null`

1307

1308 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.

1309

1310 - `"standard"`

1311

1312 - `"fast"`

1313

1314 - `BetaManagedAgentsSpanModelRequestStartEvent object`

1315

1316 Emitted when a model request is initiated by the agent.

1317

1318 - `type: "span.model_request_start"`

1319

1320 - `id: string`

1321

1322 Unique identifier for this event.

1323

1324 - `processed_at: string`

1325

1326 A timestamp in RFC 3339 format

1327

1328 format: date-time

1329

1330 - `BetaManagedAgentsSpanModelRequestEndEvent object`

1331

1332 Emitted when a model request completes.

1333

1334 - `type: "span.model_request_end"`

1335

1336 - `id: string`

1337

1338 Unique identifier for this event.

1339

1340 - `is_error: boolean or null`

1341

1342 Whether the model request resulted in an error.

1343

1344 - `model_request_start_id: string`

1345

1346 The id of the corresponding `span.model_request_start` event.

1347

1348 - `model_usage: BetaManagedAgentsSpanModelUsage`

1349

1350 Token usage for a single model request.

1351

1352 - `processed_at: string`

1353

1354 A timestamp in RFC 3339 format

1355

1356 format: date-time

1357

1358 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`

1359

1360 Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.

1361

1362 - `type: "span.outcome_evaluation_ongoing"`

1363

1364 - `id: string`

1365

1366 Unique identifier for this event.

1367

1368 - `iteration: number`

1369

1370 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

1371

1372 format: int32

1373

1374 - `outcome_id: string`

1375

1376 The `outc_` ID of the outcome being evaluated.

1377

1378 - `processed_at: string`

1379

1380 A timestamp in RFC 3339 format

1381

1382 format: date-time

1383

1384 - `BetaManagedAgentsUserDefineOutcomeEvent object`

1385

1386 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

1387

1388 - `type: "user.define_outcome"`

1389

1390 - `id: string`

1391

1392 Unique identifier for this event.

1393

1394 - `description: string`

1395

1396 What the agent should produce. Copied from the input event.

1397

1398 - `max_iterations: number or null`

1399

1400 Evaluate-then-revise cycles before giving up. Default 3, max 20.

1401

1402 format: int32

1403

1404 - `outcome_id: string`

1405

1406 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

1407

1408 - `processed_at: string`

1409

1410 A timestamp in RFC 3339 format

1411

1412 format: date-time

1413

1414 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`

1415

1416 Rubric for grading the quality of an outcome.

1417

1418 - `BetaManagedAgentsFileRubric object`

1419

1420 Rubric referenced by a file uploaded via the Files API.

1421

1422 - `type: "file"`

1423

1424 - `file_id: string`

1425

1426 ID of the rubric file.

1427

1428 - `BetaManagedAgentsTextRubric object`

1429

1430 Rubric content provided inline as text.

1431

1471432 - `type: "text"`

1481433

1434 - `content: string`

1435

1436 Rubric content. Plain text or markdown — the grader treats it as freeform text.

1437

1438 - `BetaManagedAgentsSessionDeletedEvent object`

1439

1440 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

1441

1442 - `type: "session.deleted"`

1443

1444 - `id: string`

1445

1446 Unique identifier for this event.

1447

1448 - `processed_at: string`

1449

1450 A timestamp in RFC 3339 format

1451

1452 format: date-time

1453

1454 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`

1455

1456 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

1457

1458 - `type: "session.thread_status_running"`

1459

1460 - `id: string`

1461

1462 Unique identifier for this event.

1463

1464 - `agent_name: string`

1465

1466 Name of the agent the thread runs.

1467

1468 - `processed_at: string`

1469

1470 A timestamp in RFC 3339 format

1471

1472 format: date-time

1473

1474 - `session_thread_id: string`

1475

1476 Public sthr_ ID of the thread that started running.

1477

1478 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`

1479

1480 A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

1481

1482 - `type: "session.thread_status_idle"`

1483

1484 - `id: string`

1485

1486 Unique identifier for this event.

1487

1488 - `agent_name: string`

1489

1490 Name of the agent the thread runs.

1491

1492 - `processed_at: string`

1493

1494 A timestamp in RFC 3339 format

1495

1496 format: date-time

1497

1498 - `session_thread_id: string`

1499

1500 Public sthr_ ID of the thread that went idle.

1501

1502 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`

1503

1504 The agent completed its turn naturally and is ready for the next user message.

1505

1506 - `BetaManagedAgentsSessionEndTurn object`

1507

1508 The agent completed its turn naturally and is ready for the next user message.

1509

1510 - `BetaManagedAgentsSessionRequiresAction object`

1511

1512 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

1513

1514 - `BetaManagedAgentsSessionRetriesExhausted object`

1515

1516 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.

1517

1518 - `BetaManagedAgentsSessionBudgetReached object`

1519

1520 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.

1521

1522 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`

1523

1524 A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

1525

1526 - `type: "session.thread_status_terminated"`

1527

1528 - `id: string`

1529

1530 Unique identifier for this event.

1531

1532 - `agent_name: string`

1533

1534 Name of the agent the thread runs.

1535

1536 - `processed_at: string`

1537

1538 A timestamp in RFC 3339 format

1539

1540 format: date-time

1541

1542 - `session_thread_id: string`

1543

1544 Public sthr_ ID of the thread that terminated.

1545

1546 - `BetaManagedAgentsUserToolResultEvent object`

1547

1548 Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

1549

1550 - `type: "user.tool_result"`

1551

1552 - `id: string`

1553

1554 Unique identifier for this event.

1555

1556 - `tool_use_id: string`

1557

1558 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

1559

1560 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

1561

1562 The result content returned by the tool.

1563

1564 - `BetaManagedAgentsTextBlock object`

1565

1566 Regular text content.

1567

1491568 - `BetaManagedAgentsImageBlock object`

1501569

1511570 Image content specified directly as base64 data or as a reference via a URL.

1521571

153 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

154

155 Union type for image source variants.

156

157 - `BetaManagedAgentsBase64ImageSource object`

158

159 Base64-encoded image data.

160

161 - `data: string`

162

163 Base64-encoded image data.

164

165 minLength: 1

166

167 - `media_type: string`

168

169 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

170

171 minLength: 1

172

173 - `type: "base64"`

174

175 - `BetaManagedAgentsURLImageSource object`

176

177 Image referenced by URL.

178

179 - `type: "url"`

180

181 - `url: string`

182

183 URL of the image to fetch.

184

185 minLength: 1

186

187 - `BetaManagedAgentsFileImageSource object`

188

189 Image referenced by file ID.

190

191 - `file_id: string`

192

193 ID of a previously uploaded file.

194

195 minLength: 1

196

197 - `type: "file"`

198

199 - `type: "image"`

200

2011572 - `BetaManagedAgentsDocumentBlock object`

2021573

2031574 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

2041575

205 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`

206

207 Union type for document source variants.

208

209 - `BetaManagedAgentsBase64DocumentSource object`

210

211 Base64-encoded document data.

212

213 - `data: string`

214

215 Base64-encoded document data.

216

217 minLength: 1

218

219 - `media_type: string`

220

221 MIME type of the document (e.g., "application/pdf").

222

223 minLength: 1

224

225 - `type: "base64"`

226

227 - `BetaManagedAgentsPlainTextDocumentSource object`

228

229 Plain text document content.

230

231 - `data: string`

232

233 The plain text content.

234

235 minLength: 1

236

237 - `media_type: "text/plain"`

238

239 MIME type of the text content. Must be "text/plain".

240

241 - `type: "text"`

242

243 - `BetaManagedAgentsURLDocumentSource object`

244

245 Document referenced by URL.

246

247 - `type: "url"`

248

249 - `url: string`

250

251 URL of the document to fetch.

252

253 minLength: 1

254

255 - `BetaManagedAgentsFileDocumentSource object`

256

257 Document referenced by file ID.

258

259 - `file_id: string`

260

261 ID of a previously uploaded file.

262

263 minLength: 1

264

265 - `type: "file"`

266

267 - `type: "document"`

268

269 - `context: optional string or null`

270

271 Additional context about the document for the model.

272

273 - `title: optional string or null`

274

275 The title of the document.

276

277 - `BetaManagedAgentsRedactedBlock object`

278

279 Placeholder for content withheld by Anthropic model policy.

280

281 - `type: "redacted"`

282

283 - `type: "user.message"`

1576 - `BetaManagedAgentsSearchResultBlock object`

1577

1578 A block containing a web search result.

1579

1580 - `is_error: optional boolean or null`

1581

1582 Whether the tool execution resulted in an error.

2841583

2851584 - `processed_at: optional string or null`

2861585

from line 1587

2881587

2891588 format: date-time

2901589

291 - `BetaManagedAgentsUserInterruptEvent object`

292

293 An interrupt event that pauses agent execution and returns control to the user.

294

295 - `id: string`

296

297 Unique identifier for this event.

298

299 - `type: "user.interrupt"`

1590 - `session_thread_id: optional string or null`

1591

1592 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

1593

1594 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`

1595

1596 A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

1597

1598 - `type: "session.thread_status_rescheduled"`

1599

1600 - `id: string`

1601

1602 Unique identifier for this event.

1603

1604 - `agent_name: string`

1605

1606 Name of the agent the thread runs.

1607

1608 - `processed_at: string`

1609

1610 A timestamp in RFC 3339 format

1611

1612 format: date-time

1613

1614 - `session_thread_id: string`

1615

1616 Public sthr_ ID of the thread that is retrying.

1617

1618 - `BetaManagedAgentsSessionUpdatedEvent object`

1619

1620 Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

1621

1622 - `type: "session.updated"`

1623

1624 - `id: string`

1625

1626 Unique identifier for this event.

1627

1628 - `processed_at: string`

1629

1630 A timestamp in RFC 3339 format

1631

1632 format: date-time

1633

1634 - `agent: optional BetaManagedAgentsSessionAgent or null`

1635

1636 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

1637

1638 - `type: "agent"`

1639

1640 - `id: string`

1641

1642 - `description: string or null`

1643

1644 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1645

1646 - `type: "url"`

1647

1648 - `name: string`

1649

1650 - `url: string`

1651

1652 - `model: BetaManagedAgentsModelConfig`

1653

1654 Model identifier and configuration.

1655

1656 - `id: BetaManagedAgentsModel`

1657

1658 The model that will power your agent.

1659

1660 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

1661

1662 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`

1663

1664 The model that will power your agent.

1665

1666 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

1667

1668 - `"claude-fable-5-1"`

1669

1670 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows

1671

1672 - `"claude-sonnet-5"`

1673

1674 High-performance model for coding and agents

1675

1676 - `"claude-fable-5"`

1677

1678 Next generation of intelligence for the hardest knowledge work and coding problems

1679

1680 - `"claude-opus-5"`

1681

1682 Powerful intelligence for long-running agents and coding

1683

1684 - `"claude-opus-4-8"`

1685

1686 Powerful intelligence for long-running agents and coding

1687

1688 - `"claude-opus-4-7"`

1689

1690 Powerful intelligence for long-running agents and coding

1691

1692 - `"claude-opus-4-6"`

1693

1694 Powerful intelligence for long-running agents and coding

1695

1696 - `"claude-sonnet-4-6"`

1697

1698 Best combination of speed and intelligence

1699

1700 - `"claude-haiku-4-5"`

1701

1702 Fastest model with near-frontier intelligence

1703

1704 - `"claude-haiku-4-5-20251001"`

1705

1706 Fastest model with near-frontier intelligence

1707

1708 - `"claude-opus-4-5"`

1709

1710 Powerful intelligence for long-running agents and coding

1711

1712 - `"claude-opus-4-5-20251101"`

1713

1714 Powerful intelligence for long-running agents and coding

1715

1716 - `"claude-sonnet-4-5"`

1717

1718 High-performance model for agents and coding

1719

1720 - `"claude-sonnet-4-5-20250929"`

1721

1722 High-performance model for agents and coding

1723

1724 - `string`

1725

1726 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`

1727

1728 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.

1729

1730 - `BetaManagedAgentsEffortLow object`

1731

1732 Low effort. Favors latency over reasoning depth.

1733

1734 - `type: "low"`

1735

1736 - `BetaManagedAgentsEffortMedium object`

1737

1738 Medium effort. Balances latency and reasoning depth.

1739

1740 - `type: "medium"`

1741

1742 - `BetaManagedAgentsEffortHigh object`

1743

1744 High effort. Favors reasoning depth.

1745

1746 - `type: "high"`

1747

1748 - `BetaManagedAgentsEffortXhigh object`

1749

1750 Extra-high effort. Not all models accept this level.

1751

1752 - `type: "xhigh"`

1753

1754 - `BetaManagedAgentsEffortMax object`

1755

1756 Maximum effort. Favors reasoning depth over latency.

1757

1758 - `type: "max"`

1759

1760 - `inference_geo: optional string`

1761

1762 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.

1763

1764 - `speed: optional "standard" or "fast"`

1765

1766 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.

1767

1768 - `"standard"`

1769

1770 - `"fast"`

1771

1772 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`

1773

1774 Resolved coordinator topology with full agent definitions for each roster member.

1775

1776 - `type: "coordinator"`

1777

1778 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`

1779

1780 Full `agent` definitions the coordinator may spawn as session threads.

1781

1782 - `BetaManagedAgentsSessionThreadAgent object`

1783

1784 Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.

1785

1786 - `type: "agent"`

1787

1788 - `id: string`

1789

1790 - `description: string or null`

1791

1792 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1793

1794 - `type: "url"`

1795

1796 - `name: string`

1797

1798 - `url: string`

1799

1800 - `model: BetaManagedAgentsModelConfig`

1801

1802 Model identifier and configuration.

1803

1804 - `name: string`

1805

1806 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

1807

1808 - `BetaManagedAgentsAnthropicSkill object`

1809

1810 A resolved Anthropic-managed skill.

1811

1812 - `type: "anthropic"`

1813

1814 - `skill_id: string`

1815

1816 - `version: string`

1817

1818 - `BetaManagedAgentsCustomSkill object`

1819

1820 A resolved user-created custom skill.

1821

1822 - `type: "custom"`

1823

1824 - `skill_id: string`

1825

1826 - `version: string`

1827

1828 - `system: string or null`

1829

1830 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`

1831

1832 - `BetaManagedAgentsAgentToolset20260401 object`

1833

1834 - `type: "agent_toolset_20260401"`

1835

1836 - `configs: array of BetaManagedAgentsAgentToolConfig`

1837

1838 - `BetaManagedAgentsBashToolConfig object`

1839

1840 Configuration for the bash tool.

1841

1842 - `type: "bash"`

1843

1844 - `enabled: boolean`

1845

1846 - `name: "bash"`

1847

1848 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1849

1850 Permission policy for tool execution.

1851

1852 - `BetaManagedAgentsAlwaysAllowPolicy object`

1853

1854 Tool calls are automatically approved without user confirmation.

1855

1856 - `type: "always_allow"`

1857

1858 - `BetaManagedAgentsAlwaysAskPolicy object`

1859

1860 Tool calls require user confirmation before execution.

1861

1862 - `type: "always_ask"`

1863

1864 - `BetaManagedAgentsAutoPolicy object`

1865

1866 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1867

1868 - `type: "auto"`

1869

1870 - `BetaManagedAgentsEditToolConfig object`

1871

1872 Configuration for the edit tool.

1873

1874 - `type: "edit"`

1875

1876 - `enabled: boolean`

1877

1878 - `name: "edit"`

1879

1880 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1881

1882 Permission policy for tool execution.

1883

1884 - `BetaManagedAgentsAlwaysAllowPolicy object`

1885

1886 Tool calls are automatically approved without user confirmation.

1887

1888 - `BetaManagedAgentsAlwaysAskPolicy object`

1889

1890 Tool calls require user confirmation before execution.

1891

1892 - `BetaManagedAgentsAutoPolicy object`

1893

1894 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1895

1896 - `BetaManagedAgentsReadToolConfig object`

1897

1898 Configuration for the read tool.

1899

1900 - `type: "read"`

1901

1902 - `enabled: boolean`

1903

1904 - `name: "read"`

1905

1906 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1907

1908 Permission policy for tool execution.

1909

1910 - `BetaManagedAgentsAlwaysAllowPolicy object`

1911

1912 Tool calls are automatically approved without user confirmation.

1913

1914 - `BetaManagedAgentsAlwaysAskPolicy object`

1915

1916 Tool calls require user confirmation before execution.

1917

1918 - `BetaManagedAgentsAutoPolicy object`

1919

1920 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1921

1922 - `BetaManagedAgentsWriteToolConfig object`

1923

1924 Configuration for the write tool.

1925

1926 - `type: "write"`

1927

1928 - `enabled: boolean`

1929

1930 - `name: "write"`

1931

1932 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1933

1934 Permission policy for tool execution.

1935

1936 - `BetaManagedAgentsAlwaysAllowPolicy object`

1937

1938 Tool calls are automatically approved without user confirmation.

1939

1940 - `BetaManagedAgentsAlwaysAskPolicy object`

1941

1942 Tool calls require user confirmation before execution.

1943

1944 - `BetaManagedAgentsAutoPolicy object`

1945

1946 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1947

1948 - `BetaManagedAgentsGlobToolConfig object`

1949

1950 Configuration for the glob tool.

1951

1952 - `type: "glob"`

1953

1954 - `enabled: boolean`

1955

1956 - `name: "glob"`

1957

1958 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1959

1960 Permission policy for tool execution.

1961

1962 - `BetaManagedAgentsAlwaysAllowPolicy object`

1963

1964 Tool calls are automatically approved without user confirmation.

1965

1966 - `BetaManagedAgentsAlwaysAskPolicy object`

1967

1968 Tool calls require user confirmation before execution.

1969

1970 - `BetaManagedAgentsAutoPolicy object`

1971

1972 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1973

1974 - `BetaManagedAgentsGrepToolConfig object`

1975

1976 Configuration for the grep tool.

1977

1978 - `type: "grep"`

1979

1980 - `enabled: boolean`

1981

1982 - `name: "grep"`

1983

1984 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1985

1986 Permission policy for tool execution.

1987

1988 - `BetaManagedAgentsAlwaysAllowPolicy object`

1989

1990 Tool calls are automatically approved without user confirmation.

1991

1992 - `BetaManagedAgentsAlwaysAskPolicy object`

1993

1994 Tool calls require user confirmation before execution.

1995

1996 - `BetaManagedAgentsAutoPolicy object`

1997

1998 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

1999

2000 - `BetaManagedAgentsWebFetchToolConfig object`

2001

2002 Configuration for the web_fetch tool.

2003

2004 - `type: "web_fetch"`

2005

2006 - `enabled: boolean`

2007

2008 - `name: "web_fetch"`

2009

2010 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2011

2012 Permission policy for tool execution.

2013

2014 - `BetaManagedAgentsAlwaysAllowPolicy object`

2015

2016 Tool calls are automatically approved without user confirmation.

2017

2018 - `BetaManagedAgentsAlwaysAskPolicy object`

2019

2020 Tool calls require user confirmation before execution.

2021

2022 - `BetaManagedAgentsAutoPolicy object`

2023

2024 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

2025

2026 - `allowed_domains: optional array of string`

2027

2028 - `blocked_domains: optional array of string`

2029

2030 - `max_content_tokens: optional number or null`

2031

2032 format: int32

2033

2034 - `BetaManagedAgentsWebSearchToolConfig object`

2035

2036 Configuration for the web_search tool.

2037

2038 - `type: "web_search"`

2039

2040 - `enabled: boolean`

2041

2042 - `name: "web_search"`

2043

2044 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2045

2046 Permission policy for tool execution.

2047

2048 - `BetaManagedAgentsAlwaysAllowPolicy object`

2049

2050 Tool calls are automatically approved without user confirmation.

2051

2052 - `BetaManagedAgentsAlwaysAskPolicy object`

2053

2054 Tool calls require user confirmation before execution.

2055

2056 - `BetaManagedAgentsAutoPolicy object`

2057

2058 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

2059

2060 - `allowed_domains: optional array of string`

2061

2062 - `blocked_domains: optional array of string`

2063

2064 - `user_location: optional BetaManagedAgentsUserLocation or null`

2065

2066 Approximate user location for search result localization.

2067

2068 - `type: "approximate"`

2069

2070 Location precision. Only "approximate" is supported.

2071

2072 - `city: optional string or null`

2073

2074 City name.

2075

2076 minLength: 1, maxLength: 255

2077

2078 - `country: optional string or null`

2079

2080 Two-letter ISO 3166-1 country code, uppercase.

2081

2082 - `region: optional string or null`

2083

2084 Region or state name.

2085

2086 minLength: 1, maxLength: 255

2087

2088 - `timezone: optional string or null`

2089

2090 IANA timezone identifier, e.g. "America/Los_Angeles".

2091

2092 minLength: 1, maxLength: 255

2093

2094 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`

2095

2096 Resolved default configuration for agent tools.

2097

2098 - `enabled: boolean`

2099

2100 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2101

2102 Permission policy for tool execution.

2103

2104 - `BetaManagedAgentsAlwaysAllowPolicy object`

2105

2106 Tool calls are automatically approved without user confirmation.

2107

2108 - `BetaManagedAgentsAlwaysAskPolicy object`

2109

2110 Tool calls require user confirmation before execution.

2111

2112 - `BetaManagedAgentsAutoPolicy object`

2113

2114 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

2115

2116 - `BetaManagedAgentsMCPToolset object`

2117

2118 - `type: "mcp_toolset"`

2119

2120 - `configs: array of BetaManagedAgentsMCPToolConfig`

2121

2122 - `enabled: boolean`

2123

2124 - `name: string`

2125

2126 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2127

2128 Permission policy for tool execution.

2129

2130 - `BetaManagedAgentsAlwaysAllowPolicy object`

2131

2132 Tool calls are automatically approved without user confirmation.

2133

2134 - `BetaManagedAgentsAlwaysAskPolicy object`

2135

2136 Tool calls require user confirmation before execution.

2137

2138 - `BetaManagedAgentsAutoPolicy object`

2139

2140 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

2141

2142 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

2143

2144 Resolved default configuration for all tools from an MCP server.

2145

2146 - `enabled: boolean`

2147

2148 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2149

2150 Permission policy for tool execution.

2151

2152 - `BetaManagedAgentsAlwaysAllowPolicy object`

2153

2154 Tool calls are automatically approved without user confirmation.

2155

2156 - `BetaManagedAgentsAlwaysAskPolicy object`

2157

2158 Tool calls require user confirmation before execution.

2159

2160 - `BetaManagedAgentsAutoPolicy object`

2161

2162 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.

2163

2164 - `mcp_server_name: string`

2165

2166 - `BetaManagedAgentsCustomTool object`

2167

2168 A custom tool as returned in API responses.

2169

2170 - `type: "custom"`

2171

2172 - `description: string`

2173

2174 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

2175

2176 JSON Schema for custom tool input parameters.

2177

2178 - `type: "object"`

2179

2180 - `properties: optional map[unknown] or null`

2181

2182 - `required: optional array of string or null`

2183

2184 - `name: string`

2185

2186 - `version: number`

2187

2188 format: int32

2189

2190 - `BetaManagedAgentsAdvisor object`

2191

2192 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

2193

2194 - `type: "advisor"`

2195

2196 - `model: string`

2197

2198 The advisor model id.

2199

2200 - `name: string`

2201

2202 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

2203

2204 - `BetaManagedAgentsAnthropicSkill object`

2205

2206 A resolved Anthropic-managed skill.

2207

2208 - `BetaManagedAgentsCustomSkill object`

2209

2210 A resolved user-created custom skill.

2211

2212 - `system: string or null`

2213

2214 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`

2215

2216 - `BetaManagedAgentsAgentToolset20260401 object`

2217

2218 - `BetaManagedAgentsMCPToolset object`

2219

2220 - `BetaManagedAgentsCustomTool object`

2221

2222 A custom tool as returned in API responses.

2223

2224 - `version: number`

2225

2226 format: int32

2227

2228 - `budget: optional BetaManagedAgentsBudgetLimit or null`

2229

2230 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.

2231

2232 - `type: "limit"`

2233

2234 - `max_list_cost: BetaMonetaryAmount`

2235

2236 A monetary amount in a specific currency.

2237

2238 - `amount: string`

2239

2240 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

2241

2242 - `currency: BetaCurrency`

2243

2244 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.

2245

2246 - `metadata: optional map[string]`

2247

2248 The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.

2249

2250 - `title: optional string or null`

2251

2252 The session's new title. Present only when the update changed it.

2253

2254 - `BetaManagedAgentsStartEvent object`

2255

2256 Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.

2257

2258 - `type: "event_start"`

2259

2260 - `event: BetaManagedAgentsStartEventPreview`

2261

2262 The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them.

2263

2264 - `BetaManagedAgentsAgentMessagePreview object`

2265

2266 - `type: "agent.message"`

2267

2268 - `id: string`

2269

2270 The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.

2271

2272 - `BetaManagedAgentsAgentThinkingPreview object`

2273

2274 - `type: "agent.thinking"`

2275

2276 - `id: string`

2277

2278 The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.

2279

2280 - `BetaManagedAgentsDeltaEvent object`

2281

2282 An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.

2283

2284 - `type: "event_delta"`

2285

2286 - `delta: BetaManagedAgentsDeltaContent`

2287

2288 One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array.

2289

2290 - `type: "content_delta"`

2291

2292 - `content: BetaManagedAgentsTextBlock`

2293

2294 Regular text content.

2295

2296 - `index: optional number`

2297

2298 Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.

2299

2300 format: uint32

2301

2302 - `event_id: string`

2303

2304 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.

2305

2306 - `BetaManagedAgentsSystemMessageEvent object`

2307

2308 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

2309

2310 - `type: "system.message"`

2311

2312 - `id: string`

2313

2314 Unique identifier for this event.

2315

2316 - `content: array of BetaManagedAgentsSystemContentBlock`

2317

2318 System content blocks. Text-only.

2319

2320 - `type: "text"`

2321

2322 - `text: string`

2323

2324 The text content.

2325

2326 minLength: 1

3002327

3012328 - `processed_at: optional string or null`

3022329

from line 2331

3042331

3052332 format: date-time

3062333

307 - `session_thread_id: optional string or null`

308

309 If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

310

311 - `BetaManagedAgentsUserToolConfirmationEvent object`

312

313 A tool confirmation event that approves or denies a pending tool execution.

314

315 - `id: string`

316

317 Unique identifier for this event.

318

319 - `result: "allow" or "deny"`

320

321 UserToolConfirmationResult enum

322

323 - `"allow"`

324

325 - `"deny"`

326

327 - `tool_use_id: string`

328

329 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

330

331 - `type: "user.tool_confirmation"`

332

333 - `deny_message: optional string or null`

334

335 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

336

337 maxLength: 10000

338

339 - `processed_at: optional string or null`

340

341 A timestamp in RFC 3339 format

342

343 format: date-time

344

345 - `session_thread_id: optional string or null`

346

347 When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.

348

349 - `BetaManagedAgentsUserCustomToolResultEvent object`

350

351 Event sent by the client providing the result of a custom tool execution.

352

353 - `id: string`

354

355 Unique identifier for this event.

356

357 - `custom_tool_use_id: string`

358

359 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

360

361 - `type: "user.custom_tool_result"`

362

363 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

364

365 The result content returned by the tool.

366

367 - `BetaManagedAgentsTextBlock object`

368

369 Regular text content.

370

371 - `BetaManagedAgentsImageBlock object`

372

373 Image content specified directly as base64 data or as a reference via a URL.

374

375 - `BetaManagedAgentsDocumentBlock object`

376

377 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

378

379 - `BetaManagedAgentsSearchResultBlock object`

380

381 A block containing a web search result.

382

383 - `citations: BetaManagedAgentsSearchResultCitations`

384

385 Citation settings for a search result.

386

387 - `enabled: boolean`

388

389 Whether citations are enabled for this search result.

390

391 - `content: array of BetaManagedAgentsSearchResultContent`

392

393 Array of text content blocks from the search result.

394

395 - `text: string`

396

397 The text content.

398

399 minLength: 1

400

401 - `type: "text"`

402

403 - `source: string`

404

405 The URL source of the search result.

406

407 minLength: 1

408

409 - `title: string`

410

411 The title of the search result.

412

413 minLength: 1

414

415 - `type: "search_result"`

416

417 - `is_error: optional boolean or null`

418

419 Whether the tool execution resulted in an error.

420

421 - `processed_at: optional string or null`

422

423 A timestamp in RFC 3339 format

424

425 format: date-time

426

427 - `session_thread_id: optional string or null`

428

429 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.

430

431 - `BetaManagedAgentsAgentCustomToolUseEvent object`

432

433 Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.

434

435 - `id: string`

436

437 Unique identifier for this event.

438

439 - `input: map[unknown]`

440

441 Input parameters for the tool call.

442

443 - `name: string`

444

445 Name of the custom tool being called.

446

447 - `processed_at: string`

448

449 A timestamp in RFC 3339 format

450

451 format: date-time

452

453 - `type: "agent.custom_tool_use"`

454

455 - `session_thread_id: optional string or null`

456

457 When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.

458

459 - `BetaManagedAgentsAgentMessageEvent object`

460

461 An agent response event in the session conversation.

462

463 - `id: string`

464

465 Unique identifier for this event.

466

467 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`

468

469 Array of text blocks comprising the agent response.

470

471 - `BetaManagedAgentsTextBlock object`

472

473 Regular text content.

474

475 - `BetaManagedAgentsRedactedBlock object`

476

477 Placeholder for content withheld by Anthropic model policy.

478

479 - `processed_at: string`

480

481 A timestamp in RFC 3339 format

482

483 format: date-time

484

485 - `type: "agent.message"`

486

487 - `BetaManagedAgentsAgentThinkingEvent object`

488

489 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

490

491 - `id: string`

492

493 Unique identifier for this event.

494

495 - `processed_at: string`

496

497 A timestamp in RFC 3339 format

498

499 format: date-time

500

501 - `type: "agent.thinking"`

502

503 - `BetaManagedAgentsAgentMCPToolUseEvent object`

504

505 Event emitted when the agent invokes a tool provided by an MCP server.

506

507 - `id: string`

508

509 Unique identifier for this event.

510

511 - `input: map[unknown]`

512

513 Input parameters for the tool call.

514

515 - `mcp_server_name: string`

516

517 Name of the MCP server providing the tool.

518

519 - `name: string`

520

521 Name of the MCP tool being used.

522

523 - `processed_at: string`

524

525 A timestamp in RFC 3339 format

526

527 format: date-time

528

529 - `type: "agent.mcp_tool_use"`

530

531 - `evaluated_permission: optional "allow" or "ask" or "deny"`

532

533 AgentEvaluatedPermission enum

534

535 - `"allow"`

536

537 - `"ask"`

538

539 - `"deny"`

540

541 - `session_thread_id: optional string or null`

542

543 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

544

545 - `BetaManagedAgentsAgentMCPToolResultEvent object`

546

547 Event representing the result of an MCP tool execution.

548

549 - `id: string`

550

551 Unique identifier for this event.

552

553 - `mcp_tool_use_id: string`

554

555 The id of the `agent.mcp_tool_use` event this result corresponds to.

556

557 - `processed_at: string`

558

559 A timestamp in RFC 3339 format

560

561 format: date-time

562

563 - `type: "agent.mcp_tool_result"`

564

565 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

566

567 The result content returned by the tool.

568

569 - `BetaManagedAgentsTextBlock object`

570

571 Regular text content.

572

573 - `BetaManagedAgentsImageBlock object`

574

575 Image content specified directly as base64 data or as a reference via a URL.

576

577 - `BetaManagedAgentsDocumentBlock object`

578

579 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

580

581 - `BetaManagedAgentsSearchResultBlock object`

582

583 A block containing a web search result.

584

585 - `is_error: optional boolean or null`

586

587 Whether the tool execution resulted in an error.

588

589 - `BetaManagedAgentsAgentToolUseEvent object`

590

591 Event emitted when the agent invokes a built-in agent tool.

592

593 - `id: string`

594

595 Unique identifier for this event.

596

597 - `input: map[unknown]`

598

599 Input parameters for the tool call.

600

601 - `name: string`

602

603 Name of the agent tool being used.

604

605 - `processed_at: string`

606

607 A timestamp in RFC 3339 format

608

609 format: date-time

610

611 - `type: "agent.tool_use"`

612

613 - `evaluated_permission: optional "allow" or "ask" or "deny"`

614

615 AgentEvaluatedPermission enum

616

617 - `"allow"`

618

619 - `"ask"`

620

621 - `"deny"`

622

623 - `session_thread_id: optional string or null`

624

625 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.

626

627 - `BetaManagedAgentsAgentToolResultEvent object`

628

629 Event representing the result of an agent tool execution.

630

631 - `id: string`

632

633 Unique identifier for this event.

634

635 - `processed_at: string`

636

637 A timestamp in RFC 3339 format

638

639 format: date-time

640

641 - `tool_use_id: string`

642

643 The id of the `agent.tool_use` event this result corresponds to.

644

645 - `type: "agent.tool_result"`

646

647 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

648

649 The result content returned by the tool.

650

651 - `BetaManagedAgentsTextBlock object`

652

653 Regular text content.

654

655 - `BetaManagedAgentsImageBlock object`

656

657 Image content specified directly as base64 data or as a reference via a URL.

658

659 - `BetaManagedAgentsDocumentBlock object`

660

661 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

662

663 - `BetaManagedAgentsSearchResultBlock object`

664

665 A block containing a web search result.

666

667 - `is_error: optional boolean or null`

668

669 Whether the tool execution resulted in an error.

670

671 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`

672

673 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

674

675 - `id: string`

676

677 Unique identifier for this event.

678

679 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

680

681 Message content blocks.

682

683 - `BetaManagedAgentsTextBlock object`

684

685 Regular text content.

686

687 - `BetaManagedAgentsImageBlock object`

688

689 Image content specified directly as base64 data or as a reference via a URL.

690

691 - `BetaManagedAgentsDocumentBlock object`

692

693 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

694

695 - `BetaManagedAgentsRedactedBlock object`

696

697 Placeholder for content withheld by Anthropic model policy.

698

699 - `from_session_thread_id: string`

700

701 Public `sthr_` ID of the thread that sent the message.

702

703 - `processed_at: string`

704

705 A timestamp in RFC 3339 format

706

707 format: date-time

708

709 - `type: "agent.thread_message_received"`

710

711 - `from_agent_name: optional string or null`

712

713 Name of the callable agent this message came from. Absent when received from the primary agent.

714

715 - `BetaManagedAgentsAgentThreadMessageSentEvent object`

716

717 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

718

719 - `id: string`

720

721 Unique identifier for this event.

722

723 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`

724

725 Message content blocks.

726

727 - `BetaManagedAgentsTextBlock object`

728

729 Regular text content.

730

731 - `BetaManagedAgentsImageBlock object`

732

733 Image content specified directly as base64 data or as a reference via a URL.

734

735 - `BetaManagedAgentsDocumentBlock object`

736

737 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

738

739 - `BetaManagedAgentsRedactedBlock object`

740

741 Placeholder for content withheld by Anthropic model policy.

742

743 - `processed_at: string`

744

745 A timestamp in RFC 3339 format

746

747 format: date-time

748

749 - `to_session_thread_id: string`

750

751 Public `sthr_` ID of the thread the message was sent to.

752

753 - `type: "agent.thread_message_sent"`

754

755 - `to_agent_name: optional string or null`

756

757 Name of the callable agent this message was sent to. Absent when sent to the primary agent.

758

759 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`

760

761 Indicates that context compaction (summarization) occurred during the session.

762

763 - `id: string`

764

765 Unique identifier for this event.

766

767 - `processed_at: string`

768

769 A timestamp in RFC 3339 format

770

771 format: date-time

772

773 - `type: "agent.thread_context_compacted"`

774

775 - `BetaManagedAgentsSessionErrorEvent object`

776

777 An error event indicating a problem occurred during session execution.

778

779 - `id: string`

780

781 Unique identifier for this event.

782

783 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`

784

785 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

786

787 - `BetaManagedAgentsUnknownError object`

788

789 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.

790

791 - `message: string`

792

793 Human-readable error description.

794

795 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

796

797 What the client should do next in response to this error.

798

799 - `BetaManagedAgentsRetryStatusRetrying object`

800

801 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

802

803 - `type: "retrying"`

804

805 - `BetaManagedAgentsRetryStatusExhausted object`

806

807 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

808

809 - `type: "exhausted"`

810

811 - `BetaManagedAgentsRetryStatusTerminal object`

812

813 The session encountered a terminal error and will transition to `terminated` state.

814

815 - `type: "terminal"`

816

817 - `type: "unknown_error"`

818

819 - `BetaManagedAgentsModelOverloadedError object`

820

821 The model is currently overloaded. Emitted after automatic retries are exhausted.

822

823 - `message: string`

824

825 Human-readable error description.

826

827 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

828

829 What the client should do next in response to this error.

830

831 - `BetaManagedAgentsRetryStatusRetrying object`

832

833 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

834

835 - `BetaManagedAgentsRetryStatusExhausted object`

836

837 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

838

839 - `BetaManagedAgentsRetryStatusTerminal object`

840

841 The session encountered a terminal error and will transition to `terminated` state.

842

843 - `type: "model_overloaded_error"`

844

845 - `BetaManagedAgentsModelRateLimitedError object`

846

847 The model request was rate-limited.

848

849 - `message: string`

850

851 Human-readable error description.

852

853 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

854

855 What the client should do next in response to this error.

856

857 - `BetaManagedAgentsRetryStatusRetrying object`

858

859 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

860

861 - `BetaManagedAgentsRetryStatusExhausted object`

862

863 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

864

865 - `BetaManagedAgentsRetryStatusTerminal object`

866

867 The session encountered a terminal error and will transition to `terminated` state.

868

869 - `type: "model_rate_limited_error"`

870

871 - `BetaManagedAgentsModelRequestFailedError object`

872

873 A model request failed for a reason other than overload or rate-limiting.

874

875 - `message: string`

876

877 Human-readable error description.

878

879 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

880

881 What the client should do next in response to this error.

882

883 - `BetaManagedAgentsRetryStatusRetrying object`

884

885 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

886

887 - `BetaManagedAgentsRetryStatusExhausted object`

888

889 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

890

891 - `BetaManagedAgentsRetryStatusTerminal object`

892

893 The session encountered a terminal error and will transition to `terminated` state.

894

895 - `type: "model_request_failed_error"`

896

897 - `BetaManagedAgentsMCPConnectionFailedError object`

898

899 Failed to connect to an MCP server.

900

901 - `mcp_server_name: string`

902

903 Name of the MCP server that failed to connect.

904

905 - `message: string`

906

907 Human-readable error description.

908

909 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

910

911 What the client should do next in response to this error.

912

913 - `BetaManagedAgentsRetryStatusRetrying object`

914

915 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

916

917 - `BetaManagedAgentsRetryStatusExhausted object`

918

919 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

920

921 - `BetaManagedAgentsRetryStatusTerminal object`

922

923 The session encountered a terminal error and will transition to `terminated` state.

924

925 - `type: "mcp_connection_failed_error"`

926

927 - `BetaManagedAgentsMCPAuthenticationFailedError object`

928

929 Authentication to an MCP server failed.

930

931 - `mcp_server_name: string`

932

933 Name of the MCP server that failed authentication.

934

935 - `message: string`

936

937 Human-readable error description.

938

939 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

940

941 What the client should do next in response to this error.

942

943 - `BetaManagedAgentsRetryStatusRetrying object`

944

945 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

946

947 - `BetaManagedAgentsRetryStatusExhausted object`

948

949 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

950

951 - `BetaManagedAgentsRetryStatusTerminal object`

952

953 The session encountered a terminal error and will transition to `terminated` state.

954

955 - `type: "mcp_authentication_failed_error"`

956

957 - `BetaManagedAgentsBillingError object`

958

959 The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

960

961 - `message: string`

962

963 Human-readable error description.

964

965 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

966

967 What the client should do next in response to this error.

968

969 - `BetaManagedAgentsRetryStatusRetrying object`

970

971 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

972

973 - `BetaManagedAgentsRetryStatusExhausted object`

974

975 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

976

977 - `BetaManagedAgentsRetryStatusTerminal object`

978

979 The session encountered a terminal error and will transition to `terminated` state.

980

981 - `type: "billing_error"`

982

983 - `BetaManagedAgentsCredentialHostUnreachableError object`

984

985 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.

986

987 - `credential_id: string`

988

989 ID of the affected credential.

990

991 - `message: string`

992

993 Human-readable error description.

994

995 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

996

997 What the client should do next in response to this error.

998

999 - `BetaManagedAgentsRetryStatusRetrying object`

1000

1001 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

1002

1003 - `BetaManagedAgentsRetryStatusExhausted object`

1004

1005 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

1006

1007 - `BetaManagedAgentsRetryStatusTerminal object`

1008

1009 The session encountered a terminal error and will transition to `terminated` state.

1010

1011 - `type: "credential_host_unreachable_error"`

1012

1013 - `vault_id: string`

1014

1015 ID of the vault containing the affected credential.

1016

1017 - `processed_at: string`

1018

1019 A timestamp in RFC 3339 format

1020

1021 format: date-time

1022

1023 - `type: "session.error"`

1024

1025 - `BetaManagedAgentsSessionStatusRescheduledEvent object`

1026

1027 Indicates the session is recovering from an error state and is rescheduled for execution.

1028

1029 - `id: string`

1030

1031 Unique identifier for this event.

1032

1033 - `processed_at: string`

1034

1035 A timestamp in RFC 3339 format

1036

1037 format: date-time

1038

1039 - `type: "session.status_rescheduled"`

1040

1041 - `BetaManagedAgentsSessionStatusRunningEvent object`

1042

1043 Indicates the session is actively running and the agent is working.

1044

1045 - `id: string`

1046

1047 Unique identifier for this event.

1048

1049 - `processed_at: string`

1050

1051 A timestamp in RFC 3339 format

1052

1053 format: date-time

1054

1055 - `type: "session.status_running"`

1056

1057 - `BetaManagedAgentsSessionStatusIdleEvent object`

1058

1059 Indicates the agent has paused and is awaiting user input.

1060

1061 - `id: string`

1062

1063 Unique identifier for this event.

1064

1065 - `processed_at: string`

1066

1067 A timestamp in RFC 3339 format

1068

1069 format: date-time

1070

1071 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`

1072

1073 The agent completed its turn naturally and is ready for the next user message.

1074

1075 - `BetaManagedAgentsSessionEndTurn object`

1076

1077 The agent completed its turn naturally and is ready for the next user message.

1078

1079 - `type: "end_turn"`

1080

1081 - `BetaManagedAgentsSessionRequiresAction object`

1082

1083 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

1084

1085 - `event_ids: array of string`

1086

1087 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.

1088

1089 - `type: "requires_action"`

1090

1091 - `BetaManagedAgentsSessionRetriesExhausted object`

1092

1093 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.

1094

1095 - `type: "retries_exhausted"`

1096

1097 - `BetaManagedAgentsSessionBudgetReached object`

1098

1099 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.

1100

1101 - `type: "budget_reached"`

1102

1103 - `type: "session.status_idle"`

1104

1105 - `BetaManagedAgentsSessionStatusTerminatedEvent object`

1106

1107 Indicates the session has terminated, either due to an error or completion.

1108

1109 - `id: string`

1110

1111 Unique identifier for this event.

1112

1113 - `processed_at: string`

1114

1115 A timestamp in RFC 3339 format

1116

1117 format: date-time

1118

1119 - `type: "session.status_terminated"`

1120

1121 - `BetaManagedAgentsSessionThreadCreatedEvent object`

1122

1123 Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.

1124

1125 - `id: string`

1126

1127 Unique identifier for this event.

1128

1129 - `agent_name: string`

1130

1131 Name of the callable agent the thread runs.

1132

1133 - `processed_at: string`

1134

1135 A timestamp in RFC 3339 format

1136

1137 format: date-time

1138

1139 - `session_thread_id: string`

1140

1141 Public `sthr_` ID of the newly created thread.

1142

1143 - `type: "session.thread_created"`

1144

1145 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`

1146

1147 Emitted when an outcome evaluation cycle begins.

1148

1149 - `id: string`

1150

1151 Unique identifier for this event.

1152

1153 - `iteration: number`

1154

1155 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

1156

1157 format: int32

1158

1159 - `outcome_id: string`

1160

1161 The `outc_` ID of the outcome being evaluated.

1162

1163 - `processed_at: string`

1164

1165 A timestamp in RFC 3339 format

1166

1167 format: date-time

1168

1169 - `type: "span.outcome_evaluation_start"`

1170

1171 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`

1172

1173 Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.

1174

1175 - `id: string`

1176

1177 Unique identifier for this event.

1178

1179 - `explanation: string`

1180

1181 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.

1182

1183 - `iteration: number`

1184

1185 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

1186

1187 format: int32

1188

1189 - `outcome_evaluation_start_id: string`

1190

1191 The id of the corresponding `span.outcome_evaluation_start` event.

1192

1193 - `outcome_id: string`

1194

1195 The `outc_` ID of the outcome being evaluated.

1196

1197 - `processed_at: string`

1198

1199 A timestamp in RFC 3339 format

1200

1201 format: date-time

1202

1203 - `result: string`

1204

1205 Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.

1206

1207 - `type: "span.outcome_evaluation_end"`

1208

1209 - `usage: BetaManagedAgentsSpanModelUsage`

1210

1211 Token usage for a single model request.

1212

1213 - `cache_creation_input_tokens: number`

1214

1215 Tokens used to create prompt cache in this request.

1216

1217 format: int32

1218

1219 - `cache_read_input_tokens: number`

1220

1221 Tokens read from prompt cache in this request.

1222

1223 format: int32

1224

1225 - `input_tokens: number`

1226

1227 Input tokens consumed by this request.

1228

1229 format: int32

1230

1231 - `output_tokens: number`

1232

1233 Output tokens generated by this request.

1234

1235 format: int32

1236

1237 - `speed: optional "standard" or "fast" or null`

1238

1239 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.

1240

1241 - `"standard"`

1242

1243 - `"fast"`

1244

1245 - `BetaManagedAgentsSpanModelRequestStartEvent object`

1246

1247 Emitted when a model request is initiated by the agent.

1248

1249 - `id: string`

1250

1251 Unique identifier for this event.

1252

1253 - `processed_at: string`

1254

1255 A timestamp in RFC 3339 format

1256

1257 format: date-time

1258

1259 - `type: "span.model_request_start"`

1260

1261 - `BetaManagedAgentsSpanModelRequestEndEvent object`

1262

1263 Emitted when a model request completes.

1264

1265 - `id: string`

1266

1267 Unique identifier for this event.

1268

1269 - `is_error: boolean or null`

1270

1271 Whether the model request resulted in an error.

1272

1273 - `model_request_start_id: string`

1274

1275 The id of the corresponding `span.model_request_start` event.

1276

1277 - `model_usage: BetaManagedAgentsSpanModelUsage`

1278

1279 Token usage for a single model request.

1280

1281 - `processed_at: string`

1282

1283 A timestamp in RFC 3339 format

1284

1285 format: date-time

1286

1287 - `type: "span.model_request_end"`

1288

1289 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`

1290

1291 Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.

1292

1293 - `id: string`

1294

1295 Unique identifier for this event.

1296

1297 - `iteration: number`

1298

1299 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.

1300

1301 format: int32

1302

1303 - `outcome_id: string`

1304

1305 The `outc_` ID of the outcome being evaluated.

1306

1307 - `processed_at: string`

1308

1309 A timestamp in RFC 3339 format

1310

1311 format: date-time

1312

1313 - `type: "span.outcome_evaluation_ongoing"`

1314

1315 - `BetaManagedAgentsUserDefineOutcomeEvent object`

1316

1317 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.

1318

1319 - `id: string`

1320

1321 Unique identifier for this event.

1322

1323 - `description: string`

1324

1325 What the agent should produce. Copied from the input event.

1326

1327 - `max_iterations: number or null`

1328

1329 Evaluate-then-revise cycles before giving up. Default 3, max 20.

1330

1331 format: int32

1332

1333 - `outcome_id: string`

1334

1335 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.

1336

1337 - `processed_at: string`

1338

1339 A timestamp in RFC 3339 format

1340

1341 format: date-time

1342

1343 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`

1344

1345 Rubric for grading the quality of an outcome.

1346

1347 - `BetaManagedAgentsFileRubric object`

1348

1349 Rubric referenced by a file uploaded via the Files API.

1350

1351 - `file_id: string`

1352

1353 ID of the rubric file.

1354

1355 - `type: "file"`

1356

1357 - `BetaManagedAgentsTextRubric object`

1358

1359 Rubric content provided inline as text.

1360

1361 - `content: string`

1362

1363 Rubric content. Plain text or markdown — the grader treats it as freeform text.

1364

1365 - `type: "text"`

1366

1367 - `type: "user.define_outcome"`

1368

1369 - `BetaManagedAgentsSessionDeletedEvent object`

1370

1371 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

1372

1373 - `id: string`

1374

1375 Unique identifier for this event.

1376

1377 - `processed_at: string`

1378

1379 A timestamp in RFC 3339 format

1380

1381 format: date-time

1382

1383 - `type: "session.deleted"`

1384

1385 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`

1386

1387 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

1388

1389 - `id: string`

1390

1391 Unique identifier for this event.

1392

1393 - `agent_name: string`

1394

1395 Name of the agent the thread runs.

1396

1397 - `processed_at: string`

1398

1399 A timestamp in RFC 3339 format

1400

1401 format: date-time

1402

1403 - `session_thread_id: string`

1404

1405 Public sthr_ ID of the thread that started running.

1406

1407 - `type: "session.thread_status_running"`

1408

1409 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`

1410

1411 A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

1412

1413 - `id: string`

1414

1415 Unique identifier for this event.

1416

1417 - `agent_name: string`

1418

1419 Name of the agent the thread runs.

1420

1421 - `processed_at: string`

1422

1423 A timestamp in RFC 3339 format

1424

1425 format: date-time

1426

1427 - `session_thread_id: string`

1428

1429 Public sthr_ ID of the thread that went idle.

1430

1431 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`

1432

1433 The agent completed its turn naturally and is ready for the next user message.

1434

1435 - `BetaManagedAgentsSessionEndTurn object`

1436

1437 The agent completed its turn naturally and is ready for the next user message.

1438

1439 - `BetaManagedAgentsSessionRequiresAction object`

1440

1441 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

1442

1443 - `BetaManagedAgentsSessionRetriesExhausted object`

1444

1445 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.

1446

1447 - `BetaManagedAgentsSessionBudgetReached object`

1448

1449 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.

1450

1451 - `type: "session.thread_status_idle"`

1452

1453 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`

1454

1455 A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

1456

1457 - `id: string`

1458

1459 Unique identifier for this event.

1460

1461 - `agent_name: string`

1462

1463 Name of the agent the thread runs.

1464

1465 - `processed_at: string`

1466

1467 A timestamp in RFC 3339 format

1468

1469 format: date-time

1470

1471 - `session_thread_id: string`

1472

1473 Public sthr_ ID of the thread that terminated.

1474

1475 - `type: "session.thread_status_terminated"`

1476

1477 - `BetaManagedAgentsUserToolResultEvent object`

1478

1479 Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.

1480

1481 - `id: string`

1482

1483 Unique identifier for this event.

1484

1485 - `tool_use_id: string`

1486

1487 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.

1488

1489 - `type: "user.tool_result"`

1490

1491 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`

1492

1493 The result content returned by the tool.

1494

1495 - `BetaManagedAgentsTextBlock object`

1496

1497 Regular text content.

1498

1499 - `BetaManagedAgentsImageBlock object`

1500

1501 Image content specified directly as base64 data or as a reference via a URL.

1502

1503 - `BetaManagedAgentsDocumentBlock object`

1504

1505 Document content, either specified directly as base64 data, as text, or as a reference via a URL.

1506

1507 - `BetaManagedAgentsSearchResultBlock object`

1508

1509 A block containing a web search result.

1510

1511 - `is_error: optional boolean or null`

1512

1513 Whether the tool execution resulted in an error.

1514

1515 - `processed_at: optional string or null`

1516

1517 A timestamp in RFC 3339 format

1518

1519 format: date-time

1520

1521 - `session_thread_id: optional string or null`

1522

1523 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.

1524

1525 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`

1526

1527 A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

1528

1529 - `id: string`

1530

1531 Unique identifier for this event.

1532

1533 - `agent_name: string`

1534

1535 Name of the agent the thread runs.

1536

1537 - `processed_at: string`

1538

1539 A timestamp in RFC 3339 format

1540

1541 format: date-time

1542

1543 - `session_thread_id: string`

1544

1545 Public sthr_ ID of the thread that is retrying.

1546

1547 - `type: "session.thread_status_rescheduled"`

1548

1549 - `BetaManagedAgentsSessionUpdatedEvent object`

1550

1551 Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

1552

1553 - `id: string`

1554

1555 Unique identifier for this event.

1556

1557 - `processed_at: string`

1558

1559 A timestamp in RFC 3339 format

1560

1561 format: date-time

1562

1563 - `type: "session.updated"`

1564

1565 - `agent: optional BetaManagedAgentsSessionAgent or null`

1566

1567 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.

1568

1569 - `id: string`

1570

1571 - `description: string or null`

1572

1573 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1574

1575 - `name: string`

1576

1577 - `type: "url"`

1578

1579 - `url: string`

1580

1581 - `model: BetaManagedAgentsModelConfig`

1582

1583 Model identifier and configuration.

1584

1585 - `id: BetaManagedAgentsModel`

1586

1587 The model that will power your agent.

1588

1589 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

1590

1591 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`

1592

1593 The model that will power your agent.

1594

1595 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

1596

1597 - `"claude-fable-5-1"`

1598

1599 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows

1600

1601 - `"claude-sonnet-5"`

1602

1603 High-performance model for coding and agents

1604

1605 - `"claude-fable-5"`

1606

1607 Next generation of intelligence for the hardest knowledge work and coding problems

1608

1609 - `"claude-opus-5"`

1610

1611 Powerful intelligence for long-running agents and coding

1612

1613 - `"claude-opus-4-8"`

1614

1615 Powerful intelligence for long-running agents and coding

1616

1617 - `"claude-opus-4-7"`

1618

1619 Powerful intelligence for long-running agents and coding

1620

1621 - `"claude-opus-4-6"`

1622

1623 Powerful intelligence for long-running agents and coding

1624

1625 - `"claude-sonnet-4-6"`

1626

1627 Best combination of speed and intelligence

1628

1629 - `"claude-haiku-4-5"`

1630

1631 Fastest model with near-frontier intelligence

1632

1633 - `"claude-haiku-4-5-20251001"`

1634

1635 Fastest model with near-frontier intelligence

1636

1637 - `"claude-opus-4-5"`

1638

1639 Powerful intelligence for long-running agents and coding

1640

1641 - `"claude-opus-4-5-20251101"`

1642

1643 Powerful intelligence for long-running agents and coding

1644

1645 - `"claude-sonnet-4-5"`

1646

1647 High-performance model for agents and coding

1648

1649 - `"claude-sonnet-4-5-20250929"`

1650

1651 High-performance model for agents and coding

1652

1653 - `string`

1654

1655 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`

1656

1657 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.

1658

1659 - `BetaManagedAgentsEffortLow object`

1660

1661 Low effort. Favors latency over reasoning depth.

1662

1663 - `type: "low"`

1664

1665 - `BetaManagedAgentsEffortMedium object`

1666

1667 Medium effort. Balances latency and reasoning depth.

1668

1669 - `type: "medium"`

1670

1671 - `BetaManagedAgentsEffortHigh object`

1672

1673 High effort. Favors reasoning depth.

1674

1675 - `type: "high"`

1676

1677 - `BetaManagedAgentsEffortXhigh object`

1678

1679 Extra-high effort. Not all models accept this level.

1680

1681 - `type: "xhigh"`

1682

1683 - `BetaManagedAgentsEffortMax object`

1684

1685 Maximum effort. Favors reasoning depth over latency.

1686

1687 - `type: "max"`

1688

1689 - `inference_geo: optional string`

1690

1691 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.

1692

1693 - `speed: optional "standard" or "fast"`

1694

1695 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.

1696

1697 - `"standard"`

1698

1699 - `"fast"`

1700

1701 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`

1702

1703 Resolved coordinator topology with full agent definitions for each roster member.

1704

1705 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`

1706

1707 Full `agent` definitions the coordinator may spawn as session threads.

1708

1709 - `BetaManagedAgentsSessionThreadAgent object`

1710

1711 Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.

1712

1713 - `id: string`

1714

1715 - `description: string or null`

1716

1717 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1718

1719 - `name: string`

1720

1721 - `type: "url"`

1722

1723 - `url: string`

1724

1725 - `model: BetaManagedAgentsModelConfig`

1726

1727 Model identifier and configuration.

1728

1729 - `name: string`

1730

1731 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

1732

1733 - `BetaManagedAgentsAnthropicSkill object`

1734

1735 A resolved Anthropic-managed skill.

1736

1737 - `skill_id: string`

1738

1739 - `type: "anthropic"`

1740

1741 - `version: string`

1742

1743 - `BetaManagedAgentsCustomSkill object`

1744

1745 A resolved user-created custom skill.

1746

1747 - `skill_id: string`

1748

1749 - `type: "custom"`

1750

1751 - `version: string`

1752

1753 - `system: string or null`

1754

1755 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`

1756

1757 - `BetaManagedAgentsAgentToolset20260401 object`

1758

1759 - `configs: array of BetaManagedAgentsAgentToolConfig`

1760

1761 - `BetaManagedAgentsBashToolConfig object`

1762

1763 Configuration for the bash tool.

1764

1765 - `enabled: boolean`

1766

1767 - `name: "bash"`

1768

1769 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1770

1771 Permission policy for tool execution.

1772

1773 - `BetaManagedAgentsAlwaysAllowPolicy object`

1774

1775 Tool calls are automatically approved without user confirmation.

1776

1777 - `type: "always_allow"`

1778

1779 - `BetaManagedAgentsAlwaysAskPolicy object`

1780

1781 Tool calls require user confirmation before execution.

1782

1783 - `type: "always_ask"`

1784

1785 - `type: "bash"`

1786

1787 - `BetaManagedAgentsEditToolConfig object`

1788

1789 Configuration for the edit tool.

1790

1791 - `enabled: boolean`

1792

1793 - `name: "edit"`

1794

1795 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1796

1797 Permission policy for tool execution.

1798

1799 - `BetaManagedAgentsAlwaysAllowPolicy object`

1800

1801 Tool calls are automatically approved without user confirmation.

1802

1803 - `BetaManagedAgentsAlwaysAskPolicy object`

1804

1805 Tool calls require user confirmation before execution.

1806

1807 - `type: "edit"`

1808

1809 - `BetaManagedAgentsReadToolConfig object`

1810

1811 Configuration for the read tool.

1812

1813 - `enabled: boolean`

1814

1815 - `name: "read"`

1816

1817 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1818

1819 Permission policy for tool execution.

1820

1821 - `BetaManagedAgentsAlwaysAllowPolicy object`

1822

1823 Tool calls are automatically approved without user confirmation.

1824

1825 - `BetaManagedAgentsAlwaysAskPolicy object`

1826

1827 Tool calls require user confirmation before execution.

1828

1829 - `type: "read"`

1830

1831 - `BetaManagedAgentsWriteToolConfig object`

1832

1833 Configuration for the write tool.

1834

1835 - `enabled: boolean`

1836

1837 - `name: "write"`

1838

1839 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1840

1841 Permission policy for tool execution.

1842

1843 - `BetaManagedAgentsAlwaysAllowPolicy object`

1844

1845 Tool calls are automatically approved without user confirmation.

1846

1847 - `BetaManagedAgentsAlwaysAskPolicy object`

1848

1849 Tool calls require user confirmation before execution.

1850

1851 - `type: "write"`

1852

1853 - `BetaManagedAgentsGlobToolConfig object`

1854

1855 Configuration for the glob tool.

1856

1857 - `enabled: boolean`

1858

1859 - `name: "glob"`

1860

1861 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1862

1863 Permission policy for tool execution.

1864

1865 - `BetaManagedAgentsAlwaysAllowPolicy object`

1866

1867 Tool calls are automatically approved without user confirmation.

1868

1869 - `BetaManagedAgentsAlwaysAskPolicy object`

1870

1871 Tool calls require user confirmation before execution.

1872

1873 - `type: "glob"`

1874

1875 - `BetaManagedAgentsGrepToolConfig object`

1876

1877 Configuration for the grep tool.

1878

1879 - `enabled: boolean`

1880

1881 - `name: "grep"`

1882

1883 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1884

1885 Permission policy for tool execution.

1886

1887 - `BetaManagedAgentsAlwaysAllowPolicy object`

1888

1889 Tool calls are automatically approved without user confirmation.

1890

1891 - `BetaManagedAgentsAlwaysAskPolicy object`

1892

1893 Tool calls require user confirmation before execution.

1894

1895 - `type: "grep"`

1896

1897 - `BetaManagedAgentsWebFetchToolConfig object`

1898

1899 Configuration for the web_fetch tool.

1900

1901 - `enabled: boolean`

1902

1903 - `name: "web_fetch"`

1904

1905 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1906

1907 Permission policy for tool execution.

1908

1909 - `BetaManagedAgentsAlwaysAllowPolicy object`

1910

1911 Tool calls are automatically approved without user confirmation.

1912

1913 - `BetaManagedAgentsAlwaysAskPolicy object`

1914

1915 Tool calls require user confirmation before execution.

1916

1917 - `type: "web_fetch"`

1918

1919 - `allowed_domains: optional array of string`

1920

1921 - `blocked_domains: optional array of string`

1922

1923 - `max_content_tokens: optional number or null`

1924

1925 format: int32

1926

1927 - `BetaManagedAgentsWebSearchToolConfig object`

1928

1929 Configuration for the web_search tool.

1930

1931 - `enabled: boolean`

1932

1933 - `name: "web_search"`

1934

1935 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1936

1937 Permission policy for tool execution.

1938

1939 - `BetaManagedAgentsAlwaysAllowPolicy object`

1940

1941 Tool calls are automatically approved without user confirmation.

1942

1943 - `BetaManagedAgentsAlwaysAskPolicy object`

1944

1945 Tool calls require user confirmation before execution.

1946

1947 - `type: "web_search"`

1948

1949 - `allowed_domains: optional array of string`

1950

1951 - `blocked_domains: optional array of string`

1952

1953 - `user_location: optional BetaManagedAgentsUserLocation or null`

1954

1955 Approximate user location for search result localization.

1956

1957 - `type: "approximate"`

1958

1959 Location precision. Only "approximate" is supported.

1960

1961 - `city: optional string or null`

1962

1963 City name.

1964

1965 minLength: 1, maxLength: 255

1966

1967 - `country: optional string or null`

1968

1969 Two-letter ISO 3166-1 country code, uppercase.

1970

1971 - `region: optional string or null`

1972

1973 Region or state name.

1974

1975 minLength: 1, maxLength: 255

1976

1977 - `timezone: optional string or null`

1978

1979 IANA timezone identifier, e.g. "America/Los_Angeles".

1980

1981 minLength: 1, maxLength: 255

1982

1983 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`

1984

1985 Resolved default configuration for agent tools.

1986

1987 - `enabled: boolean`

1988

1989 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1990

1991 Permission policy for tool execution.

1992

1993 - `BetaManagedAgentsAlwaysAllowPolicy object`

1994

1995 Tool calls are automatically approved without user confirmation.

1996

1997 - `BetaManagedAgentsAlwaysAskPolicy object`

1998

1999 Tool calls require user confirmation before execution.

2000

2001 - `type: "agent_toolset_20260401"`

2002

2003 - `BetaManagedAgentsMCPToolset object`

2004

2005 - `configs: array of BetaManagedAgentsMCPToolConfig`

2006

2007 - `enabled: boolean`

2008

2009 - `name: string`

2010

2011 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

2012

2013 Permission policy for tool execution.

2014

2015 - `BetaManagedAgentsAlwaysAllowPolicy object`

2016

2017 Tool calls are automatically approved without user confirmation.

2018

2019 - `BetaManagedAgentsAlwaysAskPolicy object`

2020

2021 Tool calls require user confirmation before execution.

2022

2023 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

2024

2025 Resolved default configuration for all tools from an MCP server.

2026

2027 - `enabled: boolean`

2028

2029 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

2030

2031 Permission policy for tool execution.

2032

2033 - `BetaManagedAgentsAlwaysAllowPolicy object`

2034

2035 Tool calls are automatically approved without user confirmation.

2036

2037 - `BetaManagedAgentsAlwaysAskPolicy object`

2038

2039 Tool calls require user confirmation before execution.

2040

2041 - `mcp_server_name: string`

2042

2043 - `type: "mcp_toolset"`

2044

2045 - `BetaManagedAgentsCustomTool object`

2046

2047 A custom tool as returned in API responses.

2048

2049 - `description: string`

2050

2051 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

2052

2053 JSON Schema for custom tool input parameters.

2054

2055 - `type: "object"`

2056

2057 - `properties: optional map[unknown] or null`

2058

2059 - `required: optional array of string or null`

2060

2061 - `name: string`

2062

2063 - `type: "custom"`

2064

2065 - `type: "agent"`

2066

2067 - `version: number`

2068

2069 format: int32

2070

2071 - `BetaManagedAgentsAdvisor object`

2072

2073 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

2074

2075 - `model: string`

2076

2077 The advisor model id.

2078

2079 - `type: "advisor"`

2080

2081 - `type: "coordinator"`

2082

2083 - `name: string`

2084

2085 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

2086

2087 - `BetaManagedAgentsAnthropicSkill object`

2088

2089 A resolved Anthropic-managed skill.

2090

2091 - `BetaManagedAgentsCustomSkill object`

2092

2093 A resolved user-created custom skill.

2094

2095 - `system: string or null`

2096

2097 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`

2098

2099 - `BetaManagedAgentsAgentToolset20260401 object`

2100

2101 - `BetaManagedAgentsMCPToolset object`

2102

2103 - `BetaManagedAgentsCustomTool object`

2104

2105 A custom tool as returned in API responses.

2106

2107 - `type: "agent"`

2108

2109 - `version: number`

2110

2111 format: int32

2112

2113 - `budget: optional BetaManagedAgentsBudgetLimit or null`

2114

2115 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.

2116

2117 - `max_list_cost: BetaMonetaryAmount`

2118

2119 A monetary amount in a specific currency.

2120

2121 - `amount: string`

2122

2123 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

2124

2125 - `currency: BetaCurrency`

2126

2127 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.

2128

2129 - `type: "limit"`

2130

2131 - `metadata: optional map[string]`

2132

2133 The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.

2134

2135 - `title: optional string or null`

2136

2137 The session's new title. Present only when the update changed it.

2138

2139 - `BetaManagedAgentsStartEvent object`

2140

2141 Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.

2142

2143 - `event: BetaManagedAgentsStartEventPreview`

2144

2145 The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them.

2146

2147 - `BetaManagedAgentsAgentMessagePreview object`

2148

2149 - `id: string`

2150

2151 The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.

2152

2153 - `type: "agent.message"`

2154

2155 - `BetaManagedAgentsAgentThinkingPreview object`

2156

2157 - `id: string`

2158

2159 The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.

2160

2161 - `type: "agent.thinking"`

2162

2163 - `type: "event_start"`

2164

2165 - `BetaManagedAgentsDeltaEvent object`

2166

2167 An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.

2168

2169 - `delta: BetaManagedAgentsDeltaContent`

2170

2171 One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array.

2172

2173 - `content: BetaManagedAgentsTextBlock`

2174

2175 Regular text content.

2176

2177 - `type: "content_delta"`

2178

2179 - `index: optional number`

2180

2181 Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.

2182

2183 format: uint32

2184

2185 - `event_id: string`

2186

2187 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.

2188

2189 - `type: "event_delta"`

2190

2191 - `BetaManagedAgentsSystemMessageEvent object`

2192

2193 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.

2194

2195 - `id: string`

2196

2197 Unique identifier for this event.

2198

2199 - `content: array of BetaManagedAgentsSystemContentBlock`

2200

2201 System content blocks. Text-only.

2202

2203 - `text: string`

2204

2205 The text content.

2206

2207 minLength: 1

2208

2209 - `type: "text"`

2210

2211 - `type: "system.message"`

2212

2213 - `processed_at: optional string or null`

2214

2215 A timestamp in RFC 3339 format

2216

2217 format: date-time

2218

22192334 - `BetaManagedAgentsSessionUsageEvent object`

22202335

22212336 Periodic snapshot of the session's cumulative usage and tracked list cost.

22222337

2223 - `id: string`

2224

2225 Unique identifier for this event.

2226

2227 - `processed_at: string`

2228

2229 A timestamp in RFC 3339 format

2230

2231 format: date-time

2232

22332338 - `type: "session.usage"`

2339

2340 - `id: string`

2341

2342 Unique identifier for this event.

2343

2344 - `processed_at: string`

2345

2346 A timestamp in RFC 3339 format

2347

2348 format: date-time

22342349

22352350 - `usage: BetaManagedAgentsSessionUsageSnapshot`

22362351

22372352

This page’s history 12 edits

21 Sep 2026 +4 −0
16 Sep 2026 +3 −1
15 Sep 2026 +6 −6
11 Sep 2026 +0 −6
10 Sep 2026 +2174 −2059 · this one
9 Sep 2026 +0 −4

The page’s own history →

Where it came from

The captureapi
Upstream pageplatform.claude.com

Stream Events changed

The whole hunk