跳转到主要内容
Agent 是可选的复用配置模板,修订不会改写已有 Session。不需要模板时可以直接创建 Session。全部操作检查租户归属;应用 Token 可列出、读取、创建和预检 Agent,修订、归档、复制要求 owner。

定义 schema

创建接受严格 Agent 定义,修订和预检将相同 schema 放在 definition 下。 Tool 名称必须唯一,Harness 必须支持所需初始化和 Tools。保存的绑定检查租户归属和 kind,配置有效不代表真实执行成功。Optional-at-start Tool 在创建 Session 时仍需绑定。Agent tools 是声明数组,Session tools 是名称到连接的映射。

创建、列表和读取

POST /v1/agents 返回 201,包含 id、name、definition、env_names、revision、archived_at、created_at、updated_at。环境值另行保存,不在 definition 中返回;初始 revision 同时进入历史。 将以下最小定义保存为 agent-definition.json,示例不设置默认连接:
GET /v1/agents 返回 200、{agents:[...]},按创建时间升序,包括归档模板,无分页。每项字段与创建相同。GET /v1/agents/{id} 返回 200,在相同字段之外增加 revisions,按 revision 倒序;历史项包含 revision、name、definition、env_names、created_at。不存在或其他租户 Agent 返回 404 agent_not_found。
示例假定 API origin 不含 /v1,并使用适当后端 Token。创建没有幂等键,重复会生成不同模板。响应丢失后先调查列表,不要直接再建一个。

预检未保存的定义

POST /v1/agents/preflight 接受严格 {definition,bindings}。顶层 bindings 要求 sandbox_connection_id 和 model_connection_id UUID,tools/connections 映射默认空。预检使用这些显式绑定,不要假定 definition.bindings 自动补齐顶层绑定。 保存为 agent-preflight.json,并替换两个连接占位 ID:
成功返回 200,形状与 Session 预检的 readiness/combination/lifecycle/连接边界对象相同,不插入 Agent 或 Session。它调用凭据入口就绪与本地兼容性检查,不执行云任务。范围与错误见 Session 预检。

使用乐观并发修订

PUT /v1/agents/{id} 接受严格 {expected_revision:正整数,definition:AgentDefinition}。提供最近读取的 revision 和完整替代定义,不是逐字段 PATCH。省略的非环境字段使用 schema 默认值,不继承上一版定义。 环境是例外:同时省略 variables 和 env 保留原值;提供任一字段替换整个环境映射;显式空映射清空环境。响应只暴露名称。将完整更新保存为 agent-revision.json:
将示例 revision 1 换成实际读取值。成功返回 200 和新 Agent 对象,递增 revision 并保存历史。版本不匹配返回 409 agent_revision_changed,应重新读取并合并意图,不要盲改 expected_revision。成功响应丢失后重试也可能遇到该冲突。归档模板返回 409 agent_archived。既有 Session 保持其固定 revision 和有效环境。

复制模板

POST /v1/agents/{id}/copy 接受严格 {name:string},长度 1–200。成功返回 201 和具有独立初始历史的新 Agent。它复制当前源定义及解密后的有效环境到新 Agent,不返回明文环境;新名称替换原名称。当前实现允许复制已归档源,但仍须通过当前定义与绑定校验。
复制不是空配置,也不是独立外部账户;它可能保留连接 ID 和敏感环境默认值。使用前检查绑定。接口没有请求去重保证。

归档模板

POST /v1/agents/{id}/archive 无必需请求体,返回 200、{id,revision,archived_at}。重复保留首次归档时间,不递增 revision。此处没有取消归档或硬删除接口。
归档模板仍可读取,不能修订或创建新 Session,即使选择旧 revision 也不行。它不会关闭已有 Session,资源关闭仍是独立生命周期操作。 严格输入不合法返回 400 invalid_request;模板不存在或属于其他租户返回 404 agent_not_found。校验可能先于模板查找失败,客户端应读取实际错误码。其他兼容性、环境、初始化和绑定失败遵循共享定义/Session 规则。来源:Agent schema 与操作、路由和角色检查。本文是源码审阅契约,不是新一轮 HTTP/数据库验收。下一步:模板工作流、HTTP 总览。