联枢:接口与工具

登记工具

登记或导入接口,写参数契约,设置审批档位、限额和脱敏,整理能力组和调用模板,在线调试。

登记工具(接口)

打开「接口与工具(联枢) › 能力目录 › 接口与工具」。HTTP 接口点右上角「登记 API 接口」,也可以点「导入 OpenAPI」批量生成。每行有「配置」「调试」和「更多」里的「查看修订历史」。每个联枢最多登记 500 个工具。

基础信息与调用策略

字段说明
所属连接、工具名称工具经所属连接调用上游。名称必填。
用途说明Agent 依据它判断什么时候调用这个工具,请写具体。
操作性质「只读」或「写入 / 有副作用」。按真实副作用选,不要只看 HTTP 方法名。非 GET 请求必须是写操作,否则保存时被拒绝。
调用审核策略三档,见下一小节。
审批有效期(分钟)只在需要人放行的档位出现,1 到 10080。留空时本人确认 15 分钟,他人审批 24 小时。
启用审核通过后勾选,获授权的 Agent 才能调用。
协议形式、请求方法、接口路径「HTTP JSON 接口」或「GraphQL(固定文档)」。方法有 GET、POST、PUT、PATCH、DELETE。路径里的占位符写成 {id}。

审批档位

每个工具有一个审批档位。写操作本身不决定档位,由管理员为每个工具配置。

档位怎么执行
授权后直接调用调用者持有这个工具的调用授权,参数通过契约校验,就直接调用上游,不再询问。读和写都可以选这一档。
需要本人确认调用被冻结,由发起 Agent 的归属人员本人确认后,再由原调用者执行一次。没有归属人员的 Agent 发起时会被拒绝。
需要他人审批调用被冻结,由持有「审批」授权的其他人员批准后,再由原调用者执行一次。

需要人放行的调用会冻结调用者、参数、工具和连接的版本,并向 Nexus Core 申请审批,决定回到联枢后才能执行。批准在 Nexus 审批页完成,有权的人也可以在自己 Nexus 助手的审批卡片上决定,两处的资格和规则一样。平台管理员只能撤销,不能放行。没有任何人能审批时,核心立即拒绝调用并说明原因,不会留下待批项。

调用者的授权、工具或连接的版本一变,原来的批准就失效。审批页按参数逐行展示冻结的内容:在「审批关键参数」里填的 JSON Pointer(每行一个,最多 10 个,如 /amount、/payee)按原值显示,其余参数按工具的脱敏设置显示。审批通知里不含任何参数。工具编辑页会显示当前能审批的人数,一个人也没有时会提示在「授权管理」里给人员、岗位角色或单位授予「审批」。

从 MCP 同步来的新工具或契约变化的工具,一律默认停用,并按「写入 / 有副作用」和「需要他人审批」登记。上游声明的只读或破坏性提示只显示为「提示」,不会自动改变操作性质、审批档位和授权,必须由管理员审核后配置并启用。

参数契约(JSON Schema 子集)

「参数 JSON Schema」(GraphQL 工具叫「变量 JSON Schema」)约定 Agent 只能提供哪些参数。根节点必须是 object,整份最多 16000 个字符、500 个节点、嵌套 12 层。联枢只支持 JSON Schema 的一个子集:

类别内容
支持的关键字type、properties、required、additionalProperties(只接受 true 或 false)、items、minItems、maxItems、minLength、maxLength、minimum、maximum、enum、const、description、title、anyOf、oneOf(各最多 20 个分支)
不支持的关键字$ref、pattern、format 以及上面没列出的其他关键字。登记时会直接拒绝,提示「不支持 Schema 关键字 …」
其他限制参数名不能是 __proto__、constructor、prototype。没配请求映射时,GET 参数只接受标量,不接受对象和数组,违反时在调用时才报错;配了请求映射后,查询参数可以是标量数组
{
  "type": "object",
  "properties": {
    "order_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "订单号" }
  },
  "required": ["order_id"],
  "additionalProperties": false
}

上面是一个示例契约。每次调用,联枢都先按这份契约校验输入,不通过就不会请求上游。

