api/beta/sessions/threads/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 Session Thread Events

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

4---

16# Stream Session Thread Events

38**GET** `/v1/sessions/{session_id}/threads/{thread_id}/stream`

from line 33

2833

2934 - `string`

3035

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

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

3237

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

3439

from line 81

7681

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

7883

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

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

8087

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

from line 125

118125

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

120127

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

129

121130## Returns

122131

123132- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`

from line 137

128137

129138 A user message event in the session conversation.

130139

140 - `type: "user.message"`

141

131142 - `id: string`

132143

133144 Unique identifier for this event.

from line 151

140151

141152 Regular text content.

142153

154 - `type: "text"`

155

143156 - `text: string`

144157

145158 The text content.

146159

147160 minLength: 1

148161

162 - `BetaManagedAgentsImageBlock object`

163

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

165

166 - `type: "image"`

167

168 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

169

170 Union type for image source variants.

171

172 - `BetaManagedAgentsBase64ImageSource object`

173

174 Base64-encoded image data.

175

176 - `type: "base64"`

177

178 - `data: string`

179

180 Base64-encoded image data.

181

182 minLength: 1

183

184 - `media_type: string`

185

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

187

188 minLength: 1

189

190 - `BetaManagedAgentsURLImageSource object`

191

192 Image referenced by URL.

193

194 - `type: "url"`

195

196 - `url: string`

197

198 URL of the image to fetch.

199

200 minLength: 1

201

202 - `BetaManagedAgentsFileImageSource object`

203

204 Image referenced by file ID.

205

206 - `type: "file"`

207

208 - `file_id: string`

209

210 ID of a previously uploaded file.

211

212 minLength: 1

213

214 - `BetaManagedAgentsDocumentBlock object`

215

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

217

218 - `type: "document"`

219

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

221

222 Union type for document source variants.

223

224 - `BetaManagedAgentsBase64DocumentSource object`

225

226 Base64-encoded document data.

227

228 - `type: "base64"`

229

230 - `data: string`

231

232 Base64-encoded document data.

233

234 minLength: 1

235

236 - `media_type: string`

237

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

239

240 minLength: 1

241

242 - `BetaManagedAgentsPlainTextDocumentSource object`

243

244 Plain text document content.

245

246 - `type: "text"`

247

248 - `data: string`

249

250 The plain text content.

251

252 minLength: 1

253

254 - `media_type: "text/plain"`

255

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

257

258 - `BetaManagedAgentsURLDocumentSource object`

259

260 Document referenced by URL.

261

262 - `type: "url"`

263

264 - `url: string`

265

266 URL of the document to fetch.

267

268 minLength: 1

269

270 - `BetaManagedAgentsFileDocumentSource object`

271

272 Document referenced by file ID.

273

274 - `type: "file"`

275

276 - `file_id: string`

277

278 ID of a previously uploaded file.

279

280 minLength: 1

281

282 - `context: optional string or null`

283

284 Additional context about the document for the model.

285

286 - `title: optional string or null`

287

288 The title of the document.

289

290 - `BetaManagedAgentsRedactedBlock object`

291

292 Placeholder for content withheld by Anthropic model policy.

293

294 - `type: "redacted"`

295

296 - `processed_at: optional string or null`

297

298 A timestamp in RFC 3339 format

299

300 format: date-time

301

302 - `BetaManagedAgentsUserInterruptEvent object`

303

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

305

306 - `type: "user.interrupt"`

307

308 - `id: string`

309

310 Unique identifier for this event.

311

312 - `processed_at: optional string or null`

313

314 A timestamp in RFC 3339 format

315

316 format: date-time

317

318 - `session_thread_id: optional string or null`

319

320 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.

321

322 - `BetaManagedAgentsUserToolConfirmationEvent object`

323

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

325

326 - `type: "user.tool_confirmation"`

327

328 - `id: string`

329

330 Unique identifier for this event.

331

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

333

334 UserToolConfirmationResult enum

335

336 - `"allow"`

337

338 - `"deny"`

339

340 - `tool_use_id: string`

341

342 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.

343

344 - `deny_message: optional string or null`

345

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

347

348 maxLength: 10000

349

350 - `processed_at: optional string or null`

351

352 A timestamp in RFC 3339 format

353

354 format: date-time

355

356 - `session_thread_id: optional string or null`

357

358 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.

359

360 - `BetaManagedAgentsUserCustomToolResultEvent object`

361

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

363

364 - `type: "user.custom_tool_result"`

365

366 - `id: string`

367

368 Unique identifier for this event.

369

370 - `custom_tool_use_id: string`

371

372 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.

373

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

375

376 The result content returned by the tool.

377

378 - `BetaManagedAgentsTextBlock object`

379

380 Regular text content.

381

382 - `BetaManagedAgentsImageBlock object`

383

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

385

386 - `BetaManagedAgentsDocumentBlock object`

387

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

389

390 - `BetaManagedAgentsSearchResultBlock object`

391

392 A block containing a web search result.

393

394 - `type: "search_result"`

395

396 - `citations: BetaManagedAgentsSearchResultCitations`

397

398 Citation settings for a search result.

399

400 - `enabled: boolean`

401

402 Whether citations are enabled for this search result.

403

404 - `content: array of BetaManagedAgentsSearchResultContent`

405

406 Array of text content blocks from the search result.

407

408 - `type: "text"`

409

410 - `text: string`

411

412 The text content.

413

414 minLength: 1

415

416 - `source: string`

417

418 The URL source of the search result.

419

420 minLength: 1

421

422 - `title: string`

423

424 The title of the search result.

425

426 minLength: 1

427

428 - `is_error: optional boolean or null`

429

430 Whether the tool execution resulted in an error.

431

432 - `processed_at: optional string or null`

433

434 A timestamp in RFC 3339 format

435

436 format: date-time

437

438 - `session_thread_id: optional string or null`

439

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

441

442 - `BetaManagedAgentsAgentCustomToolUseEvent object`

443

444 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.

445

446 - `type: "agent.custom_tool_use"`

447

448 - `id: string`

449

450 Unique identifier for this event.

451

452 - `input: map[unknown]`

453

454 Input parameters for the tool call.

455

456 - `name: string`

457

458 Name of the custom tool being called.

459

460 - `processed_at: string`

461

462 A timestamp in RFC 3339 format

463

464 format: date-time

465

466 - `session_thread_id: optional string or null`

467

468 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.

469

470 - `BetaManagedAgentsAgentMessageEvent object`

471

472 An agent response event in the session conversation.

473

474 - `type: "agent.message"`

475

476 - `id: string`

477

478 Unique identifier for this event.

479

480 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`

481

482 Array of text blocks comprising the agent response.

483

484 - `BetaManagedAgentsTextBlock object`

485

486 Regular text content.

487

488 - `BetaManagedAgentsRedactedBlock object`

489

490 Placeholder for content withheld by Anthropic model policy.

491

492 - `processed_at: string`

493

494 A timestamp in RFC 3339 format

495

496 format: date-time

497

498 - `BetaManagedAgentsAgentThinkingEvent object`

499

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

501

502 - `type: "agent.thinking"`

503

504 - `id: string`

505

506 Unique identifier for this event.

507

508 - `processed_at: string`

509

510 A timestamp in RFC 3339 format

511

512 format: date-time

513

514 - `BetaManagedAgentsAgentMCPToolUseEvent object`

515

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

517

518 - `type: "agent.mcp_tool_use"`

519

520 - `id: string`

521

522 Unique identifier for this event.

523

524 - `input: map[unknown]`

525

526 Input parameters for the tool call.

527

528 - `mcp_server_name: string`

529

530 Name of the MCP server providing the tool.

531

532 - `name: string`

533

534 Name of the MCP tool being used.

535

536 - `processed_at: string`

537

538 A timestamp in RFC 3339 format

539

540 format: date-time

541

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

543

544 AgentEvaluatedPermission enum

545

546 - `"allow"`

547

548 - `"ask"`

549

550 - `"deny"`

551

552 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`

553

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

555

556 - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object`

557

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

559

560 - `type: "always_allow"`

561

562 - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object`

563

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

565

566 - `type: "always_ask"`

567

568 - `BetaManagedAgentsAgentToolEvaluationAuto object`

569

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

571

572 - `type: "auto"`

573

574 - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission`

575

576 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.

577

578 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object`

579

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

581

582 - `type: "allow"`

583

584 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object`

585

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

587

588 - `type: "ask"`

589

590 - `reason_code: string`

591

592 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.

593

594 maxLength: 64

595

596 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object`

597

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

599

600 - `type: "deny"`

601

602 - `reason_code: string`

603

604 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.

605

606 maxLength: 64

607

608 - `session_thread_id: optional string or null`

609

610 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.

611

612 - `BetaManagedAgentsAgentMCPToolResultEvent object`

613

614 Event representing the result of an MCP tool execution.

615

616 - `type: "agent.mcp_tool_result"`

617

618 - `id: string`

619

620 Unique identifier for this event.

621

622 - `mcp_tool_use_id: string`

623

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

625

626 - `processed_at: string`

627

628 A timestamp in RFC 3339 format

629

630 format: date-time

631

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

633

634 The result content returned by the tool.

635

636 - `BetaManagedAgentsTextBlock object`

637

638 Regular text content.

639

640 - `BetaManagedAgentsImageBlock object`

641

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

643

644 - `BetaManagedAgentsDocumentBlock object`

645

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

647

648 - `BetaManagedAgentsSearchResultBlock object`

649

650 A block containing a web search result.

651

652 - `is_error: optional boolean or null`

653

654 Whether the tool execution resulted in an error.

655

656 - `BetaManagedAgentsAgentToolUseEvent object`

657

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

659

660 - `type: "agent.tool_use"`

661

662 - `id: string`

663

664 Unique identifier for this event.

665

666 - `input: map[unknown]`

667

668 Input parameters for the tool call.

669

670 - `name: string`

671

672 Name of the agent tool being used.

673

674 - `processed_at: string`

675

676 A timestamp in RFC 3339 format

677

678 format: date-time

679

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

681

682 AgentEvaluatedPermission enum

683

684 - `"allow"`

685

686 - `"ask"`

687

688 - `"deny"`

689

690 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`

691

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

693

694 - `session_thread_id: optional string or null`

695

696 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.

697

698 - `BetaManagedAgentsAgentToolResultEvent object`

699

700 Event representing the result of an agent tool execution.

701

702 - `type: "agent.tool_result"`

703

704 - `id: string`

705

706 Unique identifier for this event.

707

708 - `processed_at: string`

709

710 A timestamp in RFC 3339 format

711

712 format: date-time

713

714 - `tool_use_id: string`

715

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

717

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

719

720 The result content returned by the tool.

721

722 - `BetaManagedAgentsTextBlock object`

723

724 Regular text content.

725

