api/beta/sessions/events/list / 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: List Events

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

4---

16# List Events

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

from line 69

6469

6570 - `string`

6671

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

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

6873

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

7075

from line 117

112117

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

114119

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

121

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

116123

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

from line 161

154161

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

156163

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

165

157166## Returns

158167

159168- `data: optional array of BetaManagedAgentsSessionEvent`

from line 173

164173

165174 A user message event in the session conversation.

166175

176 - `type: "user.message"`

177

167178 - `id: string`

168179

169180 Unique identifier for this event.

from line 187

176187

177188 Regular text content.

178189

190 - `type: "text"`

191

179192 - `text: string`

180193

181194 The text content.

182195

183196 minLength: 1

184197

198 - `BetaManagedAgentsImageBlock object`

199

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

201

202 - `type: "image"`

203

204 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

205

206 Union type for image source variants.

207

208 - `BetaManagedAgentsBase64ImageSource object`

209

210 Base64-encoded image data.

211

212 - `type: "base64"`

213

214 - `data: string`

215

216 Base64-encoded image data.

217

218 minLength: 1

219

220 - `media_type: string`

221

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

223

224 minLength: 1

225

226 - `BetaManagedAgentsURLImageSource object`

227

228 Image referenced by URL.

229

230 - `type: "url"`

231

232 - `url: string`

233

234 URL of the image to fetch.

235

236 minLength: 1

237

238 - `BetaManagedAgentsFileImageSource object`

239

240 Image referenced by file ID.

241

242 - `type: "file"`

243

244 - `file_id: string`

245

246 ID of a previously uploaded file.

247

248 minLength: 1

249

250 - `BetaManagedAgentsDocumentBlock object`

251

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

253

254 - `type: "document"`

255

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

257

258 Union type for document source variants.

259

260 - `BetaManagedAgentsBase64DocumentSource object`

261

262 Base64-encoded document data.

263

264 - `type: "base64"`

265

266 - `data: string`

267

268 Base64-encoded document data.

269

270 minLength: 1

271

272 - `media_type: string`

273

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

275

276 minLength: 1

277

278 - `BetaManagedAgentsPlainTextDocumentSource object`

279

280 Plain text document content.

281

282 - `type: "text"`

283

284 - `data: string`

285

286 The plain text content.

287

288 minLength: 1

289

290 - `media_type: "text/plain"`

291

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

293

294 - `BetaManagedAgentsURLDocumentSource object`

295

296 Document referenced by URL.

297

298 - `type: "url"`

299

300 - `url: string`

301

302 URL of the document to fetch.

303

304 minLength: 1

305

306 - `BetaManagedAgentsFileDocumentSource object`

307

308 Document referenced by file ID.

309

310 - `type: "file"`

311

312 - `file_id: string`

313

314 ID of a previously uploaded file.

315

316 minLength: 1

317

318 - `context: optional string or null`

319

320 Additional context about the document for the model.

321

322 - `title: optional string or null`

323

324 The title of the document.

325

326 - `BetaManagedAgentsRedactedBlock object`

327

328 Placeholder for content withheld by Anthropic model policy.

329

330 - `type: "redacted"`

331

332 - `processed_at: optional string or null`

333

334 A timestamp in RFC 3339 format

335

336 format: date-time

337

338 - `BetaManagedAgentsUserInterruptEvent object`

339

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

341

342 - `type: "user.interrupt"`

343

344 - `id: string`

345

346 Unique identifier for this event.

347

348 - `processed_at: optional string or null`

349

350 A timestamp in RFC 3339 format

351

352 format: date-time

353

354 - `session_thread_id: optional string or null`

355

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

357

358 - `BetaManagedAgentsUserToolConfirmationEvent object`

359

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

361

362 - `type: "user.tool_confirmation"`

363

364 - `id: string`

365

366 Unique identifier for this event.

367

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

369

370 UserToolConfirmationResult enum

371

372 - `"allow"`

373

374 - `"deny"`

375

376 - `tool_use_id: string`

377

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

379

380 - `deny_message: optional string or null`

381

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

383

384 maxLength: 10000

385

386 - `processed_at: optional string or null`

387

388 A timestamp in RFC 3339 format

389

390 format: date-time

391

392 - `session_thread_id: optional string or null`

393

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

395

396 - `BetaManagedAgentsUserCustomToolResultEvent object`

397

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

399

400 - `type: "user.custom_tool_result"`

401

402 - `id: string`

403

404 Unique identifier for this event.

405

406 - `custom_tool_use_id: string`

407

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

409

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

411

412 The result content returned by the tool.

413

414 - `BetaManagedAgentsTextBlock object`

415

416 Regular text content.

417

418 - `BetaManagedAgentsImageBlock object`

419

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

421

422 - `BetaManagedAgentsDocumentBlock object`

423

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

425

426 - `BetaManagedAgentsSearchResultBlock object`

427

428 A block containing a web search result.

429

430 - `type: "search_result"`

431

432 - `citations: BetaManagedAgentsSearchResultCitations`

433

434 Citation settings for a search result.

435

436 - `enabled: boolean`

437

438 Whether citations are enabled for this search result.

439

440 - `content: array of BetaManagedAgentsSearchResultContent`

441

442 Array of text content blocks from the search result.

443

444 - `type: "text"`

445

446 - `text: string`

447

448 The text content.

449

450 minLength: 1

451

452 - `source: string`

453

454 The URL source of the search result.

455

456 minLength: 1

457

458 - `title: string`

459

460 The title of the search result.

461

462 minLength: 1

463

464 - `is_error: optional boolean or null`

465

466 Whether the tool execution resulted in an error.

467

468 - `processed_at: optional string or null`

469

470 A timestamp in RFC 3339 format

471

472 format: date-time

473

474 - `session_thread_id: optional string or null`

475

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

477

478 - `BetaManagedAgentsAgentCustomToolUseEvent object`

479

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

481

482 - `type: "agent.custom_tool_use"`

483

484 - `id: string`

485

486 Unique identifier for this event.

487

488 - `input: map[unknown]`

489

490 Input parameters for the tool call.

491

492 - `name: string`

493

494 Name of the custom tool being called.

495

496 - `processed_at: string`

497

498 A timestamp in RFC 3339 format

499

500 format: date-time

501

502 - `session_thread_id: optional string or null`

503

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

505

506 - `BetaManagedAgentsAgentMessageEvent object`

507

508 An agent response event in the session conversation.

509

510 - `type: "agent.message"`

511

512 - `id: string`

513

514 Unique identifier for this event.

515

516 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`

517

518 Array of text blocks comprising the agent response.

519

520 - `BetaManagedAgentsTextBlock object`

521

522 Regular text content.

523

524 - `BetaManagedAgentsRedactedBlock object`

525

526 Placeholder for content withheld by Anthropic model policy.

527

528 - `processed_at: string`

529

530 A timestamp in RFC 3339 format

531

532 format: date-time

533

534 - `BetaManagedAgentsAgentThinkingEvent object`

535

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

537

538 - `type: "agent.thinking"`

539

540 - `id: string`

541

542 Unique identifier for this event.

543

544 - `processed_at: string`

545

546 A timestamp in RFC 3339 format

547

548 format: date-time

549

550 - `BetaManagedAgentsAgentMCPToolUseEvent object`

551

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

553

554 - `type: "agent.mcp_tool_use"`

555

556 - `id: string`

557

558 Unique identifier for this event.

559

560 - `input: map[unknown]`

561

562 Input parameters for the tool call.

563

564 - `mcp_server_name: string`

565

566 Name of the MCP server providing the tool.

567

568 - `name: string`

569

570 Name of the MCP tool being used.

571

572 - `processed_at: string`

573

574 A timestamp in RFC 3339 format

575

576 format: date-time

577

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

579

580 AgentEvaluatedPermission enum

581

582 - `"allow"`

583

584 - `"ask"`

585

586 - `"deny"`

587

588 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`

589

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

591

592 - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object`

593

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

595

596 - `type: "always_allow"`

597

598 - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object`

599

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

601

602 - `type: "always_ask"`

603

604 - `BetaManagedAgentsAgentToolEvaluationAuto object`

605

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

607

608 - `type: "auto"`

609

610 - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission`

611

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

613

614 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object`

615

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

617

618 - `type: "allow"`

619

620 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object`

621

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

623

624 - `type: "ask"`

625

626 - `reason_code: string`

627

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

629

630 maxLength: 64

631

632 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object`

633

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

635

636 - `type: "deny"`

637

638 - `reason_code: string`

639

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

641

642 maxLength: 64

643

644 - `session_thread_id: optional string or null`

645

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

647

648 - `BetaManagedAgentsAgentMCPToolResultEvent object`

649

650 Event representing the result of an MCP tool execution.

651

652 - `type: "agent.mcp_tool_result"`

653

654 - `id: string`

655

656 Unique identifier for this event.

657

658 - `mcp_tool_use_id: string`

659

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

661

662 - `processed_at: string`

663

664 A timestamp in RFC 3339 format

665

666 format: date-time

667

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

669

670 The result content returned by the tool.

671

672 - `BetaManagedAgentsTextBlock object`

673

674 Regular text content.

675

676 - `BetaManagedAgentsImageBlock object`

677

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

679

680 - `BetaManagedAgentsDocumentBlock object`

681

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

683

684 - `BetaManagedAgentsSearchResultBlock object`

685

686 A block containing a web search result.

687

688 - `is_error: optional boolean or null`

689

690 Whether the tool execution resulted in an error.

691

692 - `BetaManagedAgentsAgentToolUseEvent object`

693

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

695

696 - `type: "agent.tool_use"`

697

698 - `id: string`

699

700 Unique identifier for this event.

701

702 - `input: map[unknown]`

703

704 Input parameters for the tool call.

705

706 - `name: string`

707

708 Name of the agent tool being used.

709

710 - `processed_at: string`

711

712 A timestamp in RFC 3339 format

713

714 format: date-time

715

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

717

718 AgentEvaluatedPermission enum

719

720 - `"allow"`

721

722 - `"ask"`

723

724 - `"deny"`

725

