Update a session
Updated
Changes the RTC token or the model context of a running session.
Preview documentation
https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/sessions/{agent_session_id}Use this endpoint to renew the agent's RTC token, or to replace the conversation messages or LLM parameters of a running session. Each field you pass replaces its current value as a whole, so include every LLM parameter that must stay. messages also replaces the agent's instructions, so pass the instructions as the first system message to keep them. You can't change other session or transport fields after the session starts.
Support for runtime changes depends on the provider. If the provider can't apply a change, the request fails with NotImplemented and the session doesn't change.
appidstringThe App ID of your project.
agent_session_idstringThe ID of the session, returned in agent_session_id when you start the session.
transportobjectChanges to the transport. Only the RTC token can change.
tokenstringA new RTC token for the agent. Applies only to sessions that started with a token.
agentobjectChanges to the running agent.
overridesobjectValues that replace the running agent's current values.
messagesarray<object>The conversation messages the agent uses. They replace all of the current messages, including the agent's instructions, which the session received as its first system message. To keep the instructions, pass them as the first system message in this list.
rolestringThe author of the message:
system: An instruction to the model.user: A message from the user.assistant: A message from the agent.
contentstringThe text of the message.
pipelineobjectRuntime model parameters.
llmobjectparamsobjectProvider-specific LLM parameters. They replace the current params object as a whole, so include every parameter that must stay.
Response Body
The session was updated.
Response Headers
agent_session_idstringThe ID of the session.
create_tsintegerThe time the session was created, as a Unix timestamp in seconds.
statusstringThe status of the session:
IDLE: The session is idle.STARTING: The session is starting.RUNNING: The session is running.STOPPING: The session is stopping.STOPPED: The session has ended.FAILED: The session failed.
Request examples
curl -X PATCH 'https://preview.ai.agora.io/conversational-ai/v1/projects/string/sessions/string' \ -H 'Content-Type: application/json' \ -d '{ "transport": { "token": "<your_new_rtc_token>" }, "agent": { "overrides": { "messages": [ { "role": "system", "content": "You are helping the customer with a billing question." } ], "pipeline": { "llm": { "params": { "temperature": 0.2 } } } } }}'Response example
{ "agent_session_id": "a42ac95tp25py49fc37hp94vm67ht52h", "create_ts": 1737111452, "status": "RUNNING"}