Migrate from Voice Live with Foundry Agent Service to Microsoft Foundry voice agents

Migrate an existing Voice Live with Foundry Agent Service integration to a voice-based prompt agent in Microsoft Foundry. First, compare the architectures and choose how to preserve your tools and business logic. Then move the configuration, update the WebSocket client, and test responsiveness before switching traffic.

In this article, Voice Live integration means Voice Live connected to an existing Foundry text agent. A Foundry voice agent is a separate agent with kind: voice that still uses Voice Live for the voice runtime. You manage its model, instructions, audio, and tools together in an agent definition.

You can't change an existing text agent's interaction mode to voice, so migration creates a new agent rather than modifying the original. This process is separate from migrating Agent Service (classic) to the new Agent Service.

Prerequisites

• Access to a working Voice Live integration with a Foundry text agent, including its configuration and client code.

• A Foundry project with access to the voice-agent preview and a supported model in the project's region.

• Foundry User role on the target project, with permission to create and invoke agents.

  Important

  The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

• Access to the tool connections and data resources that the new voice agent needs. Have a resource owner grant any required permissions.

• A microphone and speakers or a headset for testing spoken conversations.

• To run the Python connection example: Python 3.10 or later and the Azure CLI, signed in with az login.

Compare the two approaches

Start with the architecture, not the endpoint URL. Both approaches use Voice Live for real-time audio, configurable voices, turn detection, and interruption handling. What changes is which agent owns the conversation and where you configure it.

Compare the conversation architecture

In the existing integration, Voice Live provides the speech layer around a separate Foundry text agent. The text agent handles the transcribed request, calls its tools, and returns text for Voice Live to speak.

Caller audio
  -> Voice Live: speech recognition and turn detection
  -> Foundry text agent: text model, instructions, tools, and knowledge
  -> Voice Live: speech synthesis
  -> Spoken response

With a Foundry voice agent, one versioned definition owns the conversation, including the model, instructions, audio, greeting, and tools. Voice Live runs that definition without requiring a separate text agent to handle every turn. The agent calls tools through client functions, Model Context Protocol (MCP), or Foundry toolboxes.

Foundry voice agent
  Voice Live runtime, with one of two model paths:
    Speech-to-speech: audio -> realtime model -> audio
    Cascaded: audio -> speech recognition -> text model -> synthesis -> audio
  Tools and knowledge: client functions, MCP servers, Foundry toolboxes
  Optional specialist: an existing prompt or hosted subagent

Choose speech-to-speech for a native real-time conversation, or a cascaded text model to retain the model and speech controls your application needs. Tool and knowledge access is available with either architecture, subject to model and tool compatibility. See How voice-based agents work.

This comparison covers Voice Live connected to a text agent, not all Voice Live capabilities. Voice Live used directly also supports speech-to-speech models.

Compare capabilities and operations

Use this table to identify which parts of your application change and which capabilities to test.

Choose a Foundry voice agent if you need speech-to-speech models, service-managed model hosting, built-in telephony, or integrated voice configuration and call review. You can keep using a supported text model; migration doesn't require switching to gpt-realtime.

Model, region, network, and transport restrictions still apply. Actual latency depends on the model, deployment, prompts, tools, and channel. Measure conversation quality, latency, and cost with your workload before switching.

Choose how to reuse your existing agent

Decide which agent handles the conversation before you move configuration. Reusing a text agent for specialist tasks is different from forwarding every spoken turn to it.

For the subagent approach, the subagent must be in the same project as the voice agent. Subagents aren't supported in VNet-isolated projects. Follow Use a subagent in a voice-based agent and test delegation, follow-up questions, and failure behavior.

The rest of this article covers migration to a model-backed voice agent, with optional subagents. For a custom hosted voice application that exposes invocations_ws, see Build a voice agent with hosted agents.

Inventory the source and create a new agent

First, capture the configuration your application actually uses, including client-side overrides. Then create a separate voice agent so that you can test without changing the existing integration.