726 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`

727

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

729

730 - `session_thread_id: optional string or null`

731

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

733

734 - `BetaManagedAgentsAgentToolResultEvent object`

735

736 Event representing the result of an agent tool execution.

737

738 - `type: "agent.tool_result"`

739

740 - `id: string`

741

742 Unique identifier for this event.

743

744 - `processed_at: string`

745

746 A timestamp in RFC 3339 format

747

748 format: date-time

749

750 - `tool_use_id: string`

751

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

753

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

755

756 The result content returned by the tool.

757

758 - `BetaManagedAgentsTextBlock object`

759

760 Regular text content.

761

762 - `BetaManagedAgentsImageBlock object`

763

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

765

766 - `BetaManagedAgentsDocumentBlock object`

767

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

769

770 - `BetaManagedAgentsSearchResultBlock object`

771

772 A block containing a web search result.

773

774 - `is_error: optional boolean or null`

775

776 Whether the tool execution resulted in an error.

777

778 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`

779

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

781

782 - `type: "agent.thread_message_received"`

783

784 - `id: string`

785

786 Unique identifier for this event.

787

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

789

790 Message content blocks.

791

792 - `BetaManagedAgentsTextBlock object`

793

794 Regular text content.

795

796 - `BetaManagedAgentsImageBlock object`

797

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

799

800 - `BetaManagedAgentsDocumentBlock object`

801

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

803

804 - `BetaManagedAgentsRedactedBlock object`

805

806 Placeholder for content withheld by Anthropic model policy.

807

808 - `from_session_thread_id: string`

809

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

811

812 - `processed_at: string`

813

814 A timestamp in RFC 3339 format

815

816 format: date-time

817

818 - `from_agent_name: optional string or null`

819

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

821

822 - `BetaManagedAgentsAgentThreadMessageSentEvent object`

823

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

825

826 - `type: "agent.thread_message_sent"`

827

828 - `id: string`

829

830 Unique identifier for this event.

831

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

833

834 Message content blocks.

835

836 - `BetaManagedAgentsTextBlock object`

837

838 Regular text content.

839

840 - `BetaManagedAgentsImageBlock object`

841

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

843

844 - `BetaManagedAgentsDocumentBlock object`

845

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

847

848 - `BetaManagedAgentsRedactedBlock object`

849

850 Placeholder for content withheld by Anthropic model policy.

851

852 - `processed_at: string`

853

854 A timestamp in RFC 3339 format

855

856 format: date-time

857

858 - `to_session_thread_id: string`

859

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

861

862 - `to_agent_name: optional string or null`

863

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

865

866 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`

867

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

869

870 - `type: "agent.thread_context_compacted"`

871

872 - `id: string`

873

874 Unique identifier for this event.

875

876 - `processed_at: string`

877

878 A timestamp in RFC 3339 format

879

880 format: date-time

881

882 - `BetaManagedAgentsSessionErrorEvent object`

883

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

885

886 - `type: "session.error"`

887

888 - `id: string`

889

890 Unique identifier for this event.

891

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

893

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

895

896 - `BetaManagedAgentsUnknownError object`

897

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

899

900 - `type: "unknown_error"`

901

902 - `message: string`

903

904 Human-readable error description.

905

906 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

907

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

909

910 - `BetaManagedAgentsRetryStatusRetrying object`

911

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

913

914 - `type: "retrying"`

915

916 - `BetaManagedAgentsRetryStatusExhausted object`

917

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

919

920 - `type: "exhausted"`

921

922 - `BetaManagedAgentsRetryStatusTerminal object`

923

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

925

926 - `type: "terminal"`

927

928 - `BetaManagedAgentsModelOverloadedError object`

929

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

931

932 - `type: "model_overloaded_error"`

933

934 - `message: string`

935

936 Human-readable error description.

937

938 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

939

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

941

942 - `BetaManagedAgentsRetryStatusRetrying object`

943

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

945

946 - `BetaManagedAgentsRetryStatusExhausted object`

947

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

949

950 - `BetaManagedAgentsRetryStatusTerminal object`

951

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

953

954 - `BetaManagedAgentsModelRateLimitedError object`

955

956 The model request was rate-limited.

957

958 - `type: "model_rate_limited_error"`

959

960 - `message: string`

961

962 Human-readable error description.

963

964 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

965

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

967

968 - `BetaManagedAgentsRetryStatusRetrying object`

969

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

971

972 - `BetaManagedAgentsRetryStatusExhausted object`

973

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

975

976 - `BetaManagedAgentsRetryStatusTerminal object`

977

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

979

980 - `BetaManagedAgentsModelRequestFailedError object`

981

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

983

984 - `type: "model_request_failed_error"`

985

986 - `message: string`

987

988 Human-readable error description.

989

990 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

991

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

993

994 - `BetaManagedAgentsRetryStatusRetrying object`

995

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

997

998 - `BetaManagedAgentsRetryStatusExhausted object`

999

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

1001

1002 - `BetaManagedAgentsRetryStatusTerminal object`

1003

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

1005

1006 - `BetaManagedAgentsMCPConnectionFailedError object`

1007

1008 Failed to connect to an MCP server.

1009

1010 - `type: "mcp_connection_failed_error"`

1011

1012 - `mcp_server_name: string`

1013

1014 Name of the MCP server that failed to connect.

1015

1016 - `message: string`

1017

1018 Human-readable error description.

1019

1020 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1021

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

1023

1024 - `BetaManagedAgentsRetryStatusRetrying object`

1025

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

1027

1028 - `BetaManagedAgentsRetryStatusExhausted object`

1029

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

1031

1032 - `BetaManagedAgentsRetryStatusTerminal object`

1033

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

1035

1036 - `BetaManagedAgentsMCPAuthenticationFailedError object`

1037

1038 Authentication to an MCP server failed.

1039

1040 - `type: "mcp_authentication_failed_error"`

1041

1042 - `mcp_server_name: string`

1043

1044 Name of the MCP server that failed authentication.

1045

1046 - `message: string`

1047

1048 Human-readable error description.

1049

1050 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1051

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

1053

1054 - `BetaManagedAgentsRetryStatusRetrying object`

1055

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

1057

1058 - `BetaManagedAgentsRetryStatusExhausted object`

1059

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

1061

1062 - `BetaManagedAgentsRetryStatusTerminal object`

1063

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

1065

1066 - `BetaManagedAgentsBillingError object`

1067

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

1069

1070 - `type: "billing_error"`

1071

1072 - `message: string`

1073

1074 Human-readable error description.

1075

1076 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1077

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

1079

1080 - `BetaManagedAgentsRetryStatusRetrying object`

1081

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

1083

1084 - `BetaManagedAgentsRetryStatusExhausted object`

1085

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

1087

1088 - `BetaManagedAgentsRetryStatusTerminal object`

1089

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

1091

1092 - `BetaManagedAgentsCredentialHostUnreachableError object`

1093

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

1095

1096 - `type: "credential_host_unreachable_error"`

1097

1098 - `credential_id: string`

1099

1100 ID of the affected credential.

1101

1102 - `message: string`

1103

1104 Human-readable error description.

1105

1106 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1107

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

1109

1110 - `BetaManagedAgentsRetryStatusRetrying object`

1111

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

1113

1114 - `BetaManagedAgentsRetryStatusExhausted object`

1115

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

1117

1118 - `BetaManagedAgentsRetryStatusTerminal object`

1119

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

1121

1122 - `vault_id: string`

1123

1124 ID of the vault containing the affected credential.

1125

1126 - `processed_at: string`

1127

1128 A timestamp in RFC 3339 format

1129

1130 format: date-time

1131

1132 - `BetaManagedAgentsSessionStatusRescheduledEvent object`

1133

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

1135

1136 - `type: "session.status_rescheduled"`

1137

1138 - `id: string`

1139

1140 Unique identifier for this event.

1141

1142 - `processed_at: string`

1143

1144 A timestamp in RFC 3339 format

1145

1146 format: date-time

1147

1148 - `BetaManagedAgentsSessionStatusRunningEvent object`

1149

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

1151

1152 - `type: "session.status_running"`

1153

1154 - `id: string`

1155

1156 Unique identifier for this event.

1157

1158 - `processed_at: string`

1159

1160 A timestamp in RFC 3339 format

1161

1162 format: date-time

1163

1164 - `BetaManagedAgentsSessionStatusIdleEvent object`

1165

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

1167

1168 - `type: "session.status_idle"`

1169

1170 - `id: string`

1171

1172 Unique identifier for this event.

1173

1174 - `processed_at: string`

1175

1176 A timestamp in RFC 3339 format

1177

1178 format: date-time

1179

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

1181

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

1183

1184 - `BetaManagedAgentsSessionEndTurn object`

1185

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

1187

1188 - `type: "end_turn"`

1189

1190 - `BetaManagedAgentsSessionRequiresAction object`

1191

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

1193

1194 - `type: "requires_action"`

1195

1196 - `event_ids: array of string`

1197

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

1199

1200 - `BetaManagedAgentsSessionRetriesExhausted object`

1201

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

1203

1204 - `type: "retries_exhausted"`

1205

1206 - `BetaManagedAgentsSessionBudgetReached object`

1207

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

1209

1210 - `type: "budget_reached"`

1211

1212 - `BetaManagedAgentsSessionStatusTerminatedEvent object`

1213

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

1215

1216 - `type: "session.status_terminated"`

1217

1218 - `id: string`

1219

1220 Unique identifier for this event.

1221

1222 - `processed_at: string`

1223

1224 A timestamp in RFC 3339 format

1225

1226 format: date-time

1227

1228 - `BetaManagedAgentsSessionThreadCreatedEvent object`

1229

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

1231

1232 - `type: "session.thread_created"`

1233

1234 - `id: string`

1235

1236 Unique identifier for this event.

1237

1238 - `agent_name: string`

1239

1240 Name of the callable agent the thread runs.

1241

1242 - `processed_at: string`

1243

1244 A timestamp in RFC 3339 format

1245

1246 format: date-time

1247

1248 - `session_thread_id: string`

1249

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

1251

1252 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`

1253

1254 Emitted when an outcome evaluation cycle begins.

1255

1256 - `type: "span.outcome_evaluation_start"`

1257

1258 - `id: string`

1259

1260 Unique identifier for this event.

1261

1262 - `iteration: number`

1263

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

1265

1266 format: int32

1267

1268 - `outcome_id: string`

1269

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

1271

1272 - `processed_at: string`

1273

1274 A timestamp in RFC 3339 format

1275

1276 format: date-time

1277

