Inside Foundry Agent Service: Prompt Agents, Voice Agents, and Hosted Agents

Not every task needs the same kind of setup.

Sometimes you just need a smart assistant with clear instructions and a couple of search tools. You do not want to manage Docker containers, servers, or deployment pipelines for it.
Sometimes you need an agent that can answer a live phone call or talk in real time over a browser microphone, handling interruptions naturally.
And sometimes you have complex business logic written in C# or Python using the Microsoft Agent Framework or LangGraph, and you want Microsoft Foundry to host, scale, and secure your custom code without you having to manage a Kubernetes cluster.

Foundry Agent Service supports all three patterns under one roof: Prompt Agents, Voice Agents, and Hosted Agents.

                  [ Microsoft Foundry Agent Service ]
                                   |
       +---------------------------+---------------------------+
       |                           |                           |
       v                           v                           v
[ 1. Prompt Agents ]        [ 2. Voice Agents ]        [ 3. Hosted Agents ]
- Declarative config        - Real-time speech         - Bring Your Own Code
- Model + Instructions      - Voice Live WebSocket     - Python 3.13/3.14 or .NET 10
- Zero servers to host      - Echo cancellation        - Deploy via ZIP or Container

1. Prompt Agents (Serverless & Declarative)

A Prompt Agent is the fastest way to go live. You do not deploy any application servers. Instead, you call create_version on your Foundry project and pass a PromptAgentDefinition containing the model name, system instructions, and any tools or toolboxes you want attached.

Every time you update the instructions or tools, Foundry creates an immutable Version (Version 1, Version 2, Version 3). If Version 3 behaves poorly in testing, you can roll back to Version 2 immediately.

2. Voice Agents (Real-Time Speech with Voice Live)

Traditional voice bots are painfully slow because they stitch three separate services together: Speech-to-Text, then a text LLM, and finally Text-to-Speech. If the user interrupts the bot mid-sentence, the bot keeps talking over them.

Voice-Based Prompt Agents in Foundry use the Voice Live API (azure-realtime-native). The model processes audio natively over a low-latency WebSocket or telephony connection, includes built-in echo cancellation, handles mid-sentence interruptions gracefully, and automatically saves the written transcript into your Foundry Conversation store.

3. Hosted Agents (Bring Your Own Code via ZIP or Container)

What if you need custom pre-processing, deterministic state machines, or multi-step code loops using the Microsoft Agent Framework?

With Hosted Agents (GA), you write your agent in Python (python_3_13 or python_3_14) or .NET (dotnet_10), and upload your code directly to Foundry. You do not even need to write a Dockerfile if you don't want to:

Source-Code ZIP Deployment (code_configuration): You upload a .zip file of your code. If you set dependency_resolution="remote_build", Foundry installs your requirements.txt or restores your .csproj in the cloud automatically. If you have private packages, you set dependency_resolution="bundled" and include your pre-built packages in the zip.
Container Image Deployment (container_configuration): If you need custom OS libraries, you push a Docker image to Azure Container Registry and tell Foundry how much CPU and RAM (cpu="1", memory="2Gi") to allocate.

Step-by-Step Code: Deploying a Hosted Agent from Source Code

Let's walk through packaging and deploying a Hosted Agent programmatically using the SDK, polling until its cloud runtime is active, and invoking it.

Python Example: Deploying a ZIP Hosted Agent

import hashlib
import time
from pathlib import Path
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    CodeConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)

PROJECT_ENDPOINT = "https://your-resource.services.ai.azure.com/api/projects/your-project"
AGENT_NAME = "custom-order-agent"
ZIP_PATH = Path("agent-code.zip")  # Flat zip containing main.py and requirements.txt

# 1. Read the ZIP file and compute its SHA-256 checksum
code_zip_bytes = ZIP_PATH.read_bytes()
code_zip_sha256 = hashlib.sha256(code_zip_bytes).hexdigest()

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# 2. Upload the source code and provision the Hosted Agent container in Foundry
created_version = project.agents.create_version_from_code(
    agent_name=AGENT_NAME,
    definition=HostedAgentDefinition(
        cpu="1",
        memory="2Gi",
        code_configuration=CodeConfiguration(
            runtime="python_3_13",
            entry_point=["python", "main.py"],
            dependency_resolution="remote_build",
        ),
        protocol_versions=[
            ProtocolVersionRecord(protocol="responses", version="2.0.0")
        ],
        environment_variables={
            "AZURE_AI_MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
        },
    ),
    code=(ZIP_PATH.name, code_zip_bytes, "application/zip"),
    code_zip_sha256=code_zip_sha256,
    description="Hosted Python agent built from source zip",
)

print(f"Uploading and building version: {created_version.version}")

# 3. Poll until the cloud runtime transitions from 'provisioning' to 'active'
while True:
    version_info = project.agents.get_version(
        agent_name=AGENT_NAME,
        agent_version=created_version.version,
    )
    status = version_info["status"]
    print(f"Current runtime status: {status}")
    if status == "active":
        break
    if status == "failed":
        raise RuntimeError(f"Deployment failed: {version_info.get('error')}")
    time.sleep(5)

Fast Inner-Loop Deployment with Azure Developer CLI (`azd`)

In day-to-day work, you do not even need to write the zip-upload script above. You can run two commands with the Azure Developer CLI (azd) and it will zip your code, compute the hash, upload it, configure RBAC permissions, and wait for the agent to become active:

# Initialize a source-code hosted agent in your project
azd ai agent init --no-prompt \
  --project-id "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>" \
  --deploy-mode code \
  --runtime python_3_13 \
  --entry-point main.py

# Package and deploy to Microsoft Foundry
azd up

Decision Matrix: Which Agent Type Should You Pick?

When designing a system, use this table to decide which agent architecture fits your workload:

Requirement	Prompt Agent	Voice Agent	Hosted Agent
Where does orchestration run?	Managed by Foundry	Managed by Foundry + Voice Live	Custom Python/.NET container managed by Foundry
Custom C# / Python code loops?	No (Declarative only)	No (Declarative + Tools)	Yes (Full Agent Framework, LangGraph, custom SDKs)
Deployment effort	Instant API call	Instant API call + WebSocket client	ZIP upload (`remote_build`) or Docker image
Identity model	Project or Agent Identity	Project or Agent Identity	Dedicated Platform-Assigned Entra Agent Identity
Network outbound rules	Managed by Foundry	Managed by Foundry	Requires VNet allowlist (`mcr.microsoft.com`, `*.login.microsoft.com`)

Important Security Note for Hosted Agents: Every Hosted Agent runs under its own platform-assigned Microsoft Entra Managed Identity, completely separate from your personal developer login. By default, that identity can call models inside your Foundry project. If your Hosted Agent code needs to read an external Azure Storage account or SQL database, you must grant RBAC roles directly to the agent's Managed Identity in the Azure portal.