Send a custom instruction
Updated
Sends a custom text instruction to a specified Conversational AI agent instance.
https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/thinkUse 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.
Path Parameters
appidstringThe App ID of the project.
agentIdstringThe agent instance ID you obtained after successfully calling join to Start a conversational AI agent.
Request Body
application/json
textstringThe custom instruction text to inject into the current conversation pipeline. The system processes this as user input.
on_listening_actionstringThe 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.append: Don't interrupt the current user input. After the LLM finishes responding to it, append the custom text instruction as a separate user message and initiate a new round of dialogue.ignore: Ignore the request.
on_thinking_actionstringThe action to take when the agent is in a thinking state:
interrupt: Interrupt the current state and start a new conversation turn.append: Don't interrupt the current LLM inference. After the current turn's LLM output finishes, append the custom text instruction as a separate user message and start a new conversation turn.ignore: Ignore the request.
on_speaking_actionstringThe action to take when the agent is in a speaking state:
interrupt: Interrupt the current state and start a new conversation turn.append: Don't interrupt the current TTS playback. After the current turn's LLM output finishes, append the custom text instruction as a separate user message and start a new conversation turn.ignore: Ignore the request.
interruptablebooleanWhether user speech can interrupt the injected instruction:
true: User speech can interrupt the instruction.false: User speech cannot interrupt the instruction.
metadataobjectCustom metadata in key-value pair format. Use this field to pass additional business information such as identifiers or model references.
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 thedetailandreasonfor failure. Refer to status codes to understand the possible reasons for failure.
Response Body
The request was successful. The response body contains the result of the request.
agent_idstringUnique identifier of the agent instance.
channelstringThe name of the RTC channel where the agent is located.
start_tsintegerTimestamp indicating when the agent was created.
Request examples
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" } }'Response example
{ "agent_id": "1NT29XxxxxxxxxELWEHC8OS", "channel": "test_channel", "start_ts": 1744877089}