Agent API 调用接口

Agent API 用于把已发布的 Agent 接入到业务应用或服务中。应用服务器使用 X-API-Key 创建会话，获取实时通话凭据后，客户端通过 RTC SDK 加入房间并与 Agent 实时对话。

一、接入前准备

1. 发布 Agent

在 Agent 平台完成编排并发布 Agent。发布页会展示公开 Agent ID，例如：

ag5837b2d35a0b4500908282d74e5a4d

调用 API 时，请将发布页展示的公开 Agent ID 填入 agentId。

2. 创建 API Key

进入控制台的 API Key 管理页面创建 Key，并确保该 Key 具备 Agent 会话能力。请求时通过 Header 传入：

X-API-Key: YOUR_API_KEY

3. 生成幂等键

创建会话接口要求传入幂等键。推荐每次创建会话时生成一个 UUID，并通过 Header 传入：

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

也可以兼容性地在请求体传 clientRequestId，但推荐使用 Header。

接口总览

能力	方法与路径	说明
创建会话	`POST /api/v1/agents/openapi/sessions/create`	创建 Agent 实时通话会话，返回 RTC 入会凭据
查询状态	`GET /api/v1/agents/openapi/sessions/check`	查询当前会话状态
会话心跳	`POST /api/v1/agents/openapi/sessions/heartbeat`	通话期间保活并获取关闭信号
结束会话	`DELETE /api/v1/agents/openapi/sessions/end`	主动结束当前会话

二、创建 Agent 会话

接口路径：/api/v1/agents/openapi/sessions/create
请求方法：POST
鉴权方式：X-API-Key

参数	类型	必填	说明
X-API-Key	string	是	项目空间 API Key
Idempotency-Key	string	是	幂等键。若不传 Header，则必须在请求体中传 `clientRequestId`
Content-Type	string	是	固定为 `application/json`

请求体

参数	类型	必填	说明
agentId	string	是	发布页展示的公开 Agent ID
userIdentifier	string	否	业务方用户标识，建议格式为 `eu:{external_user_id}`；不传时自动生成
clientRequestId	string	否	兼容字段；推荐改用 Header `Idempotency-Key`
traceId	string	否	业务方链路追踪 ID；不传时自动生成

请求示例

curl -X POST 'https://api.vuilabs.cn/api/v1/agents/openapi/sessions/create' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  -d '{
    "agentId": "ag5837b2d35a0b4500908282d74e5a4d",
    "userIdentifier": "eu:user_123"
  }'

响应字段

字段	类型	说明
error_code	number	错误码，`0` 表示成功
error_message	string	错误信息，成功时为空
succeed	boolean	请求是否成功
data.item.sessionId	string	Agent 会话 ID，后续查询、心跳和结束会话时使用
data.item.wsUrl	string	RTC 服务地址
data.item.userToken	string	用户入会 Token
data.item.roomName	string	RTC 房间名称
data.item.expireAt	number	Token 过期时间，Unix 秒
data.item.status	string	会话状态，创建成功后通常为 `connecting`
data.item.agentId	string	本次使用的公开 Agent ID

成功响应示例

{
  "error_code": 0,
  "error_message": "",
  "succeed": true,
  "data": {
    "item": {
      "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "wsUrl": "wss://rtc.vuilabs.cn",
      "userToken": "<USER_TOKEN>",
      "roomName": "agent-call-worker:xxxxxxxxxxxxxxxx",
      "expireAt": 1781165756,
      "status": "connecting",
      "agentId": "ag5837b2d35a0b4500908282d74e5a4d"
    }
  }
}

三、查询会话状态

接口路径：/api/v1/agents/openapi/sessions/check
请求方法：GET
鉴权方式：X-API-Key

Query 参数

参数	类型	必填	说明
session_id	string	是	创建会话返回的 `sessionId`

请求示例

curl -X GET 'https://api.vuilabs.cn/api/v1/agents/openapi/sessions/check?session_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'X-API-Key: YOUR_API_KEY'

四、会话心跳

通话期间建议每 5 秒发送一次心跳，并根据响应获取剩余可通话时长、判断是否需要关闭会话。

