Skip to main content
Every Agent keeps a ChatContext: a structured log of messages (with their tool calls) plus agent handoffs. It’s the single source of truth across cascade and realtime pipelines and between agents, so you can switch pipelines or hand off mid-call without losing history.
For automatic summaries and token-budget trimming on long calls, see Context Window.

​
What ChatContext Records

Unlike a plain message list, ChatContext keeps an ordered log of ChatMessage items (accessible via .items) plus a separate list of agent handoffs, so the full history survives a pipeline switch or an agent handoff.
Python doesn’t expose a ChatContext-returning accessor yet: session.fetch_context_history() returns the same conversation as a plain list of message dicts (role, content, message_id, tool_calls, …) instead of ChatMessage objects with .items / .messages(). self.chat_context is reserved for future use and is None today. Don’t read from it.

​
Mid-Call Pipeline Switching

You can switch an AgentSession’s pipeline mid-call (for example, from a cascade stack, STT → LLM → TTS, to a realtime speech-to-speech model) using pipeline.change_pipeline(...). The agent’s chat_context is preserved, and the realtime model seeds itself from that context when it connects.

​
Idempotency

The switch tool stays available on the agent after the switch happens. Without a guard, a realtime model, seeded with a conversation that’s all about switching, can loop on the same tool. Track a flag such as self._switched and make the tool a safe no-op on repeat calls.

​
Supported Realtime Providers

change_pipeline(...) works with every realtime provider that records back into ChatContext: Each provider seeds its prior conversation into the realtime session’s instructions on connect, so the realtime half starts already aware of what was said and which tools were called.
For the full mid-call switch, see Configure a Pipeline.

​
Multi-Agent Context Patterns

When two or more agents share a conversation, ChatContext provides primitives for transferring control, isolating sub-agent work, and merging results back.

​
Hand Off to a Peer Agent

add_handoff(...) records a transfer marker on the shared context so the receiving agent’s first turn is informed by what the previous agent did and why.
The billing agent reads the handoff marker on takeover and can greet the caller with full context: “Hi, I see you’d like to dispute the charge on order 456. Let me pull that up.”

​
Realtime Tool-Call Recording

Realtime tool calls are automatically logged to ChatContext as both a FunctionCall and its FunctionCallOutput (deduped by call_id). This lets a cascade LLM read prior results after a realtime→cascade switch, preventing duplicate tool invocations like re-calling lookup_order(456). No configuration is needed. This happens automatically for every realtime provider listed above.

​
What’s Next

Context Window

Manage conversation history automatically.

Agent Handoffs

Share context across specialized agents.

​
References

​
Examples

Chat Context

Read and pass conversation context.

​
SDK Reference

ChatContext

ChatContext in the Python API reference.

Pipeline

Pipeline in the Python API reference.