Concepts
Concepts
we0agent 的核心心智模型：一次请求如何从业务输入进入 agent loop，并在模型、工具、事件、持久化和扩展端口之间流转。
这篇文档回答「SDK 里这些对象为什么存在、怎么协作」。如果你只是想先跑起来，先看 Quickstart；如果你要开始接业务系统，这篇能帮你判断该接哪个扩展点。
一张图
长期定义与单次请求
We0Agent 保存的是长期可复用的 agent 定义：名字、模型、系统提示词、工具、持久化、hooks 和 ports。真正变化的输入放在每次 stream() 或 invoke() 里：session_id、messages、mode、abort、metadata。
| 层级 | 对象 | 生命周期 |
|---|---|---|
| Agent 定义 | We0Agent、We0Model、SystemPrompt、tools、hooks、ports | 通常随服务进程长期存在 |
| Turn 输入 | session_id、messages、mode、abort、metadata | 每次请求创建 |
| Run 结果 | We0Event stream 或 We0TurnResult | 每次请求消费 |
| 会话状态 | session、message、part、tool state、summary、snapshot hash | 由 persistence 和 ports 保存 |
Agent Loop
一次 prompt 模式请求通常按这个顺序执行：
模型可以在一个 turn 里触发多个 step。每个 step 都可能输出文本、请求工具、执行工具、继续下一步，直到模型停止、达到 step 上限、触发压缩、出错或被 abort。
主要集成边界
| 边界 | 你什么时候关心 | 对应文档 |
|---|---|---|
| 模型边界 | 要接 OpenAI / Anthropic / Google / DeepSeek 或自建兼容网关 | We0Model |
| 工具边界 | 要让模型读写文件、调用业务 API、执行命令或查询数据库 | AnyToolDefinition |
| 事件边界 | 要把 token、工具状态、错误、session 状态推到 UI 或日志 | Streaming、Events |
| 存储边界 | 要保存会话、resume、回滚或跨进程读取历史 | Persistence |
| 中断边界 | 要从 UI 或任务管理器打断正在运行的请求 | Abort |
| 运行时边界 | 要接状态管理、快照、回滚、事件 hub | Built-ins、Snapshots、Revert |
| hook 边界 | 要介入模型请求或工具执行前后 | Hooks |
mode：prompt 和 resume
mode="prompt" 表示追加新用户消息并开始一轮新运行；mode="resume" 表示不追加消息，而是从已有会话中恢复未完成的 assistant/tool 状态。
两个模式互斥：prompt 必须传 messages，resume 必须不传 messages。这是 SDK 最重要的请求级约束之一。
选 stream 还是 invoke
| 方法 | 适合场景 | 返回 |
|---|---|---|
stream() | UI 打字机效果、工具进度、实时状态、调试事件序列 | AsyncIterator[We0Event] |
invoke() | 批处理、后台任务、只关心最终状态、结构化输出 | We0TurnResult |
build_request() | 需要直接拿 We0TurnRunner，同时协调事件流和最终结果 | We0TurnRunner |
默认建议：业务 UI 用 stream()，离线任务用 invoke()。
下一步
- 跑通第一轮：看 Quickstart。
- 接模型：看 We0Model。
- 添加工具：看 AnyToolDefinition。
- 把事件接到 UI：看 Streaming。
- 接可选增强能力：看 Built-ins 和 Revert。
- 排查失败：看 Troubleshooting。