Metadata-Version: 2.4
Name: twilio-agent-connect-google
Version: 1.0.0
Summary: Google Cloud integrations for Twilio Agent Connect (TAC) - connectors for Google Cloud agent runtimes
Project-URL: Homepage, https://github.com/twilio/twilio-agent-connect-google
Project-URL: Documentation, https://www.twilio.com/docs/conversations/agent-connect
Project-URL: Repository, https://github.com/twilio/twilio-agent-connect-google
Project-URL: Issues, https://github.com/twilio/twilio-agent-connect-google/issues
Author-email: Twilio <help@twilio.com>
License: MIT
License-File: LICENSE
Keywords: agent,conversational-ai,google-cloud,twilio,vertex-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: <3.12,>=3.10
Requires-Dist: twilio-agent-connect<3,>=2.3.0
Provides-Extra: conversational-agents
Requires-Dist: google-auth<3,>=2; extra == 'conversational-agents'
Requires-Dist: requests<3,>=2; extra == 'conversational-agents'
Provides-Extra: cx-agent-studio
Requires-Dist: google-auth<3,>=2; extra == 'cx-agent-studio'
Requires-Dist: requests<3,>=2; extra == 'cx-agent-studio'
Requires-Dist: websockets<16,>=14; extra == 'cx-agent-studio'
Provides-Extra: dev
Requires-Dist: google-adk[a2a]<2.3,>=2.2.0; extra == 'dev'
Requires-Dist: google-cloud-aiplatform[agent-engines]<2,>=1.148.1; extra == 'dev'
Requires-Dist: google-genai<3,>=2.9; extra == 'dev'
Requires-Dist: mypy<2,>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio<1,>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov<6,>=5.0.0; extra == 'dev'
Requires-Dist: pytest<8,>=7.0.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.8.0; extra == 'dev'
Requires-Dist: twilio-agent-connect[server]<3,>=2.3.0; extra == 'dev'
Requires-Dist: types-google-cloud-ndb>=2.0.0; extra == 'dev'
Provides-Extra: server
Requires-Dist: python-dotenv>=1.0.0; extra == 'server'
Requires-Dist: twilio-agent-connect[server]<3,>=2.3.0; extra == 'server'
Provides-Extra: vertex-ai
Requires-Dist: google-auth<3,>=2; extra == 'vertex-ai'
Requires-Dist: google-cloud-aiplatform[agent-engines,reasoningengine]<2,>=1.148.1; extra == 'vertex-ai'
Requires-Dist: google-genai<3,>=2.9; extra == 'vertex-ai'
Description-Content-Type: text/markdown

<div align="center">
  <div>
    <img src="https://raw.githubusercontent.com/twilio/twilio-agent-connect-google/main/logo.svg" alt="Twilio Agent Connect Google Logo" width="120" height="120">
  </div>

  <h1>
    Twilio Agent Connect Google
  </h1>

  <h2>
    Google Cloud integrations for Twilio Agent Connect — connect Google Cloud agent services to Twilio's communication channels.
  </h2>

  <div align="center">
    <a href="https://pypi.org/project/twilio-agent-connect-google/"><img alt="PyPI" src="https://img.shields.io/pypi/v/twilio-agent-connect-google.svg"/></a>
    <a href="https://github.com/twilio/twilio-agent-connect-google"><img alt="Python SDK" src="https://img.shields.io/badge/Python-3.10--3.11-3776AB.svg"/></a>
    <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-green.svg"/></a>
    <a href="getting_started/examples/"><img alt="Getting Started" src="https://img.shields.io/badge/Getting%20Started-Examples-F22F46.svg"/></a>
  </div>

  <p>
    <a href="https://www.twilio.com/docs/conversations/agent-connect">Documentation</a>
    ◆ <a href="https://github.com/twilio/twilio-agent-connect-python">Python SDK</a>
    ◆ <a href="getting_started/examples/">Examples</a>
    ◆ <a href="deploy/">Deployment</a>
  </p>
</div>