726 - `BetaManagedAgentsImageBlock object`

727

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

729

730 - `BetaManagedAgentsDocumentBlock object`

731

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

733

734 - `BetaManagedAgentsSearchResultBlock object`

735

736 A block containing a web search result.

737

738 - `is_error: optional boolean or null`

739

740 Whether the tool execution resulted in an error.

741

742 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`

743

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

745

746 - `type: "agent.thread_message_received"`

747

748 - `id: string`

749

750 Unique identifier for this event.

751

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

753

754 Message content blocks.

755

756 - `BetaManagedAgentsTextBlock object`

757

758 Regular text content.

759

760 - `BetaManagedAgentsImageBlock object`

761

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

763

764 - `BetaManagedAgentsDocumentBlock object`

765

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

767

768 - `BetaManagedAgentsRedactedBlock object`

769

770 Placeholder for content withheld by Anthropic model policy.

771

772 - `from_session_thread_id: string`

773

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

775

776 - `processed_at: string`

777

778 A timestamp in RFC 3339 format

779

780 format: date-time

781

782 - `from_agent_name: optional string or null`

783

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

785

786 - `BetaManagedAgentsAgentThreadMessageSentEvent object`

787

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

789

790 - `type: "agent.thread_message_sent"`

791

792 - `id: string`

793

794 Unique identifier for this event.

795

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

797

798 Message content blocks.

799

800 - `BetaManagedAgentsTextBlock object`

801

802 Regular text content.

803

804 - `BetaManagedAgentsImageBlock object`

805

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

807

808 - `BetaManagedAgentsDocumentBlock object`

809

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

811

812 - `BetaManagedAgentsRedactedBlock object`

813

814 Placeholder for content withheld by Anthropic model policy.

815

816 - `processed_at: string`

817

818 A timestamp in RFC 3339 format

819

820 format: date-time

821

822 - `to_session_thread_id: string`

823

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

825

826 - `to_agent_name: optional string or null`

827

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

829

830 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`

831

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

833

834 - `type: "agent.thread_context_compacted"`

835

836 - `id: string`

837

838 Unique identifier for this event.

839

840 - `processed_at: string`

841

842 A timestamp in RFC 3339 format

843

844 format: date-time

845

846 - `BetaManagedAgentsSessionErrorEvent object`

847

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

849

850 - `type: "session.error"`

851

852 - `id: string`

853

854 Unique identifier for this event.

855

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

857

858 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.

859

860 - `BetaManagedAgentsUnknownError object`

861

862 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.

863

864 - `type: "unknown_error"`

865

866 - `message: string`

867

868 Human-readable error description.

869

870 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

871

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

873

874 - `BetaManagedAgentsRetryStatusRetrying object`

875

876 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.

877

878 - `type: "retrying"`

879

880 - `BetaManagedAgentsRetryStatusExhausted object`

881

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

883

884 - `type: "exhausted"`

885

886 - `BetaManagedAgentsRetryStatusTerminal object`

887

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

889

890 - `type: "terminal"`

891

892 - `BetaManagedAgentsModelOverloadedError object`

893

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

895

896 - `type: "model_overloaded_error"`

897

898 - `message: string`

899

900 Human-readable error description.

901

902 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

903

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

905

906 - `BetaManagedAgentsRetryStatusRetrying object`

907

908 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.

909

910 - `BetaManagedAgentsRetryStatusExhausted object`

911

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

913

914 - `BetaManagedAgentsRetryStatusTerminal object`

915

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

917

918 - `BetaManagedAgentsModelRateLimitedError object`

919

920 The model request was rate-limited.

921

922 - `type: "model_rate_limited_error"`

923

924 - `message: string`

925

926 Human-readable error description.

927

928 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

929

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

931

932 - `BetaManagedAgentsRetryStatusRetrying object`

933

934 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.

935

936 - `BetaManagedAgentsRetryStatusExhausted object`

937

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

939

940 - `BetaManagedAgentsRetryStatusTerminal object`

941

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

943

944 - `BetaManagedAgentsModelRequestFailedError object`

945

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

947

948 - `type: "model_request_failed_error"`

949

950 - `message: string`

951

952 Human-readable error description.

953

954 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

955

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

957

958 - `BetaManagedAgentsRetryStatusRetrying object`

959

960 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.

961

962 - `BetaManagedAgentsRetryStatusExhausted object`

963

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

965

966 - `BetaManagedAgentsRetryStatusTerminal object`

967

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

969

970 - `BetaManagedAgentsMCPConnectionFailedError object`

971

972 Failed to connect to an MCP server.

973

974 - `type: "mcp_connection_failed_error"`

975

976 - `mcp_server_name: string`

977

978 Name of the MCP server that failed to connect.

979

980 - `message: string`

981

982 Human-readable error description.

983

984 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

985

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

987

988 - `BetaManagedAgentsRetryStatusRetrying object`

989

990 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.

991

992 - `BetaManagedAgentsRetryStatusExhausted object`

993

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

995

996 - `BetaManagedAgentsRetryStatusTerminal object`

997

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

999

1000 - `BetaManagedAgentsMCPAuthenticationFailedError object`

1001

1002 Authentication to an MCP server failed.

1003

1004 - `type: "mcp_authentication_failed_error"`

1005

1006 - `mcp_server_name: string`

1007

1008 Name of the MCP server that failed authentication.

1009

1010 - `message: string`

1011

1012 Human-readable error description.

1013

1014 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1015

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

1017

1018 - `BetaManagedAgentsRetryStatusRetrying object`

1019

1020 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.

1021

1022 - `BetaManagedAgentsRetryStatusExhausted object`

1023

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

1025

1026 - `BetaManagedAgentsRetryStatusTerminal object`

1027

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

1029

1030 - `BetaManagedAgentsBillingError object`

1031

1032 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.

1033

1034 - `type: "billing_error"`

1035

1036 - `message: string`

1037

1038 Human-readable error description.

1039

1040 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1041

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

1043

1044 - `BetaManagedAgentsRetryStatusRetrying object`

1045

1046 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.

1047

1048 - `BetaManagedAgentsRetryStatusExhausted object`

1049

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

1051

1052 - `BetaManagedAgentsRetryStatusTerminal object`

1053

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

1055

1056 - `BetaManagedAgentsCredentialHostUnreachableError object`

1057

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

1059

1060 - `type: "credential_host_unreachable_error"`

1061

1062 - `credential_id: string`

1063

1064 ID of the affected credential.

1065

1066 - `message: string`

1067

1068 Human-readable error description.

1069

1070 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1071

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

1073

1074 - `BetaManagedAgentsRetryStatusRetrying object`

1075

1076 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.

1077

1078 - `BetaManagedAgentsRetryStatusExhausted object`

1079

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

1081

1082 - `BetaManagedAgentsRetryStatusTerminal object`

1083

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

1085

1086 - `vault_id: string`

1087

1088 ID of the vault containing the affected credential.

1089

1090 - `processed_at: string`

1091

1092 A timestamp in RFC 3339 format

1093

1094 format: date-time

1095

1096 - `BetaManagedAgentsSessionStatusRescheduledEvent object`

1097

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

1099

1100 - `type: "session.status_rescheduled"`

1101

1102 - `id: string`

1103

1104 Unique identifier for this event.

1105

1106 - `processed_at: string`

1107

1108 A timestamp in RFC 3339 format

1109

1110 format: date-time

1111

1112 - `BetaManagedAgentsSessionStatusRunningEvent object`

1113

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

1115

1116 - `type: "session.status_running"`

1117

1118 - `id: string`

1119

1120 Unique identifier for this event.

1121

1122 - `processed_at: string`

1123

1124 A timestamp in RFC 3339 format

1125

1126 format: date-time

1127

1128 - `BetaManagedAgentsSessionStatusIdleEvent object`

1129

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

1131

1132 - `type: "session.status_idle"`

1133

1134 - `id: string`

1135

1136 Unique identifier for this event.

1137

1138 - `processed_at: string`

1139

1140 A timestamp in RFC 3339 format

1141

1142 format: date-time

1143

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

1145

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

1147

1148 - `BetaManagedAgentsSessionEndTurn object`

1149

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

1151

1152 - `type: "end_turn"`

1153

1154 - `BetaManagedAgentsSessionRequiresAction object`

1155

1156 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.

1157

1158 - `type: "requires_action"`

1159

1160 - `event_ids: array of string`

1161

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

1163

1164 - `BetaManagedAgentsSessionRetriesExhausted object`

1165

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

1167

1168 - `type: "retries_exhausted"`

1169

1170 - `BetaManagedAgentsSessionBudgetReached object`

1171

1172 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.

1173

1174 - `type: "budget_reached"`

1175

1176 - `BetaManagedAgentsSessionStatusTerminatedEvent object`

1177

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

1179

1180 - `type: "session.status_terminated"`

1181

1182 - `id: string`

1183

1184 Unique identifier for this event.

1185

1186 - `processed_at: string`

1187

1188 A timestamp in RFC 3339 format

1189

1190 format: date-time

1191

1192 - `BetaManagedAgentsSessionThreadCreatedEvent object`

1193

1194 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.

1195

1196 - `type: "session.thread_created"`

1197

1198 - `id: string`

1199

1200 Unique identifier for this event.

1201

1202 - `agent_name: string`

1203

1204 Name of the callable agent the thread runs.

1205

1206 - `processed_at: string`

1207

1208 A timestamp in RFC 3339 format

1209

1210 format: date-time

1211

1212 - `session_thread_id: string`

1213

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

1215

1216 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`

1217

1218 Emitted when an outcome evaluation cycle begins.

1219

1220 - `type: "span.outcome_evaluation_start"`

1221

1222 - `id: string`

1223

1224 Unique identifier for this event.

1225

1226 - `iteration: number`

1227

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

1229

1230 format: int32

1231

1232 - `outcome_id: string`

1233

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

1235

1236 - `processed_at: string`

1237

1238 A timestamp in RFC 3339 format

1239

1240 format: date-time

1241

1242 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`

1243

1244 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.

1245

1246 - `type: "span.outcome_evaluation_end"`

1247

1248 - `id: string`

1249

1250 Unique identifier for this event.

1251

1252 - `explanation: string`

1253

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

1255

1256 - `iteration: number`

1257

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

1259

1260 format: int32

1261

1262 - `outcome_evaluation_start_id: string`

1263

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

1265

1266 - `outcome_id: string`

1267

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

1269

1270 - `processed_at: string`

1271

1272 A timestamp in RFC 3339 format

1273

1274 format: date-time

1275

1276 - `result: string`

1277

1278 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.

1279

1280 - `usage: BetaManagedAgentsSpanModelUsage`

1281

1282 Token usage for a single model request.

1283

1284 - `cache_creation_input_tokens: number`

1285

1286 Tokens used to create prompt cache in this request.

1287

1288 format: int32

1289