1278 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`

1279

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

1281

1282 - `type: "span.outcome_evaluation_end"`

1283

1284 - `id: string`

1285

1286 Unique identifier for this event.

1287

1288 - `explanation: string`

1289

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

1291

1292 - `iteration: number`

1293

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

1295

1296 format: int32

1297

1298 - `outcome_evaluation_start_id: string`

1299

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

1301

1302 - `outcome_id: string`

1303

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

1305

1306 - `processed_at: string`

1307

1308 A timestamp in RFC 3339 format

1309

1310 format: date-time

1311

1312 - `result: string`

1313

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

1315

1316 - `usage: BetaManagedAgentsSpanModelUsage`

1317

1318 Token usage for a single model request.

1319

1320 - `cache_creation_input_tokens: number`

1321

1322 Tokens used to create prompt cache in this request.

1323

1324 format: int32

1325

1326 - `cache_read_input_tokens: number`

1327

1328 Tokens read from prompt cache in this request.

1329

1330 format: int32

1331

1332 - `input_tokens: number`

1333

1334 Input tokens consumed by this request.

1335

1336 format: int32

1337

1338 - `output_tokens: number`

1339

1340 Output tokens generated by this request.

1341

1342 format: int32

1343

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

1345

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

1347

1348 - `"standard"`

1349

1350 - `"fast"`

1351

1352 - `BetaManagedAgentsSpanModelRequestStartEvent object`

1353

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

1355

1356 - `type: "span.model_request_start"`

1357

1358 - `id: string`

1359

1360 Unique identifier for this event.

1361

1362 - `processed_at: string`

1363

1364 A timestamp in RFC 3339 format

1365

1366 format: date-time

1367

1368 - `BetaManagedAgentsSpanModelRequestEndEvent object`

1369

1370 Emitted when a model request completes.

1371

1372 - `type: "span.model_request_end"`

1373

1374 - `id: string`

1375

1376 Unique identifier for this event.

1377

1378 - `is_error: boolean or null`

1379

1380 Whether the model request resulted in an error.

1381

1382 - `model_request_start_id: string`

1383

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

1385

1386 - `model_usage: BetaManagedAgentsSpanModelUsage`

1387

1388 Token usage for a single model request.

1389

1390 - `processed_at: string`

1391

1392 A timestamp in RFC 3339 format

1393

1394 format: date-time

1395

1396 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`

1397

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

1399

1400 - `type: "span.outcome_evaluation_ongoing"`

1401

1402 - `id: string`

1403

1404 Unique identifier for this event.

1405

1406 - `iteration: number`

1407

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

1409

1410 format: int32

1411

1412 - `outcome_id: string`

1413

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

1415

1416 - `processed_at: string`

1417

1418 A timestamp in RFC 3339 format

1419

1420 format: date-time

1421

1422 - `BetaManagedAgentsUserDefineOutcomeEvent object`

1423

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

1425

1426 - `type: "user.define_outcome"`

1427

1428 - `id: string`

1429

1430 Unique identifier for this event.

1431

1432 - `description: string`

1433

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

1435

1436 - `max_iterations: number or null`

1437

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

1439

1440 format: int32

1441

1442 - `outcome_id: string`

1443

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

1445

1446 - `processed_at: string`

1447

1448 A timestamp in RFC 3339 format

1449

1450 format: date-time

1451

1452 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`

1453

1454 Rubric for grading the quality of an outcome.

1455

1456 - `BetaManagedAgentsFileRubric object`

1457

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

1459

1460 - `type: "file"`

1461

1462 - `file_id: string`

1463

1464 ID of the rubric file.

1465

1466 - `BetaManagedAgentsTextRubric object`

1467

1468 Rubric content provided inline as text.

1469

1851470 - `type: "text"`

1861471

1472 - `content: string`

1473

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

1475

1476 - `BetaManagedAgentsSessionDeletedEvent object`

1477

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

1479

1480 - `type: "session.deleted"`

1481

1482 - `id: string`

1483

1484 Unique identifier for this event.

1485

1486 - `processed_at: string`

1487

1488 A timestamp in RFC 3339 format

1489

1490 format: date-time

1491

1492 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`

1493

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

1495

1496 - `type: "session.thread_status_running"`

1497

1498 - `id: string`

1499

1500 Unique identifier for this event.

1501

1502 - `agent_name: string`

1503

1504 Name of the agent the thread runs.

1505

1506 - `processed_at: string`

1507

1508 A timestamp in RFC 3339 format

1509

1510 format: date-time

1511

1512 - `session_thread_id: string`

1513

1514 Public sthr_ ID of the thread that started running.

1515

1516 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`

1517

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

1519

1520 - `type: "session.thread_status_idle"`

1521

1522 - `id: string`

1523

1524 Unique identifier for this event.

1525

1526 - `agent_name: string`

1527

1528 Name of the agent the thread runs.

1529

1530 - `processed_at: string`

1531

1532 A timestamp in RFC 3339 format

1533

1534 format: date-time

1535

1536 - `session_thread_id: string`

1537

1538 Public sthr_ ID of the thread that went idle.

1539

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

1541

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

1543

1544 - `BetaManagedAgentsSessionEndTurn object`

1545

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

1547

1548 - `BetaManagedAgentsSessionRequiresAction object`

1549

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

1551

1552 - `BetaManagedAgentsSessionRetriesExhausted object`

1553

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

1555

1556 - `BetaManagedAgentsSessionBudgetReached object`

1557

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

1559

1560 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`

1561

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

1563

1564 - `type: "session.thread_status_terminated"`

1565

1566 - `id: string`

1567

1568 Unique identifier for this event.

1569

1570 - `agent_name: string`

1571

1572 Name of the agent the thread runs.

1573

1574 - `processed_at: string`

1575

1576 A timestamp in RFC 3339 format

1577

1578 format: date-time

1579

1580 - `session_thread_id: string`

1581

1582 Public sthr_ ID of the thread that terminated.

1583

1584 - `BetaManagedAgentsUserToolResultEvent object`

1585

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

1587

1588 - `type: "user.tool_result"`

1589

1590 - `id: string`

1591

1592 Unique identifier for this event.

1593

1594 - `tool_use_id: string`

1595

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

1597

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

1599

1600 The result content returned by the tool.

1601

1602 - `BetaManagedAgentsTextBlock object`

1603

1604 Regular text content.

1605

1871606 - `BetaManagedAgentsImageBlock object`

1881607

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

1901609

191 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`

192

193 Union type for image source variants.

194

195 - `BetaManagedAgentsBase64ImageSource object`

196

197 Base64-encoded image data.

198

199 - `data: string`

200

201 Base64-encoded image data.

202

203 minLength: 1

204

205 - `media_type: string`

206

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

208

209 minLength: 1

210

211 - `type: "base64"`

212

213 - `BetaManagedAgentsURLImageSource object`

214

215 Image referenced by URL.

216

217 - `type: "url"`

218

219 - `url: string`

220

221 URL of the image to fetch.

222

223 minLength: 1

224

225 - `BetaManagedAgentsFileImageSource object`

226

227 Image referenced by file ID.

228

229 - `file_id: string`

230

231 ID of a previously uploaded file.

232

233 minLength: 1

234

235 - `type: "file"`

236

237 - `type: "image"`

238

2391610 - `BetaManagedAgentsDocumentBlock object`

2401611

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

2421613

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

244

245 Union type for document source variants.

246

247 - `BetaManagedAgentsBase64DocumentSource object`

248

249 Base64-encoded document data.

250

251 - `data: string`

252

253 Base64-encoded document data.

254

255 minLength: 1

256

257 - `media_type: string`

258

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

260

261 minLength: 1

262

263 - `type: "base64"`

264

265 - `BetaManagedAgentsPlainTextDocumentSource object`

266

267 Plain text document content.

268

269 - `data: string`

270

271 The plain text content.

272

273 minLength: 1

274

275 - `media_type: "text/plain"`

276

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

278

279 - `type: "text"`

280

281 - `BetaManagedAgentsURLDocumentSource object`

282

283 Document referenced by URL.

284

285 - `type: "url"`

286

287 - `url: string`

288

289 URL of the document to fetch.

290

291 minLength: 1

292

293 - `BetaManagedAgentsFileDocumentSource object`

294

295 Document referenced by file ID.

296

297 - `file_id: string`

298

299 ID of a previously uploaded file.

300

301 minLength: 1

302

303 - `type: "file"`

304

305 - `type: "document"`

306

307 - `context: optional string or null`

308

309 Additional context about the document for the model.

310

311 - `title: optional string or null`

312

313 The title of the document.

314

315 - `BetaManagedAgentsRedactedBlock object`

316

317 Placeholder for content withheld by Anthropic model policy.

318

319 - `type: "redacted"`

320

321 - `type: "user.message"`

1614 - `BetaManagedAgentsSearchResultBlock object`

1615

1616 A block containing a web search result.

1617

1618 - `is_error: optional boolean or null`

1619

1620 Whether the tool execution resulted in an error.

3221621

3231622 - `processed_at: optional string or null`

3241623

from line 1625

3261625

3271626 format: date-time

3281627

329 - `BetaManagedAgentsUserInterruptEvent object`

330

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

332

333 - `id: string`

334

335 Unique identifier for this event.

336

337 - `type: "user.interrupt"`

1628 - `session_thread_id: optional string or null`

1629

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

1631

1632 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`

1633

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

1635

1636 - `type: "session.thread_status_rescheduled"`

1637

1638 - `id: string`

1639

1640 Unique identifier for this event.

1641

1642 - `agent_name: string`

1643

1644 Name of the agent the thread runs.

1645

1646 - `processed_at: string`

1647

1648 A timestamp in RFC 3339 format

1649

1650 format: date-time

1651

1652 - `session_thread_id: string`

1653

1654 Public sthr_ ID of the thread that is retrying.

1655

1656 - `BetaManagedAgentsSessionUpdatedEvent object`

1657

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

1659

1660 - `type: "session.updated"`

1661

1662 - `id: string`

1663

1664 Unique identifier for this event.

1665

1666 - `processed_at: string`

1667

1668 A timestamp in RFC 3339 format

1669

1670 format: date-time

1671

1672 - `agent: optional BetaManagedAgentsSessionAgent or null`

1673

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

1675

1676 - `type: "agent"`

1677

1678 - `id: string`

1679

1680 - `description: string or null`

1681

1682 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1683

1684 - `type: "url"`

1685

1686 - `name: string`

1687

1688 - `url: string`

1689

1690 - `model: BetaManagedAgentsModelConfig`

1691

1692 Model identifier and configuration.

1693

1694 - `id: BetaManagedAgentsModel`

1695

1696 The model that will power your agent.

1697

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

1699

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

1701

1702 The model that will power your agent.

1703

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

1705

1706 - `"claude-fable-5-1"`

1707

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

1709

1710 - `"claude-sonnet-5"`

1711

1712 High-performance model for coding and agents

1713

1714 - `"claude-fable-5"`

