managed-agents-events

# 托管智能体 — 事件与引导 ## 事件 ### 发送事件 通过 `POST /v1/sessions/{id}/events` 向会话发送事件。 | 事件类型 | 发送时机 | | ------------------------- | --------------------------------------------------- | | `user.message` | 发送用户消息 | | `user.interrupt` | 在智能体运行时中断它 | | `user.tool_confirmation` | 批准/拒绝工具调用（当策略为 `always_ask` 时） | | `user.custom_tool_result` | 为自定义工具调用提供结果 | ### 接收事件 两种方法： 1. **流式传输 (SSE)**: `GET /v1/sessions/{id}/events/stream` — 实时服务器发送事件。**长连接** — 服务器定期发送心跳以保持连接活跃。 2. **轮询**: `GET /v1/sessions/{id}/events` — 分页事件列表（查询参数：`limit` 默认 1000，`page`）。**立即返回** — 这是普通的 HTTP GET，不是长轮询。 所有接收到的事件都带有 `id`、`type` 和 `processed_at` (ISO 8601; 如果尚未被智能体处理则为 `null`)。 > ⚠️ **健壮的轮询（原始 HTTP）。** 如果您绕过 SDK 并自行编写轮询循环，请不要依赖 `requests` 或 `httpx` 的超时作为总时长限制 — 它们是**分块**读取超时，每次收到字节时都会重置。涓流响应（心跳、卡住的分块编码主体、行为异常的代理）即使在 `timeout=(5, 60)` 或 `httpx.Timeout(120)` 下也可能使调用无限期阻塞。这两个库都没有内置“总墙上时钟”超时。对于硬性截止时间：在循环级别跟踪 `time.monotonic()`，如果单个请求超过您的预算，则中断/取消（例如通过看门狗线程，或在异步 httpx 周围使用 `asyncio.wait_for()`）。**优先使用 SDK** — `client.beta.sessions.events.stream()` 和 `client.beta.sessions.events.list()` 可以合理地处理超时和重试。 > > 如果 `GET /v1/sessions/{id}/events` (分页) 在头部之后挂起，您很可能错误地访问了 `GET /v1/sessions/{id}/events/stream` 或遇到了服务端停滞 — 请报告它；不要将其视为客户端配置问题。 ### 事件类型 (接收) 事件类型使用点符号，按命名空间分组： | 事件类型 | 说明 | | --- | --- | | `agent.message` | 智能体文本输出 | | `agent.thinking` | 扩展思考块 | | `agent.tool_use` | 智能体使用了内置工具 (`agent_toolset_20260401`) | | `agent.tool_result` | 内置工具的结果 | | `agent.mcp_tool_use` | 智能体使用了 MCP 工具 | | `age