1290 - `cache_read_input_tokens: number`

1291

1292 Tokens read from prompt cache in this request.

1293

1294 format: int32

1295

1296 - `input_tokens: number`

1297

1298 Input tokens consumed by this request.

1299

1300 format: int32

1301

1302 - `output_tokens: number`

1303

1304 Output tokens generated by this request.

1305

1306 format: int32

1307

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

1309

1310 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.

1311

1312 - `"standard"`

1313

1314 - `"fast"`

1315

1316 - `BetaManagedAgentsSpanModelRequestStartEvent object`

1317

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

1319

1320 - `type: "span.model_request_start"`

1321

1322 - `id: string`

1323

1324 Unique identifier for this event.

1325

1326 - `processed_at: string`

1327

1328 A timestamp in RFC 3339 format

1329

1330 format: date-time

1331

1332 - `BetaManagedAgentsSpanModelRequestEndEvent object`

1333

1334 Emitted when a model request completes.

1335

1336 - `type: "span.model_request_end"`

1337

1338 - `id: string`

1339

1340 Unique identifier for this event.

1341

1342 - `is_error: boolean or null`

1343

1344 Whether the model request resulted in an error.

1345

1346 - `model_request_start_id: string`

1347

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

1349

1350 - `model_usage: BetaManagedAgentsSpanModelUsage`

1351

1352 Token usage for a single model request.

1353

1354 - `processed_at: string`

1355

1356 A timestamp in RFC 3339 format

1357

1358 format: date-time

1359

1360 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`

1361

1362 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.

1363

1364 - `type: "span.outcome_evaluation_ongoing"`

1365

1366 - `id: string`

1367

1368 Unique identifier for this event.

1369

1370 - `iteration: number`

1371

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

1373

1374 format: int32

1375

1376 - `outcome_id: string`

1377

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

1379

1380 - `processed_at: string`

1381

1382 A timestamp in RFC 3339 format

1383

1384 format: date-time

1385

1386 - `BetaManagedAgentsUserDefineOutcomeEvent object`

1387

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

1389

1390 - `type: "user.define_outcome"`

1391

1392 - `id: string`

1393

1394 Unique identifier for this event.

1395

1396 - `description: string`

1397

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

1399

1400 - `max_iterations: number or null`

1401

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

1403

1404 format: int32

1405

1406 - `outcome_id: string`

1407

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

1409

1410 - `processed_at: string`

1411

1412 A timestamp in RFC 3339 format

1413

1414 format: date-time

1415

1416 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`

1417

1418 Rubric for grading the quality of an outcome.

1419

1420 - `BetaManagedAgentsFileRubric object`

1421

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

1423

1424 - `type: "file"`

1425

1426 - `file_id: string`

1427

1428 ID of the rubric file.

1429

1430 - `BetaManagedAgentsTextRubric object`

1431

1432 Rubric content provided inline as text.

1433

1491434 - `type: "text"`

1501435

1436 - `content: string`

1437

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

1439

1440 - `BetaManagedAgentsSessionDeletedEvent object`

1441

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

1443

1444 - `type: "session.deleted"`

1445

1446 - `id: string`

1447

1448 Unique identifier for this event.

1449

1450 - `processed_at: string`

1451

1452 A timestamp in RFC 3339 format

1453

1454 format: date-time

1455

1456 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`

1457

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

1459

1460 - `type: "session.thread_status_running"`

1461

1462 - `id: string`

1463

1464 Unique identifier for this event.

1465

1466 - `agent_name: string`

1467

1468 Name of the agent the thread runs.

1469

1470 - `processed_at: string`

1471

1472 A timestamp in RFC 3339 format

1473

1474 format: date-time

1475

1476 - `session_thread_id: string`

1477

1478 Public sthr_ ID of the thread that started running.

1479

1480 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`

1481

1482 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.

1483

1484 - `type: "session.thread_status_idle"`

1485

1486 - `id: string`

1487

1488 Unique identifier for this event.

1489

1490 - `agent_name: string`

1491

1492 Name of the agent the thread runs.

1493

1494 - `processed_at: string`

1495

1496 A timestamp in RFC 3339 format

1497

1498 format: date-time

1499

1500 - `session_thread_id: string`

1501

1502 Public sthr_ ID of the thread that went idle.

1503

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

1505

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

1507

1508 - `BetaManagedAgentsSessionEndTurn object`

1509

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

1511

1512 - `BetaManagedAgentsSessionRequiresAction object`

1513

1514 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.

1515

1516 - `BetaManagedAgentsSessionRetriesExhausted object`

1517

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

1519

1520 - `BetaManagedAgentsSessionBudgetReached object`

1521

1522 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.

1523

1524 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`

1525

1526 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.

1527

1528 - `type: "session.thread_status_terminated"`

1529

1530 - `id: string`

1531

1532 Unique identifier for this event.

1533

1534 - `agent_name: string`

1535

1536 Name of the agent the thread runs.

1537

1538 - `processed_at: string`

1539

1540 A timestamp in RFC 3339 format

1541

1542 format: date-time

1543

1544 - `session_thread_id: string`

1545

1546 Public sthr_ ID of the thread that terminated.

1547

1548 - `BetaManagedAgentsUserToolResultEvent object`

1549

1550 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.

1551

1552 - `type: "user.tool_result"`

1553

1554 - `id: string`

1555

1556 Unique identifier for this event.

1557

1558 - `tool_use_id: string`

1559

1560 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.

1561

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

1563

1564 The result content returned by the tool.

1565

1566 - `BetaManagedAgentsTextBlock object`

1567

1568 Regular text content.

1569

1511570 - `BetaManagedAgentsImageBlock object`

1521571

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

1541573

155 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

156

157 Union type for image source variants.

158

159 - `BetaManagedAgentsBase64ImageSource object`

160

161 Base64-encoded image data.

162

163 - `data: string`

164

165 Base64-encoded image data.

166

167 minLength: 1

168

169 - `media_type: string`

170

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

172

173 minLength: 1

174

175 - `type: "base64"`

176

177 - `BetaManagedAgentsURLImageSource object`

178

179 Image referenced by URL.

180

181 - `type: "url"`

182

183 - `url: string`

184

185 URL of the image to fetch.

186

187 minLength: 1

188

189 - `BetaManagedAgentsFileImageSource object`

190

191 Image referenced by file ID.

192

193 - `file_id: string`

194

195 ID of a previously uploaded file.

196

197 minLength: 1

198

199 - `type: "file"`

200

201 - `type: "image"`

202

2031574 - `BetaManagedAgentsDocumentBlock object`

2041575

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

2061577

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

208

209 Union type for document source variants.

210

211 - `BetaManagedAgentsBase64DocumentSource object`

212

213 Base64-encoded document data.

214

215 - `data: string`

216

217 Base64-encoded document data.

218

219 minLength: 1

220

221 - `media_type: string`

222

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

224

225 minLength: 1

226

227 - `type: "base64"`

228

229 - `BetaManagedAgentsPlainTextDocumentSource object`

230

231 Plain text document content.

232

233 - `data: string`

234

235 The plain text content.

236

237 minLength: 1

238

239 - `media_type: "text/plain"`

240

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

242

243 - `type: "text"`

244

245 - `BetaManagedAgentsURLDocumentSource object`

246

247 Document referenced by URL.

248

249 - `type: "url"`

250

251 - `url: string`

252

253 URL of the document to fetch.

254

255 minLength: 1

256

257 - `BetaManagedAgentsFileDocumentSource object`

258

259 Document referenced by file ID.

260

261 - `file_id: string`

262

263 ID of a previously uploaded file.

264

265 minLength: 1

266

267 - `type: "file"`

268

269 - `type: "document"`

270

271 - `context: optional string or null`

272

273 Additional context about the document for the model.

274

275 - `title: optional string or null`

276

277 The title of the document.

278

279 - `BetaManagedAgentsRedactedBlock object`

280

281 Placeholder for content withheld by Anthropic model policy.

282

283 - `type: "redacted"`

284

285 - `type: "user.message"`

1578 - `BetaManagedAgentsSearchResultBlock object`

1579

1580 A block containing a web search result.

1581

1582 - `is_error: optional boolean or null`

1583

1584 Whether the tool execution resulted in an error.

2861585

2871586 - `processed_at: optional string or null`

2881587

from line 1589

2901589

2911590 format: date-time

2921591

293 - `BetaManagedAgentsUserInterruptEvent object`

294

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

296

297 - `id: string`

298

299 Unique identifier for this event.

300

301 - `type: "user.interrupt"`

1592 - `session_thread_id: optional string or null`

1593

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

1595

1596 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`

1597

1598 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.

1599

1600 - `type: "session.thread_status_rescheduled"`

1601

1602 - `id: string`

1603

1604 Unique identifier for this event.

1605

1606 - `agent_name: string`

1607

1608 Name of the agent the thread runs.

1609

1610 - `processed_at: string`

1611

1612 A timestamp in RFC 3339 format

1613

1614 format: date-time

1615

1616 - `session_thread_id: string`

1617

1618 Public sthr_ ID of the thread that is retrying.

1619

1620 - `BetaManagedAgentsSessionUpdatedEvent object`

1621

1622 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.

1623

1624 - `type: "session.updated"`

1625

1626 - `id: string`

1627

1628 Unique identifier for this event.

1629

1630 - `processed_at: string`

1631

1632 A timestamp in RFC 3339 format

1633

1634 format: date-time

1635

1636 - `agent: optional BetaManagedAgentsSessionAgent or null`

1637

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

1639

1640 - `type: "agent"`

1641

1642 - `id: string`

1643

1644 - `description: string or null`

1645

1646 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1647

1648 - `type: "url"`

1649

1650 - `name: string`

1651

1652 - `url: string`

1653

1654 - `model: BetaManagedAgentsModelConfig`

1655

1656 Model identifier and configuration.

1657

1658 - `id: BetaManagedAgentsModel`

1659

1660 The model that will power your agent.

1661

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

1663

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

1665

1666 The model that will power your agent.

1667

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

1669

1670 - `"claude-fable-5-1"`

1671

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

1673

1674 - `"claude-sonnet-5"`

1675

1676 High-performance model for coding and agents

1677

1678 - `"claude-fable-5"`

1679

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

1681

1682 - `"claude-opus-5"`

1683

1684 Powerful intelligence for long-running agents and coding

1685

1686 - `"claude-opus-4-8"`

1687

1688 Powerful intelligence for long-running agents and coding

1689

1690 - `"claude-opus-4-7"`

1691

1692 Powerful intelligence for long-running agents and coding

1693

1694 - `"claude-opus-4-6"`

1695

1696 Powerful intelligence for long-running agents and coding

1697

1698 - `"claude-sonnet-4-6"`

1699

1700 Best combination of speed and intelligence

1701

1702 - `"claude-haiku-4-5"`

