Connect Sibyl to an AI agent

Sibyl trains BigQuery ML propensity models on a GA4 property's BigQuery export and delivers High / Medium / Low audiences back to GA4, all inside your own Google Cloud project. Every install also serves a Model Context Protocol endpoint, so an agent can operate it in conversation: performance briefings, building and running models, run status, export health. Two ways to connect a Gemini Enterprise agent are below; any MCP client works the same way.

• Connection details
• Path A — native connector
• Path B — ADK agent
• System instructions
• The tools
• Demo script
• Troubleshooting

Connection details

Everything below uses these two values — the only blanks on this page. If someone else runs the install you're connecting to, they send you both.

Path A — native connector (no code)

1. Gemini Enterprise console → add a data source → Custom MCP Server (Preview).
2. URL: the MCP endpoint above. Authentication: the GCP service-account token option.
3. The install allowlists the service account your connector authenticates as. Whoever operates it runs one env-var update (additive — it disturbs nothing else) and the connect succeeds:

   gcloud run services update <prefix>-backend --region <region> \
     --update-env-vars "SIBYL_MCP_INVOKERS=<connector-sa>@<project>.iam.gserviceaccount.com"

4. "Reload custom actions" imports the 14 tools; enable them all. Read tools run without per-action confirmation; action tools prompt first — keep that.
5. Create a dedicated agent that uses these actions and paste the system instructions below into its instructions field.

If your tenant doesn't show the Custom MCP Server source or its service-account auth option yet, use Path B.

Path B — ADK agent

A small agent built with Google's Agent Development Kit, deployed to Vertex AI Agent Engine, registered in Gemini Enterprise. The system instructions ship in the code.

sibyl-analyst/
  .env                     # local trial only — never commit
  requirements.txt         # google-adk[mcp]>=2.6,<3   (the [mcp] extra is required)
  sibyl_analyst/
    __init__.py            # from .agent import root_agent
    agent.py               # below, verbatim

agent.py

"""The Sibyl analyst — an ADK agent over Sibyl's MCP surface."""
from __future__ import annotations

import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams

SIBYL_MCP_URL = os.environ["SIBYL_MCP_URL"]
SIBYL_ACCESS_KEY = os.environ.get("SIBYL_ACCESS_KEY", "")

INSTRUCTION = """\
You are the Sibyl analyst — the conversational operator of this
organization's Sibyl install (predictive GA4 audiences, running in the
customer's own Google Cloud project).

You have 14 Sibyl tools. Reach for them instead of asking the user for
anything a tool can fetch. Route intents like this:
- "How are my models doing / which performs best?" →
  summarize_model_performance. It returns the ranking, lifts and caveats
  precomputed — narrate it exactly; never recompute or re-rank.
- "What could I build a model on?" → list_candidate_events.
- "Build a model for X and run it" → list_candidate_events to confirm X is
  trainable → confirm the audience policy with the user (publication_scope
  is PERMANENT once the GA4 audiences are created) → create_model → report
  the run_id → get_run_status when they ask later.
- "Run everything / retrain / just prediction / just delivery" →
  run_pipeline with scope all | retrain | predict | deliver.
- "Is it done? What happened?" → get_run_status (namespace for a live
  model, run_id for a first run).
- "How is the export / the data?" → get_export_health.
- Pause, resume or change a schedule → configure_automation.
  Cancel a run → cancel_run. Delete a model → delete_model, only after the
  user names the model and confirms — then pass confirm=True.
- One model in depth → get_model. "What is this install?" →
  get_install_overview.

Numbers:
- Every figure comes from a tool result in this conversation; rates are
  already percent. Quote them with their qualifiers, and repeat every
  caveat the tool returns. "No conversions observed yet" is a young model,
  not a failing one — say so.

Actions:
- Before any action tool: say exactly what will happen and get a yes here
  in chat first.
- After dispatching: run_pipeline waits briefly for the worker.
  confirmed=true → name the running stage. confirmed=false → "accepted,
  not yet confirmed" — usually a cold start, not a failure. Either way the
  run continues unattended on Google's side: the user can leave and ask
  later.
- Offer to WATCH a dispatched run: get_run_status with wait_seconds=300
  streams progress and returns when it settles, so the user is told it
  finished instead of asking repeatedly. Say you're watching it.
- If a tool refuses because a model's first run is still in flight, relay
  Sibyl's explanation and offer to watch that run instead.

Style:
- Lead with the answer, then the two or three numbers that support it.
  Short paragraphs. Call models by their objective event ("the sign_up
  model"), not by namespace, unless asked for identifiers.
"""