Inventory the existing integration

Record these settings before you create the voice agent:

1. Record the source agent name and version, model deployment, instructions, tools, and project connections.
2. Export the Voice Live settings. If you used the integration sample, reassemble microsoft.voice-live.configuration and its numbered metadata entries, such as .1 and .2, in order.
3. Record any client-side session.update overrides, proactive greeting code, audio formats, interruption handling, and channel configuration.
4. Record authentication and cross-resource dependencies, including any foundry_resource_override and managed identity settings. Don't copy credentials into the new agent definition.

Create the voice agent

Use the inventory to configure a new agent:

1. Follow Create a voice-based prompt agent to create an agent with a new name. In the portal, select Voice as the interaction mode. In code, use VoiceAgentDefinition instead of PromptAgentDefinition.
2. Choose a supported speech-to-speech model, such as gpt-realtime, or a supported text model. Both model families support service-managed and self-deployed options.
3. Set model_type to managed for a service-managed model, or self_deployed for your own supported deployment. Use the corresponding model or deployment name.
4. Adapt the instructions for spoken interaction: short answers, one question at a time, and explicit confirmation before consequential actions. Preserve the source agent's business rules and escalation requirements.
5. Save the new agent version and record its name and version for testing. Keep the original text agent and client configuration unchanged until the new path is ready.

Creating a voice agent version doesn't copy the source agent's tools, connections, or conversation history. For an SDK creation example, see Create from an explicit definition.

Move voice settings into the definition

Map the existing voice settings to the new definition instead of copying the old session object into metadata. The following table uses JSON field names from the Voice Live integration samples and the voice-agent definition.

For configuration details and SDK examples, see Configure a voice agent. SDK and azure.yaml property names can differ from the JSON names in this table.

The service applies the definition when a session starts. Remove client startup code that resends the full legacy session configuration. Keep only supported per-session overrides, such as audio or avatar settings, and verify the effective configuration returned by the service.

Reconnect tools and knowledge

Voice agents support the same tools and knowledge as Foundry text agents, including Foundry IQ and MCP servers. You don't need to replace your knowledge sources or business APIs merely to add voice. The integration route changes: use a native voice-agent tool, a Foundry toolbox, or a retained specialist subagent.

The toolbox's feature support lists the available tool types. Voice agents reference the toolbox rather than accepting every text-agent tool type directly in their tools array. Model, region, network, and individual tool restrictions still apply.

Reconnect and test each dependency:

1. Create or reuse the project connections and toolbox versions required by the new voice agent. Don't copy the text agent's tools array unchanged.
2. Confirm which identity accesses each dependency. For permission-aware retrieval, verify that a caller can't retrieve content they're not authorized to read.
3. For Foundry IQ, test a question that requires knowledge_base_retrieve and confirm that the spoken answer reflects the retrieved content.
4. Test successful calls, denied permissions, timeouts, unavailable dependencies, and required user confirmations. For subagents, also test delegation and follow-up questions.

See Attach tools for configuration examples. For MCP and toolbox tools, review response_scheduling so a delayed result speaks at the intended point in the conversation.

Update the client connection

Use the Foundry project endpoint, not the Voice Live resource endpoint. The project endpoint has this form: https://<account>.services.ai.azure.com/api/projects/<project>.

The voice-agent API uses api-version=v1, but voice agents remain a preview feature. REST requests require the Foundry-Features: VoiceAgents=V1Preview opt-in. The Python realtime helper supplies this header automatically.

For a raw WebSocket client, use wss:// and replace /voice-live/realtime with /api/projects/<project>/agents/<agent-name>/endpoint/protocols/voice?api-version=v1. Request a Microsoft Entra token for https://ai.azure.com/.default, send it in the Authorization header, and include the voice-agent preview opt-in.

Resource API keys aren't a substitute for agent authentication. Don't put bearer tokens in the URL or long-lived credentials in browser code.

