Maintaining Context

Voice Agent

A voice agent's behavior on any call is the sum of a few moving parts: the prompt that shaped it, the history you handed it on connect, anything either side has injected during the call, and any function results it has gathered. This page covers every lever the API gives you for managing that context.

The rest of this page walks each lever in detail. You can mix all of them in the same session.

The system prompt is the agent's initial brief. It defines persona, scope, and any rules the agent should follow throughout the call. Set it inside the agent.think.prompt field of your Settings message at connect time.

{
  "type": "Settings",
  "agent": {
    "think": {
      "provider": { "type": "open_ai", "model": "gpt-4o-mini" },
      "prompt": "You are a friendly support agent for Acme. Always confirm the customer's account number before answering billing questions."
    }
  }
}

For voice-specific prompt-writing patterns (formatting numbers for TTS, keeping turns short, avoiding markdown the agent will try to read aloud), see Prompting Voice Agents.

If you need to change the agent's behavior part-way through a call (a phase change, a hand-off to a new persona, an updated rule), send an UpdatePrompt message. The new prompt replaces the system prompt for the rest of the session.

{
  "type": "UpdatePrompt",
  "prompt": "You are now a billing specialist. Resolve the dispute the customer just described."
}

Combine UpdatePrompt with UpdateThink if you also want to swap the LLM provider mid-call.

When you start a new session, you can hand the agent the history of prior interactions so it picks up where the last call left off. History is provided through agent.context.messages and supports two message shapes that can be mixed in the same array.

Plain back-and-forth between user and assistant.

{
  "type": "Settings",
  "agent": {
    "context": {
      "messages": [
        { "type": "History", "role": "user", "content": "I'm trying to recover my account." },
        { "type": "History", "role": "assistant", "content": "Sure, I can help. What email did you use to sign up?" }
      ]
    }
  }
}

Function calls executed in earlier sessions, with arguments and results.

{
  "type": "Settings",
  "agent": {
    "context": {
      "messages": [
        { "type": "History", "role": "user", "content": "What's the weather in New York?" },
        {
          "type": "History",
          "function_calls": [
            {
              "id": "fc_weather_12345",
              "name": "get_weather",
              "client_side": true,
              "arguments": "{\"location\": \"New York\"}",
              "response": "Partly cloudy, 22°C."
            }
          ]
        },
        { "type": "History", "role": "assistant", "content": "It's partly cloudy in New York, around 22 degrees." }
      ]
    }
  }
}

The full schema and field-by-field reference live on the History page.

Sessions close automatically at 2 hours. The server sends a MAXIMUM_SESSION_LENGTH_APPROACHING warning at 1 hour 55 minutes and a terminal MAXIMUM_SESSION_LENGTH_REACHED error at 2 hours. To carry a long conversation across that boundary, capture the session's history, open a new connection, and replay the turns in agent.context.messages. See Maximum session length.

History is enabled by default. To disable it, set:

{
  "type": "Settings",
  "settings": {
    "flags": { "history": false }
  }
}

Two client messages let you add to context mid-call.

Make the agent say something specific, immediately. The injected text is treated as if the agent had just produced it.

{ "type": "InjectAgentMessage", "content": "Hold on a moment while I check that for you." }

Useful for filler responses, status updates while a slow tool runs, or scripted follow-ups. Reference: Inject Agent Message.

Push a synthetic user turn into the conversation. The agent processes it as if the user said it. Useful for orchestrated hand-offs from your application to the agent without going through the microphone.

{ "type": "InjectUserMessage", "content": "The customer's authentication is now complete." }

Reference: Inject User Message.

Function call responses returned to the agent become part of its working context. The agent can reference them in later turns, decide whether to call again, and use the results to shape what it says next. See Function Calling for the full request/response loop and Function Call Context for how function results interact with conversation history.

If your agent's prompt, providers, and tools are stable across many sessions, save them as a Reusable Agent Configuration. You get back a UUID that you can pass in place of the full agent object on every connection.

Reusable configurations are most useful when:

• The same prompt is used by many sessions
• You want to update prompts without redeploying the client
• Multiple environments need to share the same agent definition

The reusable configuration only covers the agent block. Per-session context (history, runtime injections) is still passed at connect time or during the call.