Send a custom instruction

POST

https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/think

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.

appid stringrequired

The App ID of the project.

agentId stringrequired

The agent instance ID you obtained after successfully calling join to Start a conversational AI agent.

APPLICATION/JSON

BODYrequired

stringrequired

The custom instruction text to inject into the current conversation pipeline. The system processes this as user input.

stringnullable
Default: inject
Possible values: inject, ignore
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.
• ignore: Ignore the request.
stringnullable
Default: interrupt
Possible values: interrupt, ignore
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.
stringnullable
Default: ignore
Possible values: interrupt, ignore
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.
booleannullable
Default: true
Whether user speech can interrupt the injected instruction:
• true: User speech can interrupt the instruction.
• false: User speech cannot interrupt the instruction.
objectnullable

Custom metadata in key-value pair format. Use this field to pass additional business information such as identifiers or model references.

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

  OK

  string

  Unique identifier of the agent instance.

  string

  The name of the RTC channel where the agent is located.

  integer

  Timestamp indicating when the agent was created.

• 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 to understand the possible reasons for failure.

Authorization

This endpoint requires authentication.

Request example

• curl
• Python
• Node.js

_15

curl --request POST \

_15

--url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/think \

_15

--header 'Authorization: Basic <credentials>' \

_15

--header 'Content-Type: application/json' \

_15

--data '{

_15

"text": "The user just clicked the purchase button.",

_15

"on_listening_action": "inject",

_15

"on_thinking_action": "interrupt",

_15

"on_speaking_action": "ignore",

_15

"interruptable": true,

_15

"metadata": {

_15

"publisher": "user123",

_15

"model": "deepseek-r1"

_15

}

_15

}'

Response example

_5

{

_5

"agent_id": "1NT29XxxxxxxxxELWEHC8OS",

_5

"channel": "test_channel",

_5

"start_ts": 1744877089

_5

}