Twilio Agent Connect for Microsoft

Azure integrations for Twilio Agent Connect — connect Microsoft Foundry agents to Twilio's channels, memory, and context.

Documentation ◆ Python SDK ◆ Examples ◆ Deployment

Ships Microsoft Agent Framework and Azure AI Voice Live connectors for Twilio Agent Connect (TAC), plus production Azure deployments for each.

Features

• AgentFrameworkConnector - connects Microsoft Agent Framework agents to TAC
  • Agent lifecycle management (Voice + SMS + Chat + RCS + WhatsApp)
  • Supports Foundry Hosted Agents, Foundry Prompt Agents, Azure OpenAI (Responses API, Chat Completions), and other backends
  • Pluggable session persistence via AgentSessionStore protocol
  • Memory context injection and on_message / on_error hooks
• VoiceLiveConnector - connects the Voice Live API to TAC
  • Text-in / text-streaming-out over WebSocket (STT and TTS handled by Twilio Conversation Relay)
  • Server-side conversation state (no local session management)
  • Native interrupt handling via Voice Live response.cancel (server-side truncation of in-flight responses)
  • Tool execution with async handlers
• Multi-channel support (Voice + SMS + Chat + RCS + WhatsApp)
• Built-in TAC tools (memory recall, knowledge search, Studio Flow handoff)
• Production reference deployments (Bicep + azd) for running your TAC agent on Azure:
  • Agent Framework on Azure Container Apps
  • Agent Framework on Hosted Agents in Foundry Agent Service (TACHostedAgentsApp, APIM-fronted)
  • Voice Live on Azure Container Apps
• AgentSessionStore implementations for in-memory, file, and Cosmos DB

Installation

With Agent Framework

pip install twilio-agent-connect-microsoft[agent-framework,server]

With Voice Live

pip install twilio-agent-connect-microsoft[voice-live,server]

On Hosted Agents in Foundry Agent Service

pip install twilio-agent-connect-microsoft[hosted-agents]

The hosted-agents extra provides the Hosted Agents runtime (TACHostedAgentsApp) and includes tac[server], so a separate server extra isn't needed. TACHostedAgentsApp hosts any TAC connector, so add the extra for the connector you want — e.g. [hosted-agents,agent-framework] (as the deployment example does) or [hosted-agents,voice-live]. Or pair it with TAC core to host an agent built on any other SDK.

Development

git clone https://github.com/twilio/twilio-agent-connect-microsoft.git
cd twilio-agent-connect-microsoft
uv sync --all-extras

Prerequisites

Before running any examples, you need to create and configure the required Twilio services (Conversation Configuration, phone number, etc.). Follow the TAC Quickstart guide to set these up.

Configuration

TAC Microsoft requires TAC environment variables. See TAC Configuration for details.

Required Environment Variables

# Twilio Agent Connect (required for all examples)
TWILIO_CONVERSATION_CONFIGURATION_ID=conv_configuration_xxxxxxxxxxxxxxxxxx
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_SECRET=your_api_key_secret
TWILIO_PHONE_NUMBER=+1234567890
# Optional — set to auto-enable the RCS / WhatsApp channels on the connector
# TWILIO_RCS_SENDER_ID=rcs_sender_xxxxxxxxxxxxxxxxxx
# TWILIO_WHATSAPP_NUMBER=+1234567890

# Server (required for voice)
TWILIO_VOICE_PUBLIC_DOMAIN=your-domain.ngrok.io

# Azure OpenAI — Agent Framework basic example (API key auth)
# Endpoint is the resource base URL only — no /openai/v1 suffix.
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_AI_API_KEY=your_azure_openai_api_key
AZURE_AI_DEPLOYMENT_NAME=gpt-4o

# Agent Framework advanced example uses the same AZURE_OPENAI_ENDPOINT as basic,
# but authenticates via `DefaultAzureCredential` (run `az login` first) instead of an API key.

# Voice Live API — voice_live example (hostname only, no https:// prefix)
# AZURE_VOICE_LIVE_ENDPOINT=your-resource.services.ai.azure.com
# AZURE_VOICE_LIVE_API_KEY=your_voice_live_api_key
# AZURE_VOICE_LIVE_MODEL=gpt-realtime

See getting_started/examples/.env.example for the full list including optional features (Cosmos DB, knowledge base, conversation intelligence). Copy it to getting_started/examples/.env and fill in your values — all examples load from that shared file.

Quick Start

Everything imports from tac_microsoft — no need to import from the underlying tac package:

from tac_microsoft import (
    TAC, TACConfig, TACFastAPIServer,
    AgentFrameworkConnector, ConversationSession,
    FileAgentSessionStore,
)
from tac_microsoft.agent_framework_tools import create_memory_tool

Examples

Full examples available in getting_started/examples/:

• agent_framework/basic.py - Minimal Agent Framework setup (~30 lines)
• agent_framework/advanced.py - Full feature set (channel-aware prompts, tools, hooks, session persistence)
• voice_live/basic.py - Voice Live API with tool calling

AgentSessionStore

The AgentSessionStore protocol defines how Agent Framework sessions are persisted between requests, enabling conversation continuity across SMS messages and horizontal scaling for voice.

Three implementations are included:

• InMemoryAgentSessionStore — default, suitable for single-instance deployments
• FileAgentSessionStore — persists sessions as JSON files on disk (single-instance, local dev). Also the recommended store for Hosted Agents in Foundry Agent Service, where APIM pins each conversation to one sandbox via agent_session_id affinity and $HOME survives idle eviction — giving durable continuity without Cosmos DB
• CosmosDBAgentSessionStore — persists sessions in Azure Cosmos DB for NoSQL (horizontally scaled production). Requires the cosmos extra: pip install twilio-agent-connect-microsoft[cosmos]

Implement the protocol to use any other backing store (Redis, DynamoDB, Postgres, etc.).

Development

Setup

# Clone repository
git clone https://github.com/twilio/twilio-agent-connect-microsoft.git
cd twilio-agent-connect-microsoft

# Install dependencies
uv sync --all-extras

Getting Started

See getting_started/README.md for the full setup and deployment guide.

Dependencies

TAC Microsoft depends on:

• twilio-agent-connect - Core Twilio Agent Connect framework (installed from PyPI)
  • Requires twilio-agent-connect[server] extra for TACFastAPIServer support
• agent-framework (optional) - Microsoft Agent Framework
• websockets (optional) - For Voice Live connector
• azure-cosmos (optional) - For CosmosDB session store

Documentation

• API Reference - Full API documentation generated from the source
• CLAUDE.md - Architecture, development guide, and API reference
• Getting Started Guide - Setup instructions, environment variables, and troubleshooting

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.