Core concepts

TAC integrates with Twilio communication channels — Voice, SMS, WhatsApp, RCS, and Chat — to connect users to your agent. All channels share a unified callback interface, so you handle messages from any channel with the same function. For channel configuration and examples, see Channels.

Conversations represent ongoing interactions between participants across communication channels. TAC connects to Twilio services to retrieve conversation data and context, making it available to your agent through ConversationSession objects.

TAC retrieves context from Twilio services and passes it to your callbacks through the ConversationSession object. The callback also receives a memory parameter containing observations, summaries, and communication history (when Conversation Memory is configured).

1
async def handle_message_ready(
2
    message: str,
3
    context: ConversationSession,
4
    memory: TACMemoryResponse | None,
5
) -> str | None:
6
    # Access conversation context
7
    print(f"Conversation ID: {context.conversation_id}")
8
    print(f"Profile ID: {context.profile_id}")
9
    print(f"Channel: {context.channel}")  # "voice", "sms", "whatsapp", "rcs", or "chat"
10
    print(f"Started at: {context.started_at}")
11

12
    # Access profile data (if Conversation Memory enabled)
13
    if context.profile:
14
        print(f"User traits: {context.profile.traits}")
15

16
    # Access memory (observations, summaries, communications)
17
    if memory:
18
        print(f"Observations: {memory.observations}")

1
tac.onMessageReady(async ({ conversationId, profileId, message, memory, session, channel }) => {
2
    // Access conversation context
3
    console.log(`Conversation ID: ${conversationId}`);
4
    console.log(`Profile ID: ${profileId}`);
5
    console.log(`Channel: ${channel}`);  // "voice", "sms", "whatsapp", "rcs", or "chat"
6
    console.log(`Started at: ${session.startedAt}`);
7

8
    // Access profile data (if Conversation Memory is configured)
9
    if (session.profile) {
10
        console.log(`User traits: ${JSON.stringify(session.profile.traits)}`);
11
    }
12

13
    // Access memory (observations, summaries, communications)
14
    if (memory) {
15
        console.log(`Observations: ${JSON.stringify(memory.observations)}`);
16
    }
17
});

TAC integrates with Conversation Memory to provide persistent context across conversations.

TAC uses a dual-mode retrieval strategy with automatic fallback:

• Memory API mode (when Conversation Memory is configured): TAC looks up the customer profile, then retrieves observations, summaries, and communication history from the Memory API. This provides the richest context for your agent.
• Fallback mode (when Conversation Memory is not configured): TAC retrieves basic communication history directly from the Conversation Orchestrator API. Observations and summaries are not available in this mode, but your agent still has access to recent messages.

This fallback is automatic — you don't need to handle it in your code. Your on_message_ready callback always receives a TACMemoryResponse object, regardless of which mode is active. If the Memory API is unavailable at runtime, TAC logs a warning and falls back to the Conversation Orchestrator API for that request.

Conversation Memory integration is optional. When configured, TAC retrieves memory for each session:

1
async def handle_message_ready(
2
    message: str,
3
    context: ConversationSession,
4
    memory: TACMemoryResponse | None,
5
) -> str | None:
6
    if memory:
7
        # Access observations, summaries, communications
8
        for obs in memory.observations:
9
            print(obs.content)

1
tac.onMessageReady(async ({ memory }) => {
2
    if (memory) {
3
        // Access observations, summaries, communications
4
        for (const obs of memory.observations) {
5
            console.log(obs.content);
6
        }
7
    }
8
});

You can access user data through profile traits:

1
profile = context.profile
2

3
if profile and profile.traits:
4
    # Traits are organized by groups
5
    contact_group = profile.traits.get("Contact", {})
6
    email = contact_group.get("email")
7
    phone = contact_group.get("phone")
8

9
    preferences_group = profile.traits.get("Preferences", {})
10
    language = preferences_group.get("language", "en")

1
tac.onMessageReady(async ({ session }) => {
2
    const profile = session.profile;
3

4
    if (profile?.traits) {
5
        // Traits are organized by groups
6
        const contactGroup = profile.traits['Contact'] || {};
7
        const email = contactGroup.email;
8
        const phone = contactGroup.phone;
9

10
        const preferencesGroup = profile.traits['Preferences'] || {};
11
        const language = preferencesGroup.language || 'en';
12
    }
13
});

Traits from Conversation Memory are organized into logical groups (for example, "Contact", "Preferences"). The data structure comes pre-organized from Conversation Memory, and you can access it through context.profile.traits as shown in the example above.

To update profiles, use the Conversation Memory Console or the Conversation Memory API. TAC can only read profiles.

TAC includes a tool system that lets you define functions your agent can call during conversations. Tools follow the standard function-calling pattern used by LLM providers: you define a name, description, and JSON schema, and TAC formats them for your provider.

TAC includes built-in tools for common operations:

• Knowledge search: Query Enterprise Knowledge bases and return relevant results to your agent.
• Escalation: Transfer the conversation to a human agent in Twilio Flex.
• Memory retrieval: Search and retrieve customer observations, summaries, and conversation history.

You can also define custom tools with the @function_tool decorator (Python) or defineTool function (TypeScript). In Python, custom tools can receive the ConversationSession as a parameter, giving them access to profile data, conversation state, and channel information.

TAC integrates with Enterprise Knowledge to give your agent access to structured knowledge bases. When a user asks a question, your agent can search relevant knowledge bases and use the results to generate grounded, accurate responses.

Knowledge search is exposed as a tool that you add to your LLM's tool list. The tool handles the search request, queries the knowledge base, and returns matching results that your agent can reference in its response.

TAC supports transferring conversations from your AI agent to a human agent when the situation requires human intervention. Escalation preserves the conversation context so the human agent has full visibility into the interaction history.

The handoff flow uses the built-in create_studio_handoff_tool, which routes conversations to a Twilio Studio Flow. Set TWILIO_STUDIO_HANDOFF_FLOW_SID in your environment, create the tool with the TAC instance and session, and add it to your LLM's tools. When the LLM calls the tool:

• Voice: The tool stores the handoff payload on the session. After the LLM's final response plays, the Voice channel sends a WebSocket end message that routes the call to your Studio Flow.
• Digital: The tool POSTs the handoff payload directly to the Studio Flow Executions API.

For a complete guide, see Escalate to a human agent.

TAC supports two deployment modes to accommodate different use cases:

TAC does not run your AI logic. You provide the LLM application and control how it generates responses. TAC handles the infrastructure — channels, memory, tools, and session management — while you provide the agent.

TAC does not make decisions about what your agent should do. You define and control:

• When to escalate to human agents.
• How to interpret user intents.
• What actions to take based on conversation state.
• Custom validation or processing rules.

• Quickstart: Build and test a TAC application from scratch.
• Add TAC to your agent: Connect your agent and configure channels, tools, knowledge, and memory.
• Channels: Learn about channel configuration.