接入运行时客户端

运行时客户端通过限定范围的公开运行时契约调用一个已发布的 Agent Business。它不会获得创作者控制台权限或模型提供商凭据。

获取运行时契约

从 Agent Business 的 Surfaces Workspace 记录：

• 业务 Slug；
• 当前激活的 Capability 与交互模式；
• 以 pk_app_ 开头的公开运行时 Token；
• 输入与输出 Schema；
• 浏览器调用时允许的来源；
• 额度、身份验证、支付或 Turnstile 要求。

这个 Token 可以公开，但其权限必须限定在单个业务。它只能授权该 Agent Business 已发布的运行时 Surface，绝不能授权创作者、账单管理、提供商密钥或 Operator Endpoint。

读取运行时配置

使用受管理的 API 来源：

https://api.agentaab.com/api

运行时配置路由是：

GET /app/{business-slug}/runtime-config

它返回公开安全的 Capability、参数、Endpoint、访问和展示元数据。请根据它选择受支持的调用路由，不要假设所有业务都使用同一种交互模式。

验证运行时调用

会改变状态的运行时请求可以通过以下任一 Header 携带 Agent Business 公开运行时 Token：

Authorization: Bearer pk_app_your_scoped_token

或：

X-API-Key: pk_app_your_scoped_token

除非现有客户端约定必须使用 X-API-Key，否则优先使用 Authorization: Bearer。绝不要把创作者会话 Token 发送到公开运行时 Endpoint。

选择调用路由

根据运行时配置和运行时 API 参考为已发布契约构建请求正文：

• Prompt Completion：POST /app/{business-slug}/completion-messages；
• 对话能力：POST /app/{business-slug}/chat-messages；
• Workflow 能力：POST /app/{business-slug}/workflows/run。

当契约需要执行额度、身份、积分或支付决策时，请发送稳定且限定在该业务内的运行时用户标识。不要在无关的 Agent Business 之间复用原始内部用户 ID。

浏览器客户端与 CORS

只有当准确的 HTTPS 来源存在于 Agent Business 的允许来源策略中，浏览器才能读取响应。请登记生产来源以及每个明确支持的 Preview 来源，不要用通配符掩盖部署配置缺失。

如果 Preflight 失败，请先检查业务 Slug、路由、HTTP Method、可见性和允许来源，再修改客户端代码。

处理运行时决策

客户端应分别处理以下结果：

• 401：缺少公开运行时 Token，或 Token 无效；
• 402：执行前需要额度、积分或支付；
• 403：来源、可见性、授权或保护策略拒绝请求；
• 429：速率或使用策略限制了请求；
• 5xx：执行或必需的运行时状态不可用。

如果响应提供公开错误码和请求关联信息，可以展示或记录它们。不要在分析数据中暴露原始请求正文、响应正文、凭据或提供商 Payload。

生产前验证

1. 从生产 API 来源读取运行时配置。
2. 按已发布 Schema 发送一个有代表性的合法请求。
3. 测试非法输入以及适用的额度、身份或支付边界。
4. 如为浏览器调用，从最终 HTTPS 来源验证 CORS。
5. 确认调用出现在 Operations 中预期的 Agent Business、Release、Channel 和 Offer 下。