1715

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

1717

1718 - `"claude-opus-5"`

1719

1720 Powerful intelligence for long-running agents and coding

1721

1722 - `"claude-opus-4-8"`

1723

1724 Powerful intelligence for long-running agents and coding

1725

1726 - `"claude-opus-4-7"`

1727

1728 Powerful intelligence for long-running agents and coding

1729

1730 - `"claude-opus-4-6"`

1731

1732 Powerful intelligence for long-running agents and coding

1733

1734 - `"claude-sonnet-4-6"`

1735

1736 Best combination of speed and intelligence

1737

1738 - `"claude-haiku-4-5"`

1739

1740 Fastest model with near-frontier intelligence

1741

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

1743

1744 Fastest model with near-frontier intelligence

1745

1746 - `"claude-opus-4-5"`

1747

1748 Powerful intelligence for long-running agents and coding

1749

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

1751

1752 Powerful intelligence for long-running agents and coding

1753

1754 - `"claude-sonnet-4-5"`

1755

1756 High-performance model for agents and coding

1757

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

1759

1760 High-performance model for agents and coding

1761

1762 - `string`

1763

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

1765

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

1767

1768 - `BetaManagedAgentsEffortLow object`

1769

1770 Low effort. Favors latency over reasoning depth.

1771

1772 - `type: "low"`

1773

1774 - `BetaManagedAgentsEffortMedium object`

1775

1776 Medium effort. Balances latency and reasoning depth.

1777

1778 - `type: "medium"`

1779

1780 - `BetaManagedAgentsEffortHigh object`

1781

1782 High effort. Favors reasoning depth.

1783

1784 - `type: "high"`

1785

1786 - `BetaManagedAgentsEffortXhigh object`

1787

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

1789

1790 - `type: "xhigh"`

1791

1792 - `BetaManagedAgentsEffortMax object`

1793

1794 Maximum effort. Favors reasoning depth over latency.

1795

1796 - `type: "max"`

1797

1798 - `inference_geo: optional string`

1799

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

1801

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

1803

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

1805

1806 - `"standard"`

1807

1808 - `"fast"`

1809

1810 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`

1811

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

1813

1814 - `type: "coordinator"`

1815

1816 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`

1817

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

1819

1820 - `BetaManagedAgentsSessionThreadAgent object`

1821

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

1823

1824 - `type: "agent"`

1825

1826 - `id: string`

1827

1828 - `description: string or null`

1829

1830 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1831

1832 - `type: "url"`

1833

1834 - `name: string`

1835

1836 - `url: string`

1837

1838 - `model: BetaManagedAgentsModelConfig`

1839

1840 Model identifier and configuration.

1841

1842 - `name: string`

1843

1844 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

1845

1846 - `BetaManagedAgentsAnthropicSkill object`

1847

1848 A resolved Anthropic-managed skill.

1849

1850 - `type: "anthropic"`

1851

1852 - `skill_id: string`

1853

1854 - `version: string`

1855

1856 - `BetaManagedAgentsCustomSkill object`

1857

1858 A resolved user-created custom skill.

1859

1860 - `type: "custom"`

1861

1862 - `skill_id: string`

1863

1864 - `version: string`

1865

1866 - `system: string or null`

1867

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

1869

1870 - `BetaManagedAgentsAgentToolset20260401 object`

1871

1872 - `type: "agent_toolset_20260401"`

1873

1874 - `configs: array of BetaManagedAgentsAgentToolConfig`

1875

1876 - `BetaManagedAgentsBashToolConfig object`

1877

1878 Configuration for the bash tool.

1879

1880 - `type: "bash"`

1881

1882 - `enabled: boolean`

1883

1884 - `name: "bash"`

1885

1886 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1887

1888 Permission policy for tool execution.

1889

1890 - `BetaManagedAgentsAlwaysAllowPolicy object`

1891

1892 Tool calls are automatically approved without user confirmation.

1893

1894 - `type: "always_allow"`

1895

1896 - `BetaManagedAgentsAlwaysAskPolicy object`

1897

1898 Tool calls require user confirmation before execution.

1899

1900 - `type: "always_ask"`

1901

1902 - `BetaManagedAgentsAutoPolicy object`

1903

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

1905

1906 - `type: "auto"`

1907

1908 - `BetaManagedAgentsEditToolConfig object`

1909

1910 Configuration for the edit tool.

1911

1912 - `type: "edit"`

1913

1914 - `enabled: boolean`

1915

1916 - `name: "edit"`

1917

1918 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1919

1920 Permission policy for tool execution.

1921

1922 - `BetaManagedAgentsAlwaysAllowPolicy object`

1923

1924 Tool calls are automatically approved without user confirmation.

1925

1926 - `BetaManagedAgentsAlwaysAskPolicy object`

1927

1928 Tool calls require user confirmation before execution.

1929

1930 - `BetaManagedAgentsAutoPolicy object`

1931

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

1933

1934 - `BetaManagedAgentsReadToolConfig object`

1935

1936 Configuration for the read tool.

1937

1938 - `type: "read"`

1939

1940 - `enabled: boolean`

1941

1942 - `name: "read"`

1943

1944 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1945

1946 Permission policy for tool execution.

1947

1948 - `BetaManagedAgentsAlwaysAllowPolicy object`

1949

1950 Tool calls are automatically approved without user confirmation.

1951

1952 - `BetaManagedAgentsAlwaysAskPolicy object`

1953

1954 Tool calls require user confirmation before execution.

1955

1956 - `BetaManagedAgentsAutoPolicy object`

1957

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

1959

1960 - `BetaManagedAgentsWriteToolConfig object`

1961

1962 Configuration for the write tool.

1963

1964 - `type: "write"`

1965

1966 - `enabled: boolean`

1967

1968 - `name: "write"`

1969

1970 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1971

1972 Permission policy for tool execution.

1973

1974 - `BetaManagedAgentsAlwaysAllowPolicy object`

1975

1976 Tool calls are automatically approved without user confirmation.

1977

1978 - `BetaManagedAgentsAlwaysAskPolicy object`

1979

1980 Tool calls require user confirmation before execution.

1981

1982 - `BetaManagedAgentsAutoPolicy object`

1983

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

1985

1986 - `BetaManagedAgentsGlobToolConfig object`

1987

1988 Configuration for the glob tool.

1989

1990 - `type: "glob"`

1991

1992 - `enabled: boolean`

1993

1994 - `name: "glob"`

1995

1996 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

1997

1998 Permission policy for tool execution.

1999

2000 - `BetaManagedAgentsAlwaysAllowPolicy object`

2001

2002 Tool calls are automatically approved without user confirmation.

2003

2004 - `BetaManagedAgentsAlwaysAskPolicy object`

2005

2006 Tool calls require user confirmation before execution.

2007

2008 - `BetaManagedAgentsAutoPolicy object`

2009

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

2011

2012 - `BetaManagedAgentsGrepToolConfig object`

2013

2014 Configuration for the grep tool.

2015

2016 - `type: "grep"`

2017

2018 - `enabled: boolean`

2019

2020 - `name: "grep"`

2021

2022 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2023

2024 Permission policy for tool execution.

2025

2026 - `BetaManagedAgentsAlwaysAllowPolicy object`

2027

2028 Tool calls are automatically approved without user confirmation.

2029

2030 - `BetaManagedAgentsAlwaysAskPolicy object`

2031

2032 Tool calls require user confirmation before execution.

2033

2034 - `BetaManagedAgentsAutoPolicy object`

2035

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

2037

2038 - `BetaManagedAgentsWebFetchToolConfig object`

2039

2040 Configuration for the web_fetch tool.

2041

2042 - `type: "web_fetch"`

2043

2044 - `enabled: boolean`

2045

2046 - `name: "web_fetch"`

2047

2048 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2049

2050 Permission policy for tool execution.

2051

2052 - `BetaManagedAgentsAlwaysAllowPolicy object`

2053

2054 Tool calls are automatically approved without user confirmation.

2055

2056 - `BetaManagedAgentsAlwaysAskPolicy object`

2057

2058 Tool calls require user confirmation before execution.

2059

2060 - `BetaManagedAgentsAutoPolicy object`

2061

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

2063

2064 - `allowed_domains: optional array of string`

2065

2066 - `blocked_domains: optional array of string`

2067

2068 - `max_content_tokens: optional number or null`

2069

2070 format: int32

2071

2072 - `BetaManagedAgentsWebSearchToolConfig object`

2073

2074 Configuration for the web_search tool.

2075

2076 - `type: "web_search"`

2077

2078 - `enabled: boolean`

2079

2080 - `name: "web_search"`

2081

2082 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2083

2084 Permission policy for tool execution.

2085

2086 - `BetaManagedAgentsAlwaysAllowPolicy object`

2087

2088 Tool calls are automatically approved without user confirmation.

2089

2090 - `BetaManagedAgentsAlwaysAskPolicy object`

2091

2092 Tool calls require user confirmation before execution.

2093

2094 - `BetaManagedAgentsAutoPolicy object`

2095

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

2097

2098 - `allowed_domains: optional array of string`

2099

2100 - `blocked_domains: optional array of string`

2101

2102 - `user_location: optional BetaManagedAgentsUserLocation or null`

2103

2104 Approximate user location for search result localization.

2105

2106 - `type: "approximate"`

2107

2108 Location precision. Only "approximate" is supported.

2109

2110 - `city: optional string or null`

2111

2112 City name.

2113

2114 minLength: 1, maxLength: 255

2115

2116 - `country: optional string or null`

2117

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

2119

2120 - `region: optional string or null`

2121

2122 Region or state name.

2123

2124 minLength: 1, maxLength: 255

2125

2126 - `timezone: optional string or null`

2127

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

2129

2130 minLength: 1, maxLength: 255

2131

2132 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`

2133

2134 Resolved default configuration for agent tools.

2135

2136 - `enabled: boolean`

2137

2138 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2139

2140 Permission policy for tool execution.

2141

2142 - `BetaManagedAgentsAlwaysAllowPolicy object`

2143

2144 Tool calls are automatically approved without user confirmation.

2145

2146 - `BetaManagedAgentsAlwaysAskPolicy object`

2147

2148 Tool calls require user confirmation before execution.

2149

2150 - `BetaManagedAgentsAutoPolicy object`

2151

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

2153

2154 - `BetaManagedAgentsMCPToolset object`

2155

2156 - `type: "mcp_toolset"`

2157

2158 - `configs: array of BetaManagedAgentsMCPToolConfig`

2159

2160 - `enabled: boolean`

2161

2162 - `name: string`

2163

2164 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2165

2166 Permission policy for tool execution.

2167

2168 - `BetaManagedAgentsAlwaysAllowPolicy object`

2169

2170 Tool calls are automatically approved without user confirmation.

2171

2172 - `BetaManagedAgentsAlwaysAskPolicy object`

2173

2174 Tool calls require user confirmation before execution.

2175

2176 - `BetaManagedAgentsAutoPolicy object`

2177

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

2179

2180 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

2181

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

2183

2184 - `enabled: boolean`

2185

2186 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`

