接入运行时客户端

运行时客户端通过限定范围的公开运行时契约调用一个已发布的 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 参考为已发布契约构建请求正文：

• Single Agent Completion：POST /app/{business-slug}/completion-messages；
• 对话型 Single Agent：POST /app/{business-slug}/chat-messages；
• Workflow：POST /app/{business-slug}/workflows/run。

Workflow 请求只包含一个顶层 inputs Object。Runtime 执行准确的当前激活 Capability Release，绝不会执行最新 Workflow Draft。原生 Workflow 响应会在 Metadata 中包含脱敏执行 Trace；客户端不能把 Trace 当作凭据或私有 Provider 数据来源。

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

浏览器客户端与 CORS

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

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

处理运行时决策

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

• 401：缺少公开运行时 Token，或 Token 无效；
• 402：执行前需要额度、积分或支付；
• 403：来源、可见性、授权或保护策略拒绝请求；
• 413：有界请求正文过大；
• 422：Workflow 节点执行失败，响应可能包含脱敏的部分 Trace；
• 429：速率或使用策略限制了请求；
• 5xx：执行或必需的运行时状态不可用。

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

生产前验证

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