> ## 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.

# 创建智能体 - POST /v1/agents

> 通过提交一个 OpenAI 兼容的智能体对象（包含 name、model、instructions、tools 与 metadata）来创建新智能体。返回已创建的智能体。

在咏唱引擎上创建智能体，发送其名称、模型以及可选的指令、工具与元数据等字段。其形态镜像 OpenAI beta 的智能体对象，因此现有 SDK 代码只需极少改动即可工作。

## 接口

```http theme={null}
POST /v1/agents
```

## 认证

`Authorization: Bearer <api_key>` 或 `Authorization: ApiKey <key>`。若 `AGENT_CLOUD_API_KEY` 在服务端启动时未设置，则可选。

## 请求体

<ParamField body="name" type="string" required>
  便于识别的智能体名称。
</ParamField>

<ParamField body="model" type="string" required>
  智能体使用的模型标识符（例如 `gpt-4o`）。
</ParamField>

<ParamField body="instructions" type="string">
  引导智能体行为的系统提示或指令。
</ParamField>

<ParamField body="tools" type="array">
  智能体可用的工具定义列表。
</ParamField>

<ParamField body="metadata" type="object">
  用于你自行记账的任意键值对。
</ParamField>

## 响应

<ResponseField name="id" type="string">
  智能体的唯一标识符。
</ResponseField>

<ResponseField name="object" type="string">
  恒为 `agent`。
</ResponseField>

<ResponseField name="name" type="string">
  智能体的名称。
</ResponseField>

<ResponseField name="model" type="string">
  模型标识符。
</ResponseField>

<ResponseField name="instructions" type="string">
  系统指令（若提供）。
</ResponseField>

<ResponseField name="tools" type="array">
  为智能体注册的工具。
</ResponseField>

<ResponseField name="metadata" type="object">
  附加在智能体上的元数据映射。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://agent.example.com/v1/agents \
    -H "Authorization: Bearer <api_key>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "SupportBot",
      "model": "gpt-4o",
      "instructions": "You are a helpful support assistant.",
      "metadata": { "team": "support" }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "ag_01J1234567890ABCDEF",
    "object": "agent",
    "name": "SupportBot",
    "model": "gpt-4o",
    "instructions": "You are a helpful support assistant.",
    "tools": [],
    "metadata": { "team": "support" }
  }
  ```
</ResponseExample>