2187

2188 Permission policy for tool execution.

2189

2190 - `BetaManagedAgentsAlwaysAllowPolicy object`

2191

2192 Tool calls are automatically approved without user confirmation.

2193

2194 - `BetaManagedAgentsAlwaysAskPolicy object`

2195

2196 Tool calls require user confirmation before execution.

2197

2198 - `BetaManagedAgentsAutoPolicy object`

2199

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

2201

2202 - `mcp_server_name: string`

2203

2204 - `BetaManagedAgentsCustomTool object`

2205

2206 A custom tool as returned in API responses.

2207

2208 - `type: "custom"`

2209

2210 - `description: string`

2211

2212 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

2213

2214 JSON Schema for custom tool input parameters.

2215

2216 - `type: "object"`

2217

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

2219

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

2221

2222 - `name: string`

2223

2224 - `version: number`

2225

2226 format: int32

2227

2228 - `BetaManagedAgentsAdvisor object`

2229

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

2231

2232 - `type: "advisor"`

2233

2234 - `model: string`

2235

2236 The advisor model id.

2237

2238 - `name: string`

2239

2240 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

2241

2242 - `BetaManagedAgentsAnthropicSkill object`

2243

2244 A resolved Anthropic-managed skill.

2245

2246 - `BetaManagedAgentsCustomSkill object`

2247

2248 A resolved user-created custom skill.

2249

2250 - `system: string or null`

2251

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

2253

2254 - `BetaManagedAgentsAgentToolset20260401 object`

2255

2256 - `BetaManagedAgentsMCPToolset object`

2257

2258 - `BetaManagedAgentsCustomTool object`

2259

2260 A custom tool as returned in API responses.

2261

2262 - `version: number`

2263

2264 format: int32

2265

2266 - `budget: optional BetaManagedAgentsBudgetLimit or null`

2267

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

2269

2270 - `type: "limit"`

2271

2272 - `max_list_cost: BetaMonetaryAmount`

2273

2274 A monetary amount in a specific currency.

2275

2276 - `amount: string`

2277

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

2279

2280 - `currency: BetaCurrency`

2281

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

2283

2284 - `metadata: optional map[string]`

2285

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

2287

2288 - `title: optional string or null`

2289

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

2291

2292 - `BetaManagedAgentsSystemMessageEvent object`

2293

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

2295

2296 - `type: "system.message"`

2297

2298 - `id: string`

2299

2300 Unique identifier for this event.

2301

2302 - `content: array of BetaManagedAgentsSystemContentBlock`

2303

2304 System content blocks. Text-only.

2305

2306 - `type: "text"`

2307

2308 - `text: string`

2309

2310 The text content.

2311

2312 minLength: 1

3382313

3392314 - `processed_at: optional string or null`

3402315

from line 2317

3422317

3432318 format: date-time

3442319

345 - `session_thread_id: optional string or null`

346

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

348

349 - `BetaManagedAgentsUserToolConfirmationEvent object`

350

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

352

353 - `id: string`

354

355 Unique identifier for this event.

356

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

358

359 UserToolConfirmationResult enum

360

361 - `"allow"`

362

363 - `"deny"`

364

365 - `tool_use_id: string`

366

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

368

369 - `type: "user.tool_confirmation"`

370

371 - `deny_message: optional string or null`

372

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

374

375 maxLength: 10000

376

377 - `processed_at: optional string or null`

378

379 A timestamp in RFC 3339 format

380

381 format: date-time

382

383 - `session_thread_id: optional string or null`

384

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

386

387 - `BetaManagedAgentsUserCustomToolResultEvent object`

388

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

390

391 - `id: string`

392

393 Unique identifier for this event.

394

395 - `custom_tool_use_id: string`

396

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

398

399 - `type: "user.custom_tool_result"`

400

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

402

403 The result content returned by the tool.

404

405 - `BetaManagedAgentsTextBlock object`

406

407 Regular text content.

408

409 - `BetaManagedAgentsImageBlock object`

410

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

412

413 - `BetaManagedAgentsDocumentBlock object`

414

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

416

417 - `BetaManagedAgentsSearchResultBlock object`

418

419 A block containing a web search result.

420

421 - `citations: BetaManagedAgentsSearchResultCitations`

422

423 Citation settings for a search result.

424

425 - `enabled: boolean`

426

427 Whether citations are enabled for this search result.

428

429 - `content: array of BetaManagedAgentsSearchResultContent`

430

431 Array of text content blocks from the search result.

432

433 - `text: string`

434

435 The text content.

436

437 minLength: 1

438

439 - `type: "text"`

440

441 - `source: string`

442

443 The URL source of the search result.

444

445 minLength: 1

446

447 - `title: string`

448

449 The title of the search result.

450

451 minLength: 1

452

453 - `type: "search_result"`

454

455 - `is_error: optional boolean or null`

456

457 Whether the tool execution resulted in an error.

458

459 - `processed_at: optional string or null`

460

461 A timestamp in RFC 3339 format

462

463 format: date-time

464

465 - `session_thread_id: optional string or null`

466

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

468

469 - `BetaManagedAgentsAgentCustomToolUseEvent object`

470

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

472

473 - `id: string`

474

475 Unique identifier for this event.

476

477 - `input: map[unknown]`

478

479 Input parameters for the tool call.

480

481 - `name: string`

482

483 Name of the custom tool being called.

484

485 - `processed_at: string`

486

487 A timestamp in RFC 3339 format

488

489 format: date-time

490

491 - `type: "agent.custom_tool_use"`

492

493 - `session_thread_id: optional string or null`

494

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

496

497 - `BetaManagedAgentsAgentMessageEvent object`

498

499 An agent response event in the session conversation.

500

501 - `id: string`

502

503 Unique identifier for this event.

504

505 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`

506

507 Array of text blocks comprising the agent response.

508

509 - `BetaManagedAgentsTextBlock object`

510

511 Regular text content.

512

513 - `BetaManagedAgentsRedactedBlock object`

514

515 Placeholder for content withheld by Anthropic model policy.

516

517 - `processed_at: string`

518

519 A timestamp in RFC 3339 format

520

521 format: date-time

522

523 - `type: "agent.message"`

524

525 - `BetaManagedAgentsAgentThinkingEvent object`

526

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

528

529 - `id: string`

530

531 Unique identifier for this event.

532

533 - `processed_at: string`

534

535 A timestamp in RFC 3339 format

536

537 format: date-time

538

539 - `type: "agent.thinking"`

540

541 - `BetaManagedAgentsAgentMCPToolUseEvent object`

542

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

544

545 - `id: string`

546

547 Unique identifier for this event.

548

549 - `input: map[unknown]`

550

551 Input parameters for the tool call.

552

553 - `mcp_server_name: string`

554

555 Name of the MCP server providing the tool.

556

557 - `name: string`

558

559 Name of the MCP tool being used.

560

561 - `processed_at: string`

562

563 A timestamp in RFC 3339 format

564

565 format: date-time

566

567 - `type: "agent.mcp_tool_use"`

568

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

570

571 AgentEvaluatedPermission enum

572

573 - `"allow"`

574

575 - `"ask"`

576

577 - `"deny"`

578

579 - `session_thread_id: optional string or null`

580

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

582

583 - `BetaManagedAgentsAgentMCPToolResultEvent object`

584

585 Event representing the result of an MCP tool execution.

586

587 - `id: string`

588

589 Unique identifier for this event.

590

591 - `mcp_tool_use_id: string`

592

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

594

595 - `processed_at: string`

596

597 A timestamp in RFC 3339 format

598

599 format: date-time

600

601 - `type: "agent.mcp_tool_result"`

602

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

604

605 The result content returned by the tool.

606

607 - `BetaManagedAgentsTextBlock object`

608

609 Regular text content.

610

611 - `BetaManagedAgentsImageBlock object`

612

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

614

615 - `BetaManagedAgentsDocumentBlock object`

616

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

618

619 - `BetaManagedAgentsSearchResultBlock object`

620

621 A block containing a web search result.

622

623 - `is_error: optional boolean or null`

624

625 Whether the tool execution resulted in an error.

626

627 - `BetaManagedAgentsAgentToolUseEvent object`

628

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

630

631 - `id: string`

632

633 Unique identifier for this event.

634

635 - `input: map[unknown]`

636

637 Input parameters for the tool call.

638

639 - `name: string`

640

641 Name of the agent tool being used.

642

643 - `processed_at: string`

644

645 A timestamp in RFC 3339 format

646

647 format: date-time

648

649 - `type: "agent.tool_use"`

650

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

652

653 AgentEvaluatedPermission enum

654

655 - `"allow"`

656

657 - `"ask"`

658

659 - `"deny"`

660

661 - `session_thread_id: optional string or null`

662

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

664

665 - `BetaManagedAgentsAgentToolResultEvent object`

666

667 Event representing the result of an agent tool execution.

668

669 - `id: string`

670

671 Unique identifier for this event.

672

673 - `processed_at: string`

674

675 A timestamp in RFC 3339 format

676

677 format: date-time

678

679 - `tool_use_id: string`

680

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

682

683 - `type: "agent.tool_result"`

684

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

686

687 The result content returned by the tool.

688

689 - `BetaManagedAgentsTextBlock object`

690

691 Regular text content.

692

693 - `BetaManagedAgentsImageBlock object`

694

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

696

697 - `BetaManagedAgentsDocumentBlock object`

698

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

700

701 - `BetaManagedAgentsSearchResultBlock object`

702

703 A block containing a web search result.

704

705 - `is_error: optional boolean or null`

706

707 Whether the tool execution resulted in an error.

708

709 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`

710

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

712

713 - `id: string`

714

715 Unique identifier for this event.

716

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

718

719 Message content blocks.

720

721 - `BetaManagedAgentsTextBlock object`

722

723 Regular text content.

724

725 - `BetaManagedAgentsImageBlock object`

726

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

728

729 - `BetaManagedAgentsDocumentBlock object`

730

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

732

