# 发送自定义指令 (/zh-CN/api-reference/api-ref/conversational-ai/think)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

向指定智能体发送一段自定义文本指令。

- OpenAPI: /openapi/conversational-ai/rest-api.zh-CN.yaml
- Operation ID: agent-think
- Method: POST
- Path: /v2/projects/{appid}/agents/{agentId}/think
- Endpoint: https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/think

## Servers

- https://api.agora.io/cn/api/conversational-ai-agent

该接口会将传入文本作为用户输入注入当前对话链路，并由对话式 AI 引擎继续按照普通用户输入的处理逻辑进行推理和响应。你可以使用该接口实现隐式指令注入、客户端事件触发和语音与文本协同等场景。


## Authorization

This endpoint requires authentication.

- `Basic Auth`
- `Agora Token`

## Parameters

No parameters.

## Request body

- `text` (string, required) - 自定义指令文本内容。系统会将其作为用户输入注入当前对话链路。
- `on_listening_action` (string) - 智能体处于倾听状态时的处理动作，支持以下值：
- `"inject"`：自定义文本指令注入当前轮次，不打断当前轮次。
- `"interrupt"`：（默认）立即打断当前处理流程，并发起新一轮对话。
- `"append"`：不打断当前用户输入。等待当前用户输入对应的 LLM 输出完成后，将自定义文本指令作为独立的 user 消息追加到上下文，并发起新一轮对话。
- `"ignore"`：忽略本次请求。

  - Allowed: `inject` | `interrupt` | `append` | `ignore`
  - Default: `interrupt`
- `on_thinking_action` (string) - 智能体处于思考状态时的处理动作，支持以下值：
- `"interrupt"`：（默认）打断当前状态，并发起新一轮对话。
- `"append"`：不打断当前 LLM 推理。等待当前轮次的 LLM 输出完成后，将自定义文本指令作为独立的 user 消息追加到上下文，并发起新一轮对话。
- `"ignore"`：忽略本次请求。

  - Allowed: `interrupt` | `append` | `ignore`
  - Default: `interrupt`
- `on_speaking_action` (string) - 智能体处于说话状态时的处理动作，支持以下值：
- `"interrupt"`：打断当前状态，并发起新一轮对话。
- `"append"`：不打断当前 TTS 播报。等待当前轮次的 LLM 输出完成后，将自定义文本指令作为独立的 user 消息追加到上下文，并发起新一轮对话。
- `"ignore"`：（默认）忽略本次请求。

  - Allowed: `interrupt` | `append` | `ignore`
  - Default: `ignore`
- `interruptable` (boolean) - 是否允许用户说话打断自定义指令：
- `true`：（默认）允许。
- `false`：不允许。

  - Default: `true`
- `metadata` (object) - 自定义元数据。你可以通过该字段传入业务标识等附加信息。

### Request body example

```json
{
  "text": "用户刚才点击了购买按钮",
  "on_listening_action": "append",
  "on_thinking_action": "append",
  "on_speaking_action": "append",
  "interruptable": true,
  "metadata": {
    "publisher": "user123",
    "model": "deepseek-r1"
  }
}
```

## Responses

### 200

- 若返回的状态码为 `200` 则表示请求成功。响应包体为智能体信息。
- 若返回的状态码不为 `200` 则表示请求失败。响应包体中包含错误的类别和描述，你可以参考[响应状态码](/zh-CN/api-reference/conversational-ai/rest-api/api/response-code)了解可能的原因。

- `agent_id` (string) - 对话式智能体 ID，即智能体唯一标识。
- `channel` (string) - 智能体所在 RTC 频道名。
- `start_ts` (integer) - 智能体创建时间戳。

## Response examples

### 200

```json
{
  "agent_id": "1NT29XxxxxxxxxELWEHC8OS",
  "channel": "test_channel",
  "start_ts": 1744877089
}
```