The new endpoint path identifies both the project and agent. Use this mapping when you replace the handshake:

Review cross-resource connection parameters separately; don't append them to the new URL unchanged. For the earlier connection contract, see Voice Live agent integration.

Check the connection with Python

In Python, replace the azure-ai-voicelive live-session connection with the beta.voice_agents.realtime client in azure-ai-projects.

Install the Azure AI Projects client library with its voice dependencies:

python -m pip install "azure-ai-projects[voice]>=2.7.0" azure-identity

Reference: Azure AI Projects client library for Python.

Set these environment variables in the shell that runs the example:

Save the following example as check_voice_connection.py, and run it with python check_voice_connection.py. It connects to the specified agent version, waits for session.created, and then closes the connection. It uses the saved configuration without overrides and doesn't send microphone audio.

import os
import time

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    RealtimeServerEventError,
    RealtimeServerEventSessionCreated,
)
from azure.identity import DefaultAzureCredential

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(
        endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        credential=credential,
        allow_preview=True,
    ) as project_client,
):
    with project_client.beta.voice_agents.realtime.connect(
        agent_name=os.environ["FOUNDRY_VOICE_AGENT_NAME"],
        api_version="v1",
        extra_query={
            "x-agent-version-override": os.environ[
                "FOUNDRY_VOICE_AGENT_VERSION"
            ],
        },
    ) as connection:
        deadline = time.monotonic() + 45
        while True:
            remaining = deadline - time.monotonic()
            if remaining <= 0:
                raise TimeoutError("Voice session didn't become ready.")
            event = connection.recv(timeout=remaining)
            if isinstance(event, RealtimeServerEventError):
                raise RuntimeError(event.error.message)
            if isinstance(event, RealtimeServerEventSessionCreated):
                if event.conversation_id:
                    print(f"Conversation ID: {event.conversation_id}")
                print("Voice session ready.")
                break

Reference: Python realtime client and event models.

The example prints Voice session ready. when the session is created. If your client sends a session.update override, also wait for its session.updated acknowledgment before using the changed settings. To test a complete spoken turn, follow Talk to the agent or adapt the live microphone sample.

Use the current Projects SDK samples for the public preview. Earlier private-preview samples that use a separate azure-ai-voiceagents package or /voice_agents management route don't describe this API.

Update session configuration messages

Keep the model, instructions, tools, and default audio settings in the saved definition. You don't need a startup session.update when those defaults match your client. If you need an override in the middle of the session, translate its fields to the voice-agent schema.

For example, an older Voice Live client can set PCM audio formats with this message:

{
  "type": "session.update",
  "session": {
    "input_audio_format": "pcm16",
    "output_audio_format": "pcm16",
    "input_audio_sampling_rate": 24000
  }
}

Reference: Voice Live session.update.

For a voice-agent session using 24-kHz PCM input and output, the equivalent override uses nested format objects:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "audio": {
      "input": {
        "format": {"type": "audio/pcm", "rate": 24000}
      },
      "output": {
        "format": {"type": "audio/pcm", "rate": 24000}
      }
    }
  }
}

Reference: VoiceAgentSessionUpdateConfig and audio models.

Expect session.updated with the effective configuration, or an error event if the update is rejected. Don't start sending audio in a new format until the update succeeds.

Adapt audio and event handling

Changing the URL alone isn't enough to migrate an older Voice Live client. Update the event dispatcher, but retain the input and response-control events that keep the same names.

Reference: Voice Live events and voice-agent realtime event mappings.

For a complete spoken turn with automatic turn detection and response creation enabled:

1. Receive session.created and capture conversation_id when present. If you send a configuration override, wait for session.updated before enabling microphone input.
2. Send microphone chunks in input_audio_buffer.append. Let the configured turn detector commit the input and start the response; don't also send manual response.create events for the same turn.
3. On response.created, track the response ID. Decode each response.output_audio.delta payload and queue it for playback in the configured output format.
4. Render response.output_audio_transcript.* events separately from the audio stream. Don't treat transcript arrival as proof that the audio has played.
5. On response.done, check whether the response completed, was cancelled, failed, or is incomplete. Generation completion doesn't mean the local playback buffer is empty.
6. Handle error events throughout the session and report failures instead of leaving the caller waiting indefinitely.