733 - `BetaManagedAgentsRedactedBlock object`

734

735 Placeholder for content withheld by Anthropic model policy.

736

737 - `from_session_thread_id: string`

738

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

740

741 - `processed_at: string`

742

743 A timestamp in RFC 3339 format

744

745 format: date-time

746

747 - `type: "agent.thread_message_received"`

748

749 - `from_agent_name: optional string or null`

750

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

752

753 - `BetaManagedAgentsAgentThreadMessageSentEvent object`

754

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

756

757 - `id: string`

758

759 Unique identifier for this event.

760

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

762

763 Message content blocks.

764

765 - `BetaManagedAgentsTextBlock object`

766

767 Regular text content.

768

769 - `BetaManagedAgentsImageBlock object`

770

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

772

773 - `BetaManagedAgentsDocumentBlock object`

774

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

776

777 - `BetaManagedAgentsRedactedBlock object`

778

779 Placeholder for content withheld by Anthropic model policy.

780

781 - `processed_at: string`

782

783 A timestamp in RFC 3339 format

784

785 format: date-time

786

787 - `to_session_thread_id: string`

788

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

790

791 - `type: "agent.thread_message_sent"`

792

793 - `to_agent_name: optional string or null`

794

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

796

797 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`

798

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

800

801 - `id: string`

802

803 Unique identifier for this event.

804

805 - `processed_at: string`

806

807 A timestamp in RFC 3339 format

808

809 format: date-time

810

811 - `type: "agent.thread_context_compacted"`

812

813 - `BetaManagedAgentsSessionErrorEvent object`

814

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

816

817 - `id: string`

818

819 Unique identifier for this event.

820

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

822

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

824

825 - `BetaManagedAgentsUnknownError object`

826

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

828

829 - `message: string`

830

831 Human-readable error description.

832

833 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

834

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

836

837 - `BetaManagedAgentsRetryStatusRetrying object`

838

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

840

841 - `type: "retrying"`

842

843 - `BetaManagedAgentsRetryStatusExhausted object`

844

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

846

847 - `type: "exhausted"`

848

849 - `BetaManagedAgentsRetryStatusTerminal object`

850

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

852

853 - `type: "terminal"`

854

855 - `type: "unknown_error"`

856

857 - `BetaManagedAgentsModelOverloadedError object`

858

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

860

861 - `message: string`

862

863 Human-readable error description.

864

865 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

866

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

868

869 - `BetaManagedAgentsRetryStatusRetrying object`

870

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

872

873 - `BetaManagedAgentsRetryStatusExhausted object`

874

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

876

877 - `BetaManagedAgentsRetryStatusTerminal object`

878

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

880

881 - `type: "model_overloaded_error"`

882

883 - `BetaManagedAgentsModelRateLimitedError object`

884

885 The model request was rate-limited.

886

887 - `message: string`

888

889 Human-readable error description.

890

891 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

892

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

894

895 - `BetaManagedAgentsRetryStatusRetrying object`

896

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

898

899 - `BetaManagedAgentsRetryStatusExhausted object`

900

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

902

903 - `BetaManagedAgentsRetryStatusTerminal object`

904

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

906

907 - `type: "model_rate_limited_error"`

908

909 - `BetaManagedAgentsModelRequestFailedError object`

910

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

912

913 - `message: string`

914

915 Human-readable error description.

916

917 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

918

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

920

921 - `BetaManagedAgentsRetryStatusRetrying object`

922

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

924

925 - `BetaManagedAgentsRetryStatusExhausted object`

926

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

928

929 - `BetaManagedAgentsRetryStatusTerminal object`

930

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

932

933 - `type: "model_request_failed_error"`

934

935 - `BetaManagedAgentsMCPConnectionFailedError object`

936

937 Failed to connect to an MCP server.

938

939 - `mcp_server_name: string`

940

941 Name of the MCP server that failed to connect.

942

943 - `message: string`

944

945 Human-readable error description.

946

947 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

948

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

950

951 - `BetaManagedAgentsRetryStatusRetrying object`

952

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

954

955 - `BetaManagedAgentsRetryStatusExhausted object`

956

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

958

959 - `BetaManagedAgentsRetryStatusTerminal object`

960

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

962

963 - `type: "mcp_connection_failed_error"`

964

965 - `BetaManagedAgentsMCPAuthenticationFailedError object`

966

967 Authentication to an MCP server failed.

968

969 - `mcp_server_name: string`

970

971 Name of the MCP server that failed authentication.

972

973 - `message: string`

974

975 Human-readable error description.

976

977 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

978

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

980

981 - `BetaManagedAgentsRetryStatusRetrying object`

982

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

984

985 - `BetaManagedAgentsRetryStatusExhausted object`

986

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

988

989 - `BetaManagedAgentsRetryStatusTerminal object`

990

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

992

993 - `type: "mcp_authentication_failed_error"`

994

995 - `BetaManagedAgentsBillingError object`

996

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

998

999 - `message: string`

1000

1001 Human-readable error description.

1002

1003 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1004

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

1006

1007 - `BetaManagedAgentsRetryStatusRetrying object`

1008

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

1010

1011 - `BetaManagedAgentsRetryStatusExhausted object`

1012

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

1014

1015 - `BetaManagedAgentsRetryStatusTerminal object`

1016

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

1018

1019 - `type: "billing_error"`

1020

1021 - `BetaManagedAgentsCredentialHostUnreachableError object`

1022

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

1024

1025 - `credential_id: string`

1026

1027 ID of the affected credential.

1028

1029 - `message: string`

1030

1031 Human-readable error description.

1032

1033 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`

1034

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

1036

1037 - `BetaManagedAgentsRetryStatusRetrying object`

1038

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

1040

1041 - `BetaManagedAgentsRetryStatusExhausted object`

1042

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

1044

1045 - `BetaManagedAgentsRetryStatusTerminal object`

1046

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

1048

1049 - `type: "credential_host_unreachable_error"`

1050

1051 - `vault_id: string`

1052

1053 ID of the vault containing the affected credential.

1054

1055 - `processed_at: string`

1056

1057 A timestamp in RFC 3339 format

1058

1059 format: date-time

1060

1061 - `type: "session.error"`

1062

1063 - `BetaManagedAgentsSessionStatusRescheduledEvent object`

1064

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

1066

1067 - `id: string`

1068

1069 Unique identifier for this event.

1070

1071 - `processed_at: string`

1072

1073 A timestamp in RFC 3339 format

1074

1075 format: date-time

1076

1077 - `type: "session.status_rescheduled"`

1078

1079 - `BetaManagedAgentsSessionStatusRunningEvent object`

1080

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

1082

1083 - `id: string`

1084

1085 Unique identifier for this event.

1086

1087 - `processed_at: string`

1088

1089 A timestamp in RFC 3339 format

1090

1091 format: date-time

1092

1093 - `type: "session.status_running"`

1094

1095 - `BetaManagedAgentsSessionStatusIdleEvent object`

1096

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

1098

1099 - `id: string`

1100

1101 Unique identifier for this event.

1102

1103 - `processed_at: string`

1104

1105 A timestamp in RFC 3339 format

1106

1107 format: date-time

1108

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

1110

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

1112

1113 - `BetaManagedAgentsSessionEndTurn object`

1114

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

1116

1117 - `type: "end_turn"`

1118

1119 - `BetaManagedAgentsSessionRequiresAction object`

1120

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

1122

1123 - `event_ids: array of string`

1124

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

1126

1127 - `type: "requires_action"`

1128

1129 - `BetaManagedAgentsSessionRetriesExhausted object`

1130

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

1132

1133 - `type: "retries_exhausted"`

1134

1135 - `BetaManagedAgentsSessionBudgetReached object`

1136

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

1138

1139 - `type: "budget_reached"`

1140

1141 - `type: "session.status_idle"`

1142

1143 - `BetaManagedAgentsSessionStatusTerminatedEvent object`

1144

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

1146

1147 - `id: string`

1148

1149 Unique identifier for this event.

1150

1151 - `processed_at: string`

1152

1153 A timestamp in RFC 3339 format

1154

1155 format: date-time

1156

1157 - `type: "session.status_terminated"`

1158

1159 - `BetaManagedAgentsSessionThreadCreatedEvent object`

1160

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

1162

1163 - `id: string`

1164

1165 Unique identifier for this event.

1166

1167 - `agent_name: string`

1168

1169 Name of the callable agent the thread runs.

1170

1171 - `processed_at: string`

1172

1173 A timestamp in RFC 3339 format

1174

1175 format: date-time

1176

1177 - `session_thread_id: string`

1178

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

1180

1181 - `type: "session.thread_created"`

1182

1183 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`

1184

1185 Emitted when an outcome evaluation cycle begins.

1186

1187 - `id: string`

1188

1189 Unique identifier for this event.

1190

1191 - `iteration: number`

1192

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

1194

1195 format: int32

1196

1197 - `outcome_id: string`

1198

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

1200

1201 - `processed_at: string`

1202

1203 A timestamp in RFC 3339 format

1204

1205 format: date-time

1206

1207 - `type: "span.outcome_evaluation_start"`

1208

1209 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`

1210

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

1212

1213 - `id: string`

1214

1215 Unique identifier for this event.

1216

1217 - `explanation: string`

1218

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

1220

1221 - `iteration: number`

1222

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

1224

1225 format: int32

1226

1227 - `outcome_evaluation_start_id: string`

1228

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

1230

1231 - `outcome_id: string`

1232

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

1234

1235 - `processed_at: string`

1236

1237 A timestamp in RFC 3339 format

1238

1239 format: date-time

1240

1241 - `result: string`

1242

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

1244

1245 - `type: "span.outcome_evaluation_end"`

1246

1247 - `usage: BetaManagedAgentsSpanModelUsage`

1248

1249 Token usage for a single model request.

1250

1251 - `cache_creation_input_tokens: number`

1252

1253 Tokens used to create prompt cache in this request.

1254

1255 format: int32

1256

1257 - `cache_read_input_tokens: number`

1258

1259 Tokens read from prompt cache in this request.

1260

1261 format: int32

1262

1263 - `input_tokens: number`

1264

1265 Input tokens consumed by this request.

1266

1267 format: int32

1268

1269 - `output_tokens: number`

1270

1271 Output tokens generated by this request.

1272

1273 format: int32

1274

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

1276

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

1278

1279 - `"standard"`

1280

1281 - `"fast"`

1282

1283 - `BetaManagedAgentsSpanModelRequestStartEvent object`

1284

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

1286

1287 - `id: string`

1288

1289 Unique identifier for this event.

