接入智能体
一个智能体接入 Nexus,只需要一个 Nexus 地址和一把 Key。Key 能用哪些模块、做哪些事,由控制台里的授权决定。
两样东西
- Nexus 地址:Nexus Core 对外的访问地址,也就是你在浏览器里打开控制台用的地址。只写到端口,不带路径或查询。
- Key:控制台给某个 Agent 签发的凭据。智能体每次调用都带着它,Nexus 按这把 Key 对应的授权决定它能看到什么、能做什么。
人和智能体用的是两套身份。人用账号登录控制台,或经客户自己的身份系统登录审批页;Agent 只用 Key。Key 只能调用 /v1/harness/*,访问控制台接口会被拒绝,也不能用来审批。
登记 Agent 并签发 Key
每个 Agent 归属于一名人员或一个单位,调用和审计按这个归属追溯。归属绑定后不能更改。
- 在「组织 › 组织架构」里创建 Agent。个人使用的,在人员详情的「个人 Agent」里新建;自动化程序用的,在单位的「服务 Agent」标签里新建。
- 创建后进入它的密钥页,在「访问 Key」里签发新 Key。有效期默认从签发起 365 天,可以改成别的日期。也可以勾选「永不过期」,控制台不建议这样做,这次签发会在审计里记为永不过期。
- Key 只显示一次,请立即复制保存。丢了就撤销旧 Key,重新签发。
- 在「接入中心 › 授权管理」里为这个 Agent 授权。没有授权的模块不会出现在它的目录里。
已经存在的 Agent,在「接入中心 › Agent 与密钥」里进入详情签发。Agent 所属的人员已离职,或所属的单位已停用时,不能再签发 Key。
在 Nexus 助手里连接
Nexus 助手里的 Nexus 连接只有两项设置:Nexus 地址和 Key。
- 在 Nexus 助手的「业务模块」下打开「配置模块连接」,进入「模块连接」。
- 「Nexus 地址」填上面的地址,「Nexus 统一接入 Key」填刚才复制的 Key,点「保存连接」。Key 输入框只写不读,保存后显示为已配置。
- 在对话里输入
/nexus check。正常时会显示 Agent 的身份、Key 的有效期和这把 Key 当前可用的模块。
这里填的是 Nexus 签发的 Key,不是大模型服务的 API Key。修改地址或 Key 不需要重启。连接成功后,Nexus 助手按这把 Key 的授权动态生成工具目录:有授权的模块才有对应的工具,授权改了,目录在下一次读取时跟着变。
127.0.0.1、localhost)上的 HTTP。Nexus 对外是非本机的 HTTP 地址时,需要先配置 HTTPS,否则连接会报 INVALID_CONFIGURATION。侧栏的「Nexus 管理」页
连接成功后,Nexus 助手的侧栏里有「Nexus 管理」页,显示登录的这个 Agent 和它所属的人关心的事。页面全部用这个 Agent 自己的 Key 读取,不增加任何权限。
- 概览:待你处理的条数、已授权的模块、常用内容、24 小时内的结果文件、Key 还剩几天,以及身份和许可信息。
- 各模块的标签:只有这把 Key 获授权的模块才有标签,顺序是数脉、知汇、运枢、联枢、研枢。标签里是等你处理的事项、常用内容、模块的拓扑和这把 Key 的授权范围。
- 读取的边界:页面只做只读浏览。读取数据行、读取资源状态这类动作只在你点击时发生,并且会记入对应模块的审计。
如果客户端没有提供读取通道,页面会显示「这个客户端没有提供概览通道」,其余功能不受影响。
查看这把 Key 能做什么
Agent 可以随时读取自己当前的授权,不需要管理员权限。三种方式读到的是同一份内容:
- HTTP 接口
GET /v1/harness/permissions,不接受任何参数; - Nexus 助手里的工具
nexus_permissions_get,Agent 可以自己调用; - 命令
/nexus permissions。
响应里有这把 Key 能调用的模块、操作和只读属性,有效期,每次最多返回的行数,以及明确授权的数据源、表、字段和业务说明。数脉部分会带上可读名称、字段类型和字段说明。私有的行条件、固定值、权限关联表路径和连接凭据不会公开。
没有任何可调用的模块时,返回 status: no_access 和空列表。Key 无效、已撤销或已过期时,返回 AUTH_INVALID。读取权限不会读取数据行;需要看一眼数据时,拥有数脉执行权限的 Key 可以调用 data.preview,最多返回 5 行样例,行范围仍按这把 Key 的行条件限定。
用 HTTP 接入自己的 Agent
不使用 Nexus 助手时,直接调用 Nexus Core 的 /v1/harness/*。所有请求用 Authorization: Bearer <Key> 认证,并带 nexus-protocol-version: 2,这是目前唯一的协议版本;不带这个头时也按协议 2 应答,写其他版本会返回 422。
| 接口 | 作用 |
|---|---|
GET /v1/harness/connection | 连接自检:Agent 身份、有效期、可用的模块 |
GET /v1/harness/permissions | 当前 Key 的授权 |
GET /v1/harness/modules | 这把 Key 可用的模块和操作,没有可用操作的模块不出现 |
GET /v1/harness/modules/{模块 ID} | 模块的操作和输入输出格式;加 ?operation_ids=a,b 只取点名的操作的输入格式,篇幅小得多 |
POST /v1/harness/modules/{模块 ID}/call | 调用一个操作 |
先把地址和 Key 放进环境变量,读取可用的模块:
export NEXUS_URL="https://nexus.example.com"
export NEXUS_KEY="<你的 Nexus Key>"
curl -sS "$NEXUS_URL/v1/harness/modules" \
-H "Authorization: Bearer $NEXUS_KEY" \
-H "nexus-protocol-version: 2"
调用时,正文是 {operation_id, input, expected_module_version?},不能有别的字段。下面以数脉的 sources.list 为例,它列出这把 Key 有权使用的数据源:
curl -sS -X POST "$NEXUS_URL/v1/harness/modules/warehouse/call" \
-H "Authorization: Bearer $NEXUS_KEY" \
-H "nexus-protocol-version: 2" \
-H "Content-Type: application/json" \
-d '{"operation_id":"sources.list","input":{}}'
成功时返回 {protocol_version, module_id, module_version, operation_id, result_kind, data}。input 必须符合模块描述里的输入格式,整个请求正文最多 32 KiB,单次结果最多 256 KiB。
提交任务要带幂等键
模块描述里标为 execution: job 的操作会提交一个任务,例如数脉的 question.submit。这类操作必须带 Idempotency-Key 请求头,缺少时返回 422。
- 格式是 1 到 128 个字母、数字或
. _ : -,每次新提交用一个新值。 - 结果未知时,用同一个键和完全相同的正文重试,Nexus 返回原任务,不会重复执行。
- 同一个键配不同的正文,返回 409
IDEMPOTENCY_CONFLICT。 - 提交后用对应的查询操作取结果,例如
job.get,不要自动重复提交。
常见响应
| 状态 | 含义 |
|---|---|
401 AUTH_INVALID | Key 无效、已撤销或已过期,或者 Agent 已停用。这几种情况不作区分 |
404 RESOURCE_NOT_FOUND | 模块或操作未安装,或没有授权给这把 Key。两者对调用方看起来一样 |
409 VERSION_CONFLICT | 调用期间模块版本或授权变了,或与 expected_module_version 不符。重新读取描述后再调用 |
422 PLAN_REJECTED | 输入不符合格式,或提交任务缺少 Idempotency-Key |
429 BUDGET_EXCEEDED | 请求或结果超过大小限制,缩小范围 |
503 DEPENDENCY_UNAVAILABLE | 模块离线或暂时没有应答,可以稍后重试 |
403 LICENSE_EXPIRED 等 | 许可证状态不允许调用,与这把 Key 的权限无关 |
配置模型
数脉问数这类功能需要调用大模型。模型在控制台的「系统设置 › 模型设置」里配置,所有连接按 OpenAI chat/completions 协议调用。这里配置的是 Nexus 模块自己调用的模型。智能体的客户端用哪个模型,由客户端自己决定,Nexus 只记录管理员对它的声明(见出站控制)。
- 点「添加模型连接」,选服务商。预设有 DeepSeek、通义千问、Kimi、智谱 GLM、豆包,接口地址是固定的公网地址。接入自己的模型网关或本机模型,选「OpenAI 兼容(自定义地址)」,自己填接口地址。
- 填模型名称,以服务商控制台里的名称为准。预设服务商必须填 API Key,自定义地址可以不填。API Key 加密保存,只写不回显,编辑时留空表示保留原 Key。
- 标明部署位置:「企业内部部署」表示模型运行在本企业的网络和设备上,「外部」表示云服务或第三方托管。预设服务商固定是外部,不能改成内部。自定义地址必须明确选一个,不选无法保存。
- 保存后验证连接。验证结果和失败原因显示在连接列表里,修改连接的任何设置都需要重新验证。
- 在「按用途分配」里选默认连接,也可以为某个用途单独指定连接。第一个新建的连接自动成为默认连接。
数脉有三个用途:SQL 生成、选表与问数规划、结构理解。常见做法是默认连接用速度快、成本低的模型,SQL 生成单独指定推理能力更强的。知汇的向量化和重排需要专门的模型,只有单独指定后才生效,不会沿用默认连接。
ECHOMIND_EGRESS_ALLOW),再添加连接并选「企业内部部署」。地址没有放行时,验证和调用都会失败,页面会提示。停用与轮换 Key
- 轮换:先签发新 Key,更新智能体里的配置,再撤销旧 Key。Key 快到期时(14 天内)控制台会在 Agent 列表、详情和概览里提醒。
- 撤销一把 Key:在 Agent 详情的「访问 Key」里点「撤销」,使用这把 Key 的调用立即被拒绝。
- 停用一个 Agent:在 Agent 详情里点「停用 Agent」,它的所有 Key 立即失效。授权保留,但不再生效。
- 人员离职:办理离职后,这个人的个人 Agent 和全部 Key 立即停用,返聘不会自动恢复。
- 到期:到期的 Key 在网关上和未知、已撤销的 Key 一样返回
AUTH_INVALID,需要重新签发。