Agent 调用应用
让 agent 也能用你的应用:skill + CLI 薄客户端、agent 的身份、代人办事。
Agent 调用应用
预览:本页用到的 Agent 应用令牌(
POST /api/v1/app-agent-tokens)和主人授权(/api/v1/app-agent-grants)两个接口,请求和响应格式还没有公开文档。agent 用什么身份调你的应用有两种做法(见「token」):平台的「Agent 应用令牌」+ 主人授权(推荐,参考实现 OpenMax Workflows 就这样做),或由应用自己给 Agent 发 API key。本页按前一种写。
做法
- 交付形式:skill 只做薄客户端,调你的 CLI。CLI 命令从接口契约(OpenAPI)生成,契约是唯一正本,每个操作要么对应一个命令,要么写明为什么没有。
- 分发:skill + CLI 放在公开仓库,release 附各平台二进制和 sha256,安装时核对。参考:openmaxai/zylos-workflows。
- Agent 的身份:CLI 用本机已有的 agent 凭据,先换 agent 令牌,再换只给本应用用的应用令牌(
POST /api/v1/app-agent-tokens,带 client_id),15 分钟有效。agent 令牌只发给 OpenMax。 - 服务端每次都核:RS256、JWKS 验签、
aud= client_id、exp / iat、kind=agent,再调/api/v1/me确认 sub。 - 主人授权:agent 的主人在应用页面里点「让它用」,服务端用主人自己的应用令牌调
/api/v1/app-agent-grants登记 / 撤销;组织管理员要停,在 OpenMax 侧撤。 - 登记只认主人私信:主人在私信里发安装话,脚本把部署地址、org_id、client_id 写进本地登记文件(权限 0600)。
- CLI 退出码:2 = 没身份或没登记,3 = 授权失效 / 401,75 = OpenMax 暂时不可用。凭据不从命令参数传、不落盘。
- 代人办事:agent 用自己的身份调,另带请求头说明替谁办(说话人 member_id、来源消息、会话,JSON ≤1024 字节)。只有白名单路由收这个头,其余回 403;说话人不是本组织在职成员、是 AI 成员、格式不对,都回 422。权限按说话人和 agent 两档取低。
- 不让 agent 直接拍板:要起的事先出确认卡,回 202 和确认链接,说话人在网页上点「提交」才生效;审批不能代批。
- OpenMax 以外的渠道:只允许发起运行,并且必须用固定的认人工具对到一个成员,不能从对话里推断是谁。
- 审计:代办记入口「代办」,操作人记本人。见提交审批与安装「权限与审计」。
踩过的坑
- 平台自定义连接器只能存固定 Bearer,装不了 15 分钟一换的令牌,所以连接器这条路只是过渡,新接入只用 CLI。
- 停发 key 要三样同一版就绪才能上:CLI、CLI 能装上(release 附 sha256)、主人能授权。少一样,老 agent 一升级就连不上。
- 部署共用一个个人 API Key 去查平台数据,只能查到 key 主人所在的组织,还要人手轮换。改成用 agent 主人的应用令牌,manifest 补申请对应 scope。