1290

1291 - `processed_at: string`

1292

1293 A timestamp in RFC 3339 format

1294

1295 format: date-time

1296

1297 - `type: "span.model_request_start"`

1298

1299 - `BetaManagedAgentsSpanModelRequestEndEvent object`

1300

1301 Emitted when a model request completes.

1302

1303 - `id: string`

1304

1305 Unique identifier for this event.

1306

1307 - `is_error: boolean or null`

1308

1309 Whether the model request resulted in an error.

1310

1311 - `model_request_start_id: string`

1312

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

1314

1315 - `model_usage: BetaManagedAgentsSpanModelUsage`

1316

1317 Token usage for a single model request.

1318

1319 - `processed_at: string`

1320

1321 A timestamp in RFC 3339 format

1322

1323 format: date-time

1324

1325 - `type: "span.model_request_end"`

1326

1327 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`

1328

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

1330

1331 - `id: string`

1332

1333 Unique identifier for this event.

1334

1335 - `iteration: number`

1336

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

1338

1339 format: int32

1340

1341 - `outcome_id: string`

1342

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

1344

1345 - `processed_at: string`

1346

1347 A timestamp in RFC 3339 format

1348

1349 format: date-time

1350

1351 - `type: "span.outcome_evaluation_ongoing"`

1352

1353 - `BetaManagedAgentsUserDefineOutcomeEvent object`

1354

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

1356

1357 - `id: string`

1358

1359 Unique identifier for this event.

1360

1361 - `description: string`

1362

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

1364

1365 - `max_iterations: number or null`

1366

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

1368

1369 format: int32

1370

1371 - `outcome_id: string`

1372

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

1374

1375 - `processed_at: string`

1376

1377 A timestamp in RFC 3339 format

1378

1379 format: date-time

1380

1381 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`

1382

1383 Rubric for grading the quality of an outcome.

1384

1385 - `BetaManagedAgentsFileRubric object`

1386

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

1388

1389 - `file_id: string`

1390

1391 ID of the rubric file.

1392

1393 - `type: "file"`

1394

1395 - `BetaManagedAgentsTextRubric object`

1396

1397 Rubric content provided inline as text.

1398

1399 - `content: string`

1400

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

1402

1403 - `type: "text"`

1404

1405 - `type: "user.define_outcome"`

1406

1407 - `BetaManagedAgentsSessionDeletedEvent object`

1408

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

1410

1411 - `id: string`

1412

1413 Unique identifier for this event.

1414

1415 - `processed_at: string`

1416

1417 A timestamp in RFC 3339 format

1418

1419 format: date-time

1420

1421 - `type: "session.deleted"`

1422

1423 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`

1424

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

1426

1427 - `id: string`

1428

1429 Unique identifier for this event.

1430

1431 - `agent_name: string`

1432

1433 Name of the agent the thread runs.

1434

1435 - `processed_at: string`

1436

1437 A timestamp in RFC 3339 format

1438

1439 format: date-time

1440

1441 - `session_thread_id: string`

1442

1443 Public sthr_ ID of the thread that started running.

1444

1445 - `type: "session.thread_status_running"`

1446

1447 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`

1448

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

1450

1451 - `id: string`

1452

1453 Unique identifier for this event.

1454

1455 - `agent_name: string`

1456

1457 Name of the agent the thread runs.

1458

1459 - `processed_at: string`

1460

1461 A timestamp in RFC 3339 format

1462

1463 format: date-time

1464

1465 - `session_thread_id: string`

1466

1467 Public sthr_ ID of the thread that went idle.

1468

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

1470

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

1472

1473 - `BetaManagedAgentsSessionEndTurn object`

1474

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

1476

1477 - `BetaManagedAgentsSessionRequiresAction object`

1478

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

1480

1481 - `BetaManagedAgentsSessionRetriesExhausted object`

1482

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

1484

1485 - `BetaManagedAgentsSessionBudgetReached object`

1486

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

1488

1489 - `type: "session.thread_status_idle"`

1490

1491 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`

1492

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

1494

1495 - `id: string`

1496

1497 Unique identifier for this event.

1498

1499 - `agent_name: string`

1500

1501 Name of the agent the thread runs.

1502

1503 - `processed_at: string`

1504

1505 A timestamp in RFC 3339 format

1506

1507 format: date-time

1508

1509 - `session_thread_id: string`

1510

1511 Public sthr_ ID of the thread that terminated.

1512

1513 - `type: "session.thread_status_terminated"`

1514

1515 - `BetaManagedAgentsUserToolResultEvent object`

1516

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

1518

1519 - `id: string`

1520

1521 Unique identifier for this event.

1522

1523 - `tool_use_id: string`

1524

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

1526

1527 - `type: "user.tool_result"`

1528

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

1530

1531 The result content returned by the tool.

1532

1533 - `BetaManagedAgentsTextBlock object`

1534

1535 Regular text content.

1536

1537 - `BetaManagedAgentsImageBlock object`

1538

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

1540

1541 - `BetaManagedAgentsDocumentBlock object`

1542

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

1544

1545 - `BetaManagedAgentsSearchResultBlock object`

1546

1547 A block containing a web search result.

1548

1549 - `is_error: optional boolean or null`

1550

1551 Whether the tool execution resulted in an error.

1552

1553 - `processed_at: optional string or null`

1554

1555 A timestamp in RFC 3339 format

1556

1557 format: date-time

1558

1559 - `session_thread_id: optional string or null`

1560

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

1562

1563 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`

1564

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

1566

1567 - `id: string`

1568

1569 Unique identifier for this event.

1570

1571 - `agent_name: string`

1572

1573 Name of the agent the thread runs.

1574

1575 - `processed_at: string`

1576

1577 A timestamp in RFC 3339 format

1578

1579 format: date-time

1580

1581 - `session_thread_id: string`

1582

1583 Public sthr_ ID of the thread that is retrying.

1584

1585 - `type: "session.thread_status_rescheduled"`

1586

1587 - `BetaManagedAgentsSessionUpdatedEvent object`

1588

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

1590

1591 - `id: string`

1592

1593 Unique identifier for this event.

1594

1595 - `processed_at: string`

1596

1597 A timestamp in RFC 3339 format

1598

1599 format: date-time

1600

1601 - `type: "session.updated"`

1602

1603 - `agent: optional BetaManagedAgentsSessionAgent or null`

1604

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

1606

1607 - `id: string`

1608

1609 - `description: string or null`

1610

1611 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1612

1613 - `name: string`

1614

1615 - `type: "url"`

1616

1617 - `url: string`

1618

1619 - `model: BetaManagedAgentsModelConfig`

1620

1621 Model identifier and configuration.

1622

1623 - `id: BetaManagedAgentsModel`

1624

1625 The model that will power your agent.

1626

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

1628

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

1630

1631 The model that will power your agent.

1632

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

1634

1635 - `"claude-fable-5-1"`

1636

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

1638

1639 - `"claude-sonnet-5"`

1640

1641 High-performance model for coding and agents

1642

1643 - `"claude-fable-5"`

1644

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

1646

1647 - `"claude-opus-5"`

1648

1649 Powerful intelligence for long-running agents and coding

1650

1651 - `"claude-opus-4-8"`

1652

1653 Powerful intelligence for long-running agents and coding

1654

1655 - `"claude-opus-4-7"`

1656

1657 Powerful intelligence for long-running agents and coding

1658

1659 - `"claude-opus-4-6"`

1660

1661 Powerful intelligence for long-running agents and coding

1662

1663 - `"claude-sonnet-4-6"`

1664

1665 Best combination of speed and intelligence

1666

1667 - `"claude-haiku-4-5"`

1668

1669 Fastest model with near-frontier intelligence

1670

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

1672

1673 Fastest model with near-frontier intelligence

1674

1675 - `"claude-opus-4-5"`

1676

1677 Powerful intelligence for long-running agents and coding

1678

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

1680

1681 Powerful intelligence for long-running agents and coding

1682

1683 - `"claude-sonnet-4-5"`

1684

1685 High-performance model for agents and coding

1686

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

1688

1689 High-performance model for agents and coding

1690

1691 - `string`

1692

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

1694

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

1696

1697 - `BetaManagedAgentsEffortLow object`

1698

1699 Low effort. Favors latency over reasoning depth.

1700

1701 - `type: "low"`

1702

1703 - `BetaManagedAgentsEffortMedium object`

1704

1705 Medium effort. Balances latency and reasoning depth.

1706

1707 - `type: "medium"`

1708

1709 - `BetaManagedAgentsEffortHigh object`

1710

1711 High effort. Favors reasoning depth.

1712

1713 - `type: "high"`

1714

1715 - `BetaManagedAgentsEffortXhigh object`

1716

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

1718

1719 - `type: "xhigh"`

1720

1721 - `BetaManagedAgentsEffortMax object`

1722

1723 Maximum effort. Favors reasoning depth over latency.

1724

1725 - `type: "max"`

1726

1727 - `inference_geo: optional string`

1728

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

1730

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

1732

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

1734

1735 - `"standard"`

1736

1737 - `"fast"`

1738

1739 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`

1740

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

1742

1743 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`

1744

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

1746

1747 - `BetaManagedAgentsSessionThreadAgent object`

1748

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

1750

1751 - `id: string`

1752

1753 - `description: string or null`

1754

