Deploy to Google Cloud Run

Each deployment has two independent pieces:

• Agent: Your Google Cloud agent. Deploy it to Agent Platform Runtime, or build it in the CX Agent Studio or Conversational Agents console.
• TAC server: A FastAPI app that terminates Twilio webhooks and the ConversationRelay WebSocket, and forwards turns to your agent. The server runs on Cloud Run.

The connector links the two.

The deployment uses the following Google Cloud resources:

• Cloud Run: Container runtime for the TAC server
• Artifact Registry: Container image storage, created automatically
• Secret Manager: Stores TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_API_KEY, and TWILIO_API_SECRET
• Cloud Build: Builds the server image

Cloud Run provides a built-in HTTPS endpoint and handles the ConversationRelay WebSocket connection, so you don't need ngrok or a reverse proxy in production.

Before you begin, make sure you have:

• Google Cloud CLI installed
• A Google Cloud project with billing enabled
• A working TAC application with your chosen connector (ADK, Studio, CX Agent Studio, or Conversational Agents)
• Your Twilio Account SID, Auth Token, API Key and Secret, and phone number. To find them, see the Quickstart prerequisites.
• Your Conversation Configuration ID. In the Twilio Console, go to Orchestration > Conversation Orchestrator > Conversation configurations.

Each connector also has its own prerequisites:

The twilio-agent-connect-google repository includes a deployment directory for each connector. Each directory has its own .env file and Makefile.

1. Clone the repository:

   Copy code block

   1
   git clone https://github.com/twilio/twilio-agent-connect-google.git
   2
   cd twilio-agent-connect-google

2. Move into the deployment directory for your connector and copy the environment template:

   ADKStudioCX Agent StudioConversational Agents

   Copy code block

   1
   cd deploy/agent_platform/adk
   2
   cp .env.example .env

3. Edit .env and fill in your Twilio credentials and the Google Cloud values for your connector:

   ADKStudioCX Agent StudioConversational Agents

   Copy code block

   1
   GOOGLE_CLOUD_PROJECT=your-project-id
   2
   GOOGLE_CLOUD_LOCATION=your-region
   3
   GCP_REASONING_ENGINE_ID=

   Leave GCP_REASONING_ENGINE_ID blank. The agent deploy fills it in.

   Also set the Twilio values in the same file:

   Copy code block

   1
   TWILIO_ACCOUNT_SID=your_account_sid
   2
   TWILIO_AUTH_TOKEN=your_auth_token
   3
   TWILIO_API_KEY=your_api_key
   4
   TWILIO_API_SECRET=your_api_secret
   5
   TWILIO_PHONE_NUMBER=+15555550100
   6
   TWILIO_CONVERSATION_CONFIGURATION_ID=conv_configuration_xxx

   The deploy stores the four Twilio credentials in Secret Manager and passes the remaining values as environment variables.

4. Authenticate with Google Cloud. You only need to do this once per machine.

   Copy code block

   1
   gcloud auth login
   2
   gcloud auth application-default login

5. Create the deploy service account. You only need to do this once. The command creates a tac-deployer service account and grants it the roles it needs.

   Copy code block

   make create-sa

6. Deploy:

   Copy code block

   make deploy-all

   For the ADK connector, deploy-all deploys the agent, stores the secrets, and then deploys the server. For the other connectors, it stores the secrets and then deploys the server. To run the steps individually, use make deploy-agent (ADK only), make deploy-secret, and make deploy-server.

When the deploy completes, it prints the Cloud Run service URL and the webhook URLs to configure in Twilio:

1
Deployed: https://tac-server-xxxxx.<region>.run.app
2

3
Configure Twilio:
4
  Conversation Orchestrator status callback : https://tac-server-xxxxx.<region>.run.app/webhook   (POST)
5
  Voice "A call comes in" webhook           : https://tac-server-xxxxx.<region>.run.app/twiml     (POST)

Running make deploy-server again keeps the same URL.

The CX Agent Studio server defaults to cascaded voice, where Twilio handles speech-to-text and text-to-speech. To use native speech-to-speech voice, open server/main.py, comment out the cascaded block, and uncomment the speech-to-speech block. Then run make deploy-server.

Speech-to-speech voice doesn't support Conversation Orchestrator or Conversation Memory. Messaging channels keep both in either mode.

1. In the Twilio Console, go to Communications > Numbers & senders.
2. Select your phone number.
3. Under Configuration details, find Voice configuration and click Edit details.
4. Set the primary webhook URL to https://<service-url>/twiml and the method to POST.
5. Save.

1. In the Twilio Console, go to Orchestration > Conversation Orchestrator > Conversation configurations.
2. Select your Conversation Configuration.
3. Set the status callback Webhook URL to https://<service-url>/webhook and the method to POST.
4. Save.

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

1
gcloud run services logs read tac-server-adk \
2
  --project your-project-id \
3
  --region your-region \
4
  --limit 50

1
gcloud run services logs read tac-server-studio \
2
  --project your-project-id \
3
  --region your-region \
4
  --limit 50

1
gcloud run services logs read tac-cx-server \
2
  --project your-project-id \
3
  --region your-region \
4
  --limit 50

1
gcloud run services logs read tac-df-server \
2
  --project your-project-id \
3
  --region your-region \
4
  --limit 50

Replace your-project-id and your-region with the values from your .env file.

• After you edit an ADK agent, run make deploy-agent.
• After you edit an Agent Studio, CX Agent Studio, or Conversational Agents agent, redeploy it from its console.
• After you edit the server or the package, run make deploy-server.
• After you rotate Twilio credentials in .env, run make deploy-secret.

• Google Cloud connectors: Learn about the available connectors.
• Troubleshooting: Debug common issues.
• Escalate to a human agent: Transfer conversations from your agent to a human agent.