接口路径：/api/v1/agents/openapi/sessions/heartbeat
请求方法：POST
鉴权方式：X-API-Key

Query 参数

参数	类型	必填	说明
session_id	string	是	创建会话返回的 `sessionId`

请求示例

curl -X POST 'https://api.vuilabs.cn/api/v1/agents/openapi/sessions/heartbeat?session_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'X-API-Key: YOUR_API_KEY'

响应字段

字段	类型	说明
data.item.sessionId	string	会话 ID
data.item.status	string	会话状态，例如 `in_call`、`ended`、`failed`
data.item.shouldClose	boolean	是否要求客户端关闭会话
data.item.closeReason	string	关闭原因；为空表示暂无关闭原因
data.item.remainingSeconds	number	剩余可通话秒数

成功响应示例

{
  "error_code": 0,
  "error_message": "",
  "succeed": true,
  "data": {
    "item": {
      "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "status": "in_call",
      "shouldClose": false,
      "closeReason": "",
      "remainingSeconds": 1500
    }
  }
}

五、结束会话

用户主动结束通话、页面关闭或业务侧不再需要会话时，应调用结束会话接口。

接口路径：/api/v1/agents/openapi/sessions/end
请求方法：DELETE
鉴权方式：X-API-Key

Query 参数

参数	类型	必填	说明
session_id	string	是	创建会话返回的 `sessionId`

请求示例

curl -X DELETE 'https://api.vuilabs.cn/api/v1/agents/openapi/sessions/end?session_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'X-API-Key: YOUR_API_KEY'

成功响应示例

{
  "error_code": 0,
  "error_message": "",
  "succeed": true,
  "data": {
    "item": {
      "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "status": "ended",
      "shouldClose": false
    }
  }
}

六、前端接入示例

建议在应用服务器保存 API Key 并创建 Agent 会话。客户端仅接收 wsUrl、userToken、roomName、sessionId 等临时凭据。

const resp = await fetch('https://api.vuilabs.cn/api/v1/agents/openapi/sessions/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.VUI_API_KEY,
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    agentId: 'ag5837b2d35a0b4500908282d74e5a4d',
    userIdentifier: 'eu:user_123',
  }),
});

const payload = await resp.json();
if (!resp.ok || payload.succeed === false) {
  throw new Error(payload.error_message || `HTTP ${resp.status}`);
}

const session = payload.data.item;

拿到会话凭据后，可以使用 @vuilabs/rtc-web-sdk 建立实时语音连接。业务侧应在通话期间定时调用心跳接口，并在用户挂断时调用结束会话接口。

七、计费说明

具体计费规则、价格和免费额度请参见产品计费。

八、常见错误

错误码	说明	建议处理
10001	参数错误	检查 `agentId`、`Idempotency-Key` 或 `session_id` 是否为空
10003	未授权	检查 `X-API-Key` 是否正确传入、是否已失效
10004	禁止访问	检查 API Key 是否具备 Agent 会话能力，Agent 是否属于当前项目空间
10002	资源不存在	检查公开 Agent ID 或会话 ID 是否正确
10014	连接数限制	降低并发连接数或联系支持扩容
20003	余额不足	检查对应免费额度和账户余额，充值后重试

更多错误码请参考错误码说明。

一、接入前准备​

1. 发布 Agent​

2. 创建 API Key​

3. 生成幂等键​

接口总览​

二、创建 Agent 会话​

Header 参数​

请求体​

请求示例​

响应字段​

成功响应示例​

三、查询会话状态​

Query 参数​

请求示例​

四、会话心跳​

Query 参数​

请求示例​

响应字段​

成功响应示例​

五、结束会话​

Query 参数​

请求示例​

成功响应示例​

六、前端接入示例​

七、计费说明​

八、常见错误​

一、接入前准备

1. 发布 Agent

2. 创建 API Key

3. 生成幂等键

接口总览

二、创建 Agent 会话

Header 参数

请求体

请求示例

响应字段

成功响应示例

三、查询会话状态

Query 参数

请求示例

四、会话心跳

Query 参数

请求示例

响应字段

成功响应示例

五、结束会话

Query 参数

请求示例

成功响应示例

六、前端接入示例

七、计费说明

八、常见错误