响应处理与请求映射

  • 默认行为:没有配置请求映射时,路径固定,GET 的标量参数放进查询串,POST、PUT、PATCH、DELETE 的参数整体作为 JSON 请求体。
  • 请求映射:在「请求映射」里把参数映射到路径占位符 {name}、查询参数、请求头和请求体。值取自输入里的 JSON Pointer,或填固定值。请求头不能是 Host、Authorization、Cookie,也不能是名称像凭据的请求头。映射在发出请求之前校验失败时,不会发出任何请求,写操作也直接记为失败,不会标成结果待核验。
  • 调用者身份:路径、查询、请求头和请求体字段还可以取 caller.employee_no(本人工号)或 caller.external_id.<体系编码>(本人在某个外部系统里的 ID),例如「查本人假期」。值来自 Nexus Core 的授权快照,只有归属在职人员的个人 Agent 才有。这些字段不能出现在参数契约里,Agent 传入同名字段会被拒绝。服务 Agent、控制台管理员调用,或人员没有登记对应外部 ID 时,在发出请求前就拒绝,不会到达上游。GraphQL 工具不支持。
  • 响应投影:在「响应处理」里用 JSON Pointer 白名单(* 匹配数组每一项)只返回需要的字段。上游原始响应一般以 96KB 为限,配置了返回字段的只读工具放宽到 4 MiB,投影后的结果仍以 96KB 为限,超出时返回 RESULT_TOO_LARGE,要减少字段或改用分页聚合。
  • 分页聚合与分组计数:只读 GET 工具可以配置游标或页码分页,联枢最多取 20 页再聚合,返回 {items, pages, truncated},达到上限时 truncated 为 true。group_count 由联枢按某个字段给列表计数,返回各值的条数,最多 100 个不同值,用来回答「各评级有多少个」这类问题,不用让模型自己数。MCP 工具和 GraphQL 工具不支持这两项。
  • GraphQL:HTTP 连接上的工具可以固定一份 GraphQL 文档,只能含一个 query 或 mutation(可带 fragment),不接受 subscription。始终以 POST 发 {query, variables},Agent 只提供变量。mutation 必须是写操作,并且需要本人确认或他人审批。
  • 文件:HTTP 工具可以勾选「上传文件」(以 multipart/form-data 发送,工具须用 POST、PUT 或 PATCH,且不用请求映射)或「下载文件」(上游返回的文件保存在联枢,调用者只得到文件引用)。「文件敏感级别」分内部、机密、绝密,会在审批页提示。文件内容不经过 Agent 和模型,不进调用日志。单个文件最大 20 MiB,一次工作流运行合计最大 100 MiB。文件只属于产出它的调用者。
  • 幂等键:写工具可以在「接收幂等键的请求头」里填上游用来去重的请求头,如 Idempotency-Key。有了它,工作流里结果未知的写步骤才允许「重试该步」。读工具和 MCP 工具不能声明,连接认证或请求映射已用到的请求头也不能用。

调用限额

在「调用限额」里按工具设置,留空表示不限。限额写入工具定义,随修订历史一起记录。

字段计数范围
每分钟调用次数、每日调用次数每个调用方对这个工具分别计数
最大并发每个调用方对这个工具正在执行的请求数
写操作日预算只有写工具有。每个调用方对这个工具每天实际执行的写操作数
全部调用方每分钟、每日、最大并发这个工具所有调用方合计

计数发生在实际调用上游的时候:授权后直接调用在发起时计入,需要审批的工具在批准后执行时计入,生成待批请求时不计入。超出限额时返回 429 和 BUDGET_EXCEEDED,消息说明哪一项超了、上限多少、什么时候重置,不调用上游,也不留下请求。每分钟的窗口按整分钟,每日额度按北京时间零点重置。工作流的每一步都计入对应工具的限额。被限额拒绝的调用不进入调用日志,要到「操作审计」里查。

结果脱敏