1755 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`

1756

1757 - `name: string`

1758

1759 - `type: "url"`

1760

1761 - `url: string`

1762

1763 - `model: BetaManagedAgentsModelConfig`

1764

1765 Model identifier and configuration.

1766

1767 - `name: string`

1768

1769 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

1770

1771 - `BetaManagedAgentsAnthropicSkill object`

1772

1773 A resolved Anthropic-managed skill.

1774

1775 - `skill_id: string`

1776

1777 - `type: "anthropic"`

1778

1779 - `version: string`

1780

1781 - `BetaManagedAgentsCustomSkill object`

1782

1783 A resolved user-created custom skill.

1784

1785 - `skill_id: string`

1786

1787 - `type: "custom"`

1788

1789 - `version: string`

1790

1791 - `system: string or null`

1792

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

1794

1795 - `BetaManagedAgentsAgentToolset20260401 object`

1796

1797 - `configs: array of BetaManagedAgentsAgentToolConfig`

1798

1799 - `BetaManagedAgentsBashToolConfig object`

1800

1801 Configuration for the bash tool.

1802

1803 - `enabled: boolean`

1804

1805 - `name: "bash"`

1806

1807 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1808

1809 Permission policy for tool execution.

1810

1811 - `BetaManagedAgentsAlwaysAllowPolicy object`

1812

1813 Tool calls are automatically approved without user confirmation.

1814

1815 - `type: "always_allow"`

1816

1817 - `BetaManagedAgentsAlwaysAskPolicy object`

1818

1819 Tool calls require user confirmation before execution.

1820

1821 - `type: "always_ask"`

1822

1823 - `type: "bash"`

1824

1825 - `BetaManagedAgentsEditToolConfig object`

1826

1827 Configuration for the edit tool.

1828

1829 - `enabled: boolean`

1830

1831 - `name: "edit"`

1832

1833 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1834

1835 Permission policy for tool execution.

1836

1837 - `BetaManagedAgentsAlwaysAllowPolicy object`

1838

1839 Tool calls are automatically approved without user confirmation.

1840

1841 - `BetaManagedAgentsAlwaysAskPolicy object`

1842

1843 Tool calls require user confirmation before execution.

1844

1845 - `type: "edit"`

1846

1847 - `BetaManagedAgentsReadToolConfig object`

1848

1849 Configuration for the read tool.

1850

1851 - `enabled: boolean`

1852

1853 - `name: "read"`

1854

1855 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1856

1857 Permission policy for tool execution.

1858

1859 - `BetaManagedAgentsAlwaysAllowPolicy object`

1860

1861 Tool calls are automatically approved without user confirmation.

1862

1863 - `BetaManagedAgentsAlwaysAskPolicy object`

1864

1865 Tool calls require user confirmation before execution.

1866

1867 - `type: "read"`

1868

1869 - `BetaManagedAgentsWriteToolConfig object`

1870

1871 Configuration for the write tool.

1872

1873 - `enabled: boolean`

1874

1875 - `name: "write"`

1876

1877 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1878

1879 Permission policy for tool execution.

1880

1881 - `BetaManagedAgentsAlwaysAllowPolicy object`

1882

1883 Tool calls are automatically approved without user confirmation.

1884

1885 - `BetaManagedAgentsAlwaysAskPolicy object`

1886

1887 Tool calls require user confirmation before execution.

1888

1889 - `type: "write"`

1890

1891 - `BetaManagedAgentsGlobToolConfig object`

1892

1893 Configuration for the glob tool.

1894

1895 - `enabled: boolean`

1896

1897 - `name: "glob"`

1898

1899 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1900

1901 Permission policy for tool execution.

1902

1903 - `BetaManagedAgentsAlwaysAllowPolicy object`

1904

1905 Tool calls are automatically approved without user confirmation.

1906

1907 - `BetaManagedAgentsAlwaysAskPolicy object`

1908

1909 Tool calls require user confirmation before execution.

1910

1911 - `type: "glob"`

1912

1913 - `BetaManagedAgentsGrepToolConfig object`

1914

1915 Configuration for the grep tool.

1916

1917 - `enabled: boolean`

1918

1919 - `name: "grep"`

1920

1921 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1922

1923 Permission policy for tool execution.

1924

1925 - `BetaManagedAgentsAlwaysAllowPolicy object`

1926

1927 Tool calls are automatically approved without user confirmation.

1928

1929 - `BetaManagedAgentsAlwaysAskPolicy object`

1930

1931 Tool calls require user confirmation before execution.

1932

1933 - `type: "grep"`

1934

1935 - `BetaManagedAgentsWebFetchToolConfig object`

1936

1937 Configuration for the web_fetch tool.

1938

1939 - `enabled: boolean`

1940

1941 - `name: "web_fetch"`

1942

1943 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1944

1945 Permission policy for tool execution.

1946

1947 - `BetaManagedAgentsAlwaysAllowPolicy object`

1948

1949 Tool calls are automatically approved without user confirmation.

1950

1951 - `BetaManagedAgentsAlwaysAskPolicy object`

1952

1953 Tool calls require user confirmation before execution.

1954

1955 - `type: "web_fetch"`

1956

1957 - `allowed_domains: optional array of string`

1958

1959 - `blocked_domains: optional array of string`

1960

1961 - `max_content_tokens: optional number or null`

1962

1963 format: int32

1964

1965 - `BetaManagedAgentsWebSearchToolConfig object`

1966

1967 Configuration for the web_search tool.

1968

1969 - `enabled: boolean`

1970

1971 - `name: "web_search"`

1972

1973 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

1974

1975 Permission policy for tool execution.

1976

1977 - `BetaManagedAgentsAlwaysAllowPolicy object`

1978

1979 Tool calls are automatically approved without user confirmation.

1980

1981 - `BetaManagedAgentsAlwaysAskPolicy object`

1982

1983 Tool calls require user confirmation before execution.

1984

1985 - `type: "web_search"`

1986

1987 - `allowed_domains: optional array of string`

1988

1989 - `blocked_domains: optional array of string`

1990

1991 - `user_location: optional BetaManagedAgentsUserLocation or null`

1992

1993 Approximate user location for search result localization.

1994

1995 - `type: "approximate"`

1996

1997 Location precision. Only "approximate" is supported.

1998

1999 - `city: optional string or null`

2000

2001 City name.

2002

2003 minLength: 1, maxLength: 255

2004

2005 - `country: optional string or null`

2006

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

2008

2009 - `region: optional string or null`

2010

2011 Region or state name.

2012

2013 minLength: 1, maxLength: 255

2014

2015 - `timezone: optional string or null`

2016

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

2018

2019 minLength: 1, maxLength: 255

2020

2021 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`

2022

2023 Resolved default configuration for agent tools.

2024

2025 - `enabled: boolean`

2026

2027 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

2028

2029 Permission policy for tool execution.

2030

2031 - `BetaManagedAgentsAlwaysAllowPolicy object`

2032

2033 Tool calls are automatically approved without user confirmation.

2034

2035 - `BetaManagedAgentsAlwaysAskPolicy object`

2036

2037 Tool calls require user confirmation before execution.

2038

2039 - `type: "agent_toolset_20260401"`

2040

2041 - `BetaManagedAgentsMCPToolset object`

2042

2043 - `configs: array of BetaManagedAgentsMCPToolConfig`

2044

2045 - `enabled: boolean`

2046

2047 - `name: string`

2048

2049 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

2050

2051 Permission policy for tool execution.

2052

2053 - `BetaManagedAgentsAlwaysAllowPolicy object`

2054

2055 Tool calls are automatically approved without user confirmation.

2056

2057 - `BetaManagedAgentsAlwaysAskPolicy object`

2058

2059 Tool calls require user confirmation before execution.

2060

2061 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`

2062

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

2064

2065 - `enabled: boolean`

2066

2067 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`

2068

2069 Permission policy for tool execution.

2070

2071 - `BetaManagedAgentsAlwaysAllowPolicy object`

2072

2073 Tool calls are automatically approved without user confirmation.

2074

2075 - `BetaManagedAgentsAlwaysAskPolicy object`

2076

2077 Tool calls require user confirmation before execution.

2078

2079 - `mcp_server_name: string`

2080

2081 - `type: "mcp_toolset"`

2082

2083 - `BetaManagedAgentsCustomTool object`

2084

2085 A custom tool as returned in API responses.

2086

2087 - `description: string`

2088

2089 - `input_schema: BetaManagedAgentsCustomToolInputSchema`

2090

2091 JSON Schema for custom tool input parameters.

2092

2093 - `type: "object"`

2094

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

2096

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

2098

2099 - `name: string`

2100

2101 - `type: "custom"`

2102

2103 - `type: "agent"`

2104

2105 - `version: number`

2106

2107 format: int32

2108

2109 - `BetaManagedAgentsAdvisor object`

2110

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

2112

2113 - `model: string`

2114

2115 The advisor model id.

2116

2117 - `type: "advisor"`

2118

2119 - `type: "coordinator"`

2120

2121 - `name: string`

2122

2123 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`

2124

2125 - `BetaManagedAgentsAnthropicSkill object`

2126

2127 A resolved Anthropic-managed skill.

2128

2129 - `BetaManagedAgentsCustomSkill object`

2130

2131 A resolved user-created custom skill.

2132

2133 - `system: string or null`

2134

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

2136

2137 - `BetaManagedAgentsAgentToolset20260401 object`

2138

2139 - `BetaManagedAgentsMCPToolset object`

2140

2141 - `BetaManagedAgentsCustomTool object`

2142

2143 A custom tool as returned in API responses.

2144

2145 - `type: "agent"`

2146

2147 - `version: number`

2148

2149 format: int32

2150

2151 - `budget: optional BetaManagedAgentsBudgetLimit or null`

2152

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

2154

2155 - `max_list_cost: BetaMonetaryAmount`

2156

2157 A monetary amount in a specific currency.

2158

2159 - `amount: string`

2160

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

2162

2163 - `currency: BetaCurrency`

2164

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

2166

2167 - `type: "limit"`

2168

2169 - `metadata: optional map[string]`

2170

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

2172

2173 - `title: optional string or null`

2174

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

2176

2177 - `BetaManagedAgentsSystemMessageEvent object`

2178

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

2180

2181 - `id: string`

2182

2183 Unique identifier for this event.

2184

2185 - `content: array of BetaManagedAgentsSystemContentBlock`

2186

2187 System content blocks. Text-only.

2188

2189 - `text: string`

2190

2191 The text content.

2192

2193 minLength: 1

2194

2195 - `type: "text"`

2196

2197 - `type: "system.message"`

2198

2199 - `processed_at: optional string or null`

2200

2201 A timestamp in RFC 3339 format

2202

2203 format: date-time

2204

22052320 - `BetaManagedAgentsSessionUsageEvent object`

22062321

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

22082323

2209 - `id: string`

2210

2211 Unique identifier for this event.

2212

2213 - `processed_at: string`

2214

2215 A timestamp in RFC 3339 format

2216

2217 format: date-time

2218

22192324 - `type: "session.usage"`

2325

2326 - `id: string`

2327

2328 Unique identifier for this event.

2329

2330 - `processed_at: string`

2331

2332 A timestamp in RFC 3339 format

2333

2334 format: date-time

22202335

22212336 - `usage: BetaManagedAgentsSessionUsageSnapshot`

22222337

22232338

This page’s history 11 edits

21 Sep 2026 +4 −2
16 Sep 2026 +3 −1
15 Sep 2026 +6 −6
11 Sep 2026 +0 −6
10 Sep 2026 +2122 −2007 · this one
1 Sep 2026 +14 −4

The page’s own history →

Where it came from

The captureapi
Upstream pageplatform.claude.com

List Events changed

The whole hunk