The Python SDK maps these events to typed models. RealtimeServerEventResponseAudioDelta represents response.output_audio.delta, and its delta already contains decoded audio bytes. Don't base64-decode it again; raw JSON clients must decode the string themselves.

Complete client-executed function calls

If you move a function from your text-agent application to a native voice-agent function tool, add its execution loop to the live client:

1. Handle response.function_call_arguments.done. Read name and call_id, parse the JSON string in arguments, and validate the requested function and arguments.
2. Wait for the corresponding response.done and check the response and call state. Don't execute calls from failed, incomplete, or cancelled responses. Preserve authorization and required user confirmations.
3. Execute the function and return its result with conversation.item.create. Use the original call_id and serialize the result into the string-valued output field.
4. If the response includes multiple calls, return their outputs before sending one response.create for the follow-up response. Starting it before the previous response finishes can cause a concurrent-response error.

The result message has this shape. Replace both placeholders with the actual call ID and serialized result:

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "<call-id-from-the-function-call>",
    "output": "<serialized-tool-result>"
  }
}

Reference: Client-executed function sample.

Then send {"type": "response.create"} when no response is active. Don't run MCP or toolbox calls through this client loop; the service executes those tools.

Preserve interruption and greeting behavior

Stopping generation, stopping playback, and updating conversation context are separate actions.

If the definition includes a greeting, handle its response separately from the reply to the first user turn. Remove the old client-side greeting trigger to avoid duplicate greetings.

Validate each required browser or telephony path separately.

Configure history, recordings, and monitoring

Plan conversation storage and monitoring before switching traffic. Each voice conversation is a new record, not a continuation of the old text-agent conversation.

• Start a new voice conversation at cutover. Retain prior text-agent history according to your existing policy; don't pass its conversation ID expecting an automatic import.
• Decide whether to enable store, which defaults to false. Setting it to true stores the transcript, event timeline, and raw audio together. Review notice, consent, access, and retention requirements before enabling it.
• Capture the voice conversation ID from session.created for correlation and, when storage is enabled, read-back through beta.voice_agents.conversations. Don't confuse it with a realtime session ID.
• Retrieve merged recordings after the session ends. Recording finalization isn't necessarily immediate; follow the conversation audio sample.
• Configure voice-agent tracing and monitoring. Conversation storage and sensitive-content capture in traces are separate controls.

Review voice-agent pricing for model hosting, audio usage, tools, and optional features. Measure latency and cost with the new agent rather than assuming they stay the same.

Validate and switch traffic

Test the new agent alongside the existing integration before changing production routing.

For latency comparisons, keep prompts, tools, channel, and load consistent. If you also change models, record that change separately. Use voice-agent monitoring to diagnose stage delays, and measure client-side time until playback starts.

After the checks pass, switch traffic gradually:

1. Pin the tested voice-agent version and any toolbox or subagent versions your release depends on.
2. Configure the required voice-agent channels. Creating a voice agent doesn't migrate existing text-agent app publishing or phone configuration.
3. Update a test client or a limited traffic route to use the new voice endpoint, and repeat the checks for that route.
4. Increase traffic only after the checks pass. Let existing calls finish on their original integration; don't change the endpoint during a call.
5. Keep the old endpoint, agent, and client configuration available for rollback. If needed, route new sessions back to the original integration.
6. Retire the old path only after confirming that no applications still depend on it and that required historical records are retained.

Troubleshoot migration issues

Use these symptoms to identify configuration differences between the existing integration and the new voice agent.

Related content

• Configure a voice agent.
• Use a subagent in a voice-based agent.
• Voice agent tracing, monitoring, and evaluation.