Skip to content

Connectors

Agent Framework

tac_microsoft.agent_framework_connector

Agent Framework connector for TAC

Connector logic (agent lifecycle, session management, tool factories) for Microsoft Agent Framework. HTTP/WebSocket routing is delegated to TACFastAPIServer from the tac package.

Key design:

  • create_agent factory returns an Agent Framework Agent
  • Voice, SMS, chat, RCS, and WhatsApp channel instances are exposed as voice_channel / sms_channel / chat_channel / rcs_channel / whatsapp_channel — pass whichever you need to TACFastAPIServer to wire up routing. Voice/SMS/Chat are always created; RCS and WhatsApp are created only when their address is configured (rcs_sender_id / whatsapp_number on TACConfig), and are None otherwise.

Conversation history:

  • The bridge passes an AgentSession to every agent.run() call so that Agent Framework can load/save conversation history automatically.

  • Voice: agent + session are cached in-memory for the duration of the WebSocket call. The same agent handles all utterances within a single call, and history accumulates naturally. The session is also persisted to the AgentSessionStore in the background (fire-and-forget) after each utterance and on disconnect, enabling auditing and persistence of Foundry thread IDs without impacting voice latency.

  • SMS/chat: an AgentSessionStore persists the AgentSession between messages. Before each agent.run(), the bridge loads the session from the store (or creates a new one); after the run it saves the session back. This enables conversation continuity across messages for all provider types:

    • Foundry Agent Service: the server-side thread_id (stored as session.service_session_id) is preserved so subsequent messages reuse the same thread.
    • Responses API / Chat Completions: session state (including messages from InMemoryHistoryProvider) is preserved across messages. The default InMemoryAgentSessionStore works for single-instance deployments. For horizontal scaling, supply a persistent store (Redis, CosmosDB, etc.) via the session_store parameter.

AgentFrameworkConnector 

AgentFrameworkConnector(
    tac: Any,
    create_agent: Callable[[ConversationSession], Agent],
    on_message: Callable[
        [
            str,
            ConversationSession,
            TACMemoryResponse | None,
        ],
        str,
    ]
    | None = None,
    on_error: Callable[
        [Exception, ConversationSession], str
    ]
    | None = None,
    voice_config: VoiceChannelConfig
    | dict[str, Any]
    | None = None,
    sms_config: SMSChannelConfig
    | dict[str, Any]
    | None = None,
    chat_config: ChatChannelConfig
    | dict[str, Any]
    | None = None,
    rcs_config: RCSChannelConfig
    | dict[str, Any]
    | None = None,
    whatsapp_config: WhatsAppChannelConfig
    | dict[str, Any]
    | None = None,
    session_store: AgentSessionStore | None = None,
)

Connector for Twilio channels (Voice, SMS, Chat, RCS, WhatsApp) with Agent Framework agents.

All channel flows are fully managed internally. The developer supplies a create_agent factory and, optionally, hooks for message augmentation and error handling. HTTP/WebSocket routing is handled by TACFastAPIServer — pass voice_channel and/or messaging channels (sms_channel / chat_channel / rcs_channel / whatsapp_channel) to it to control which channels are active. RCS and WhatsApp are opt-in (see rcs_config / whatsapp_config below); when not configured, the corresponding attribute is None.

Conversation history is managed via Agent Framework's AgentSession. For voice, the agent and session persist in-memory for the duration of the WebSocket call, with background saves to the AgentSessionStore after each utterance for persistence/auditing. For SMS and chat, the session is loaded from and saved to the AgentSessionStore on every message.

Lifecycle callbacks (on_conversation_ended, on_interrupt) are wired automatically to handle voice agent cleanup and logging.

Parameters:

Name Type Description Default
tac Any

TAC instance.

 required
create_agent Callable[[ConversationSession], Agent]

(session: ConversationSession) -> Agent.

 required
on_message Callable[[str, ConversationSession, TACMemoryResponse | None], str] | None

Optional hook called before agent.run() for both voice and SMS. Signature: (user_message, context, memory_response) -> str. When None, defaults to format_memory_context(memory, msg).

 None
on_error Callable[[Exception, ConversationSession], str] | None

Optional hook to customize error responses. Signature: (error, context) -> str. When None, returns a default apology message.

 None
voice_config VoiceChannelConfig | dict[str, Any] | None

Optional Voice channel configuration (VoiceChannelConfig or dict). Controls auto memory retrieval, session manager, etc.

 None
sms_config SMSChannelConfig | dict[str, Any] | None

Optional SMS channel configuration (SMSChannelConfig or dict). Controls auto memory retrieval, deduplication capacity, etc.

 None
chat_config ChatChannelConfig | dict[str, Any] | None

Optional Chat channel configuration (ChatChannelConfig or dict). Controls agent identity, auto memory retrieval, deduplication capacity, etc.

 None
rcs_config RCSChannelConfig | dict[str, Any] | None

Optional RCS channel configuration (RCSChannelConfig or dict). Optional like sms_config. The rcs_channel is created when an RCS sender ID is configured (TWILIO_RCS_SENDER_ID / TACConfig.rcs_sender_id) and is None otherwise.

 None
