RealtimeAgent
Bases:AgentBase,Generic[TContext]
A specialized agent instance that is meant to be used within aRealtimeSession to buildvoice agents. Due to the nature of this agent, some configuration options are not supportedthat are supported by regularAgent instances. For example:-model choice is not supported, as all RealtimeAgents will be handled by the same model within aRealtimeSession.-modelSettings is not supported, as all RealtimeAgents will be handled by the same model within aRealtimeSession.-outputType is not supported, as RealtimeAgents do not support structured outputs.-toolUseBehavior is not supported, as all RealtimeAgents will be handled by the same model within aRealtimeSession.-voice can be configured on anAgent level; however, it cannot be changed after the first agent within aRealtimeSession has spoken.
SeeAgentBase for base parameters that are shared withAgents.
Source code insrc/agents/realtime/agent.py
instructionsclass-attributeinstance-attribute
instructions:(str|Callable[[RunContextWrapper[TContext],RealtimeAgent[TContext],],MaybeAwaitable[str],]|None)=NoneThe instructions for the agent. Will be used as the "system prompt" when this agent isinvoked. Describes what the agent should do, and how it responds.
Can either be a string, or a function that dynamically generates instructions for the agent. Ifyou provide a function, it will be called with the context and the agent instance. It mustreturn a string.
promptclass-attributeinstance-attribute
prompt:Prompt|None=NoneA prompt object. Prompts allow you to dynamically configure the instructions, toolsand other config for an agent outside of your code. Only usable with OpenAI models.
handoffsclass-attributeinstance-attribute
handoffs:list[RealtimeAgent[Any]|Handoff[TContext,RealtimeAgent[Any]]]=field(default_factory=list)Handoffs are sub-agents that the agent can delegate to. You can provide a list of handoffs,and the agent can choose to delegate to them if relevant. Allows for separation of concerns andmodularity.
output_guardrailsclass-attributeinstance-attribute
output_guardrails:list[OutputGuardrail[TContext]]=field(default_factory=list)A list of checks that run on the final output of the agent, after generating a response.Runs only if the agent produces a final output.
hooksclass-attributeinstance-attribute
A class that receives callbacks on various lifecycle events for this agent.
handoff_descriptionclass-attributeinstance-attribute
A description of the agent. This is used when the agent is used as a handoff, so that anLLM knows what it does and when to invoke it.
toolsclass-attributeinstance-attribute
tools:list[Tool]=field(default_factory=list)A list of tools that the agent can use.
mcp_serversclass-attributeinstance-attribute
mcp_servers:list[MCPServer]=field(default_factory=list)A list ofModel Context Protocol servers thatthe agent can use. Every time the agent runs, it will include tools from these servers in thelist of available tools.
NOTE: You are expected to manage the lifecycle of these servers. Specifically, you must callserver.connect() before passing it to the agent, andserver.cleanup() when the server is nolonger needed.
mcp_configclass-attributeinstance-attribute
Configuration for MCP servers.
clone
clone(**kwargs:Any)->RealtimeAgent[TContext]Make a copy of the agent, with the given arguments changed. For example, you could do:
Source code insrc/agents/realtime/agent.py
get_system_promptasync
get_system_prompt(run_context:RunContextWrapper[TContext],)->str|NoneGet the system prompt for the agent.
Source code insrc/agents/realtime/agent.py
get_mcp_toolsasync
get_mcp_tools(run_context:RunContextWrapper[TContext],)->list[Tool]Fetches the available tools from the MCP servers.
Source code insrc/agents/agent.py
get_all_toolsasync
get_all_tools(run_context:RunContextWrapper[TContext],)->list[Tool]All agent tools, including MCP tools and function tools.