给智能体的入口：Agent Key 与 MCP

第 4 课 · 共 6 课 约 8 分钟

智能体能做的事 = 它代表的人或服务的权限 ∩ 这把 Key 的限制；AIDC 今天开放了什么，目前还没有什么。

本课目标

读完这一课，你将能够

  • 分清「用本体（Ontology）」和「建本体」两类智能体入口
  • 用「权限 ∩ 限制」算出一个智能体实际能做什么
  • 说出 AIDC 今天给智能体开放了什么，哪些目前还没有

两类智能体，两扇门

智能体和本体打交道有两种方式。一种是用：读对象、执行 Action、查数据。另一种是建：改 Object Type、Link Type 和 Action 定义。使用受权限与 Key 限制约束；构建走分支与提案，按 review 或 yolo 审核。

用本体建本体
做什么读对象，执行预先定义好的 Action，查询改对象类型、关系、Action 的定义，不写业务数据
谁来把关权限与限制：代表者的权限和 Key 的限制取交集分支加提案，按 review 或 yolo 审核与合并
AIDC 里的入口Agent Key（按权限与限制读写）、Ontology MCP、应用 MCP、CLI 与 REST带 AIDC_AGENT_ID 的开发者 Key 在分支上改、开提案；受限 Agent Key 不允许开分支或提提案

权限取交集

智能体是替某个人或某个服务办事的，不能凭空多出权限。它实际能做的，取两样东西的交集：一是它所代表的人或服务用户本来有的权限，二是这把凭证上的限制，也就是放行了哪些对象类型、哪些 Action。限制是一个上限：设计时从最小开始，一项一项加。

PERSON

它代表的采购员

能读 material、supplier、purchaseOrder，能执行 create-purchase-order 和 approve-purchase-order。

RESTRICTION

Key 的限制

允许读 material、supplier、purchaseOrder，允许执行 create-purchase-order。

RESULT

智能体实际能做

读这三类对象，起草采购订单。批准不行：限制里没有放行它。

示例工厂的物料低于安全库存时，智能体起草采购订单，采购员批准。Key 用 restrictions.operations 限定操作，用 objectTypes 限定 Object Type，用 actionTypes 限定 Action。只放行起草，不放行批准。

身份由凭证决定。review 要本组织 developer 的网页会话审核，作者自批不算数。yolo 也接受能改本体的开发者 Key，或主体为 Editor、Owner 的 Agent Key。合格作者可自批，检查通过后自动合并。

工具、说明和 Skill

MCP（模型上下文协议）是智能体接工具的通用协议：服务端把一批工具摆出来，智能体读到每个工具的名字、参数和说明，再决定什么时候调用哪一个。所以说明写得好不好，直接决定智能体会不会用对。

Action 有一个专给智能体看的说明字段 toolDescription，最多 500 个字符：写清这个 Action 什么时候用、需要什么前提。一个工具只讲一件事；需要几个工具配合的流程，比如先查有没有，没有再建，写成 Skill，不要塞进说明里。

{
  "kind": "actionType",
  "apiName": "hold-work-order",
  "schema": {
    "parameters": [ … ],
    "rules": [ … ],
    "toolDescription": "Pause a running work order when a quality or material problem stops the line."
  }
}

在 AIDC 里，智能体读到的说明来自两处：aidc semantic describe --markdown 给的整份说明书，它先读这个再干活；以及公司应用的 Skills。

AIDC 今天开放了什么

  • 读：Agent Key 按主体权限与 Key 限制读本体。用 SQL 还须在本体上有 Viewer 以上授予，同时有 api:use-ontologies-read、api:use-sql-queries-execute 权限，且 objectTypes 为 ["*"]。只授予部分 Object Type 时不能用 SQL。
  • 带 AIDC_AGENT_ID 的开发者 Key 在分支上改、开提案；受限 Agent Key 不允许开分支或提提案
  • 改数据：Agent Key 可以按主体权限与 Key 限制直接执行获准 Action。先用 aidc semantic apply <Action> --validate-only 校验，再去掉开关执行。
  • MCP：每个公司应用有自己的 MCP 服务器（Streamable HTTP），工具是应用的 APIs，名字里的「.」换成「__」；prompts 是应用的 Skills；凭证是开发者 Key。

接一个应用的 MCP 只要这几样。每个支持 MCP 的客户端都有自己添加服务器的命令，把它们填进去就行：

地址    https://www.ai-dc.ai/api/v1/developer/apps/<命名空间>/<slug>/mcp
传输    Streamable HTTP
请求头  Authorization: Bearer $AIDC_API_KEY

拿凭证也有规矩：智能体不索要、不转述人的密码；无人值守的环境用人交给它的 Key，不要在机器上翻 .env 去找别人的 Key。

要点

  • 智能体有两扇门：用（读、执行 Action）和建（改定义），把关方式不同。
  • 能做的事 = 代表的人或服务的权限 ∩ 这把 Key 的限制；限制是上限，从最小开始加。
  • 身份由凭证决定。review 要本组织 developer 的网页会话审核，作者自批不算数。yolo 也接受能改本体的开发者 Key，或主体为 Editor、Owner 的 Agent Key。合格作者可自批，检查通过后自动合并。
  • MCP 把工具的名字、参数和说明摆给智能体；说明写得好，工具才会被用对。
  • Agent Key 按权限与限制执行 Action。Ontology MCP 已可用，除 report_issue 外只读。受限 Agent Key 不能开分支或提提案。

练一练

给一个智能体设计入口

用示例工厂练习。不需要真的配置，把设计写下来就行。

为一个「起草采购订单」的智能体写出权限表：它读哪些对象类型、执行哪个 Action，明确不放行哪个。

小测

选一个答案，马上看解析。

Q1代表的采购员能批准采购订单，但 Key 的限制只放行了 create-purchase-order。智能体能批准吗？

Q2审批策略为 review 时，智能体在分支上改了本体、开了提案。谁能批准？

Q3今天想让智能体按公司应用的能力办事，最直接的 MCP 入口是？

延伸阅读