Google Cloud connectors

Before you begin, make sure you have:

• TAC SDK installed and configured with your Twilio credentials and a Conversation Configuration (see Add TAC to your agent prerequisites)
• A Google Cloud project with billing enabled
• Application Default Credentials configured locally (gcloud auth application-default login)
• Python 3.10 or later, within the range that the twilio-agent-connect-google package supports

The twilio-agent-connect-google package provides connectors for different Google Cloud agent services.

All connectors support voice and messaging. SMS, Voice, and Chat are always available. RCS and WhatsApp activate automatically when you set TWILIO_RCS_SENDER_ID or TWILIO_WHATSAPP_NUMBER alongside your TAC credentials.

The ADKAgentEngineConnector connects Twilio to an ADK agent deployed on Agent Platform Runtime. The connector creates one session per conversation and reuses it across turns, so ADK manages conversation history on the server.

Add the following to your .env file alongside your existing TAC credentials.

1
GOOGLE_CLOUD_PROJECT=your-project-id
2
GOOGLE_CLOUD_LOCATION=us-central1
3
GCP_REASONING_ENGINE_ID=your-reasoning-engine-id

1
import os
2

3
import vertexai
4
from dotenv import load_dotenv
5
from tac import TAC, TACConfig
6
from tac.channels.sms import SMSChannelConfig
7
from tac.channels.voice import VoiceChannelConfig
8
from tac.server import TACFastAPIServer
9

10
from tac_google.connectors import ADKAgentEngineConnector
11

12
load_dotenv()
13

14
GCP_PROJECT = os.environ["GOOGLE_CLOUD_PROJECT"]
15
GCP_LOCATION = os.environ["GOOGLE_CLOUD_LOCATION"]
16
REASONING_ENGINE_ID = os.environ["GCP_REASONING_ENGINE_ID"]
17

18
client = vertexai.Client(project=GCP_PROJECT, location=GCP_LOCATION)
19
tac = TAC(config=TACConfig.from_env())
20
agent = client.agent_engines.get(
21
    name=f"projects/{GCP_PROJECT}/locations/{GCP_LOCATION}/reasoningEngines/{REASONING_ENGINE_ID}"
22
)
23

24
connector = ADKAgentEngineConnector(
25
    tac=tac,
26
    agent=agent,
27
    voice_config=VoiceChannelConfig(memory_mode="once"),
28
    sms_config=SMSChannelConfig(memory_mode="once"),
29
)
30

31
server = TACFastAPIServer(
32
    tac=tac,
33
    voice_channel=connector.voice,
34
    messaging_channels=[connector.sms],
35
)
36

37
if __name__ == "__main__":
38
    server.start()

The connector automatically:

• Retrieves memory context from Conversation Memory and includes it in the first message (when memory_mode is set to "always" or "once")
• Routes responses to the correct channel
• Reuses one ADK session for the life of each conversation

To disable memory retrieval, omit voice_config and sms_config or set memory_mode to "never".

The StudioAgentEngineConnector connects Twilio to a source-code app that you build and deploy from the Agent Studio console. Agent Studio apps don't register SDK query or stream_query methods, so the connector calls the streamQuery REST endpoint instead. Session handling works the same way as the ADK connector.

Add the following to your .env file alongside your existing TAC credentials.

1
GOOGLE_CLOUD_PROJECT=your-project-id
2
GOOGLE_CLOUD_LOCATION=us-west1
3
GCP_REASONING_ENGINE_ID=your-reasoning-engine-id

1
import os
2

3
import vertexai
4
from dotenv import load_dotenv
5
from tac import TAC, TACConfig
6
from tac.channels.sms import SMSChannelConfig
7
from tac.channels.voice import VoiceChannelConfig
8
from tac.server import TACFastAPIServer
9

10
from tac_google.connectors import StudioAgentEngineConnector
11

12
load_dotenv()
13

14
GCP_PROJECT = os.environ["GOOGLE_CLOUD_PROJECT"]
15
GCP_LOCATION = os.environ["GOOGLE_CLOUD_LOCATION"]
16
REASONING_ENGINE_ID = os.environ["GCP_REASONING_ENGINE_ID"]
17

18
client = vertexai.Client(project=GCP_PROJECT, location=GCP_LOCATION)
19
tac = TAC(config=TACConfig.from_env())
20
agent = client.agent_engines.get(
21
    name=f"projects/{GCP_PROJECT}/locations/{GCP_LOCATION}/reasoningEngines/{REASONING_ENGINE_ID}"
22
)
23