1703

1704 Fastest model with near-frontier intelligence

1705

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

1707

1708 Fastest model with near-frontier intelligence

1709

1710 - `"claude-opus-4-5"`

1711

1712 Powerful intelligence for long-running agents and coding

1713

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

1715

1716 Powerful intelligence for long-running agents and coding

1717

1718 - `"claude-sonnet-4-5"`

1719

1720 High-performance model for agents and coding

1721

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

1723

1724 High-performance model for agents and coding

1725

1726 - `string`

1727

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

1729

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

1731

1732 - `BetaManagedAgentsEffortLow object`

1733

1734 Low effort. Favors latency over reasoning depth.

1735

1736 - `type: "low"`

1737

1738 - `BetaManagedAgentsEffortMedium object`

1739

1740 Medium effort. Balances latency and reasoning depth.

1741

1742 - `type: "medium"`

1743

1744 - `BetaManagedAgentsEffortHigh object`

1745

1746 High effort. Favors reasoning depth.

1747

1748 - `type: "high"`

1749

1750 - `BetaManagedAgentsEffortXhigh object`

1751

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

1753

1754 - `type: "xhigh"`

1755

1756 - `BetaManagedAgentsEffortMax object`

1757

1758 Maximum effort. Favors reasoning depth over latency.

1759

1760 - `type: "max"`

1761

1762 - `inference_geo: optional string`

1763

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

1765

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

1767

1768 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.

1769

1770 - `"standard"`

1771

1772 - `"fast"`

1773

1774 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`

1775

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

1777

1778 - `type: "coordinator"`

1779

1780 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`

1781

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

1783

1784 - `BetaManagedAgentsSessionThreadAgent object`

1785

1786 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`.

1787

1788 - `type: "agent"`

1789

1790 - `id: string`

1791

1792 - `description: string or null`

1793

1794 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1795

1796 - `type: "url"`

1797

1798 - `name: string`

1799

1800 - `url: string`

1801

1802 - `model: BetaManagedAgentsModelConfig`

1803

1804 Model identifier and configuration.

1805

1806 - `name: string`

1807

1808 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

1809

1810 - `BetaManagedAgentsAnthropicSkill object`

1811

1812 A resolved Anthropic-managed skill.

1813

1814 - `type: "anthropic"`

1815

1816 - `skill_id: string`

1817

1818 - `version: string`

1819

1820 - `BetaManagedAgentsCustomSkill object`

1821

1822 A resolved user-created custom skill.

1823

1824 - `type: "custom"`

1825

1826 - `skill_id: string`

1827

1828 - `version: string`

1829

1830 - `system: string or null`

1831

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

1833

1834 - `BetaManagedAgentsAgentToolset20260401 object`

1835

1836 - `type: "agent_toolset_20260401"`

1837

1838 - `configs: array of BetaManagedAgentsAgentToolConfig`

1839

1840 - `BetaManagedAgentsBashToolConfig object`

1841

1842 Configuration for the bash tool.

1843

1844 - `type: "bash"`

1845

1846 - `enabled: boolean`

1847

1848 - `name: "bash"`

1849

1850 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1851

1852 Permission policy for tool execution.

1853

1854 - `BetaManagedAgentsAlwaysAllowPolicy object`

1855

1856 Tool calls are automatically approved without user confirmation.

1857

1858 - `type: "always_allow"`

1859

1860 - `BetaManagedAgentsAlwaysAskPolicy object`

1861

1862 Tool calls require user confirmation before execution.

1863

1864 - `type: "always_ask"`

1865

1866 - `BetaManagedAgentsAutoPolicy object`

1867

1868 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.

1869

1870 - `type: "auto"`

1871

1872 - `BetaManagedAgentsEditToolConfig object`

1873

1874 Configuration for the edit tool.

1875

1876 - `type: "edit"`

1877

1878 - `enabled: boolean`

1879

1880 - `name: "edit"`

1881

1882 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1883

1884 Permission policy for tool execution.

1885

1886 - `BetaManagedAgentsAlwaysAllowPolicy object`

1887

1888 Tool calls are automatically approved without user confirmation.

1889

1890 - `BetaManagedAgentsAlwaysAskPolicy object`

1891

1892 Tool calls require user confirmation before execution.

1893

1894 - `BetaManagedAgentsAutoPolicy object`

1895

1896 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.

1897

1898 - `BetaManagedAgentsReadToolConfig object`

1899

1900 Configuration for the read tool.

1901

1902 - `type: "read"`

1903

1904 - `enabled: boolean`

1905

1906 - `name: "read"`

1907

1908 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1909

1910 Permission policy for tool execution.

1911

1912 - `BetaManagedAgentsAlwaysAllowPolicy object`

1913

1914 Tool calls are automatically approved without user confirmation.

1915

1916 - `BetaManagedAgentsAlwaysAskPolicy object`

1917

1918 Tool calls require user confirmation before execution.

1919

1920 - `BetaManagedAgentsAutoPolicy object`

1921

1922 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.

1923

1924 - `BetaManagedAgentsWriteToolConfig object`

1925

1926 Configuration for the write tool.

1927

1928 - `type: "write"`

1929

1930 - `enabled: boolean`

1931

1932 - `name: "write"`

1933

1934 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1935

1936 Permission policy for tool execution.

1937

1938 - `BetaManagedAgentsAlwaysAllowPolicy object`

1939

1940 Tool calls are automatically approved without user confirmation.

1941

1942 - `BetaManagedAgentsAlwaysAskPolicy object`

1943

1944 Tool calls require user confirmation before execution.

1945

1946 - `BetaManagedAgentsAutoPolicy object`

1947

1948 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.

1949

1950 - `BetaManagedAgentsGlobToolConfig object`

1951

1952 Configuration for the glob tool.

1953

1954 - `type: "glob"`

1955

1956 - `enabled: boolean`

1957

1958 - `name: "glob"`

1959

1960 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1961

1962 Permission policy for tool execution.

1963

1964 - `BetaManagedAgentsAlwaysAllowPolicy object`

1965

1966 Tool calls are automatically approved without user confirmation.

1967

1968 - `BetaManagedAgentsAlwaysAskPolicy object`

1969

1970 Tool calls require user confirmation before execution.

1971

1972 - `BetaManagedAgentsAutoPolicy object`

1973

1974 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.

1975

1976 - `BetaManagedAgentsGrepToolConfig object`

1977

1978 Configuration for the grep tool.

1979

1980 - `type: "grep"`

1981

1982 - `enabled: boolean`

1983

1984 - `name: "grep"`

1985

1986 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1987

1988 Permission policy for tool execution.

1989

1990 - `BetaManagedAgentsAlwaysAllowPolicy object`

1991

1992 Tool calls are automatically approved without user confirmation.

1993

1994 - `BetaManagedAgentsAlwaysAskPolicy object`

1995

1996 Tool calls require user confirmation before execution.

1997

1998 - `BetaManagedAgentsAutoPolicy object`

1999

2000 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.

2001

2002 - `BetaManagedAgentsWebFetchToolConfig object`

2003

2004 Configuration for the web_fetch tool.

2005

2006 - `type: "web_fetch"`

2007

2008 - `enabled: boolean`

2009

2010 - `name: "web_fetch"`

2011

2012 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2013

2014 Permission policy for tool execution.

2015

2016 - `BetaManagedAgentsAlwaysAllowPolicy object`

2017

2018 Tool calls are automatically approved without user confirmation.

2019

2020 - `BetaManagedAgentsAlwaysAskPolicy object`

2021

2022 Tool calls require user confirmation before execution.

2023

2024 - `BetaManagedAgentsAutoPolicy object`

2025

2026 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.

2027

2028 - `allowed_domains: optional array of string`

2029

2030 - `blocked_domains: optional array of string`

2031

2032 - `max_content_tokens: optional number or null`

2033

2034 format: int32

2035

2036 - `BetaManagedAgentsWebSearchToolConfig object`

2037

2038 Configuration for the web_search tool.

2039

2040 - `type: "web_search"`

2041

2042 - `enabled: boolean`

2043

2044 - `name: "web_search"`

2045

2046 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2047

2048 Permission policy for tool execution.

2049

2050 - `BetaManagedAgentsAlwaysAllowPolicy object`

2051

2052 Tool calls are automatically approved without user confirmation.

2053

2054 - `BetaManagedAgentsAlwaysAskPolicy object`

2055

2056 Tool calls require user confirmation before execution.

2057

2058 - `BetaManagedAgentsAutoPolicy object`

2059

2060 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.

2061

2062 - `allowed_domains: optional array of string`

2063

2064 - `blocked_domains: optional array of string`

2065

2066 - `user_location: optional BetaManagedAgentsUserLocation or null`

2067

2068 Approximate user location for search result localization.

2069

2070 - `type: "approximate"`

2071

2072 Location precision. Only "approximate" is supported.

2073

2074 - `city: optional string or null`

2075

2076 City name.

2077

2078 minLength: 1, maxLength: 255

2079

2080 - `country: optional string or null`

2081

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

2083

2084 - `region: optional string or null`

2085

2086 Region or state name.

2087

2088 minLength: 1, maxLength: 255

2089

2090 - `timezone: optional string or null`

2091

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

2093

2094 minLength: 1, maxLength: 255

2095

2096 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`

2097

2098 Resolved default configuration for agent tools.

2099

2100 - `enabled: boolean`

2101

2102 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2103

2104 Permission policy for tool execution.

2105

2106 - `BetaManagedAgentsAlwaysAllowPolicy object`

2107

2108 Tool calls are automatically approved without user confirmation.

2109

2110 - `BetaManagedAgentsAlwaysAskPolicy object`

2111

2112 Tool calls require user confirmation before execution.

2113

2114 - `BetaManagedAgentsAutoPolicy object`

2115

2116 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.

2117

2118 - `BetaManagedAgentsMCPToolset object`

2119

2120 - `type: "mcp_toolset"`

2121

2122 - `configs: array of BetaManagedAgentsMCPToolConfig`

2123

2124 - `enabled: boolean`

2125

2126 - `name: string`

2127

2128 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2129

2130 Permission policy for tool execution.

2131

2132 - `BetaManagedAgentsAlwaysAllowPolicy object`

2133

2134 Tool calls are automatically approved without user confirmation.

2135

2136 - `BetaManagedAgentsAlwaysAskPolicy object`

2137

2138 Tool calls require user confirmation before execution.

2139

2140 - `BetaManagedAgentsAutoPolicy object`

2141

2142 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.

2143

2144 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

2145

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

2147

2148 - `enabled: boolean`

2149

2150 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2151

2152 Permission policy for tool execution.

2153

2154 - `BetaManagedAgentsAlwaysAllowPolicy object`

2155

2156 Tool calls are automatically approved without user confirmation.

2157

2158 - `BetaManagedAgentsAlwaysAskPolicy object`

