​

Integrating the Email Triage Agent over the API

​

When to use this guide

• Local inference — email bodies are classified and summarized on-device by Lemonade. There is no configuration path that routes email content to a cloud LLM; the agent rejects a non-local base_url at startup.
• Your own UX and mailbox connection — your app runs OAuth, owns the tokens, and forwards a connection to GAIA so the agent can read/send on the user’s behalf.
• A structured contract — a frozen request/response schema (SCHEMA_VERSION 2.5) you can code against, over REST or MCP stdio.

​

Architecture

┌──────────────────────┐     HTTP / MCP stdio      ┌───────────────────────┐
│   Your application    │ ────────────────────────► │  GAIA email surface   │
│  (owns UX + OAuth +   │   /v1/email/*  (triage,   │  /v1/email/*          │
│   mailbox tokens)     │    draft, send, …)        │  /v1/connections/*    │
│                       │ ◄──────────────────────── │                       │
└──────────────────────┘   structured results      └───────────┬───────────┘
          │                                                     │ local inference
          │ 1. self-OAuth (your client)                        ▼
          │ 2. forward connection ───────────────►   ┌───────────────────────┐
          │    POST /v1/connections/{provider}       │   Lemonade Server     │
          │                                          │  (local, on-device)   │
                                                     └───────────────────────┘

• Your app runs its own OAuth, holds the user’s refresh_token, and drives the agent over HTTP (or MCP).
• The GAIA email surface persists the forwarded connection and processes each email locally. It never runs a second consent flow — it refreshes as your client.
• Lemonade Server is the one runtime dependency: the agent calls a local Lemonade for inference. With none reachable — or the triage model unavailable on it — POST /v1/email/triage returns HTTP 502.

​

Standing up the API surface

pip install gaia-agent-email        # installs the email REST routes
python -m gaia.ui.server --port 4200 --host 127.0.0.1

curl -s http://127.0.0.1:4200/v1/email/health
# {"status":"ok","service":"gaia-agent-email"}

import { fetchBinary, startSidecar, shutdown } from "@amd-gaia/agent-email";
const { binaryPath } = await fetchBinary({ outDir: "resources" });
const sidecar = await startSidecar({ binaryPath, port: 8131 });
const res = await sidecar.client.triage({ payload: { /* … */ } });
await shutdown(sidecar);

python -m gaia_agent_email.mcp_server --transport stdio

​

Pointing the sidecar at an existing (embedded) Lemonade

export LEMONADE_BASE_URL=http://127.0.0.1:8555   # your app's embedded Lemonade
python -m gaia.ui.server --port 4200 --host 127.0.0.1

# Confirm the wiring:
curl -s http://127.0.0.1:4200/v1/email/init | jq '.lemonade.base_url, .model.id'
# "http://127.0.0.1:8555/api/v1"
# "Gemma-4-E4B-it-GGUF"

​

Fast local iteration (dev mode)

pip install -e hub/agents/email/python

1. Start the source agent with auto-reload (caller token off for local dev):
   gaia-agent-email serve --reload            # http://127.0.0.1:8131
   # editing core too? watch it as well:
   # gaia-agent-email serve --reload --reload-dir path/to/gaia/src
   
2. Attach your app. connectSidecar health- and version-checks the running server, spawns nothing, and returns a bound client — same API as production:
   import { connectSidecar } from "@amd-gaia/agent-email";
   
   const dev = await connectSidecar({ baseUrl: "http://127.0.0.1:8131" });
   const res = await dev.client.triage({ payload: { /* … */ } });
   
3. Edit the Python under gaia_agent_email/, save — it reloads in ~a second — and re-run your call. That’s the whole loop.

​

Authentication

