Get started
Introduction
we0agent 的定位、适用场景和最小心智模型。
we0agent 是一个面向业务系统的 agent loop SDK。它不只是模型调用封装，而是把模型、工具、会话、事件流、持久化、snapshot、resume、abort 和 hooks 组合成一套可集成的运行时。
它解决什么问题
普通模型 SDK 解决「怎么调用一次模型」。we0agent 解决的是「怎么把一个 agent 长期接进产品」：
| 问题 | we0agent 的答案 |
|---|---|
| 模型输出要实时显示 | stream() 产出 text-delta、工具、step 和 session 事件。 |
| 模型需要调用工具 | 用 Pydantic 参数 schema 定义工具，engine 负责调度和记录结果。 |
| 会话要保存和恢复 | persistence 保存 session/message/part，mode="resume" 恢复未完成状态。 |
| agent 会改文件 | snapshot tracker 记录文件变更，revert service 支持回滚。 |
| 业务需要观测和扩展 | hooks 介入模型/工具调用，ports 接入事件、状态、summary、snapshot 等服务。 |
最小心智模型
核心使用模型分为两层：
We0Agent是长期定义：模型、prompt、tools、persistence、ports、hooks。stream()/invoke()是单次请求：session_id、messages、mode、abort、metadata。
核心对象
| 对象 | 作用 | 下一步 |
|---|---|---|
We0Agent | SDK 主入口，持有 agent 定义并执行请求。 | We0Agent |
We0Model | 封装模型卡片和 LangChain chat model。 | We0Model |
SystemPrompt | 声明系统提示词 blocks，参与模型输入。 | SystemPrompt |
MessageWithParts | 会话消息容器，保存用户、assistant、工具等 part。 | Persistence |
AnyToolDefinition | 可暴露给模型调用的工具定义。 | AnyToolDefinition |
We0Event | 流式输出、工具、状态和错误的统一事件。 | Streaming、Events |
推荐学习顺序
- 先按 Installation 安装。
- 跑 Quickstart，确认模型和事件流正常。
- 看 Concepts，建立完整心智模型。
- 依次定义 We0Model、SystemPrompt 和 AnyToolDefinition。
- 看 We0Agent，掌握
agent.py主入口、stream()和invoke()。 - 按使用顺序阅读 guide：stream 事件、持久化续聊、hooks、ports 可选增强能力、abort。
- 需要精确字段时再查 API reference。
不适合什么
we0agent 不替代这些东西：
- 不替代权限系统。生产工具仍需要业务侧鉴权和沙箱。
- 不替代模型供应商 SDK 的所有参数说明。provider 专属能力通过
ModelCard.options透传。 - 不替代持久化运维。SQLite/Postgres 的备份、迁移和监控仍由业务系统负责。
- 不保证 abort 立刻杀死副作用。中断是协作式收口，已经发生的外部副作用不会自动回滚。