whatsapp_config WhatsAppChannelConfig | dict[str, Any] | None

Optional WhatsApp channel configuration (WhatsAppChannelConfig or dict). Optional like sms_config. The whatsapp_channel is created when a WhatsApp number is configured (TWILIO_WHATSAPP_NUMBER / TACConfig.whatsapp_number) and is None otherwise.

 None
session_store AgentSessionStore | None

Persistence layer for AgentSession objects. Used for SMS session continuity across messages and for background persistence of voice sessions (auditing, Foundry thread IDs). Defaults to InMemoryAgentSessionStore (suitable for single-instance deployments). For horizontal scaling, provide a persistent implementation (Redis, CosmosDB, etc.).

 None

Voice Live

tac_microsoft.voice_live_connector

Voice Live connector for TAC.

Connector logic for Azure AI Foundry Voice Live. Parallel to AgentFrameworkConnector but uses Voice Live's WebSocket API for LLM inference instead of Microsoft Agent Framework's agent.run().

Voice Live is used in text-only mode (modalities: ["text"]) because Conversation Relay handles STT/TTS. The connector sends text in and streams text deltas back.

Key design:

  • VoiceLiveConfig holds connection parameters, instructions, tools, and tool executors

  • A voice_channel instance is exposed — pass it to TACFastAPIServer

Conversation history:

  • A single VoiceLiveSession (WebSocket) is kept open for the duration of the call. Voice Live manages conversation state server-side, so all utterances within a call share context.

VoiceLiveConnector 

VoiceLiveConnector(
    tac: Any,
    config: VoiceLiveConfig,
    on_message: Callable[
        [
            str,
            ConversationSession,
            TACMemoryResponse | None,
        ],
        str,
    ]
    | None = None,
    on_error: Callable[
        [Exception, ConversationSession], str
    ]
    | None = None,
    voice_config: VoiceChannelConfig
    | dict[str, Any]
    | None = None,
)

Connector for Twilio voice using Azure Voice Live for LLM inference.

Parallel to AgentFrameworkConnector but uses Voice Live's WebSocket API instead of Agent Framework. Voice Live manages conversation state server-side, so no AgentSession or session store is needed.

This connector is voice-only. For SMS/messaging, use AgentFrameworkConnector or a separate connector.

Parameters:

Name Type Description Default
tac Any

TAC instance.

 required
config VoiceLiveConfig

VoiceLiveConfig with endpoint, auth, instructions, tools.

 required
on_message Callable[[str, ConversationSession, TACMemoryResponse | None], str] | None

Optional hook called before sending to Voice Live. Signature: (user_message, context, memory_response) -> str. When None, defaults to format_memory_context(memory, msg).

 None
on_error Callable[[Exception, ConversationSession], str] | None

Optional hook to customize error responses. Signature: (error, context) -> str.

 None
voice_config VoiceChannelConfig | dict[str, Any] | None

Optional Voice channel configuration (VoiceChannelConfig or dict). Controls auto memory retrieval, session manager, etc.

 None

Voice Live configuration and errors

tac_microsoft.voice_live_types

Type definitions for the Voice Live connector.

VoiceLiveError

Bases: Exception

Raised when a Voice Live API error occurs.

VoiceLiveConfig dataclass 

VoiceLiveConfig(
    endpoint: str,
    model: str,
    api_key: str | None = None,
    credential: Any = None,
    api_version: str = "2025-10-01",
    instructions: str = "",
    tools: list[Any] = list(),
    tool_executors: dict[
        str, Callable[..., Awaitable[Any]]
    ] = dict(),
    modalities: list[str] = (lambda: ["text"])(),
    temperature: float | None = None,
    max_response_output_tokens: int | str | None = None,
)

Configuration for connecting to Azure AI Foundry Voice Live.

Voice Live is used in text-only mode (modalities: ["text"]) because Conversation Relay handles STT/TTS. The connector sends text in and streams text deltas back.

Parameters:

Name Type Description Default
endpoint str

Azure resource hostname, e.g. "your-resource.services.ai.azure.com".

 required
model str

Voice Live model name, e.g. "gpt-4o".

 required
api_key str | None

API key for authentication (mutually exclusive with credential).

 None
credential Any

Azure identity credential for Entra token auth (mutually exclusive with api_key).

 None
api_version str

Voice Live API version.

 '2025-10-01'
instructions str

System instructions for the model.

 ''
tools list[Any]

Tool list — accepts TACTool instances (from @function_tool or create_*_tool factories) and/or raw OpenAI function-tool dicts. TACTool entries are automatically converted to dict definitions and their executors are registered in tool_executors.

 list()
tool_executors dict[str, Callable[..., Awaitable[Any]]]

Map of tool name to async callable that executes the tool. Auto-populated from any TACTool objects in tools; you only need to set this manually when using raw dict tool definitions.

 dict()
modalities list[str]

Session modalities. Defaults to ["text"].

 (lambda: ['text'])()
temperature float | None

Sampling temperature (0.6 – 1.2).

 None
max_response_output_tokens int | str | None

Max output tokens per response.

 None

ws_url property 

ws_url: str

Build the Voice Live WebSocket URL.