工具结果在返回调用者、保存到请求和写入调用日志之前先脱敏。

  • 指定脱敏字段:每行一个 JSON Pointer,如 /customer/name、/items/*/phone。命中的值替换为 "[MASKED]",不改变 JSON 结构。路径不存在时什么都不做。
  • 自动识别个人信息:默认开启,识别大陆手机号、18 位身份证号、银行卡号和邮箱,只替换匹配到的字符。成员名含订单、单号、流水等字样的值不做银行卡识别,避免误伤订单号。
  • 调用日志里的输入参数和上游错误响应体也按同一设置脱敏,导出 CSV 时对仍开启脱敏的工具再脱敏一次。
  • 管理员可以按工具关闭自动识别,关闭和重新开启都会单独记入审计。规则识别不了的姓名、地址等,请用指定字段。

导入 OpenAPI 与同步 MCP 工具

  • 导入 OpenAPI:点「导入 OpenAPI」,选择所属 HTTP 连接,上传本地的 OpenAPI 3.0 或 3.1 文档(.json、.yaml、.yml,最大 800KB),每次最多导入 100 个操作。联枢不会访问文档里的服务器地址或远程引用。预览会列出每个操作的方法、路径、参数,以及能否导入,不能导入的会写明原因,例如用了 pattern 这类子集之外的关键字、非 JSON 请求体、字典型 additionalProperties。勾选后导入,工具默认停用,GET 为只读,其他方法一律是写操作并按「需要他人审批」登记。同一连接里方法和路径相同的工具已存在时会跳过。导入的结果只是候选工具,还要逐个审核契约和策略并做连通验证。
  • 同步 MCP 工具:在 MCP 连接上点「同步工具」。联枢读取上游声明的参数契约、输出契约和只读、破坏性提示。声明了输出契约的工具,结果里必须有符合它的结构化内容,否则调用失败。没有声明时,有结构化内容就原样返回,否则返回 {"text": "…"}。契约变化的工具会重新停用,等待审核。

修订历史

每次保存工具、同步 MCP 目录,都会记录一版完整定义:修订号、时间、操作人、来源和各项设置。连接凭据不属于工具定义,不会被记录。在行上「更多」里点「查看修订历史」,按版本从新到旧逐版比较,参数契约显示逐行差异。

能力组与调用模板

能力组

能力组按业务功能整理跨连接的工具,给 Agent 一份使用说明。打开「接口与工具(联枢) › 能力目录 › 能力组」,点「新增能力组」。

字段说明
能力组名称、功能说明这个组是做什么的。
给 Agent 的使用说明按顺序写给 Agent 参考的步骤说明。它本身不可执行,每一步仍按工具的权限和审批策略办理。
组内接口可以跨 HTTP 和 MCP 连接选择,同一个工具可以加入多个组。
发布到 Agent 能力目录未发布时是草稿,Agent 看不到。

能力组只整理能力,不授予权限。新工具加入组不会自动获得授权。Agent 只能看到含有它已授权工具的已发布组,组里返回的成员也只含它仍被授权且已启用的工具。获授权访问组内任一工具的调用者可以读完整的组说明,所以说明里不要写凭据和内部敏感信息。组下架只隐藏说明,不撤销已单独授予的授权。

调用模板

调用模板为一个工具保存一份部分预置的参数。打开「接口与工具(联枢) › 调用与审批 › 调用模板」,点「新增调用模板」,填名称、说明、工具和「预置参数(JSON 对象,可只填部分字段)」,字段必须被工具的契约接受。勾选「发布给有该工具 catalog 授权的 Agent」后,Agent 才能读到它。Agent 用模板时,把预置参数和本次参数合并,仍然是一次普通的工具调用,照常受授权、审批、限额和脱敏约束,模板不授予任何权限。

在线调试

打开「接口与工具(联枢) › 调用与审批 › 在线调试」。在「调用请求」里,从「接口 / 工具」下拉里选一个已启用的工具,在「JSON 参数」里填符合契约的参数,点「发送调用」。联枢以当前控制台管理员的身份实际调用上游,与 Agent 共用同一条执行链:权限、审批、幂等、限额、脱敏和调用日志都照常生效。下拉里只能选已启用的工具,没启用的工具不能调试。

联枢在线调试页面
「接口与工具(联枢) › 调用与审批 › 在线调试」页面。截图来自测试环境,数据为示例。
  • 「响应与执行状态」显示调用状态、请求编号和已投影、已脱敏的上游结果。超时或结果未知时,请先核验原请求,不要重复发送。
  • 需要审批的工具,调试页按「他人审批」办理:页面给出审批页链接,由持有审批权的人员批准后,再回到调试页,展开「执行已批准的请求」,在「已批准的请求编号」里点「执行已批准请求」。管理员不能批准,管理员关联的人员也不能批准自己的调试调用。
  • 调试会实际调用上游。写工具请用测试环境或测试数据,并按上游凭据的权限评估影响。

进一步交流

带一件正在做的事来聊

告诉我们你想让智能体接哪一类系统。我们在演示环境里把这件事走一遍,再一起判断合不合适。