Deploy to Azure Container Apps

The deployment provisions different resources depending on which connector you use.

• Container Apps — Container runtime with built-in ingress, TLS, and auto-scaling
• Cosmos DB (serverless NoSQL) — AgentSession persistence for horizontal scaling
• Container Registry (Basic SKU) — Docker image storage
• Log Analytics — Application logs (30-day retention)
• Managed Identity (system-assigned) — Passwordless authentication to Cosmos DB and Azure OpenAI

The Agent Framework deployment assumes an existing Azure OpenAI (or Microsoft Foundry) account and assigns the Container App's managed identity the Cognitive Services OpenAI User role on it.

• Container Apps — Container runtime with built-in ingress, TLS, and auto-scaling
• Container Registry (Basic SKU) — Docker image storage
• Log Analytics — Application logs (30-day retention)

The Voice Live deployment assumes an existing Microsoft Foundry Voice Live resource. You pass the endpoint and API key as parameters.

Container Apps provides a built-in HTTPS endpoint with a valid TLS certificate, so you don't need ngrok or a reverse proxy in production.

Before you begin, make sure you have:

• Azure Developer CLI (azd) v1.18.0 or later
• Azure CLI (az) installed and logged in
• Docker installed and running
• Python 3.10+ with pip
• An Azure subscription with permission to create Container Apps, Container Registry, and Log Analytics
• A working TAC application with your chosen connector (Agent Framework or Voice Live)

Connector-specific prerequisites:

• Agent Framework — An Azure OpenAI or Microsoft Foundry deployment (GPT-4o recommended) and permission to create Cosmos DB.
• Voice Live — A Microsoft Foundry resource with Voice Live enabled, and its endpoint and API key.

You also need your Twilio Auth Token, API Key and Secret, phone number, and Conversation Configuration ID. To find these values:

• Auth Token and API Keys: Go to Twilio Console > Account > API Keys & Tokens.
• Conversation Configuration ID: Go to Twilio Console > Conversation Orchestrator > Configuration.

The azd up command builds dependency wheels, provisions Azure infrastructure, builds and pushes the Docker image, and configures the Container App in a single step.

1. Clone the twilio-agent-connect-microsoft repository:

   Copy code block

   1
   git clone https://github.com/twilio/twilio-agent-connect-microsoft.git
   2
   cd twilio-agent-connect-microsoft

2. Move into the deployment directory for your connector and copy the environment template:

   Agent FrameworkVoice Live

   Copy code block

   1
   cd deploy/agent_framework_container_apps
   2
   cp .env.template .env

3. Edit .env and fill in your Twilio credentials and the Azure values for your connector (Azure OpenAI endpoint for Agent Framework, Voice Live endpoint and API key for Voice Live).

4. Create a new azd environment and deploy:

   Agent FrameworkVoice Live

   Copy code block

   1
   azd env new my-tac-agent
   2
   azd up

When azd up completes, it prints the Container App's fully qualified domain name (FQDN). Use this FQDN to configure Twilio webhooks in the next section.

Configure your Twilio webhooks to point at the Container App FQDN that azd up printed.

1. Go to Twilio Console > Phone Numbers > Active Numbers.
2. Select your phone number.
3. Set Voice URL to https://<FQDN>/twiml (POST).

The Voice Live connector supports voice only. Skip this section if you deployed the Voice Live connector.

1. Go to Twilio Console > Conversation Orchestrator.
2. Select your Conversation Configuration.
3. Set Webhook URL to https://<FQDN>/webhook (POST).

Call or text your Twilio phone number to verify that the deployment works. If something fails, stream the Container App logs:

1
az containerapp logs show \
2
  --name <environmentName>-app \
3
  --resource-group rg-<environmentName> \
4
  --type console \
5
  --follow

1
az containerapp logs show \
2
  --name <environmentName>-app \
3
  --resource-group rg-<environmentName> \
4
  --type console \
5
  --follow

Replace <environmentName> with the azd environment name you created earlier (for example, my-tac-agent).

Run azd up again. It rebuilds the Docker image, pushes it to the container registry, and updates the Container App. Infrastructure deployments are idempotent, so unchanged resources aren't re-created.

azd up

To remove all resources that azd provisioned, run:

azd down --purge

• Microsoft Foundry connectors: Explore the available Microsoft Foundry connectors.
• Troubleshooting: Debug common issues.
• Escalate to a human agent: Transfer conversations from your agent to a human agent.