• Per-session bearer token. Every /v1/email/* request to the sidecar must carry Authorization: Bearer <token> or it is rejected with HTTP 401. The token is a cryptographically-random per-session secret the spawning parent hands to the sidecar — preferably as a 0600 owner-only file whose path arrives in GAIA_EMAIL_SIDECAR_TOKEN_FILE (the GAIA daemon does this for 0.6.0+ binaries, so the secret never sits in the process environment), or directly in the GAIA_EMAIL_SIDECAR_TOKEN env var (npm lifecycle and older binaries).
• Host / Origin allowlist. A non-loopback Host header → HTTP 400 (DNS-rebinding); a non-loopback browser Origin → HTTP 403 (drive-by web page). No permissive CORS is ever sent.

• Frozen sidecar / npm — startSidecar mints the token, injects it, and binds it to sidecar.client, so sidecar.client.triage(...) just works. A client you construct yourself must pass authToken (from sidecar.authToken); forward it to a browser/Electron renderer over your own IPC — never embed it in a page.
• GAIA backend (REST) — the Agent UI backend proxies /v1/email/* to a sidecar supervised by the GAIA daemon (gaia daemon), which spawns it and mints its token; the backend acquires and replays the token for you, so your calls to 127.0.0.1:4200 need no bearer token — it is internal to the backend→sidecar hop. Because the daemon owns the sidecar, it keeps running after the backend exits; stop it with gaia daemon stop-agent email or gaia daemon stop.
• Direct-to-sidecar for local dev — if you launch the frozen binary yourself, set GAIA_EMAIL_SIDECAR_TOKEN (or point GAIA_EMAIL_SIDECAR_TOKEN_FILE at a file holding the token) and send the matching bearer header. Running it with neither variable disables the token check (local development only, logged loudly) — the Host/Origin controls still apply. A set GAIA_EMAIL_SIDECAR_TOKEN_FILE whose file is missing or empty fails startup loudly rather than silently disabling auth.

// npm path — the bound client carries the token for you.
const sidecar = await startSidecar({ binaryPath, port: 8131 });
await sidecar.client.draft({ to: [{ email: "[email protected]" }], subject: "Re: x", body: "hi" });

// Construct-your-own client (e.g. renderer over IPC) — pass the token explicitly.
import { EmailClient } from "@amd-gaia/agent-email/client";
const client = new EmailClient({ baseUrl: sidecar.baseUrl, authToken: sidecar.authToken });

​

Connection forwarding

​

1. Run your own OAuth

​

2. Forward the connection to GAIA

curl -s -X POST http://127.0.0.1:4200/v1/connections/google \
  -H "Content-Type: application/json" \
  -H "X-Gaia-UI: 1" \
  -d '{
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>",
    "refresh_token": "<USER_REFRESH_TOKEN>",
    "scopes": [
      "https://www.googleapis.com/auth/gmail.modify",
      "https://www.googleapis.com/auth/gmail.send"
    ],
    "account_email": "[email protected]",
    "grant_agents": ["installed:email"]
  }'

{
  "provider": "google",
  "account_email": "[email protected]",
  "scopes": [
    "https://www.googleapis.com/auth/gmail.modify",
    "https://www.googleapis.com/auth/gmail.send"
  ],
  "connected_at": null,
  "grant_agents": ["installed:email"],
  "forwarded": true
}

• refresh_token and client_secret are write-only secret inputs. They are stored in the OS keyring and never returned by any endpoint (GET /v1/connections and GET /v1/connections/{provider} return metadata only).
• grant_agents must include installed:email. Without this grant the connection exists but the email agent can’t resolve it at send time, and you’ll hit a “no grant” dead end. (Ties to #1592.)
• X-Gaia-UI: 1 header is required on the POST and DELETE. It’s a CSRF guard — a custom header forces a CORS preflight, so a drive-by form POST can’t forge it. Missing header → 403.
• Empty client_id / refresh_token → 422. Missing required scopes for the granted agent → 403 with a missing_scopes detail. GAIA cannot widen scope at refresh time, so forward everything the agent needs up front.

​

The triage contract

​

Single email

curl -s -X POST http://127.0.0.1:4200/v1/email/triage \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "kind": "single",
      "principal": { "email": "[email protected]" },
      "message": {
        "message_id": "m1",
        "from": { "name": "Sarah Chen", "email": "[email protected]" },
        "subject": "Prod incident follow-up",
        "body": "Please review the report and reply by Friday."
      }
    }
  }'

{
  "schema_version": "2.14",
  "request_kind": "single",
  "result": {
    "category": "URGENT",
    "is_spam": false,
    "is_phishing": false,
    "summary": "Prod incident follow-up — Please review the report and reply by Friday.",
    "action_items": [
      { "description": "Please review the report and reply by Friday.",
        "due_hint": "by Friday", "type": "text", "url": null }
    ],
    "draft": {
      "to": [{ "name": "Sarah Chen", "email": "[email protected]" }],
      "subject": "Re: Prod incident follow-up"
    },
    "suggested_action": "reply",
    "message_id": "m1",
    "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "tokens_per_second": 0.0 }
  }
}

• category is one of the five buckets: URGENT, NEEDS_RESPONSE, FYI, PROMOTIONAL, PERSONAL. is_spam / is_phishing are independent boolean signals.
• suggested_action is reply, archive, or none.
• draft is a DraftScaffold (to + subject only, no body — schema 2.3) or null — triage classifies and summarizes but never composes reply prose, and it never proposes a reply to spam/phishing or to yourself. To get a sendable reply, compose the body yourself and pass it to POST /v1/email/draft.
• usage is null on the heuristic-only path (no LLM call made).

​

Thread

​

Batch

​

Mid-run questions (needs_input)

// A needs_input event on the stream. It is NOT terminal — keep reading.
{
  "type": "needs_input",
  "run_id": "0f9c…",
  "request_id": "8c21…",
  "question": "Your Gmail sign-in has stopped working. Reconnect?",
  "options": [
    {"value": "yes", "label": "Reconnect Gmail",
     "description": "Opens your browser to sign in again. Your mail is untouched."},
    {"value": "no", "label": "Not now", "description": "Change nothing."}
  ],
  "allow_free_text": true,
  "sensitive": false,
  "respond_url": "/v1/email/query/0f9c…/respond",
  "timeout_seconds": 240
}

curl -s -X POST http://127.0.0.1:4200/v1/email/query/$RUN_ID/respond \
  -H 'content-type: application/json' \
  -d '{"request_id": "8c21…", "value": "yes"}'
# {"run_id":"0f9c…","request_id":"8c21…","accepted":true,"status":"ok"}

​

Draft → confirmed send

​

1. Mint a token

curl -s -X POST http://127.0.0.1:4200/v1/email/draft \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{ "email": "[email protected]" }],
    "subject": "Re: Prod incident follow-up",
    "body": "Thanks Sarah — reviewing now, will reply by Thursday."
  }'

{
  "draft": {
    "to": [{ "name": null, "email": "[email protected]" }],
    "subject": "Re: Prod incident follow-up",
    "body": "Thanks Sarah — reviewing now, will reply by Thursday."
  },
  "confirmation_token": "a1b2c3…"
}

​

2. A send without the token is rejected (403)

curl -s -o /dev/null -w "%{http_code}\n" -X POST http://127.0.0.1:4200/v1/email/send \
  -H "Content-Type: application/json" \
  -d '{ "to": [{ "email": "[email protected]" }],
        "subject": "Re: Prod incident follow-up",
        "body": "Thanks Sarah — reviewing now, will reply by Thursday." }'
# 403

​

3. Send with the token (200)

curl -s -X POST http://127.0.0.1:4200/v1/email/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{ "email": "[email protected]" }],
    "subject": "Re: Prod incident follow-up",
    "body": "Thanks Sarah — reviewing now, will reply by Thursday.",
    "confirmation_token": "a1b2c3…"
  }'

{ "sent_id": "18f…", "to": [{ "name": null, "email": "[email protected]" }],
  "subject": "Re: Prod incident follow-up", "sent": true }

​

MCP stdio alternative

python -m gaia_agent_email.mcp_server --transport stdio

​

Self-describing reference

• GET /v1/email/spec — a human-readable HTML page describing every endpoint.
• GET /v1/email/version — {"apiVersion": "2.5", "agentVersion": "…"}. apiVersion is the frozen contract version; negotiate against its MAJOR so a breaking upgrade fails loudly.
• GET /v1/email/init — readiness: the effective Lemonade base_url, the resolved model.id, and a 503 with an actionable hint when not ready. This is how you confirm a LEMONADE_BASE_URL override took effect.
• POST /v1/email/init — provisioning: tells a running Lemonade to download the triage model, streaming newline-delimited text/plain progress (curl -N). Once the stream commits 200, the final ✓/✗ line is the authoritative outcome; a 503 means Lemonade itself is unreachable.
• GET /v1/email/health — liveness only ({"status":"ok"}). A green health check means the REST surface is up, not that Lemonade is reachable — the readiness signal is GET /v1/email/init.

​

Provider coverage

• Gmail — full support (triage, search, draft/send, archive, quarantine, calendar).
• Outlook — personal (Outlook.com) and work/school (Microsoft 365 / Entra ID) mailboxes, via the browser (PKCE) or device-code OAuth flow on the common tenant. Phishing quarantine is Gmail-only (an Outlook mailbox is refused with 400, because its label-based undo can’t reverse Outlook’s folder move).

​

Related

• Email Triage — the Agent UI / gaia email flow (GAIA owns the UX).
• Email Triage Contract — the full #1262 request/response schema.
• @amd-gaia/agent-email — the JS/TS client + frozen sidecar.