# Send a custom instruction (/en/api-reference/api-ref/conversational-ai/think)

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

Sends a custom text instruction to a specified Conversational AI agent instance.

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

## Servers

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

Use this endpoint to send a custom text instruction to the specified Conversational AI agent instance. The instruction is injected into the current conversation pipeline as user input, and the agent processes and responds to it following the standard user input logic.

Use this endpoint for the following scenarios:

- **Implicit instruction injection**: Inject hidden context or directives into the conversation.
- **Client-side event triggering**: Notify the agent of client-side events, such as a user clicking a button.
- **Voice and text collaboration**: Combine text instructions with voice input for richer interaction.


## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of the project.
- `agentId` (path, required, string) - The agent instance ID you obtained after successfully calling `join` to [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join).

## Request body

- `text` (string, required) - The custom instruction text to inject into the current conversation pipeline. The system processes this as user input.
- `on_listening_action` (string) - The action to take when the agent is in a listening state:
- `inject`: Inject the custom text instruction into the current turn without interrupting it.
- `interrupt`: Immediately interrupt the current flow and initiate a new round of dialogue.
- `ignore`: Ignore the request.
  - Allowed: `inject` | `interrupt` | `ignore`
  - Default: `interrupt`
- `on_thinking_action` (string) - The action to take when the agent is in a thinking state:
- `interrupt`: Interrupt the current state and start a new conversation turn.
- `ignore`: Ignore the request.
  - Allowed: `interrupt` | `ignore`
  - Default: `interrupt`
- `on_speaking_action` (string) - The action to take when the agent is in a speaking state:
- `interrupt`: Interrupt the current state and start a new conversation turn.
- `ignore`: Ignore the request.
  - Allowed: `interrupt` | `ignore`
  - Default: `ignore`
- `interruptable` (boolean) - Whether user speech can interrupt the injected instruction:
- `true`: User speech can interrupt the instruction.
- `false`: User speech cannot interrupt the instruction.
  - Default: `true`
- `metadata` (object) - Custom metadata in key-value pair format. Use this field to pass additional business information such as identifiers or model references.

## Request examples

### curl

```bash
curl --request POST \
    --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/think \
    --header 'Authorization: Basic <credentials>' \
    --header 'Content-Type: application/json' \
    --data '{
      "text": "The user just clicked the purchase button.",
      "on_listening_action": "interrupt",
      "on_thinking_action": "interrupt",
      "on_speaking_action": "ignore",
      "interruptable": true,
      "metadata": {
        "publisher": "user123",
        "model": "deepseek-r1"
      }
    }'
```

### Python

```python
import requests

  url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/think"
  headers = {
      "Authorization": "Basic <credentials>",
      "Content-Type": "application/json"
  }
  payload = {
      "text": "The user just clicked the purchase button.",
      "on_listening_action": "interrupt",
      "on_thinking_action": "interrupt",
      "on_speaking_action": "ignore",
      "interruptable": True,
      "metadata": {
          "publisher": "user123",
          "model": "deepseek-r1"
      }
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.text)
```

### Node.js

```javascript
const axios = require("axios");

const url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/think";
const headers = {
    Authorization: "Basic <credentials>",
    "Content-Type": "application/json"
};
const payload = {
    text: "The user just clicked the purchase button.",
    on_listening_action: "interrupt",
    on_thinking_action: "interrupt",
    on_speaking_action: "ignore",
    interruptable: true,
    metadata: {
        publisher: "user123",
        model: "deepseek-r1"
    }
};

axios.post(url, payload, { headers })
  .then(response => console.log(response.data))
  .catch(error => console.error(error.response ? error.response.data : error.message));
```


### Response

- If the returned status code is `200`, the request was successful. The response body contains the result of the request.

- If the returned status code is not `200`, the request failed. The response body includes the `detail` and `reason` for failure. Refer to [status codes](/en/api-reference/api-ref/conversational-ai/status-codes) to understand the possible reasons for failure.


## Responses

### 200

The request was successful. The response body contains the result of the request.

- `agent_id` (string) - Unique identifier of the agent instance.
- `channel` (string) - The name of the RTC channel where the agent is located.
- `start_ts` (integer) - Timestamp indicating when the agent was created.
### default

The request failed. The response body includes the error details.

- `detail` (string) - Detailed error information.
- `reason` (string) - The reason for the failure.

## Response examples

### 200

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