Files · Google Gemini Multi-Agent Handoff for Gorgias Support Triage

# Google Gemini Multi-Agent Handoff for Gorgias Support Triage
 
> Route Gorgias tickets between a FAQ agent and a human takeover using multi-agent handoff, driven by Google Gemini.
 
A reference implementation demonstrating how to build a production-grade support ticket triage system. Incoming Gorgias webhooks are classified by Gemini Flash, answered by an FAQ bot when possible, or escalated to a human agent via the `@reaatech/*` agent-handoff protocol with context compression.
 
## Architecture
 
```
Gorgias Webhook → POST /api/webhook/gorgias → TriageOrchestrator
                                                   │
                                          ┌────────┴────────┐
                                          ▼                  ▼
                                    classifierService    FaqAgent.answerQuestion()
                                          │                  │
                                    ┌─────┴─────┐      Post reply back
                                    │           │      to Gorgias ticket
                                    ▼           ▼
                              FAQ (≥0.6)    Escalate (<0.6)
                                    │           │
                                    │           ▼
                                    │      HybridCompressor
                                    │           │
                                    │      CapabilityBasedRouter
                                    │           │
                                    │      HandoffManager.executeHandoff
                                    │           │
                                    │      Update Gorgias ticket
                                    │           │
                                    └───────────┘
                              recordAgentDispatchDuration
```
 
## Environment Variables
 
| Variable | Required | Description |
|---|---|---|
| `GORGIAS_API_KEY` | Yes | API token for the Gorgias REST API |
| `GORGIAS_DOMAIN` | Yes | Gorgias tenant subdomain (e.g. `acme` → `https://acme.gorgias.com`) |
| `GEMINI_API_KEY` | Yes | API key from [Google AI Studio](https://aistudio.google.com/apikey) |
| `GORGIAS_WEBHOOK_SECRET` | Yes | Secret for verifying Gorgias webhook signatures |
| `LOG_LEVEL` | No | Log severity: `debug`, `info`, `warn`, `error` (default: `info`) |
| `NODE_ENV` | No | Runtime environment (default: `development`) |
 
## Setup
 
```bash
# Clone and install
pnpm install
 
# Configure environment
cp .env.example .env
# Edit .env with your API keys
 
# Run tests
pnpm test
 
# Start dev server
pnpm dev
```
 
### Gorgias Webhook Configuration
 
1. Go to **Settings → Integrations → Webhooks** in your Gorgias admin panel.
2. Create a new webhook pointing to `https://your-domain.com/api/webhook/gorgias`.
3. Select the `ticket.created` and `ticket.updated` events.
4. Copy the webhook secret into `GORGIAS_WEBHOOK_SECRET` in `.env`.
 
## Project Layout
 
```
app/api/webhook/gorgias/route.ts   Webhook endpoint (POST + GET health check)
src/
  index.ts                         Barrel re-exports
  instrumentation.ts               OpenTelemetry initialization
  lib/
    gorgias.ts                     Gorgias REST API client
    gemini.ts                      Gemini LLM wrapper (GoogleGenAI)
    types.ts                       Shared TypeScript types
  services/
    faq-agent.ts                   FAQ bot powered by Gemini
    triage-orchestrator.ts         Central orchestration logic
tests/                             Vitest test suite
packages/                          API reference docs for dependencies
DEV_PLAN.md                        Implementation plan
```
 
## Dependencies
 
- `@reaatech/agent-handoff` — Core handoff types, errors, and utilities
- `@reaatech/agent-handoff-compression` — Context compression (`HybridCompressor`)
- `@reaatech/agent-handoff-routing` — Agent routing (`CapabilityBasedRouter`, `AgentRegistry`)
- `@reaatech/agent-handoff-protocol` — Full handoff orchestration (`HandoffManager`)
- `@reaatech/agent-mesh-classifier` — Gemini Flash intent classifier
- `@reaatech/agent-mesh-observability` — Logging, metrics, and tracing
- `@google/genai` — Google Gen AI SDK for Gemini
 
## License
 
MIT — see [LICENSE](./LICENSE).