2159

2160 Tool calls require user confirmation before execution.

2161

2162 - `BetaManagedAgentsAutoPolicy object`

2163

2164 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.

2165

2166 - `mcp_server_name: string`

2167

2168 - `BetaManagedAgentsCustomTool object`

2169

2170 A custom tool as returned in API responses.

2171

2172 - `type: "custom"`

2173

2174 - `description: string`

2175

2176 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

2177

2178 JSON Schema for custom tool input parameters.

2179

2180 - `type: "object"`

2181

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

2183

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

2185

2186 - `name: string`

2187

2188 - `version: number`

2189

2190 format: int32

2191

2192 - `BetaManagedAgentsAdvisor object`

2193

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

2195

2196 - `type: "advisor"`

2197

2198 - `model: string`

2199

2200 The advisor model id.

2201

2202 - `name: string`

2203

2204 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

2205

2206 - `BetaManagedAgentsAnthropicSkill object`

2207

2208 A resolved Anthropic-managed skill.

2209

2210 - `BetaManagedAgentsCustomSkill object`

2211

2212 A resolved user-created custom skill.

2213

2214 - `system: string or null`

2215

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

2217

2218 - `BetaManagedAgentsAgentToolset20260401 object`

2219

2220 - `BetaManagedAgentsMCPToolset object`

2221

2222 - `BetaManagedAgentsCustomTool object`

2223

2224 A custom tool as returned in API responses.

2225

2226 - `version: number`

2227

2228 format: int32

2229

2230 - `budget: optional BetaManagedAgentsBudgetLimit or null`

2231

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

2233

2234 - `type: "limit"`

2235

2236 - `max_list_cost: BetaMonetaryAmount`

2237

2238 A monetary amount in a specific currency.

2239

2240 - `amount: string`

2241

2242 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.

2243

2244 - `currency: BetaCurrency`

2245

2246 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.

2247

2248 - `metadata: optional map[string]`

2249

2250 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.

2251

2252 - `title: optional string or null`

2253

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

2255

2256 - `BetaManagedAgentsStartEvent object`

2257

2258 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.

2259

2260 - `type: "event_start"`

2261

2262 - `event: BetaManagedAgentsStartEventPreview`

2263

2264 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.

2265

2266 - `BetaManagedAgentsAgentMessagePreview object`

2267

2268 - `type: "agent.message"`

2269

2270 - `id: string`

2271

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

2273

2274 - `BetaManagedAgentsAgentThinkingPreview object`

2275

2276 - `type: "agent.thinking"`

2277

2278 - `id: string`

2279

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

2281

2282 - `BetaManagedAgentsDeltaEvent object`

2283

2284 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.

2285

2286 - `type: "event_delta"`

2287

2288 - `delta: BetaManagedAgentsDeltaContent`

2289

2290 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.

2291

2292 - `type: "content_delta"`

2293

2294 - `content: BetaManagedAgentsTextBlock`

2295

2296 Regular text content.

2297

2298 - `index: optional number`

2299

2300 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.

2301

2302 format: uint32

2303

2304 - `event_id: string`

2305

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

2307

2308 - `BetaManagedAgentsSystemMessageEvent object`

2309

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

2311

2312 - `type: "system.message"`

2313

2314 - `id: string`

2315

2316 Unique identifier for this event.

2317

2318 - `content: array of BetaManagedAgentsSystemContentBlock`

2319

2320 System content blocks. Text-only.

2321

2322 - `type: "text"`

2323

2324 - `text: string`

2325

2326 The text content.

2327

2328 minLength: 1

3022329

3032330 - `processed_at: optional string or null`

3042331

from line 2333

3062333

3072334 format: date-time

3082335

309 - `session_thread_id: optional string or null`

310

311 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.

312

313 - `BetaManagedAgentsUserToolConfirmationEvent object`

314

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

316

317 - `id: string`

318

319 Unique identifier for this event.

320

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

322

323 UserToolConfirmationResult enum

324

325 - `"allow"`

326

327 - `"deny"`

328

329 - `tool_use_id: string`

330

331 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.

332

333 - `type: "user.tool_confirmation"`

334

335 - `deny_message: optional string or null`

336

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

338

339 maxLength: 10000

340

341 - `processed_at: optional string or null`

342

343 A timestamp in RFC 3339 format

344

345 format: date-time

346

347 - `session_thread_id: optional string or null`

348

349 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.

350

351 - `BetaManagedAgentsUserCustomToolResultEvent object`

352

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

354

355 - `id: string`

356

357 Unique identifier for this event.

358

359 - `custom_tool_use_id: string`

360

361 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.

362

363 - `type: "user.custom_tool_result"`

364

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

366

367 The result content returned by the tool.

368

369 - `BetaManagedAgentsTextBlock object`

370

371 Regular text content.

372

373 - `BetaManagedAgentsImageBlock object`

374

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

376

377 - `BetaManagedAgentsDocumentBlock object`

378

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

380

381 - `BetaManagedAgentsSearchResultBlock object`

382

383 A block containing a web search result.

384

385 - `citations: BetaManagedAgentsSearchResultCitations`

386

387 Citation settings for a search result.

388

389 - `enabled: boolean`

390

391 Whether citations are enabled for this search result.

392

393 - `content: array of BetaManagedAgentsSearchResultContent`

394

395 Array of text content blocks from the search result.

396

397 - `text: string`

398

399 The text content.

400

401 minLength: 1

402

403 - `type: "text"`

404

405 - `source: string`

406

407 The URL source of the search result.

408

409 minLength: 1

410

411 - `title: string`

412

413 The title of the search result.

414

415 minLength: 1

416

417 - `type: "search_result"`

418

419 - `is_error: optional boolean or null`

420

421 Whether the tool execution resulted in an error.

422

423 - `processed_at: optional string or null`

424

425 A timestamp in RFC 3339 format

426

427 format: date-time

428

429 - `session_thread_id: optional string or null`

430

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

432

433 - `BetaManagedAgentsAgentCustomToolUseEvent object`

434

435 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.

436

437 - `id: string`

438

439 Unique identifier for this event.

440

441 - `input: map[unknown]`

442

443 Input parameters for the tool call.

444

445 - `name: string`

446

447 Name of the custom tool being called.

448

449 - `processed_at: string`

450

451 A timestamp in RFC 3339 format

452

453 format: date-time

454

455 - `type: "agent.custom_tool_use"`

456

457 - `session_thread_id: optional string or null`

458

459 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.

460

461 - `BetaManagedAgentsAgentMessageEvent object`

462

463 An agent response event in the session conversation.

464

465 - `id: string`

466

467 Unique identifier for this event.

468

469 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`

470

471 Array of text blocks comprising the agent response.

472

473 - `BetaManagedAgentsTextBlock object`

474

475 Regular text content.

476

477 - `BetaManagedAgentsRedactedBlock object`

478

479 Placeholder for content withheld by Anthropic model policy.

480

481 - `processed_at: string`

482

483 A timestamp in RFC 3339 format

484

485 format: date-time

486

487 - `type: "agent.message"`

488

489 - `BetaManagedAgentsAgentThinkingEvent object`

490

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

492

493 - `id: string`

494

495 Unique identifier for this event.

496

497 - `processed_at: string`

498

499 A timestamp in RFC 3339 format

500

501 format: date-time

502

503 - `type: "agent.thinking"`

504

505 - `BetaManagedAgentsAgentMCPToolUseEvent object`

506

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

508

509 - `id: string`

510

511 Unique identifier for this event.

512

513 - `input: map[unknown]`

514

515 Input parameters for the tool call.

516

517 - `mcp_server_name: string`

518

519 Name of the MCP server providing the tool.

520

521 - `name: string`

522

523 Name of the MCP tool being used.

524

525 - `processed_at: string`

526

527 A timestamp in RFC 3339 format

528

529 format: date-time

530

531 - `type: "agent.mcp_tool_use"`

532

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

534

535 AgentEvaluatedPermission enum

536

537 - `"allow"`

538

539 - `"ask"`

540

541 - `"deny"`

542

543 - `session_thread_id: optional string or null`

544

545 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.

546

547 - `BetaManagedAgentsAgentMCPToolResultEvent object`

548

549 Event representing the result of an MCP tool execution.

550

551 - `id: string`

552

553 Unique identifier for this event.

554

555 - `mcp_tool_use_id: string`

556

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

558

559 - `processed_at: string`

560

561 A timestamp in RFC 3339 format

562

563 format: date-time

564

565 - `type: "agent.mcp_tool_result"`

566

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

568

569 The result content returned by the tool.

570

571 - `BetaManagedAgentsTextBlock object`

572

573 Regular text content.

574

575 - `BetaManagedAgentsImageBlock object`

576

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

578

579 - `BetaManagedAgentsDocumentBlock object`

580

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

582

583 - `BetaManagedAgentsSearchResultBlock object`

584

585 A block containing a web search result.

586

587 - `is_error: optional boolean or null`

588

589 Whether the tool execution resulted in an error.

590

591 - `BetaManagedAgentsAgentToolUseEvent object`

592

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

594

595 - `id: string`

596

597 Unique identifier for this event.

598

599 - `input: map[unknown]`

600

601 Input parameters for the tool call.

602

603 - `name: string`

604

605 Name of the agent tool being used.

606

607 - `processed_at: string`

608

609 A timestamp in RFC 3339 format

610

611 format: date-time

612

613 - `type: "agent.tool_use"`

614

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

616

617 AgentEvaluatedPermission enum

618

619 - `"allow"`

620

621 - `"ask"`

622

623 - `"deny"`

624

625 - `session_thread_id: optional string or null`

626

627 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.

628

629 - `BetaManagedAgentsAgentToolResultEvent object`

630

631 Event representing the result of an agent tool execution.

632

633 - `id: string`

634

635 Unique identifier for this event.

636

637 - `processed_at: string`

638

639 A timestamp in RFC 3339 format

640

641 format: date-time

642

643 - `tool_use_id: string`

644

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

646

647 - `type: "agent.tool_result"`

648

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

650

651 The result content returned by the tool.

652

653 - `BetaManagedAgentsTextBlock object`

654

655 Regular text content.

656

657 - `BetaManagedAgentsImageBlock object`

658

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

660

661 - `BetaManagedAgentsDocumentBlock object`

662

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

664

665 - `BetaManagedAgentsSearchResultBlock object`

666

667 A block containing a web search result.

668

669 - `is_error: optional boolean or null`

670

671 Whether the tool execution resulted in an error.

672

673 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`

674

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

676

677 - `id: string`

678

679 Unique identifier for this event.

680

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

682

683 Message content blocks.

684

685 - `BetaManagedAgentsTextBlock object`

686

687 Regular text content.

688

689 - `BetaManagedAgentsImageBlock object`

690

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

692

693 - `BetaManagedAgentsDocumentBlock object`

