Docs
we0agent SDK
面向 SDK 用户的 we0agent 使用手册：从首次运行、核心概念、任务集成到 API reference 和排障路径。
we0agent 是一个 agent loop SDK。你用 We0Agent 组合模型、系统提示词、工具、持久化、hooks 和运行时端口，再通过 stream() 或 invoke() 执行一次请求。
你可以用它做什么
we0agent 适合需要这些能力的业务系统：
| 能力 | 说明 |
|---|---|
| Agent loop | 让模型多 step 推理、调用工具、继续执行直到收口。 |
| 流式事件 | 把文本增量、工具调用、工具结果、step 状态、错误和 session 状态统一成 We0Event。 |
| 可恢复会话 | 用 persistence 保存 session/message/part，再用 mode="resume" 恢复未完成状态。 |
| 文件快照 | 对会修改文件的 agent 记录 git-backed snapshot，支持 patch 和回滚。 |
| 可插拔运行时 | 通过 ports 和 hooks 接入状态管理、事件 hub、prompt cache、观测和业务上下文。 |
第一次阅读路径
- Installation：安装私有 Git 依赖，确认 Python、SSH 和 API key。
- Quickstart：运行
example.stream_agent，看到第一条事件流。 - Concepts：理解 agent、turn、message、event、tool、persistence 和 ports 的关系。
- Examples：按能力运行官方示例，找到最接近你业务场景的入口。
- Troubleshooting：遇到安装、模型、事件、resume、snapshot 或工具问题时从这里查。
文档分层
这套文档按 SDK 用户的真实路径组织：
| 层级 | 解决的问题 | 页面 |
|---|---|---|
| Get started | 怎么安装、跑通、看到结果 | Introduction、Installation、Quickstart |
| Concepts | 这些对象是什么、为什么这样设计 | Concepts、Prompts |
| Guides | 怎么完成一个集成任务 | Streaming、Persistence、Snapshots、Resume、Abort、Hooks、Diagrams |
| Examples | 哪些仓库示例可以直接运行 | Examples |
| API reference | 精确字段、参数、返回值和约束 | We0Agent、We0Model、Tools、Events、Built-ins |
| Troubleshooting | 出错时怎么定位 | Troubleshooting |
最小运行形态
import asyncio
async for event in agent.stream(
abort=asyncio.Event(),
session_id="demo-session",
messages=[build_user_message("用三句话介绍 we0agent。")],
):
if event["type"] == "text-delta":
print(event["text"], end="", flush=True)stream() 返回的是统一事件流，不只是文本。工具调用、工具结果、step、session 状态和 provider 错误都会通过同一个异步迭代器返回。
什么时候看 reference
如果你还没跑通过示例，不建议先从 reference 开始。reference 适合这些问题：
We0Agent(...)构造参数有哪些默认值？stream()和invoke()的请求级参数有什么约束？We0Event每种事件的字段是什么？ToolExecuteResult应该返回哪些字段？We0AgentPorts可以接哪些运行时能力？
对应页面在 API reference 分组里。