# Deploy to Azure Container Apps

This guide shows you how to deploy your TAC application to [Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/overview) using the [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/) (`azd`). The deployment creates a Container Apps environment with built-in ingress, TLS, and auto-scaling, and provisions the supporting services each connector needs.

## Architecture overview

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

### Agent Framework connector

* **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.

### Voice Live connector

* **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.

## Prerequisites

Before you begin, make sure you have:

* [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (`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](/docs/conversations/agent-connect/integrations/microsoft-foundry#agent-framework-connector) or [Voice Live](/docs/conversations/agent-connect/integrations/microsoft-foundry#voice-live-connector))

**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**.

## Quick deploy with the Azure Developer CLI

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:

   ```bash
   git clone https://github.com/twilio/twilio-agent-connect-microsoft.git
   cd twilio-agent-connect-microsoft
   ```
2. Move into the deployment directory for your connector and copy the environment template:

   ## Agent Framework

   ```bash
   cd deploy/agent_framework_container_apps
   cp .env.template .env
   ```

   ## Voice Live

   ```bash
   cd deploy/voice_live_container_apps
   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 Framework

   ```bash
   azd env new my-tac-agent
   azd up
   ```

   ## Voice Live

   ```bash
   azd env new my-tac-voice-live
   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 Twilio webhooks

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

### Voice

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

### Messaging

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`).

## Test your deployment

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

## Agent Framework

```bash
az containerapp logs show \
  --name <environmentName>-app \
  --resource-group rg-<environmentName> \
  --type console \
  --follow
```

## Voice Live

```bash
az containerapp logs show \
  --name <environmentName>-app \
  --resource-group rg-<environmentName> \
  --type console \
  --follow
```

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

## Redeploy after code changes

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.

```bash
azd up
```

## Tear down

To remove all resources that `azd` provisioned, run:

```bash
azd down --purge
```

## Next steps

* [Microsoft Foundry connectors](/docs/conversations/agent-connect/integrations/microsoft-foundry): Explore the available Microsoft Foundry connectors.
* [Troubleshooting](/docs/conversations/agent-connect/troubleshooting): Debug common issues.
* [Escalate to a human agent](/docs/conversations/agent-connect/escalate-to-human-agent): Transfer conversations from your agent to a human agent.