Google Cloud-specific connectors for [Twilio Agent Connect (TAC)](https://www.twilio.com/docs/conversations/agent-connect) — Twilio's framework for connecting AI agents to voice and messaging channels ([Python SDK](https://github.com/twilio/twilio-agent-connect-python)) — enabling seamless integration with Google Cloud agent services like Agent Platform Runtime (Reasoning Engine), CX Agent Studio (Customer Engagement Suite), Conversational Agents (Dialogflow CX), and the Agent Development Kit (ADK).

---

## Features

### Agent Runtime Integration
- **GCP Agent Platform Runtime** (Reasoning Engine) — two connectors, one per deployment type:
  - **`ADKAgentEngineConnector`** — Google ADK agents, session-based, streaming `async_stream_query()`
  - **`StudioAgentEngineConnector`** — Agent Studio apps, invoked over the `streamQuery` REST endpoint
- **CX Agent Studio** (Customer Engagement Suite) via `CXAgentStudioConnector` — connect an agent built in the CX Agent Studio console; SMS/RCS/WhatsApp/Chat + ConversationRelay voice invoke the text `runSession` API, or switch voice to native speech-to-speech over `BidiRunSession`
- **Conversational Agents** (Dialogflow CX) via `ConversationalAgentsConnector` — connect an agent built in the Conversational Agents console; invoked over the Dialogflow CX `detectIntent` API (works for Playbook and Flow agents)

### Multi-Channel Communication
- **Voice, SMS, RCS, WhatsApp, and Chat support** - Single codebase handles phone calls and every messaging channel; SMS/Voice/Chat are always available, RCS/WhatsApp activate automatically once their Twilio resource (`TWILIO_RCS_SENDER_ID` / `TWILIO_WHATSAPP_NUMBER`) is configured
- **Automatic conversation routing** - Messages route to the correct agent instance per conversation
- **Memory injection** - Customer history and preferences automatically included in agent context

### Deployment Options
- **Cloud Run server** ⭐ **Recommended** - Containerized TAC server with a public HTTPS URL and WebSocket support (required for Twilio ConversationRelay voice)
- **Local (ngrok)** - Run the FastAPI server locally against a deployed agent for testing

### Production Ready
- **Twilio webhook validation** - Automatic signature verification for secure integrations
- **Secret Manager** - Twilio credentials stored in Google Secret Manager, injected at runtime
- **Session & memory** - Server-side sessions (ADK and Agent Studio), with Conversation Memory injection

## Installation

### With Agent Platform Runtime

```bash
pip install twilio-agent-connect-google[vertex-ai,server]
```

### With CX Agent Studio

```bash
pip install twilio-agent-connect-google[cx-agent-studio,server]
```

### With Conversational Agents

```bash
pip install twilio-agent-connect-google[conversational-agents,server]
```

### Development

```bash
# Install with development tools (includes all connectors)
pip install twilio-agent-connect-google[dev]
```

> **Note**: Requires **Python 3.10 or 3.11**. Python 3.12+ is not supported because GCP Agent Platform Runtime (Reasoning Engine) only supports Python 3.8–3.11. We recommend Python 3.11.

## Configuration

twilio-agent-connect-google requires TAC environment variables. See [TAC Configuration](https://github.com/twilio/twilio-agent-connect-python#configuration) for details.

### Required Environment Variables

```bash
# GCP Configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=your-region
GCP_REASONING_ENGINE_ID=your-reasoning-engine-id

# Twilio Configuration
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_API_KEY=your_api_key          # Starts with SK
TWILIO_API_SECRET=your_api_secret    # Secret for API key
TWILIO_PHONE_NUMBER=+1234567890
TWILIO_CONVERSATION_CONFIGURATION_ID=conv_configuration_xxx

# Optional: enables RCS / WhatsApp
# TWILIO_RCS_SENDER_ID=rcs_sender_xxxxxxxxxxxxxxxxxx
# TWILIO_WHATSAPP_NUMBER=whatsapp:+1234567890

# Server Configuration (for Voice)
TWILIO_VOICE_PUBLIC_DOMAIN=your-domain.ngrok.io
```

## Examples

Full examples available in [`getting_started/examples/`](getting_started/examples/):

- **`agent_platform/adk_agent_engine.py`** - Connect Twilio to an ADK agent deployed on GCP Agent Platform Runtime
- **`agent_platform/studio_agent_engine.py`** - Connect Twilio to an Agent Studio app deployed on GCP Agent Platform Runtime
- **`cx_agent_studio/cascaded.py`** - Connect Twilio to an agent built in CX Agent Studio (Customer Engagement Suite), text/SMS + ConversationRelay voice
- **`cx_agent_studio/s2s.py`** - Same CX Agent Studio agent, but native speech-to-speech voice (Twilio Media Streams + `BidiRunSession`, no ConversationRelay)
- **`conversational_agents.py`** - Connect Twilio to an agent built in Conversational Agents (Dialogflow CX)
- **`features/whatsapp.py`**, **`features/rcs.py`** - Enable a single messaging channel (WhatsApp or RCS) on its own
- **`features/chat/`** - Browser-based web chat (Twilio Conversations JS SDK), runnable entirely on localhost

## Deployment

See [`deploy/`](deploy/) for production deployment guides:

### Cloud Run (Agent Platform Runtime) ⭐ Recommended
- Deploy your **agent** (ADK, or a source-code app built in Agent Studio) to Agent Platform Runtime and the **TAC server** to Cloud Run
- Public HTTPS URL + WebSocket for Twilio ConversationRelay (voice)
- Twilio credentials stored in Secret Manager
- Two fully independent setups (`adk/` and `studio/`), each with its own `.env` and `make` workflow (`create-sa`, `deploy-secret`, `deploy-server`, `deploy-all`)
- See [`deploy/agent_platform/`](deploy/agent_platform/) for the setup guide

### Cloud Run (CX Agent Studio)
- Build the **agent** in the CX Agent Studio console; deploy the **TAC server** to Cloud Run
- Same Cloud Run + Secret Manager + `make` workflow; voice defaults to ConversationRelay (`runSession`) but can switch to native speech-to-speech (`BidiRunSession`)
- See [`deploy/cx_agent_studio/`](deploy/cx_agent_studio/) for the setup guide

### Cloud Run (Conversational Agents)
- Build the **agent** in the Conversational Agents (Dialogflow CX) console; deploy the **TAC server** to Cloud Run
- Same Cloud Run + Secret Manager + `make` workflow, invoking the Dialogflow CX `detectIntent` API
- See [`deploy/conversational_agents/`](deploy/conversational_agents/) for the setup guide

## Development

### Setup

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

# Install dependencies
make sync

# Setup dev environment
make dev-setup
```

### Code Quality

```bash
# Format code
make format

# Type check
make type-check

# Lint
make lint

# Run tests
make test

# Run all checks
make check
```

## Dependencies

twilio-agent-connect-google depends on:
- **twilio-agent-connect** - Core Twilio Agent Connect framework
  - Requires the `[server]` extra for TAC Server support
- **google-cloud-aiplatform** - Vertex AI / Agent Platform Runtime (Reasoning Engine)
- **google-adk** (optional) - Google Agent Development Kit, for ADK agents
- **google-auth**, **requests**, **websockets** - used by the CX Agent Studio connector to call the CX Agent Studio API (via the `cx-agent-studio` extra)

## Contributing

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

## License

MIT License - see [LICENSE](LICENSE) file for details.
