> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 来调用。

<CardGroup cols={2}>
  <Card title="认证" icon="key" href="/api-reference/agent/authentication">
    Bearer 与 ApiKey 两种方案，自助式密钥管理
  </Card>

  <Card title="创建智能体" icon="plus" href="/api-reference/agent/agents/create">
    使用模型、指令、工具与元数据创建智能体
  </Card>

  <Card title="创建会话" icon="play" href="/api-reference/agent/sessions/create">
    为已有智能体启动会话并追踪其状态
  </Card>

  <Card title="API 密钥" icon="lock" href="/api-reference/agent/api-keys">
    生成并管理用于编程访问的 API 密钥
  </Card>
</CardGroup>

## 基础 URL

```text theme={null}
https://agent.example.com
```

## 认证

API 支持两种请求头方案：

* `Authorization: Bearer <api_key>`
* `Authorization: ApiKey <key>`

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

## 错误格式

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

```json theme={null}
{
  "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`