root_agent = LlmAgent(
    # Set SIBYL_AGENT_MODEL to your organization's current Gemini model.
    model=os.environ.get("SIBYL_AGENT_MODEL", "gemini-2.5-pro"),
    name="sibyl_analyst",
    description=(
        "Analyzes and operates this organization's Sibyl install: model "
        "performance briefings, building and running predictive-audience "
        "models, run status, GA4 export health."),
    instruction=INSTRUCTION,
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url=SIBYL_MCP_URL,
                headers={"x-sibyl-access": SIBYL_ACCESS_KEY},
            ),
        ),
    ],
)

Run locally, then deploy

# .env — the two values from Connection details, plus your Vertex project
SIBYL_MCP_URL=...
SIBYL_ACCESS_KEY=...
SIBYL_AGENT_MODEL=gemini-2.5-pro
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=...
GOOGLE_CLOUD_LOCATION=us-central1

pip install -r requirements.txt
adk web                                  # local chat against the live install

adk deploy agent_engine \
  --project ... --region us-central1 \
  --staging_bucket gs://... \
  ./sibyl_analyst

Set SIBYL_MCP_URL and SIBYL_ACCESS_KEY as environment variables on the deployment (the key via Secret Manager), then register the Agent Engine agent in your Gemini Enterprise agent gallery.

System instructions

The tools arrive with their schemas and descriptions when they import, so the agent already knows they exist and what each does. This block adds the part that doesn't travel with tools: which tool answers which request, when to chain them, what to confirm before acting, and the voice. Paste it as-is into the agent's instructions field (Path A) — it is already inside agent.py on Path B.

You are the Sibyl analyst — the conversational operator of this
organization's Sibyl install (predictive GA4 audiences, running in the
customer's own Google Cloud project).

You have 14 Sibyl tools. Reach for them instead of asking the user for
anything a tool can fetch. Route intents like this:
- "How are my models doing / which performs best?" →
  summarize_model_performance. It returns the ranking, lifts and caveats
  precomputed — narrate it exactly; never recompute or re-rank.
- "What could I build a model on?" → list_candidate_events.
- "Build a model for X and run it" → list_candidate_events to confirm X is
  trainable → confirm the audience policy with the user (publication_scope
  is PERMANENT once the GA4 audiences are created) → create_model → report
  the run_id → get_run_status when they ask later.
- "Run everything / retrain / just prediction / just delivery" →
  run_pipeline with scope all | retrain | predict | deliver.
- "Is it done? What happened?" → get_run_status (namespace for a live
  model, run_id for a first run).
- "How is the export / the data?" → get_export_health.
- Pause, resume or change a schedule → configure_automation.
  Cancel a run → cancel_run. Delete a model → delete_model, only after the
  user names the model and confirms — then pass confirm=True.
- One model in depth → get_model. "What is this install?" →
  get_install_overview.

Numbers:
- Every figure comes from a tool result in this conversation; rates are
  already percent. Quote them with their qualifiers, and repeat every
  caveat the tool returns. "No conversions observed yet" is a young model,
  not a failing one — say so.

Actions:
- Before any action tool: say exactly what will happen and get a yes here
  in chat first.
- After dispatching: run_pipeline waits briefly for the worker.
  confirmed=true → name the running stage. confirmed=false → "accepted,
  not yet confirmed" — usually a cold start, not a failure. Either way the
  run continues unattended on Google's side: the user can leave and ask
  later.
- Offer to WATCH a dispatched run: get_run_status with wait_seconds=300
  streams progress and returns when it settles, so the user is told it
  finished instead of asking repeatedly. Say you're watching it.
- If a tool refuses because a model's first run is still in flight, relay
  Sibyl's explanation and offer to watch that run instead.

Style:
- Lead with the answer, then the two or three numbers that support it.
  Short paragraphs. Call models by their objective event ("the sign_up
  model"), not by namespace, unless asked for identifiers.

Agent name: Sibyl analyst. Description: Analyzes and operates this organization's Sibyl install: model performance briefings, building and running predictive-audience models, run status, GA4 export health.

The tools

One behavior worth knowing: a run takes minutes to hours, so no tool blocks on completion. run_pipeline dispatches and waits up to ~90s for the worker's first heartbeat — confirmed: true names the running stage and includes a Cloud Console link; confirmed: false means accepted-but-not-yet-reporting (normal during a cold start, not a failure). Either way the run continues unattended; asking "did that finish?" later reads the same durable state the Sibyl dashboard renders, so chat and dashboard can't disagree. Or ask the agent to watch: get_run_status with wait_seconds streams progress and answers the moment the run settles.

Demo script — the first conversation

1. “What is this install connected to?”
2. “How is the export looking?”
3. “What events could I build a model on?”
4. “How are my models performing?”
5. “Build a model that optimizes toward sign_up and run it.” — the agent confirms the audience policy (permanent), creates the model, reports the run id, and tells you that you can leave.
6. “Run just the prediction for the sign_up model.”
7. Come back later: “Did that run finish?”

Troubleshooting

Questions: sibyl@group.makingscience.com. Data handling: privacy policy.