发送自定义指令
更新时间不可用
向指定智能体发送一段自定义文本指令。
POST
https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/think该接口会将传入文本作为用户输入注入当前对话链路，并由对话式 AI 引擎继续按照普通用户输入的处理逻辑进行推理和响应。你可以使用该接口实现隐式指令注入、客户端事件触发和语音与文本协同等场景。
鉴权
appidstring必填
你的项目使用的 App ID。
agentIdstring必填
智能体实例 ID，即智能体的唯一标识。调用 POST 创建对话式智能体 成功后在响应包体中获取。
Authorizationstring必填
发送 HTTP 请求时，你可以从以下鉴权方式中任选其一：
- 使用 Token 认证（推荐）：参考实现 HTTP 鉴权生成 Token 并填入
AuthorizationHeader。传参示例：Authorization: agora token="007abcxxxxxxx123"。 - 使用 Basic Auth：参考实现 HTTP 鉴权生成 Base64 编码的
Authorization字段。传参示例：Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=。
textstring必填
自定义指令文本内容。系统会将其作为用户输入注入当前对话链路。
on_listening_actionstring智能体处于倾听状态时的处理动作，支持以下值：
"inject"：自定义文本指令注入当前轮次，不打断当前轮次。"interrupt"：（默认）立即打断当前处理流程，并发起新一轮对话。"append"：不打断当前用户输入。等待当前用户输入对应的 LLM 输出完成后，将自定义文本指令作为独立的 user 消息追加到上下文，并发起新一轮对话。"ignore"：忽略本次请求。
on_thinking_actionstring智能体处于思考状态时的处理动作，支持以下值：
"interrupt"：（默认）打断当前状态，并发起新一轮对话。"append"：不打断当前 LLM 推理。等待当前轮次的 LLM 输出完成后，将自定义文本指令作为独立的 user 消息追加到上下文，并发起新一轮对话。"ignore"：忽略本次请求。
on_speaking_actionstring智能体处于说话状态时的处理动作，支持以下值：
"interrupt"：打断当前状态，并发起新一轮对话。"append"：不打断当前 TTS 播报。等待当前轮次的 LLM 输出完成后，将自定义文本指令作为独立的 user 消息追加到上下文，并发起新一轮对话。"ignore"：（默认）忽略本次请求。
interruptableboolean是否允许用户说话打断自定义指令：
true：（默认）允许。false：不允许。
metadataobject自定义元数据。你可以通过该字段传入业务标识等附加信息。
响应
- 若返回的状态码为
200则表示请求成功。响应包体为智能体信息。 - 若返回的状态码不为
200则表示请求失败。响应包体中包含错误的类别和描述，你可以参考响应状态码了解可能的原因。
响应 Body
agent_idstring对话式智能体 ID，即智能体唯一标识。
channelstring智能体所在 RTC 频道名。
start_tsinteger智能体创建时间戳。
请求示例
curl --request POST \
--url "https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/think" \
--header 'Authorization: agora token="007abcxxxxxxx123"' \
-H 'Content-Type: application/json' \
-d '{
"text": "用户刚才点击了购买按钮",
"on_listening_action": "append",
"on_thinking_action": "append",
"on_speaking_action": "append",
"interruptable": true,
"metadata": {
"publisher": "user123",
"model": "deepseek-r1"
}
}'响应示例
{
"agent_id": "1NT29XxxxxxxxxELWEHC8OS",
"channel": "test_channel",
"start_ts": 1744877089
}