694

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

696

697 - `BetaManagedAgentsRedactedBlock object`

698

699 Placeholder for content withheld by Anthropic model policy.

700

701 - `from_session_thread_id: string`

702

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

704

705 - `processed_at: string`

706

707 A timestamp in RFC 3339 format

708

709 format: date-time

710

711 - `type: "agent.thread_message_received"`

712

713 - `from_agent_name: optional string or null`

714

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

716

717 - `BetaManagedAgentsAgentThreadMessageSentEvent object`

718

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

720

721 - `id: string`

722

723 Unique identifier for this event.

724

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

726

727 Message content blocks.

728

729 - `BetaManagedAgentsTextBlock object`

730

731 Regular text content.

732

733 - `BetaManagedAgentsImageBlock object`

734

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

736

737 - `BetaManagedAgentsDocumentBlock object`

738

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

740

741 - `BetaManagedAgentsRedactedBlock object`

742

743 Placeholder for content withheld by Anthropic model policy.

744

745 - `processed_at: string`

746

747 A timestamp in RFC 3339 format

748

749 format: date-time

750

751 - `to_session_thread_id: string`

752

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

754

755 - `type: "agent.thread_message_sent"`

756

757 - `to_agent_name: optional string or null`

758

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

760

761 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`

762

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

764

765 - `id: string`

766

767 Unique identifier for this event.

768

769 - `processed_at: string`

770

771 A timestamp in RFC 3339 format

772

773 format: date-time

774

775 - `type: "agent.thread_context_compacted"`

776

777 - `BetaManagedAgentsSessionErrorEvent object`

778

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

780

781 - `id: string`

782

783 Unique identifier for this event.

784

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

786

787 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.

788

789 - `BetaManagedAgentsUnknownError object`

790

791 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.

792

793 - `message: string`

794

795 Human-readable error description.

796

797 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

798

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

800

801 - `BetaManagedAgentsRetryStatusRetrying object`

802

803 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.

804

805 - `type: "retrying"`

806

807 - `BetaManagedAgentsRetryStatusExhausted object`

808

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

810

811 - `type: "exhausted"`

812

813 - `BetaManagedAgentsRetryStatusTerminal object`

814

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

816

817 - `type: "terminal"`

818

819 - `type: "unknown_error"`

820

821 - `BetaManagedAgentsModelOverloadedError object`

822

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

824

825 - `message: string`

826

827 Human-readable error description.

828

829 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

830

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

832

833 - `BetaManagedAgentsRetryStatusRetrying object`

834

835 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.

836

837 - `BetaManagedAgentsRetryStatusExhausted object`

838

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

840

841 - `BetaManagedAgentsRetryStatusTerminal object`

842

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

844

845 - `type: "model_overloaded_error"`

846

847 - `BetaManagedAgentsModelRateLimitedError object`

848

849 The model request was rate-limited.

850

851 - `message: string`

852

853 Human-readable error description.

854

855 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

856

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

858

859 - `BetaManagedAgentsRetryStatusRetrying object`

860

861 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.

862

863 - `BetaManagedAgentsRetryStatusExhausted object`

864

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

866

867 - `BetaManagedAgentsRetryStatusTerminal object`

868

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

870

871 - `type: "model_rate_limited_error"`

872

873 - `BetaManagedAgentsModelRequestFailedError object`

874

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

876

877 - `message: string`

878

879 Human-readable error description.

880

881 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

882

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

884

885 - `BetaManagedAgentsRetryStatusRetrying object`

886

887 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.

888

889 - `BetaManagedAgentsRetryStatusExhausted object`

890

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

892

893 - `BetaManagedAgentsRetryStatusTerminal object`

894

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

896

897 - `type: "model_request_failed_error"`

898

899 - `BetaManagedAgentsMCPConnectionFailedError object`

900

901 Failed to connect to an MCP server.

902

903 - `mcp_server_name: string`

904

905 Name of the MCP server that failed to connect.

906

907 - `message: string`

908

909 Human-readable error description.

910

911 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

912

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

914

915 - `BetaManagedAgentsRetryStatusRetrying object`

916

917 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.

918

919 - `BetaManagedAgentsRetryStatusExhausted object`

920

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

922

923 - `BetaManagedAgentsRetryStatusTerminal object`

924

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

926

927 - `type: "mcp_connection_failed_error"`

928

929 - `BetaManagedAgentsMCPAuthenticationFailedError object`

930

931 Authentication to an MCP server failed.

932

933 - `mcp_server_name: string`

934

935 Name of the MCP server that failed authentication.

936

937 - `message: string`

938

939 Human-readable error description.

940

941 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

942

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

944

945 - `BetaManagedAgentsRetryStatusRetrying object`

946

947 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.

948

949 - `BetaManagedAgentsRetryStatusExhausted object`

950

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

952

953 - `BetaManagedAgentsRetryStatusTerminal object`

954

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

956

957 - `type: "mcp_authentication_failed_error"`

958

959 - `BetaManagedAgentsBillingError object`

960

961 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.

962

963 - `message: string`

964

965 Human-readable error description.

966

967 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

968

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

970

971 - `BetaManagedAgentsRetryStatusRetrying object`

972

973 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.

974

975 - `BetaManagedAgentsRetryStatusExhausted object`

976

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

978

979 - `BetaManagedAgentsRetryStatusTerminal object`

980

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

982

983 - `type: "billing_error"`

984

985 - `BetaManagedAgentsCredentialHostUnreachableError object`

986

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

988

989 - `credential_id: string`

990

991 ID of the affected credential.

992

993 - `message: string`

994

995 Human-readable error description.

996

997 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

998

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

1000

1001 - `BetaManagedAgentsRetryStatusRetrying object`

1002

1003 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.

1004

1005 - `BetaManagedAgentsRetryStatusExhausted object`

1006

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

1008

1009 - `BetaManagedAgentsRetryStatusTerminal object`

1010

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

1012

1013 - `type: "credential_host_unreachable_error"`

1014

1015 - `vault_id: string`

1016

1017 ID of the vault containing the affected credential.

1018

1019 - `processed_at: string`

1020

1021 A timestamp in RFC 3339 format

1022

1023 format: date-time

1024

1025 - `type: "session.error"`

1026

1027 - `BetaManagedAgentsSessionStatusRescheduledEvent object`

1028

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

1030

1031 - `id: string`

1032

1033 Unique identifier for this event.

1034

1035 - `processed_at: string`

1036

1037 A timestamp in RFC 3339 format

1038

1039 format: date-time

1040

1041 - `type: "session.status_rescheduled"`

1042

1043 - `BetaManagedAgentsSessionStatusRunningEvent object`

1044

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

1046

1047 - `id: string`

1048

1049 Unique identifier for this event.

1050

1051 - `processed_at: string`

1052

1053 A timestamp in RFC 3339 format

1054

1055 format: date-time

1056

1057 - `type: "session.status_running"`

1058

1059 - `BetaManagedAgentsSessionStatusIdleEvent object`

1060

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

1062

1063 - `id: string`

1064

1065 Unique identifier for this event.

1066

1067 - `processed_at: string`

1068

1069 A timestamp in RFC 3339 format

1070

1071 format: date-time

1072

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

1074

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

1076

1077 - `BetaManagedAgentsSessionEndTurn object`

1078

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

1080

1081 - `type: "end_turn"`

1082

1083 - `BetaManagedAgentsSessionRequiresAction object`

1084

1085 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.

1086

1087 - `event_ids: array of string`

1088

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

1090

1091 - `type: "requires_action"`

1092

1093 - `BetaManagedAgentsSessionRetriesExhausted object`

1094

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

1096

1097 - `type: "retries_exhausted"`

1098

1099 - `BetaManagedAgentsSessionBudgetReached object`

1100

1101 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.

1102

1103 - `type: "budget_reached"`

1104

1105 - `type: "session.status_idle"`

1106

1107 - `BetaManagedAgentsSessionStatusTerminatedEvent object`

1108

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

1110

1111 - `id: string`

1112

1113 Unique identifier for this event.

1114

1115 - `processed_at: string`

1116

1117 A timestamp in RFC 3339 format

1118

1119 format: date-time

1120

1121 - `type: "session.status_terminated"`

1122

1123 - `BetaManagedAgentsSessionThreadCreatedEvent object`

1124

1125 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.

1126

1127 - `id: string`

1128

1129 Unique identifier for this event.

1130

1131 - `agent_name: string`

1132

1133 Name of the callable agent the thread runs.

1134

1135 - `processed_at: string`

1136

1137 A timestamp in RFC 3339 format

1138

1139 format: date-time

1140

1141 - `session_thread_id: string`

1142

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

1144

1145 - `type: "session.thread_created"`

1146

1147 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`

1148

1149 Emitted when an outcome evaluation cycle begins.

1150

1151 - `id: string`

1152

1153 Unique identifier for this event.

1154

1155 - `iteration: number`

1156

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

1158

1159 format: int32

1160

1161 - `outcome_id: string`

1162

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

1164

1165 - `processed_at: string`

1166

1167 A timestamp in RFC 3339 format

1168

1169 format: date-time

1170

1171 - `type: "span.outcome_evaluation_start"`

1172

1173 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`

1174

1175 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.

1176

1177 - `id: string`

1178

1179 Unique identifier for this event.

1180

1181 - `explanation: string`

1182

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

1184

1185 - `iteration: number`

1186

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

1188

1189 format: int32

1190

1191 - `outcome_evaluation_start_id: string`

1192

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

1194

1195 - `outcome_id: string`

1196

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

1198

1199 - `processed_at: string`

1200

1201 A timestamp in RFC 3339 format

1202

1203 format: date-time

1204

1205 - `result: string`

1206

1207 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.

1208

1209 - `type: "span.outcome_evaluation_end"`

1210

1211 - `usage: BetaManagedAgentsSpanModelUsage`

1212

1213 Token usage for a single model request.

1214

1215 - `cache_creation_input_tokens: number`

1216

1217 Tokens used to create prompt cache in this request.

1218

1219 format: int32

1220

1221 - `cache_read_input_tokens: number`

1222

1223 Tokens read from prompt cache in this request.

1224

1225 format: int32

1226

1227 - `input_tokens: number`

1228

1229 Input tokens consumed by this request.

1230

1231 format: int32

1232

1233 - `output_tokens: number`

1234

1235 Output tokens generated by this request.

1236

1237 format: int32

1238

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

1240

1241 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.

1242

1243 - `"standard"`

1244

1245 - `"fast"`

1246

1247 - `BetaManagedAgentsSpanModelRequestStartEvent object`

1248

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

1250

1251 - `id: string`

1252

1253 Unique identifier for this event.

1254

1255 - `processed_at: string`

1256

1257 A timestamp in RFC 3339 format

1258

1259 format: date-time

1260

1261 - `type: "span.model_request_start"`

1262

1263 - `BetaManagedAgentsSpanModelRequestEndEvent object`

1264

1265 Emitted when a model request completes.

1266

1267 - `id: string`

1268

1269 Unique identifier for this event.

1270

1271 - `is_error: boolean or null`

1272

1273 Whether the model request resulted in an error.

1274

1275 - `model_request_start_id: string`

1276

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

1278

1279 - `model_usage: BetaManagedAgentsSpanModelUsage`

1280

1281 Token usage for a single model request.

1282

1283 - `processed_at: string`

1284

1285 A timestamp in RFC 3339 format

1286

1287 format: date-time

1288

1289 - `type: "span.model_request_end"`

1290

1291 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`

