跳转到内容
OpenBot

Agents

Agent（智能体）是一个有角色的工作者，例如程序员、写作者或设计师。每个 Agent 都有自己的指令、自己的 Sessions 和自己的长期记忆。Agents 之间互相分派工作，所以每个 Agent 都能专注于自己的任务。 本页介绍 Agents 的种类，以及 /v1/agents 下的路由。每个路由都接受用户令牌或 session cookie。见 身份验证。

三种 Agents

种类 所有者 存在多久 用途
main 一个成员 和成员存在的时间一样长 代表这个人行动。简单的工作自己做，其他工作分派出去。
persistent 一个成员、组织，或另一个 Agent 直到你把它归档 一个有角色的长期工作者。它会随着时间从工作中学习。
session 一个 Session 和拥有它的 Session 存在的时间一样长 处理一条工作线的助手。它把上下文保存在那个 Session 中。

每个成员都正好有一个 Main Agent（主 Agent）。OpenBot 在第一次需要它时创建它。你创建 Session 时如果没有指定 Agent，这个 Session 就属于你的 Main Agent。

新的 Main Agent 没有模型。在你创建没有自己模型的 Session 之前，请先设置它的 model。见 Models。

Session Agent 是“几乎长期存在”的。Agent 在工作时用一个工具启动它。只要它的 Session 还在，Session Agent 就会保留上下文，所以 Agent 可以多次给它分派工作。当你删除这个 Session 时，它的 Session Agents 也会被归档。你可以把有用的 Session Agent 提升 为长期存在的 Agent。

Agent 也可以拥有长期存在的 Agents。见 拥有 Agents 的 Agents。

每个 Session 都属于一个 Agent。见 Sessions。Agents 之间如何分派工作，见 委派。

Agent 不知道的限制

Agents 没有一份“可以做什么”的清单。Agent 只管尝试。当它第一次尝试新的事情时，例如创建 Agent 或调用 App 工具，它上面的决策者会做决定。见 Requests。这些决定会被保存，所以每个 Agent 的限制是从真实的工作中逐步形成的。

创建 Agent

Terminal window
curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Programmer","role":"Writes and reviews TypeScript code","instructions":"Write small, tested changes. Explain each change in one short paragraph."}' \
  https://api.example.com/v1/agents
字段 含义
name 必填。一个简短的名字。OpenBot 会去掉首尾空格。剩下的部分必须有 1 到 100 个字符。
role 必填。用一行话说明 Agent 做什么。其他 Agents 读取它来选择工作者。
instructions 必填。Agent 的长期指令，类似一份职位说明。
model 可选。当 Session 没有选择自己的模型时，这个 Agent 的 Session 使用的模型。
planApproval 可选。这个 Agent 的计划如何被批准。见 计划模式。
shared 可选。true 会创建一个组织 Agent，每个成员都可以使用。
agent 可选。拥有这个新 Agent 的 Agent 的 ID。它不能和 shared 一起使用。

OpenBot 返回 201 和这个 Agent：

{
  "id": "agt_5c0e…",
  "kind": "persistent",
  "owner": { "_tag": "Member", "userId": "u-1" },
  "name": "Programmer",
  "role": "Writes and reviews TypeScript code",
  "instructions": "Write small, tested changes. …",
  "archived": false,
  "revision": 0,
  "createdAt": 1792486800000,
  "updatedAt": 1792486800000
}

owner 是 Member、Organization、Session 或 Agent。共享的 Agent 使用当前使用它的成员的权限和 App 连接，从不使用创建它的人的权限和连接。

列出、读取和修改 Agents

GET /v1/agents 列出你的 Main Agent、你自己的 Agents，以及你可以使用的共享 Agents。加上 ?archived=false 可以隐藏已归档的 Agents。加上 ?session=<id> 可以列出某个 Session 的 Session Agents。加上 ?agent=<id> 可以列出某个 Agent 拥有的 Agents。

GET /v1/agents/:agentId 返回一个 Agent。

Terminal window
curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":0,"instructions":"Write small changes with tests first."}' \
  https://api.example.com/v1/agents/$AGENT

expected 是当前的 revision。你可以修改 name（规则和上面相同）、role、instructions、model（发送 null 来移除它）和 archived。Main Agent 不能被归档。当你归档一个 Agent 时，OpenBot 也会归档它拥有的每个 Agent，以及它们下面的 Agents。当你取消归档时，只有这一个 Agent 会恢复。

提升 Session Agent

Terminal window
curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":3}' \
  https://api.example.com/v1/agents/$AGENT/promote

这个 Session Agent 会成为成员的一个长期 Agent。发送 agent 并填入某个 Agent 的 ID，可以让那个 Agent 成为它的所有者。OpenBot 还会把它 Session 记忆中的长期条目添加到它的 Agent memory。

Agent 可以用 openbot_promote_agent 工具提升它自己 Session 中的 Session Agent。这样，这个 Agent 就拥有了它。

拥有 Agents 的 Agents

Agent 可以拥有长期存在的 Agents。所以 Agent 可以组建自己的团队，团队中的每个成员都保留自己的记忆。

  • Agent 用 openbot_create_agent 工具创建一个归它所有的 Agent。人则通过 POST /v1/agents 并带上 agent 字段来创建。
  • 一个 Agent 用工具创建的 Agent（长期 Agent 或 Session Agent）会得到创建它的 Agent 的 model。工具调用可以指定另一个 model。
  • 所有者是 { "_tag": "Agent", "agent": "<owner ID>", "userId": "<member>" }。userId 是所有者树最顶层的成员。当最顶层是组织拥有的 Agent 时，它是 null。
  • Agent 可以给它拥有的 Agents 分派工作，不需要 request。
  • Agent 的所有者链沿着它的所有者向上，到达一个 Main Agent，然后到达人。例如：人 → Main → Worker → Scout。Agent 的 requests 会沿着这条链向上传递，即使人直接和这个 Agent 一起工作也是如此。见 Requests。
  • 在这条链中，成员的 Agent 或共享 Agent 的所有者，是和它一起工作的那个人的 Main Agent。

Agent 在每个 Turn 中知道什么

OpenBot 会在每个 Turn 的指令中加入以下内容：

  • Agent 的名字、角色和指令，
  • 它现在服务的人，包括这个人的名字和成员 ID。在 Channel 中，这个人是写下这个 Turn 的消息的人，
  • 关于隐私的规则：Agent 从一个人那里学到的内容可能是私密的，所以它只把明确共享的内容告诉另一个人，
  • 对于包含另一个 Agent 分派的工作的 Session，如何把结果发回去，
  • 它的 Agent memory 中的有效条目。

权限

权限 允许你
agents.read 读取 Agents，以及它们的记忆、Rules 和 Grants。
agents.write 创建和修改 Agents，以及它们的记忆、Rules 和 Grants。
agents.delegate 从客户端或另一个 Agent，把工作交给某个 Agent。

你自己的 Agents 位于你的成员键之下。共享的 Agents 位于 openbot.org.<org>.agent 之下。成员可以读取和使用共享的 Agents。管理员还可以修改它们。见 权限。

错误

状态码 错误 何时出现
400 AgentInvalid 不允许这个修改，例如归档 Main Agent。
403 PermissionDenied 你可以读取这个 Agent，但不能修改或使用它。
404 AgentNotFound 没有你可以读取的、使用这个 ID 的 Agent。
409 AgentConflict expected 已过时。请重新读取 Agent，然后再试。
503 AgentStorageUnavailable OpenBot 无法连接到它的数据库。