How to build a voice agent

Learn how to use Voice Live with Foundry Agent Service to build real-time voice agents.

This article covers Voice Live connected to a Foundry text agent.

For new voice experiences, consider starting with Microsoft Foundry voice agents (preview). They support speech-to-speech and text models, with built-in telephony and voice-pipeline tracing. To compare the approaches or plan a migration, see Compare and migrate to Microsoft Foundry voice agents.

That migration is different from the classic-to-new Agent Service migration described later in this article.

Migrate from Agent Service (classic)

If you’re using Voice Live with Agent Service (classic), we recommend you migrate to the new Foundry Agent Service. For general Agent Service migration steps, see Migrate from Agent Service (classic) to Foundry Agent Service.

Voice Live SDK changes

The Voice Live SDK introduces typed configuration classes that replace the raw query parameters used in the classic integration:

Classic (v1)	New (v2)
agent-id query parameter	agent_name in AgentConfig / AgentSessionConfig
agent-project-name query parameter	Project endpoint in client constructor
agent-access-token query parameter	Handled automatically by SDK
Manual connect() with query dict	Strongly typed AgentSessionConfig passed to session options

Minimum SDK versions

Language	Package	Minimum version
Python	azure-ai-voicelive	1.2.0
C#	Azure.AI.VoiceLive	1.1.0
Java	azure-ai-voicelive	1.0.0
JavaScript	@azure/ai-voicelive	1.0.0

Before and after: Python connection setup

Classic (v1) — raw query parameters in connect():

async with connect(
    endpoint=self.endpoint,
    credential=self.credential,
    query={
        "agent-id": self.agent_id,
        "agent-project-name": self.foundry_project_name,
        "agent-access-token": agent_access_token
    },
) as connection:

New (v2) — strongly typed AgentSessionConfig:

from azure.ai.voicelive import AgentConfig, AgentSessionConfig

agent_config = AgentConfig(agent_name=agent_name)
agent_session_config = AgentSessionConfig(agent_config=agent_config)

session_options = VoiceLiveSessionOptions(
    agent_session_config=agent_session_config,
    # ... other options
)

For complete code examples, see the new agent quickstart. The classic quickstart remains available.

Related content

• Explore How to add proactive messages
• Explore How to improve tool calling and latency wait times
• Learn more about How to use the Voice Live API
• See the Voice Live API reference