1292

1293 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.

1294

1295 - `id: string`

1296

1297 Unique identifier for this event.

1298

1299 - `iteration: number`

1300

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

1302

1303 format: int32

1304

1305 - `outcome_id: string`

1306

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

1308

1309 - `processed_at: string`

1310

1311 A timestamp in RFC 3339 format

1312

1313 format: date-time

1314

1315 - `type: "span.outcome_evaluation_ongoing"`

1316

1317 - `BetaManagedAgentsUserDefineOutcomeEvent object`

1318

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

1320

1321 - `id: string`

1322

1323 Unique identifier for this event.

1324

1325 - `description: string`

1326

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

1328

1329 - `max_iterations: number or null`

1330

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

1332

1333 format: int32

1334

1335 - `outcome_id: string`

1336

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

1338

1339 - `processed_at: string`

1340

1341 A timestamp in RFC 3339 format

1342

1343 format: date-time

1344

1345 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`

1346

1347 Rubric for grading the quality of an outcome.

1348

1349 - `BetaManagedAgentsFileRubric object`

1350

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

1352

1353 - `file_id: string`

1354

1355 ID of the rubric file.

1356

1357 - `type: "file"`

1358

1359 - `BetaManagedAgentsTextRubric object`

1360

1361 Rubric content provided inline as text.

1362

1363 - `content: string`

1364

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

1366

1367 - `type: "text"`

1368

1369 - `type: "user.define_outcome"`

1370

1371 - `BetaManagedAgentsSessionDeletedEvent object`

1372

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

1374

1375 - `id: string`

1376

1377 Unique identifier for this event.

1378

1379 - `processed_at: string`

1380

1381 A timestamp in RFC 3339 format

1382

1383 format: date-time

1384

1385 - `type: "session.deleted"`

1386

1387 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`

1388

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

1390

1391 - `id: string`

1392

1393 Unique identifier for this event.

1394

1395 - `agent_name: string`

1396

1397 Name of the agent the thread runs.

1398

1399 - `processed_at: string`

1400

1401 A timestamp in RFC 3339 format

1402

1403 format: date-time

1404

1405 - `session_thread_id: string`

1406

1407 Public sthr_ ID of the thread that started running.

1408

1409 - `type: "session.thread_status_running"`

1410

1411 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`

1412

1413 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.

1414

1415 - `id: string`

1416

1417 Unique identifier for this event.

1418

1419 - `agent_name: string`

1420

1421 Name of the agent the thread runs.

1422

1423 - `processed_at: string`

1424

1425 A timestamp in RFC 3339 format

1426

1427 format: date-time

1428

1429 - `session_thread_id: string`

1430

1431 Public sthr_ ID of the thread that went idle.

1432

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

1434

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

1436

1437 - `BetaManagedAgentsSessionEndTurn object`

1438

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

1440

1441 - `BetaManagedAgentsSessionRequiresAction object`

1442

1443 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.

1444

1445 - `BetaManagedAgentsSessionRetriesExhausted object`

1446

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

1448

1449 - `BetaManagedAgentsSessionBudgetReached object`

1450

1451 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.

1452

1453 - `type: "session.thread_status_idle"`

1454

1455 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`

1456

1457 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.

1458

1459 - `id: string`

1460

1461 Unique identifier for this event.

1462

1463 - `agent_name: string`

1464

1465 Name of the agent the thread runs.

1466

1467 - `processed_at: string`

1468

1469 A timestamp in RFC 3339 format

1470

1471 format: date-time

1472

1473 - `session_thread_id: string`

1474

1475 Public sthr_ ID of the thread that terminated.

1476

1477 - `type: "session.thread_status_terminated"`

1478

1479 - `BetaManagedAgentsUserToolResultEvent object`

1480

1481 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.

1482

1483 - `id: string`

1484

1485 Unique identifier for this event.

1486

1487 - `tool_use_id: string`

1488

1489 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.

1490

1491 - `type: "user.tool_result"`

1492

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

1494

1495 The result content returned by the tool.

1496

1497 - `BetaManagedAgentsTextBlock object`

1498

1499 Regular text content.

1500

1501 - `BetaManagedAgentsImageBlock object`

1502

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

1504

1505 - `BetaManagedAgentsDocumentBlock object`

1506

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

1508

1509 - `BetaManagedAgentsSearchResultBlock object`

1510

1511 A block containing a web search result.

1512

1513 - `is_error: optional boolean or null`

1514

1515 Whether the tool execution resulted in an error.

1516

1517 - `processed_at: optional string or null`

1518

1519 A timestamp in RFC 3339 format

1520

1521 format: date-time

1522

1523 - `session_thread_id: optional string or null`

1524

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

1526

1527 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`

1528

1529 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.

1530

1531 - `id: string`

1532

1533 Unique identifier for this event.

1534

1535 - `agent_name: string`

1536

1537 Name of the agent the thread runs.

1538

1539 - `processed_at: string`

1540

1541 A timestamp in RFC 3339 format

1542

1543 format: date-time

1544

1545 - `session_thread_id: string`

1546

1547 Public sthr_ ID of the thread that is retrying.

1548

1549 - `type: "session.thread_status_rescheduled"`

1550

1551 - `BetaManagedAgentsSessionUpdatedEvent object`

1552

1553 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.

1554

1555 - `id: string`

1556

1557 Unique identifier for this event.

1558

1559 - `processed_at: string`

1560

1561 A timestamp in RFC 3339 format

1562

1563 format: date-time

1564

1565 - `type: "session.updated"`

1566

1567 - `agent: optional BetaManagedAgentsSessionAgent or null`

1568

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

1570

1571 - `id: string`

1572

1573 - `description: string or null`

1574

1575 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1576

1577 - `name: string`

1578

1579 - `type: "url"`

1580

1581 - `url: string`

1582

1583 - `model: BetaManagedAgentsModelConfig`

1584

1585 Model identifier and configuration.

1586

1587 - `id: BetaManagedAgentsModel`

1588

1589 The model that will power your agent.

1590

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

1592

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

1594

1595 The model that will power your agent.

1596

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

1598

1599 - `"claude-fable-5-1"`

1600

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

1602

1603 - `"claude-sonnet-5"`

1604

1605 High-performance model for coding and agents

1606

1607 - `"claude-fable-5"`

1608

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

1610

1611 - `"claude-opus-5"`

1612

1613 Powerful intelligence for long-running agents and coding

1614

1615 - `"claude-opus-4-8"`

1616

1617 Powerful intelligence for long-running agents and coding

1618

1619 - `"claude-opus-4-7"`

1620

1621 Powerful intelligence for long-running agents and coding

1622

1623 - `"claude-opus-4-6"`

1624

1625 Powerful intelligence for long-running agents and coding

1626

1627 - `"claude-sonnet-4-6"`

1628

1629 Best combination of speed and intelligence

1630

1631 - `"claude-haiku-4-5"`

1632

1633 Fastest model with near-frontier intelligence

1634

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

1636

1637 Fastest model with near-frontier intelligence

1638

1639 - `"claude-opus-4-5"`

1640

1641 Powerful intelligence for long-running agents and coding

1642

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

1644

1645 Powerful intelligence for long-running agents and coding

1646

1647 - `"claude-sonnet-4-5"`

1648

1649 High-performance model for agents and coding

1650

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

1652

1653 High-performance model for agents and coding

1654

1655 - `string`

1656

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

1658

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

1660

1661 - `BetaManagedAgentsEffortLow object`

1662

1663 Low effort. Favors latency over reasoning depth.

1664

1665 - `type: "low"`

1666

1667 - `BetaManagedAgentsEffortMedium object`

1668

1669 Medium effort. Balances latency and reasoning depth.

1670

1671 - `type: "medium"`

1672

1673 - `BetaManagedAgentsEffortHigh object`

1674

1675 High effort. Favors reasoning depth.

1676

1677 - `type: "high"`

1678

1679 - `BetaManagedAgentsEffortXhigh object`

1680

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

1682

1683 - `type: "xhigh"`

1684

1685 - `BetaManagedAgentsEffortMax object`

1686

1687 Maximum effort. Favors reasoning depth over latency.

1688

1689 - `type: "max"`

1690

1691 - `inference_geo: optional string`

1692

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

1694

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

1696

1697 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.

1698

1699 - `"standard"`

1700

1701 - `"fast"`

1702

1703 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`

1704

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

1706

1707 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`

1708

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

1710

1711 - `BetaManagedAgentsSessionThreadAgent object`

1712

1713 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`.

1714

1715 - `id: string`

1716

1717 - `description: string or null`

1718

1719 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1720

1721 - `name: string`

1722

1723 - `type: "url"`

1724

1725 - `url: string`

1726

1727 - `model: BetaManagedAgentsModelConfig`

1728

1729 Model identifier and configuration.

1730

1731 - `name: string`

1732

1733 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

1734

1735 - `BetaManagedAgentsAnthropicSkill object`

1736

1737 A resolved Anthropic-managed skill.

1738

1739 - `skill_id: string`

1740

1741 - `type: "anthropic"`

1742

1743 - `version: string`

1744

1745 - `BetaManagedAgentsCustomSkill object`

1746

1747 A resolved user-created custom skill.

1748

1749 - `skill_id: string`

1750

1751 - `type: "custom"`

1752

1753 - `version: string`

1754

1755 - `system: string or null`

1756

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

1758

1759 - `BetaManagedAgentsAgentToolset20260401 object`

1760

1761 - `configs: array of BetaManagedAgentsAgentToolConfig`

1762

1763 - `BetaManagedAgentsBashToolConfig object`

1764

1765 Configuration for the bash tool.

1766

1767 - `enabled: boolean`

1768

1769 - `name: "bash"`

1770

1771 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1772

1773 Permission policy for tool execution.

1774

1775 - `BetaManagedAgentsAlwaysAllowPolicy object`

1776

1777 Tool calls are automatically approved without user confirmation.

1778

1779 - `type: "always_allow"`

1780

1781 - `BetaManagedAgentsAlwaysAskPolicy object`

1782

1783 Tool calls require user confirmation before execution.

1784

1785 - `type: "always_ask"`

1786

1787 - `type: "bash"`

