声明式配置(Agent 与知识库)

这是管理 Agent 与知识库配置的推荐主路径。每个资源都由 metadata、spec 和只读 status 组成,支持 JSON Merge Patch 局部修改、写入前 dry_run 预演、模板派生与乐观锁防覆盖。

核心端点与写入契约

路径中的 {workspace_id} 为目标组织 ID,所有写接口都作用于组织内资源。详细 Schema 见 API 参考。

资源 读取与候选项 创建 局部修改(PATCH) 整份替换(PUT) 删除
Agent GET /api/v2/workspaces/{id}/agents
GET …/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}

四条核心语义保证配置变更可控、可回滚:

编写 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"
        }
      }
    }
  }'

读懂 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 声明式接口,但需注意三条约束:

使用 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

下一步