AGENT API 概览：OpenAI Agents 接口

咏唱引擎 AGENT API 暴露 OpenAI beta Agents 资源接口，具备持久化的 Postgres + pgvector 状态，并提供 JS 与 Python SDK。

AGENT API 是咏唱引擎基于 OpenAI codex harness 构建的分层智能体平台。它暴露 OpenAI beta Agents API，因此你可以创建智能体、管理会话，并将状态持久化到 Postgres（配合 pgvector 实现按主体的 context_fragments）。你可以直接使用 API，或通过镜像 OpenAI Agents SDK 的 JS 与 Python SDK 来调用。

认证

Bearer 与 ApiKey 两种方案，自助式密钥管理

创建智能体

使用模型、指令、工具与元数据创建智能体

创建会话

为已有智能体启动会话并追踪其状态

API 密钥

生成并管理用于编程访问的 API 密钥

基础 URL

https://agent.example.com

认证

API 支持两种请求头方案：

• Authorization: Bearer <api_key>
• Authorization: ApiKey <key>

当服务端以未设置 AGENT_CLOUD_API_KEY 的方式启动时，认证是可选的。此时接口开放，无需 Authorization 头。当该环境变量被设置时，每个请求都必须携带有效的密钥。

错误格式

错误返回 HTTP 状态码与一个 JSON 响应体：

{
  "error": "Description of what went wrong"
}

版本管理

当前接口以 /v1 为前缀，并遵循 OpenAI beta Agents API 的形态。部分接口已被识别但返回 HTTP 501 Not Implemented：

• Vaults：/v1/vaults*
• Environments：/v1/agents/environments*
• 会话产物：/v1/agents/sessions/{id}/artifacts