Docs / API

API 接入说明

面向私有化项目的接口契约样板。正式字段、域名、权限和额度以客户环境交付版本为准。
返回文档中心预约接口评审

鉴权与环境

  • API 以客户私有环境或专属网关为准，域名、租户和权限范围在交付阶段确认。
  • 调用方需使用项目分配的 access key 或内网 SSO 令牌，所有请求写入审计日志。
  • 生产接入前需确认网络白名单、回调地址、数据分级和调用频率上限。

模型调度调用

  • POST /api/v1/model-routes/{routeId}/invoke 用于按路由调用指定模型能力。
  • 请求包含 input、context、traceId 和 policyTags，响应返回 output、usage、routeVersion 与 auditId。
  • 支持按业务系统、模型供应商、数据等级和审批策略配置不同调用边界。

任务与审计

  • POST /api/v1/tasks 创建 Agent OS 任务，并绑定执行人、数据范围和审批策略。
  • GET /api/v1/audit-events 按 traceId、taskId、userId 或时间范围查询审计事件。
  • 审计字段至少包含调用来源、模型路由、权限策略、数据范围、结果状态和异常说明。

回调与错误码

  • POST /api/v1/webhooks/events 用于接收任务状态、审批结果和模型调用完成事件。
  • 错误码按 auth、policy、quota、model、integration、system 六类归档。
  • 上线验收需覆盖鉴权失败、权限拒绝、额度超限、模型超时和回调重试场景。

Read Path

从鉴权到审计，完成一次可复核的调用路径。

  1. 确认环境和鉴权边界
  2. 选择模型路由或任务对象
  3. 带 traceId 发起请求
  4. 按错误码和审计事件完成验收

请求样板

HTTP / JSON
POST /api/v1/model-routes/security-review/invoke
Authorization: Bearer <project-token>
Content-Type: application/json

{
  "traceId": "poc-20260615-001",
  "input": {
    "documentId": "case-file-001",
    "question": "提取本次审批中的关键风险点"
  },
  "context": {
    "businessSystem": "oa",
    "dataLevel": "internal",
    "operatorId": "u-1001"
  },
  "policyTags": ["private-deployment", "audit-required"]
}

响应样板

JSON
{
  "auditId": "audit-7f23",
  "routeVersion": "2026.06-preview",
  "status": "completed",
  "output": {
    "summary": "已识别 3 项审批风险，需补充附件授权记录。",
    "riskLevel": "medium"
  },
  "usage": {
    "model": "customer-private-route",
    "tokens": 1840
  }
}