API Reference

Agent Hub 管理、认证与聊天接口的入口说明。

​

API Reference

Hub HTTP 接口主要位于 /api/v1。所有 /api/v1/* 接口都需要 Authorization: Bearer <JWT>（CLI token 也可作为 bearer token 使用）。认证模式决定登录流程，但业务接口仍由 Hub 的角色中间件授权。

角色（admin / maintainer / member）由 Hub 本地管理，见 配置。/api/v1/admin/* 路径按两个分组注册在相同路径上：

• adminWrite（RequireManager = admin + maintainer）：所有写方法（POST/PUT/PATCH/DELETE）与敏感读（AIGC 配置、Agent 运行时文件内容 files/content、Provider 密钥明文）。
• adminRead（admin + maintainer + member）：非敏感 GET（列表、详情、tools/skills/mcps/knowledge 绑定、文件列表、部署状态）。member 只读。

用户管理（/api/v1/admin/users、/api/v1/admin/invites）仅 admin 可用（RequireAdmin）。

​

接口区域

区域	用途	访问边界
/api/v1/admin/*	Agent、Tool、Skill、Provider 和部署管理	按角色区分读写
/api/v1/cli/*	CLI token 与身份	admin、maintainer
/api/v1/chat/*	聊天与会话	登录用户或受控回传密钥
/api/v1/ops/*	多组织 OAuth client 运维	仅设置 OPS_API_KEY 后挂载

Ops API 默认不挂载，未配置时返回 404。外部自动化应先确认部署采用的认证模式，并保存最小权限 token。

​

认证

两个可互换的认证后端由 AUTH_MODE 选择（默认 builtin）：

方法	路径	说明
GET	/auth/mode	报告当前认证模式（builtin / casdoor）
GET	/auth/login?org=<org>	（casdoor）重定向到指定组织的 Casdoor 登录。org 省略/为空 → default 组织 → 全局环境变量 CASDOOR_CLIENT_ID；未注册的未知组织 → 404，绝不回落
GET	/auth/org-check?org=<org>	（casdoor）登录预检：重定向前校验组织（未注册组织 → 404）
GET	/auth/callback	（casdoor）OAuth 回调，返回 token
POST	/auth/login	（builtin）用户名密码登录
POST	/auth/setup	（builtin）首次运行初始化，创建初始 admin 账号
POST	/auth/register	（builtin）通过一次性邀请 token 注册
GET	/auth/invite/:token	（builtin）邀请预检
POST	/auth/change-password	（builtin）修改自己的密码
GET	/auth/userinfo	当前用户信息。tenant_id 是权威字段（casdoor 模式 = Casdoor 组织名；builtin 模式 = default）；org_id 为同源兼容字段
POST	/auth/refresh	刷新 access_token（轮转：旧 refresh token 被吊销）
POST	/auth/logout	吊销 token

​

Agent（公开）

方法	路径	说明
GET	/api/v1/agents/manifest	Agent 清单（含 contentHash，供客户端缓存失效判断）
GET	/api/v1/agents	已启用 Agent 的完整配置
GET	/api/v1/agents/:name	单个 Agent 详情
GET	/api/v1/agents/:name/chat/sessions	列出某 Agent 的聊天会话
POST	/api/v1/agents/:name/chat/sessions	创建聊天会话
GET	/api/v1/agents/:name/chat/sessions/:id/messages	列出会话消息
POST	/api/v1/agents/:name/chat/sessions/:id/messages	发送消息（SSE 流）
DELETE	/api/v1/agents/:name/chat/sessions/:id	删除会话

​

Provider（公开，供客户端消费）

方法	路径	说明
GET	/api/v1/providers	本租户 Provider + 共享种子行；锁定的 API key 以掩码返回，绝不返回明文
GET	/api/v1/providers/:id	单个 Provider（同样掩码）
GET	/api/v1/providers/runtime-config	面向 Runtime 的 Provider 配置（供 Agent Runtime 消费）

明文密钥仅 admin/maintainer 可通过 POST /api/v1/admin/providers/:id/reveal-key 获取。

​

Skill（公开）

方法	路径	说明
GET	/api/v1/skills	Skill 列表（支持 ?type=expert|community）
GET	/api/v1/skills/:name	Skill 详情
GET	/api/v1/skills/:name/download	预签名下载链接（有效期 1 小时）

​

Scene（公开）

方法	路径	说明
GET	/api/v1/scenes	Scene 列表
GET	/api/v1/scenes/:name	Scene 详情

​

Chat（普通用户）

方法	路径	说明
POST	/api/v1/chat/push	回传会话/消息（每请求最多 50 个会话，按 updated_at 做冲突检测）。鉴权：JWT/CLI token（默认）或 X-Chat-Push-Key: <CHAT_PUSH_API_KEY>——密钥模式下，每个会话的 user_name（必填）成为 user_id/display_name；租户由 org 决定：builtin 模式忽略 org（恒为 default）；casdoor 模式显式传则用所传值，省略时解析为已登记的 default 租户组织（未登记则返回 400）

​

管理端点（/api/v1/admin/*）

覆盖 Agent / Tool / Skill / Scene / Provider / Knowledge / Chat 的 CRUD 与探活。重要成员：

方法	路径	分组	说明
GET	/api/v1/admin/agents/:name/deploy	adminRead	部署状态（含 runtimeUrl/apiKey，member 可读）
POST	/api/v1/admin/agents/:name/deploy（+ /stop、/start、DELETE）	adminWrite	部署与生命周期控制
GET	/api/v1/admin/agents/:name/files、/files/content	read / write	文件列表 member 可读；文件内容仅 admin/maintainer
GET×3 + DELETE	/api/v1/admin/chat/sessions...	adminRead	聊天历史。Handler 层 chatScopeUserID 隔离：member 只能查看/删除自己的会话（他人的返回 404）；admin/maintainer 可见本租户全部会话
GET/PUT/DELETE	/api/v1/admin/aigc/config（+ POST /config/rotate-key）	adminWrite	每租户的 AIGC 内容标识配置（GB 45438-2025）
GET/POST/DELETE	/api/v1/admin/users、/admin/invites	仅 admin	用户管理 / 邀请链接
GET	/api/v1/admin/audit-logs	仅 admin	审计日志查询——过滤 + 快照分页，见下文

​

审计日志（仅 admin）

GET /api/v1/admin/audit-logs——审计查询，仅 admin（RequireAdmin；maintainer/member 返回 403）。审计日志只读，没有更新/删除接口。

查询参数：

参数	默认值	说明
page	1	页码，≥ 1；非法 → 400「无效的分页参数」
page_size	20	≥ 1，上限 100（超过 100 被截断而非拒绝）；非法 → 400「无效的分页参数」
category	—	精确匹配：auth | user | invite | provider | agent | token | aigc
action	—	精确匹配，如 user.update_role
user	—	对 userName / userId 模糊匹配（LIKE %…%）
from、to	—	RFC3339 时间戳；createdAt 闭区间（from ≤ t ≤ to）；非法 → 400「无效的时间范围」
snapshotId	—	十进制字符串，可选。快照一致分页：首次请求省略时服务器捕获全租户 MAX(id)；后续请求回传返回的 snapshotId，使 items 与 total 共享同一 id <= snapshotId 视图。"0" 是空集哨兵（租户无日志）。非法 → 400「无效的快照参数」

响应（按 createdAt DESC, id DESC 排序）：

{"items":[{"id":"42","tenantId":"default","userId":"7","userName":"alice","category":"user","action":"user.update_role","targetType":"user","targetId":"2","targetName":"bob","status":"success","detail":{"field":"role","from":"member","to":"maintainer"},"remoteIp":"10.0.0.1","userAgent":"…","createdAt":"2026-09-10T12:00:00.123456Z"}],"total":1,"snapshotId":"42"}

• id / snapshotId 是十进制字符串：uint64 超过 2^53-1 的值作为 JS number 会丢精度——保持字符串，绝不转成 number。
• detail 是 JSON 对象或 null，结构由按 action 的强类型白名单决定。
• status 为三态：success / failure / partial。

​

CLI Tokens（/api/v1/cli/*——仅 admin/maintainer）

方法	路径	说明
POST	/api/v1/cli/issue-token	签发长效 CLI token（cli_<hex>；仅存 SHA-256 哈希）
GET	/api/v1/cli/tokens	列出自己的 token
DELETE	/api/v1/cli/tokens/:id	吊销 token

CLI token 拥有与签发用户相同的权限。

​

Ops API（/api/v1/ops/*——X-Ops-Key 请求头）

仅在设置 OPS_API_KEY 时挂载。用于登记各组织的 Casdoor OAuth client（多组织登录），运维手册见 配置。

方法	路径	说明
POST	/api/v1/ops/tenant-clients	新增或更新组织 → Casdoor Application 映射
GET	/api/v1/ops/tenant-clients	列出已登记组织（不返回 secret）
DELETE	/api/v1/ops/tenant-clients/:org	删除映射（若它是 default 且仍有其他行 → 409；删除不存在的组织幂等返回 204）

​

Agent ID、部署键与公开 URL

自 deployer v3.1 起，已部署 Agent 携带三个相互独立的标识：

• Agent ID（裸 <name>）：runtime agent 图身份；Hub 的聊天/详情代理通过 /v1/agents/<name> 裸名寻址 runtime（subagent 同样使用裸名）。
• Deployment key（<org>-<name>）：Kong 实体 / deployer 容器键——所有生命周期寻址（get/start/stop/delete）与网关实体命名。
• Public URL：casdoor 模式为 https://<gateway>/<org>/<name>；builtin 模式为 https://<gateway>/<name>（无 /default 前缀，但部署键仍保留 default- 前缀）。无 Kong 时，Hub 代理在 /runtime 前缀下提供相同路径。

​

Provider 探活示例

# 测试已保存 Provider 的连通性
curl -X POST http://localhost:8081/api/v1/admin/providers/1/probe \
  -H "Authorization: Bearer $TOKEN"

# 测试未保存的配置
curl -X POST http://localhost:8081/api/v1/admin/providers/probe \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "baseUrl": "https://api.anthropic.com",
    "apiKey": "sk-ant-...",
    "protocol": "anthropic",
    "authStyle": "api_key"
  }'

​

核心能力端点速查

领域	关键端点
Agent	GET /api/v1/agents/manifest
Tool	POST /api/v1/admin/tools（multipart 上传自定义工具）；PUT /api/v1/admin/tools/:name/file（补传/替换）；GET /api/v1/admin/tools/:name/download
Skill	GET /api/v1/skills/:name/download
Provider	GET /api/v1/providers
Scene	GET /api/v1/scenes
Chat	POST /api/v1/chat/push

​

自定义工具

• 单文件 .ts/.mts/.js/.mjs，≤ 5 MiB；工具名来自文件默认导出的 name（Hub 不执行代码，由 Runtime 在部署时校验）。
• tools.source：builtin（共享只读预设）/ custom（租户制品）；custom 制品状态派生 ready | missing。
• 删除仍被 Agent 挂载的自定义工具返回 409 + data.agents 名单；内置工具拒绝一切写操作。
• 部署请求向 agent-deployer 下发 customTools []ToolSource{name,url,hash,fileName}（仅 custom + ready，按名排序；URL = OSS_CDN_HOST + 内容寻址 key）。
• PUT /api/v1/admin/tools/:name 仅接受 title / description / descriptionEn；其他字段（如 isDefault）会被静默忽略。