24
connector = StudioAgentEngineConnector(
25
    tac=tac,
26
    agent=agent,
27
    voice_config=VoiceChannelConfig(memory_mode="once"),
28
    sms_config=SMSChannelConfig(memory_mode="once"),
29
)
30

31
server = TACFastAPIServer(
32
    tac=tac,
33
    voice_channel=connector.voice,
34
    messaging_channels=[connector.sms],
35
)
36

37
if __name__ == "__main__":
38
    server.start()

The connector uses the same memory and session behavior as the ADK connector.

The CXAgentStudioConnector connects Twilio to an agent built in the CX Agent Studio console (Customer Engagement Suite). Voice runs in one of two modes:

Messaging channels (SMS, RCS, WhatsApp, and Chat) always use the text runSession API with Conversation Orchestrator and Conversation Memory.

Add the following to your .env file alongside your existing TAC credentials.

CX_AGENT_ID=projects/your-project/locations/your-location/apps/your-app-id

The service account or user running the server needs the roles/ces.client role on the agent.

1
import os
2

3
from dotenv import load_dotenv
4
from tac import TAC, TACConfig
5
from tac.channels.sms import SMSChannelConfig
6
from tac.channels.voice import VoiceChannelConfig
7

8
from tac_google.connectors import CXAgentStudioConnector
9
from tac_google.connectors.cx_agent_studio.server import CXAgentStudioFastAPIServer
10

11
load_dotenv()
12

13
CX_AGENT_ID = os.environ["CX_AGENT_ID"]
14

15
tac = TAC(config=TACConfig.from_env())
16

17
connector = CXAgentStudioConnector(
18
    tac=tac,
19
    agent_id=CX_AGENT_ID,
20
    voice_config=VoiceChannelConfig(memory_mode="once"),
21
    sms_config=SMSChannelConfig(memory_mode="once"),
22
)
23

24
server = CXAgentStudioFastAPIServer(
25
    tac=tac,
26
    voice_channel=connector.voice,
27
    messaging_channels=[connector.sms],
28
)
29

30
if __name__ == "__main__":
31
    server.start()

To use native speech-to-speech voice, see the getting_started/examples/cx_agent_studio/s2s.py example in the repository.

The ConversationalAgentsConnector connects Twilio to an agent built in the Conversational Agents (Dialogflow CX) console. The connector calls the Dialogflow CX detectIntent API. Twilio ConversationRelay handles speech, so the connector exchanges text only, and Dialogflow keeps conversation history on the server for each session ID.

Add the following to your .env file alongside your existing TAC credentials.

1
CONVERSATIONAL_AGENT_ID=projects/your-project/locations/us-central1/agents/your-agent-id
2
DIALOGFLOW_LANGUAGE_CODE=en

The service account or user running the server needs the roles/dialogflow.client role.

To start from a working example instead of writing the server code yourself, clone the twilio-agent-connect-google repository and run one of the included examples.

1. Clone the repository and install dependencies:

   Copy code block

   1
   git clone https://github.com/twilio/twilio-agent-connect-google.git
   2
   cd twilio-agent-connect-google
   3
   make sync
   4
   make dev-setup

2. Create a .env file in the examples directory:

   Copy code block

   cp getting_started/examples/.env.example getting_started/examples/.env

3. Fill in your TAC credentials and the Google Cloud variables for the connector you want to run:

   ADK Agent EngineStudio Agent EngineCX Agent StudioConversational Agents

   Copy code block

   1
   GOOGLE_CLOUD_PROJECT=your-project-id
   2
   GOOGLE_CLOUD_LOCATION=us-central1
   3
   GCP_REASONING_ENGINE_ID=your-reasoning-engine-id

4. From the repository root, start the example server:

   ADK Agent EngineStudio Agent EngineCX Agent StudioConversational Agents

   Copy code block

   uv run getting_started/examples/agent_platform/adk_agent_engine.py

5. Expose your local server with ngrok so Twilio can reach it, then configure your Twilio webhooks to point at the ngrok domain. For detailed steps, see Expose your local server with ngrok and Configure Twilio webhooks.

The repository also includes examples that enable a single messaging channel (features/whatsapp.py, features/rcs.py) and a browser-based web chat (features/chat/) that runs entirely on localhost.

1. Start your server and make sure ngrok is running.
2. Send an SMS to your Twilio phone number and verify that you receive a response.
3. Call your Twilio phone number and verify that the voice channel works.
4. If you configured Conversation Memory, verify that responses include personalized context from the customer's profile.

• Deploy to Google Cloud Run: Deploy your TAC application to production on Google Cloud.
• Add TAC to your agent: Add custom tools and knowledge search.
• Troubleshooting: Common issues and solutions.