The custom instruction text to inject into the current conversation pipeline. The system processes this as user input.
Send a custom instruction
Updated
Sends a custom text instruction to a specified Conversational AI agent instance.
post
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
The App ID of the project.
The agent instance ID you obtained after successfully calling join to Start a conversational AI agent.
Request Body
application/json
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.
Default
interruptAllowedinject | interrupt | ignoreThe 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.
Default
interruptAllowedinterrupt | ignoreThe 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.
Default
ignoreAllowedinterrupt | ignoreWhether user speech can interrupt the injected instruction:
true: User speech can interrupt the instruction.false: User speech cannot interrupt the instruction.
Default
trueCustom 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
application/json
application/json
Response schema
200application/jsonThe request was successful. The response body contains the result of the request.
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}{ "detail": "string", "reason": "string"}