1788

1789 - `BetaManagedAgentsEditToolConfig object`

1790

1791 Configuration for the edit tool.

1792

1793 - `enabled: boolean`

1794

1795 - `name: "edit"`

1796

1797 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1798

1799 Permission policy for tool execution.

1800

1801 - `BetaManagedAgentsAlwaysAllowPolicy object`

1802

1803 Tool calls are automatically approved without user confirmation.

1804

1805 - `BetaManagedAgentsAlwaysAskPolicy object`

1806

1807 Tool calls require user confirmation before execution.

1808

1809 - `type: "edit"`

1810

1811 - `BetaManagedAgentsReadToolConfig object`

1812

1813 Configuration for the read tool.

1814

1815 - `enabled: boolean`

1816

1817 - `name: "read"`

1818

1819 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1820

1821 Permission policy for tool execution.

1822

1823 - `BetaManagedAgentsAlwaysAllowPolicy object`

1824

1825 Tool calls are automatically approved without user confirmation.

1826

1827 - `BetaManagedAgentsAlwaysAskPolicy object`

1828

1829 Tool calls require user confirmation before execution.

1830

1831 - `type: "read"`

1832

1833 - `BetaManagedAgentsWriteToolConfig object`

1834

1835 Configuration for the write tool.

1836

1837 - `enabled: boolean`

1838

1839 - `name: "write"`

1840

1841 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1842

1843 Permission policy for tool execution.

1844

1845 - `BetaManagedAgentsAlwaysAllowPolicy object`

1846

1847 Tool calls are automatically approved without user confirmation.

1848

1849 - `BetaManagedAgentsAlwaysAskPolicy object`

1850

1851 Tool calls require user confirmation before execution.

1852

1853 - `type: "write"`

1854

1855 - `BetaManagedAgentsGlobToolConfig object`

1856

1857 Configuration for the glob tool.

1858

1859 - `enabled: boolean`

1860

1861 - `name: "glob"`

1862

1863 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1864

1865 Permission policy for tool execution.

1866

1867 - `BetaManagedAgentsAlwaysAllowPolicy object`

1868

1869 Tool calls are automatically approved without user confirmation.

1870

1871 - `BetaManagedAgentsAlwaysAskPolicy object`

1872

1873 Tool calls require user confirmation before execution.

1874

1875 - `type: "glob"`

1876

1877 - `BetaManagedAgentsGrepToolConfig object`

1878

1879 Configuration for the grep tool.

1880

1881 - `enabled: boolean`

1882

1883 - `name: "grep"`

1884

1885 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1886

1887 Permission policy for tool execution.

1888

1889 - `BetaManagedAgentsAlwaysAllowPolicy object`

1890

1891 Tool calls are automatically approved without user confirmation.

1892

1893 - `BetaManagedAgentsAlwaysAskPolicy object`

1894

1895 Tool calls require user confirmation before execution.

1896

1897 - `type: "grep"`

1898

1899 - `BetaManagedAgentsWebFetchToolConfig object`

1900

1901 Configuration for the web_fetch tool.

1902

1903 - `enabled: boolean`

1904

1905 - `name: "web_fetch"`

1906

1907 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1908

1909 Permission policy for tool execution.

1910

1911 - `BetaManagedAgentsAlwaysAllowPolicy object`

1912

1913 Tool calls are automatically approved without user confirmation.

1914

1915 - `BetaManagedAgentsAlwaysAskPolicy object`

1916

1917 Tool calls require user confirmation before execution.

1918

1919 - `type: "web_fetch"`

1920

1921 - `allowed_domains: optional array of string`

1922

1923 - `blocked_domains: optional array of string`

1924

1925 - `max_content_tokens: optional number or null`

1926

1927 format: int32

1928

1929 - `BetaManagedAgentsWebSearchToolConfig object`

1930

1931 Configuration for the web_search tool.

1932

1933 - `enabled: boolean`

1934

1935 - `name: "web_search"`

1936

1937 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1938

1939 Permission policy for tool execution.

1940

1941 - `BetaManagedAgentsAlwaysAllowPolicy object`

1942

1943 Tool calls are automatically approved without user confirmation.

1944

1945 - `BetaManagedAgentsAlwaysAskPolicy object`

1946

1947 Tool calls require user confirmation before execution.

1948

1949 - `type: "web_search"`

1950

1951 - `allowed_domains: optional array of string`

1952

1953 - `blocked_domains: optional array of string`

1954

1955 - `user_location: optional BetaManagedAgentsUserLocation or null`

1956

1957 Approximate user location for search result localization.

1958

1959 - `type: "approximate"`

1960

1961 Location precision. Only "approximate" is supported.

1962

1963 - `city: optional string or null`

1964

1965 City name.

1966

1967 minLength: 1, maxLength: 255

1968

1969 - `country: optional string or null`

1970

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

1972

1973 - `region: optional string or null`

1974

1975 Region or state name.

1976

1977 minLength: 1, maxLength: 255

1978

1979 - `timezone: optional string or null`

1980

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

1982

1983 minLength: 1, maxLength: 255

1984

1985 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`

1986

1987 Resolved default configuration for agent tools.

1988

1989 - `enabled: boolean`

1990

1991 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1992

1993 Permission policy for tool execution.

1994

1995 - `BetaManagedAgentsAlwaysAllowPolicy object`

1996

1997 Tool calls are automatically approved without user confirmation.

1998

1999 - `BetaManagedAgentsAlwaysAskPolicy object`

2000

2001 Tool calls require user confirmation before execution.

2002

2003 - `type: "agent_toolset_20260401"`

2004

2005 - `BetaManagedAgentsMCPToolset object`

2006

2007 - `configs: array of BetaManagedAgentsMCPToolConfig`

2008

2009 - `enabled: boolean`

2010

2011 - `name: string`

2012

2013 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

2014

2015 Permission policy for tool execution.

2016

2017 - `BetaManagedAgentsAlwaysAllowPolicy object`

2018

2019 Tool calls are automatically approved without user confirmation.

2020

2021 - `BetaManagedAgentsAlwaysAskPolicy object`

2022

2023 Tool calls require user confirmation before execution.

2024

2025 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

2026

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

2028

2029 - `enabled: boolean`

2030

2031 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

2032

2033 Permission policy for tool execution.

2034

2035 - `BetaManagedAgentsAlwaysAllowPolicy object`

2036

2037 Tool calls are automatically approved without user confirmation.

2038

2039 - `BetaManagedAgentsAlwaysAskPolicy object`

2040

2041 Tool calls require user confirmation before execution.

2042

2043 - `mcp_server_name: string`

2044

2045 - `type: "mcp_toolset"`

2046

2047 - `BetaManagedAgentsCustomTool object`

2048

2049 A custom tool as returned in API responses.

2050

2051 - `description: string`

2052

2053 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

2054

2055 JSON Schema for custom tool input parameters.

2056

2057 - `type: "object"`

2058

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

2060

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

2062

2063 - `name: string`

2064

2065 - `type: "custom"`

2066

2067 - `type: "agent"`

2068

2069 - `version: number`

2070

2071 format: int32

2072

2073 - `BetaManagedAgentsAdvisor object`

2074

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

2076

2077 - `model: string`

2078

2079 The advisor model id.

2080

2081 - `type: "advisor"`

2082

2083 - `type: "coordinator"`

2084

2085 - `name: string`

2086

2087 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

2088

2089 - `BetaManagedAgentsAnthropicSkill object`

2090

2091 A resolved Anthropic-managed skill.

2092

2093 - `BetaManagedAgentsCustomSkill object`

2094

2095 A resolved user-created custom skill.

2096

2097 - `system: string or null`

2098

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

2100

2101 - `BetaManagedAgentsAgentToolset20260401 object`

2102

2103 - `BetaManagedAgentsMCPToolset object`

2104

2105 - `BetaManagedAgentsCustomTool object`

2106

2107 A custom tool as returned in API responses.

2108

2109 - `type: "agent"`

2110

2111 - `version: number`

2112

2113 format: int32

2114

2115 - `budget: optional BetaManagedAgentsBudgetLimit or null`

2116

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

2118

2119 - `max_list_cost: BetaMonetaryAmount`

2120

2121 A monetary amount in a specific currency.

2122

2123 - `amount: string`

2124

2125 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.

2126

2127 - `currency: BetaCurrency`

2128

2129 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.

2130

2131 - `type: "limit"`

2132

2133 - `metadata: optional map[string]`

2134

2135 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.

2136

2137 - `title: optional string or null`

2138

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

2140

2141 - `BetaManagedAgentsStartEvent object`

2142

2143 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.

2144

2145 - `event: BetaManagedAgentsStartEventPreview`

2146

2147 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.

2148

2149 - `BetaManagedAgentsAgentMessagePreview object`

2150

2151 - `id: string`

2152

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

2154

2155 - `type: "agent.message"`

2156

2157 - `BetaManagedAgentsAgentThinkingPreview object`

2158

2159 - `id: string`

2160

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

2162

2163 - `type: "agent.thinking"`

2164

2165 - `type: "event_start"`

2166

2167 - `BetaManagedAgentsDeltaEvent object`

2168

2169 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.

2170

2171 - `delta: BetaManagedAgentsDeltaContent`

2172

2173 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.

2174

2175 - `content: BetaManagedAgentsTextBlock`

2176

2177 Regular text content.

2178

2179 - `type: "content_delta"`

2180

2181 - `index: optional number`

2182

2183 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.

2184

2185 format: uint32

2186

2187 - `event_id: string`

2188

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

2190

2191 - `type: "event_delta"`

2192

2193 - `BetaManagedAgentsSystemMessageEvent object`

2194

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

2196

2197 - `id: string`

2198

2199 Unique identifier for this event.

2200

2201 - `content: array of BetaManagedAgentsSystemContentBlock`

2202

2203 System content blocks. Text-only.

2204

2205 - `text: string`

2206

2207 The text content.

2208

2209 minLength: 1

2210

2211 - `type: "text"`

2212

2213 - `type: "system.message"`

2214

2215 - `processed_at: optional string or null`

2216

2217 A timestamp in RFC 3339 format

2218

2219 format: date-time

2220

22212336 - `BetaManagedAgentsSessionUsageEvent object`

22222337

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

22242339

2225 - `id: string`

2226

2227 Unique identifier for this event.

2228

2229 - `processed_at: string`

2230

2231 A timestamp in RFC 3339 format

2232

2233 format: date-time

2234

22352340 - `type: "session.usage"`

2341

2342 - `id: string`

2343

2344 Unique identifier for this event.

2345

2346 - `processed_at: string`

2347

2348 A timestamp in RFC 3339 format

2349

2350 format: date-time

22362351

22372352 - `usage: BetaManagedAgentsSessionUsageSnapshot`

22382353

22392354

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 Session Thread Events changed

The whole hunk