stream: true,即可在事件发生时实时接收,而不必等待完整响应。
SSE 与 OpenAI 和 Anthropic 使用的协议相同——任何能解析 text/event-stream 的 HTTP 客户端都可以使用。SDK 会将其封装为一个异步可迭代对象。
为什么要使用流式?
- 快速模式下首个令牌延迟低于 300ms——用户能立即看到输出,而不是干等一个加载动画。
- 智能体循环的透明度——
tool和artifact事件会在 Theo 使用工具或生成文件的那一刻触发,因此你可以渲染出实时的”Theo 正在浏览…”或”已生成图片”卡片。 - 优雅的取消——关闭 HTTP 连接(或在 SDK 中调用
stream.cancel())即可停止为不想要的令牌计费。
事件流
一次正常的对话轮次会按以下顺序发出事件:thinking—— 一个心跳信号,用于让代理服务器刷新响应。meta—— 解析后的模式、品牌化的模型、路由遥测信息、conversation_id、request_id。skills(可选)—— 本轮触发了哪些技能。genui_meta(可选)—— 仅当resolved_mode === "genui"时出现。tool/artifact—— 随发生顺序出现(可能交错)。token—— 每个文本块一个。done—— 完整内容、后续建议、用量、conversation_id、request_id。
error 事件,其负载与 REST 错误信封格式一致({ error: { message, type, code, request_id } }),随后关闭流。无需特殊处理——复用你现有的 HTTP 错误处理路径即可。
关于各事件的 JSON schema、传输格式规则,以及流式过程中出现 429 的示例,请参见流式补全(API 参考)。
SDK 流式
SDK 会返回一个TheoStream。它是异步可迭代的,因此可以直接使用 for await。流结束后,它会以属性形式暴露 conversationId、usage、model 和 requestId。
在生成过程中取消
TheoStream.cancel() 会中止底层的 HTTP 连接,使服务器停止生成并停止计费。迭代器会在下一个事件边界处结束。
原始 SSE(curl / fetch)
请使用规范的www 主机,以避免某些 HTTP 客户端在处理 apex 到 www 的重定向时会剥离 Authorization 头(参见401 故障排查):
多轮对话
conversation_id 会同时出现在 meta 和 done 事件中。如果你在请求中传入了一个,它会被原样回传;如果没有传入,则为 null(服务器不会为 API 密钥调用方自动创建持久化对话,除非你显式调用 POST /api/v1/conversations)。
SDK 会自动捕获该 ID——在流完成后读取 stream.conversationId 即可。
E.V.I. 流式
E.V.I. 实例(theo.evi(...))支持使用相同的 TheoStream 接口进行流式传输:
