核心端点与写入契约
路径中的 {workspace_id} 为目标组织 ID,所有写接口都作用于组织内资源。详细 Schema 见 API 参考。
| 资源 | 读取与候选项 | 创建 | 局部修改(PATCH) | 整份替换(PUT) | 删除 |
|---|---|---|---|---|---|
| Agent | GET /api/v2/workspaces/{id}/agentsGET …/agents/{agent_id}GET …/agents/options |
POST …/agents |
PATCH …/agents/{agent_id} |
PUT …/agents/{agent_id} |
DELETE …/agents/{agent_id} |
| 知识库 | GET /api/v2/workspaces/{id}/knowledge-bases/{kb_id}/config |
POST …/knowledge-bases/config |
PATCH …/{kb_id}/config |
PUT …/{kb_id}/config |
DELETE …/knowledge-bases/{kb_id} |
四条核心语义保证配置变更可控、可回滚:
PATCH局部修改(RFC 7396):使用Content-Type: application/merge-patch+json。只改动请求体中写出的字段;值为null表示删除该字段或条目;数组整体替换;If-Match可选。PUT整份替换:读出的metadata + spec可原样改完后写回(只读status会被服务端忽略),未写出的字段回到默认值。必须通过If-Match: "<revision>"或metadata.revision指定所基于的版本(If-Match: *表示强制覆盖)。?dry_run=true预演:任意POST/PATCH/PUT/DELETE都可附加该参数,完整执行字段校验、权限检查与差异计算但不落库,响应返回字段级changes[]与grants.{added, removed}。- 严格校验与并发保护:未知字段直接报
400并一次列出details.errors[](引用资源不存在时附带candidates);版本过期返回409并给出expected_revision与current_revision。
编写 Agent 声明(AgentSpec)
开始前调用 GET /api/v2/workspaces/{org_id}/agents/options,一次拿齐当前身份可选的模型、决策模型、知识库、技能、外部连接、MCP Server 以及各资源组可授予的权限档位。
完整能力字段(spec.capabilities)
能力遵循「出现即启用,置 null 即关闭」原则。服务端会根据 capabilities 自动推导并同步 Agent 专属运行身份的授权,调用方只能授出自己持有的权限:
| 能力字段 | 配置结构 | 行为说明 |
|---|---|---|
knowledge |
{scope: "all"|"listed", bases: {"<kb_id>": {default: bool}}, level: "view"|"edit"|"manage"} |
控制 Agent 可访问的知识库范围与默认检索集合 |
connectors |
{connections: {"<conn_id>": {level: "use"|"use_write"|"maintain"|"custom", operations: [...] | null}}} |
挂载组织内已登记的外部连接(PostgreSQL / MySQL / MCP / HTTP / 飞书 / 邮箱等);凭据与地址不写入 Agent 声明。operations 为 null 时继承档位与连接策略允许的全部操作 |
workspace |
{network: "off"|"gated"|..., secrets: ["SECRET_NAME"]} |
启用沙箱工作区(代码模式):允许在隔离 Linux 目录执行命令与文件操作,并注入指定组织密钥;启用后默认向每轮签发受限平台访问临时 Key |
functions |
{} |
允许调用组织内的受管函数(实际可调列表由函数侧授权决定) |
skills |
{"<skill_id>": {}} |
挂载平台技能或组织技能(SKILL.md) |
mcp |
{servers: {"<server_id>": {tools: [...] | null}}} |
兼容历史独立 MCP Server 配置;新接入的外部 MCP 推荐统一走 connectors |
agents |
{scope: "all"|"listed", allow: {"self"|"<agent_id>": {}}, level} |
允许读取或编排其他 Agent |
planning |
{} |
启用跨轮次任务计划工具(write_plan) |
其他高频顶层 spec 字段:model(支持写 "default" 自动解析组织默认模型)、decision_model(用于回答评估与句级引用核对)、instructions(最长 8,000 字)、runtime(budget / max_tool_calls / max_tool_rounds / deadline_s)、audience(maintainers 或 org)、builtin_tools(MCP 模式下的内置工具白名单,null 表示全开)和 policy(write_confirmation、ask_user)。
示例:预演挂载知识库与外部连接
curl --fail-with-body \
-X PATCH "${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/agents/${AGENT_ID}?dry_run=true" \
-H "Authorization: Bearer ${APEMIND_API_KEY}" \
-H "Content-Type: application/merge-patch+json" \
-H 'If-Match: "5"' \
-d '{
"spec": {
"capabilities": {
"knowledge": {
"scope": "listed",
"bases": {"col_finance": {"default": true}},
"level": "view"
},
"connectors": {
"connections": {
"cnx_erp_ro": {
"level": "use",
"operations": ["schema_overview", "execute_sql"]
}
}
}
},
"policy": {
"write_confirmation": true,
"ask_user": true
}
}
}'
核对响应中的 changes、grants 与 status.conditions 无异常后,去掉 ?dry_run=true 提交即可落库。
基于模板创建 Agent
不再需要单独调用旧的模板创建接口。查询可用模板列表后,只需在 POST …/agents 请求的 metadata.created_from.template 中填入模板 key,服务端会先加载模板声明,再将你在本次请求中写出的 metadata 和 spec 字段覆盖合并上去:
# 1. 查看平台与组织可用模板
curl --fail-with-body \
-H "Authorization: Bearer ${APEMIND_API_KEY}" \
"${APEMIND_BASE_URL}/api/v2/agent-templates"
# 2. 基于模板创建 Agent,并覆盖标题、模型与知识库
curl --fail-with-body \
-X POST "${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/agents" \
-H "Authorization: Bearer ${APEMIND_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"title": "研报分析师",
"created_from": {"template": "research-assistant"}
},
"spec": {
"model": "default",
"capabilities": {
"knowledge": {
"scope": "listed",
"bases": {"col_reports": {"default": true}},
"level": "view"
}
}
}
}'
metadata.created_from只记录创建来源(含template与当时的revision);后续修改模板不会反向影响已创建的 Agent,后续PATCH也不会改写created_from。- 需要沙箱的模板(模板元数据中
requires_workspace: true)要求当前部署已启用沙箱工作区,否则创建会被拒绝。
读懂 status.conditions 配置诊断
读取或写入 Agent 时,服务端会自动校验配置内部一致性,并将潜在冲突写入只读字段 status.conditions[](每条包含 type、status: "False"、reason、message 和问题字段 path)。conditions 为空数组表示配置完全健康。
reason |
含义与运行时影响 | 修复方式 |
|---|---|---|
ToolsIgnoredInCodeMode |
同时启用了 spec.capabilities.workspace(代码模式)和 spec.builtin_tools 白名单;沙箱内命令不受 MCP 工具白名单约束 |
若希望走代码模式,将 builtin_tools 置 null;若需严格限制工具集,关闭 workspace |
ConnectorToolsOff |
在 MCP 模式下挂载了数据库 / HTTP 等非 MCP 连接,但 builtin_tools 白名单缺少 list_connections 和 invoke_connection,导致 Agent 无法调用这些连接 |
把 list_connections 与 invoke_connection 加入 builtin_tools,或将 builtin_tools 设为 null |
ConnectionDisabled |
connectors 引用的连接已被停用,运行时调用会被拒绝 |
由连接维护者重新启用连接,或从 spec.capabilities.connectors.connections 移除 |
ConnectorOperationUnavailable |
指定的 operations 未启用,或定义变更后等待重新批准 |
在连接管理中启用/审批该操作,或调整 operations 列表 |
DefaultKnowledgeBaseOutOfScope |
标记为 default: true 的知识库不在允许访问的范围内,对话时无法检索 |
将该知识库加入 scope 或取消其 default 标记 |
BuiltinServerOff |
该 Agent 关闭了平台内置 MCP Server,MCP 模式下没有任何内置工具 | 在 Agent 的 MCP 设置中重新开启内置 Server |
IdentityInactive |
Agent 的专属服务身份被停用,运行时不持有任何权限 | 重新启用 Agent 身份后再恢复调用 |
知识库声明与 CLI 工作流
文档型知识库同样使用 metadata + spec 声明式接口,但需注意三条约束:
parser_isolation、fulltext_backend_type、database由服务端决定,不可在spec中写入;- 已有知识库的
embedding配置创建后不可修改(更换向量模型需新建知识库并重新入库); - 未知字段直接报错,不会静默忽略。
使用 apemind CLI 可以像管理 Kubernetes 清单一样用 Git 维护 Agent 配置:
# 导出当前声明到本地文件
apemind agent get "${AGENT_ID}" --workspace "${APEMIND_ORG_ID}" > agent.json
# 本地修改 agent.json 后先看服务端差异预演
apemind agent diff --input agent.json --workspace "${APEMIND_ORG_ID}"
# 确认无误后应用(自动携带 metadata.revision 防覆盖)
apemind agent apply --input agent.json --workspace "${APEMIND_ORG_ID}" --confirm
旧写接口迁移对照
历史 /api/v2/bots 和 /api/v2/collections 写接口在 OpenAPI 中已标记为 deprecated,底层与声明式接口读写同一份数据、共享资源 ID 与 revision。建议按下表迁移:
| 旧接口 / 字段(已废弃) | 推荐声明式接口 / 字段 |
|---|---|
POST /api/v2/bots、POST /api/v2/agent-templates/{key}/bots |
POST …/agents(模板写在 metadata.created_from.template) |
PUT /api/v2/bots/{bot_id} |
PATCH 或 PUT …/agents/{agent_id} |
GET /api/v2/bots/permission-options |
GET …/agents/options |
access.collections + permissions.knowledge_base + config.agent.collections |
spec.capabilities.knowledge |
/api/v2/bots/{bot_id}/mcp/...、外部连接绑定 |
spec.capabilities.connectors(历史独立 MCP 用 spec.capabilities.mcp) |
config.capabilities.workspace / planning / config.skills |
spec.capabilities.workspace / planning / skills |
POST /api/v2/collections、PUT /api/v2/collections/{id} |
POST / PATCH / PUT …/knowledge-bases/config |