Gemini 2.0 Flash vs Gemini 1.5 Flash Deprecated

Changelog

April 9, 2025

Model updates:

Released veo-2.0-generate-001, a generally available (GA) text- and image-to-video model, capable of generating detailed and artistically nuanced videos. To learn more, see the Veo docs.

Released gemini-2.0-flash-live-001, a public preview version of the Live API model with billing enabled.

# 80,000 NOK ($7,500) drained from my Google Cloud account in 5 minutes — full forensic breakdown of how the attack worked

I want to write this up while it's fresh, because the *mechanism* of the attack is more interesting than the "I leaked a key, oops" headline — and the platform design that allowed it is something every Google Cloud user should know about.

# What happened

* May 8, 2026, evening (CET): I get a billing alert email saying I owe NOK 82,305.36 (\~$7,500 USD) on my Google Cloud account.
* My typical monthly spend: \~100 NOK ($10).
* The spike happened in roughly 5 minutes.
* All charges were on the Gemini API in a single project I'd barely touched (an old "no-code maps" project from 2017).
* An API key from that project was leaked somewhere — I'm still hunting where. Most likely an old GitHub repo or a public webpage from 2018-ish that had Gemini API enabled on its project years later (I think this is what made it exploitable — the key sat dormant, but the moment Gemini got enabled on its project, the dormant key became a Gemini-capable wallet).

# What the attacker actually did (the part nobody talks about)

I pulled the SKU-level breakdown from Billing → Reports. The attacker didn't just hit one model. They ran an automated framework that fanned out across every Gemini variant simultaneously:

* Gemini 3 Pro (text + image generation)
* Gemini 3 Flash
* Gemini 3.1 Flash Image
* Gemini 3.1 Flash Lite Preview
* Gemini 2.5 Pro (text + TTS)
* Gemini 2.5 Flash (short + long context, multimodal)
* Gemini 2.5 Flash Lite
* Gemini 2.0 Flash TTS
* Gemini Embedding-2 + Embedding-001

15+ distinct models in 5 minutes. No human application uses 15 models in parallel. This is the signature of an automated abuse framework, almost certainly a credential-resale operation.

Token volumes:

* 1.09 BILLION input tokens on Gemini 2.5 Flash Lite alone
* 402M image input tokens on Gemini 3 Pro
* 226M text input tokens on Gemini 3 Pro
* 19.4M image output tokens on Gemini 3 Pro Image — kr 21,674 ($2,000) on this single SKU, the most expensive line item

The attacker prioritized image generation because that's where the real money is — image output tokens are 50–100x more expensive than text.

# How they bypassed rate limits (this is the architectural problem)

You'd think rate limits would protect you. They don't — at least not on Google Cloud:

* Gemini 3 Pro: 1,000 RPM
* Gemini 3 Flash: 2,000 RPM
* Gemini 2.5 Flash Lite: 4,000 RPM
* (etc., for every model — *each with its own independent quota*)

There is no per-key aggregate cap across models. If you fan out across 15 models concurrently, you cap at the *sum* — easily 30,000+ RPM combined.

OpenAI, Anthropic, and Mistral all have per-key aggregate caps. Google does not. This is not a policy oversight — it's the core mechanism that makes a single compromised key a 5-minute, 5-figure liability.

Also: Google Cloud does not offer a hard spending cap. No "stop all spend at $X" option. The closest is a budget alert that *emails you* (after the fact), or — and this is the documented "solution" — you can write your own Cloud Function that listens to budget Pub/Sub events and programmatically disables your billing account. Yes, Google's official answer to "how do I stop runaway spending" is "deploy code on the same platform that's billing you." This has been a known gripe for years.

# What logging gave me — almost nothing

I tried every audit log query:

* `protoPayload.serviceName="generativelanguage.googleapis.com"` → empty
* `resource.type="consumed_api"` for the project → empty
* Vertex AI logs → empty

Google does not log per-request data for Gemini API key calls. No caller IP, no user-agent, no request size. The only forensic record that exists is the SKU-level billing report — and that only goes down to "model + token type", not session/request/key.

So I can't tell you who did it, where they were, or what they generated. I just know it was 15 models in parallel and 19M image output tokens.

# What I did in the first 90 minutes

* Deleted all 13 API keys on the affected project (after seeing the alert at \~01:25)
* Disabled [`generativelanguage.googleapis.com`](http://generativelanguage.googleapis.com) and [`aiplatform.googleapis.com`](http://aiplatform.googleapis.com) on every one of my 25+ projects (script via `gcloud services disable`)
* Closed all 3 billing accounts
* Called my bank, blocked the Visa
* Got into Google's billing chat queue, escalated to specialist team within 5 messages
* Case 71021804 opened, 24-48h response window
* Pulled SKU-level forensic evidence

The chat agent confirmed end-of-month billing cycle, so the actual charge attempt won't fire until \~May 28-31. By then either the specialist team has waived it, or the card-block + chargeback dispute kicks in.

# What I'm pretty sure happens next

* \~85% chance: specialist team waives the charge under the compromised-credentials policy. Google has standardized this for exactly this scenario because they know the rate-limit architecture allows it.
* \~10% chance: partial waiver / settlement.
* \~5% chance: they refuse, my bank chargeback wins it under Norwegian Finansavtaleloven (450 NOK max liability for unauthorized card use).

I'm not actually going to pay 80k. The realistic worst case is several months of paperwork.

# Lessons / PSA for everyone running Google Cloud

1. Restrict every API key at creation time. Application restriction (HTTP referrer or IP allowlist) + API restriction (only the APIs you use). An unrestricted key on a project where Gemini happens to be enabled is a wallet.
2. Audit every project for keys you've forgotten about. I had keys from 2017, 2020, 2021 — most predating Gemini's existence. The moment Gemini got enabled on those old projects, the old keys could call it.
3. Disable APIs you don't actively use. Per-project. An enabled API + an unrestricted key = exposure.
4. Set up a budget-disables-billing Cloud Function. The auto-shutdown one. Yes it's stupid that Google makes you write code for this, but it's the only real circuit breaker.
5. Don't trust rate limits. They protect Google's infrastructure, not your wallet. Per-model RPM × N models = no real cap.
6. Don't store API keys in client-side code, ever. Even if you think a project is dead.

# Where the leak came from

Honestly, I don't know yet. The project was created in 2017 (back when Google appended a numeric suffix like `-364317` to project IDs). It had 13 keys accumulated over years. One of them is somewhere out in the wild. I'll be searching GitHub history, old Vercel deployments, Wayback Machine, and screenshots over the coming days. If I find it I'll edit this post.

If anyone has run into the same multi-model abuse pattern recently, I'd love to hear about it — particularly if you have any signals on which credential-resale operations are currently active.

Edit: Will update with specialist team's response when it arrives in 24-48h.

There are currently 481 models listed on the [arena.ai](http://arena.ai) website.

Here's the full list:

amazon.nova-pro-v1:0

anonymous-0410

anonymous-1111

anonymous-1218

anonymous-1221

anonymous-1800

anonymous-1815

anonymous-1825

anonymous-1835

apex-atlas

april26-chatbot1

april26-chatbot2

arastradero

atlas

autobear

badger

basalt-0303-1

basalt-0422-1

baseliner

beluga-0311-1

beluga-0413-1

blackhawk

blue-forge

botbot2

chatgpt-image-latest-high-fidelity (20251216)

chipmunk

chives

citrus

claude-3-5-sonnet-20241022

claude-3-7-sonnet-20250219

claude-3-7-sonnet-20250219-thinking-32k

claude-haiku-4-5-20251001

claude-opus-4-1-20250805

claude-opus-4-1-20250805-thinking-16k

claude-opus-4-1-search

claude-opus-4-20250514

claude-opus-4-20250514-thinking-16k

claude-opus-4-5-20251101

claude-opus-4-5-20251101-thinking-32k

claude-opus-4-5-search

claude-opus-4-6

claude-opus-4-6-search

claude-opus-4-6-thinking

claude-opus-4-7

claude-opus-4-7-search

claude-opus-4-7-thinking

claude-opus-4-search

claude-sonnet-4-20250514

claude-sonnet-4-20250514-thinking-32k

claude-sonnet-4-5-20250929

claude-sonnet-4-5-20250929-thinking-32k

claude-sonnet-4-5-search

claude-sonnet-4-6

claude-sonnet-4-6-search

clawl

clinkz

cloud-buddy

dall-e-3

dart-frog-0206

deep-octo

deepseek-v4-flash

deepseek-v4-flash-thinking

deepseek-v4-pro

deepseek-v4-pro-thinking

devstral-2

devstral-medium-2507

dialogue

dola-seed-2.0-preview-text

dola-seed-2.0-preview-vision

dola-seed-2.0-pro-text

dola-seed-2.0-pro-vision

dove

duomo-1-hero

EB45-turbo

EB45-vision

ember

emu

epilogue

ernie-5.0-0110

ernie-5.0-preview-1220

ernie-exp-251023

ernie-exp-251024

ernie-exp-251025

ernie-exp-251026

ernie-exp-251027

ernie-exp-vl-251016

ernie-image

eureka

february26-chatbot2

february26-chatbot3

february26-chatbot4

flashbrown-a

flashbrown-b

flow-state

flow-state-2

flow-state-3

flux-1-kontext-dev

flux-1-kontext-max

flux-1-kontext-pro

flux-2-dev

flux-2-flex

flux-2-klein-4b

flux-2-klein-9b

flux-2-max

flux-2-pro

flying-octopus

frenchfry

frieza

gallant

gallery

gcps-fast

gemini-2.0-flash-001

gemini-2.5-flash

gemini-2.5-flash-image-preview (nano-banana)

gemini-2.5-pro

gemini-2.5-pro-grounding

gemini-2.5-pro-grounding-exp

gemini-3-flash

gemini-3-flash (thinking-minimal)

gemini-3-flash-grounding

gemini-3-pro

gemini-3-pro-image-preview-2k (nano-banana-pro)

gemini-3.1-flash-image-preview (nano-banana-2) \[web-search\]

gemini-3.1-flash-lite-preview

gemini-3.1-pro

gemini-3.1-pro-grounding

gemini-3.1-pro-preview

gemma-3-27b-it

gemma-3n-e4b-it

glm-4.7

glm-4.7-flash

glm-5

glm-5.1

glm-5v-turbo

globe\_2

gpt-4.1-2025-04-14

gpt-4.1-mini-2025-04-14

gpt-5-chat

gpt-5-high

gpt-5-high-new-system-prompt

gpt-5-high-no-system-prompt

gpt-5-medium

gpt-5-mini-high

gpt-5-nano-high

gpt-5-search

gpt-5.1

gpt-5.1-codex

gpt-5.1-codex-max

gpt-5.1-codex-mini

gpt-5.1-high

gpt-5.1-medium

gpt-5.1-search

gpt-5.1-search-sp

gpt-5.2

gpt-5.2-chat-latest

gpt-5.2-codex

gpt-5.2-high

gpt-5.2-search

gpt-5.2-search-non-reasoning

gpt-5.3-chat-latest

gpt-5.3-codex

gpt-5.4

gpt-5.4-high

gpt-5.4-high-no-system-prompt

gpt-5.4-medium

gpt-5.4-mini-high

gpt-5.4-nano-high

gpt-5.4-no-system-prompt

gpt-5.4-search

gpt-5.5

gpt-5.5-high

gpt-5.5-search

gpt-image-1

gpt-image-1-high-fidelity

gpt-image-1-mini

gpt-image-1.5-high-fidelity

gpt-image-2 (medium)

gpt-oss-120b

gpt-oss-20b

grok-3-mini-beta

grok-3-mini-high

grok-4-0709

grok-4-1-fast-non-reasoning

grok-4-1-fast-reasoning

grok-4-1-fast-search

grok-4-fast-chat

grok-4-fast-reasoning

grok-4-fast-search

grok-4-search

grok-4.1

grok-4.1-thinking

grok-4.20-beta-0309-reasoning

grok-4.20-beta1

grok-4.20-multi-agent-beta-0309

grok-code-fast-1

grok-imagine-image

grok-imagine-image-pro

grok-imagine-video

hailuo-02-fast

hailuo-02-pro

hailuo-02-standard

hailuo-2.3

hailuo-2.3-fast

happy-friday-testing-1

happy-friday-testing-2

hearth

hidream-e1.1

hofburg\_2

hofburg\_2\_alt

hofburg\_3

hofburg\_4

hofburg\_5

hofburg\_5\_alt

hofburg-1

hunyuan-hy3-preview

hunyuan-image-2.1

hunyuan-image-3.0

hunyuan-image-3.0-fal

hunyuan-t1-20250711

hunyuan-video-1.5

hunyuan-vision-1.5-thinking

ibm-granite-h-small

ideogram-v3-quality

imagen-3.0-generate-002

imagen-4.0-fast-generate-001

imagen-4.0-generate-001

imagen-4.0-ultra-generate-001

intellect-3

jester

jumbo-dungeness

juniper

k2

kandinsky-5.0-i2v-pro

kandinsky-5.0-t2v-lite

kandinsky-5.0-t2v-pro

karyu

KAT-Coder-Pro-V1

ketchup-v2

kimi-k2-0711-preview

kimi-k2-0905-preview

kimi-k2-thinking-turbo

kimi-k2.5

kimi-k2.5-instant

kimi-k2.6

kiteki

kiwi-do

kiwire

kizen-alpha

kizen-beta

kling-2.5-turbo-1080p

kling-2.6-pro

kling-2.6-standard

kling-image-o1

kling-o1-pro

kling-o3-pro

kling-v2.1-master

kling-v2.1-standard

kling-v3

leepwal

left-bank

ling-1t

ling-1t-1031

ling-2.5-1t

ling-flash-2.0

llama-3.3-70b-instruct

longcat-flash-chat

ltx-2-19b

lucid-origin

mammoth-newt-0206

mammoth-newt-0226

march26-chatbot1

march26-chatbot1-public

march26-chatbot2

march26-chatbot3

markhor

Max

mercury

mercury-2

micro-mango

mimo-v2-flash

mimo-v2-flash (thinking)

mimo-v2-omni

mimo-v2-pro

mimo-v2.5

mimo-v2.5-pro

minicpm-sala

minimax-m1

minimax-m2

minimax-m2-preview

minimax-m2.1-preview

minimax-m2.5

mistral-large-3

mistral-medium-2505

mistral-medium-2508

mistral-small-2506

mistral-small-2603

mistral-small-3.1-24b-instruct-2503

mochi-v1

model-x

model-x-2

molmo-2-8b

monologue

monster

monterey

neon

nightride-on

nightride-on-v2

nova-2-lite

nvidia-nemotron-3-nano-30b-a3b-bf16

o3-2025-04-16

o3-mini

o3-search

o4-mini-2025-04-16

olmo-3-32b-think

olmo-3.1-32b-instruct

olmo-3.1-32b-think

orion

p-image

p-image-edit

paper-lantern

pebble-1

pebble-2

pepper

photon

pika-v2.2

pine

pisces-0226d

pisces-0309

pisces-0309-vision

pisces-0309b

pisces-0309c

pisces-0309d

pisces-0318-text

pisces-0318-vision

pisces-0320

pisces-llm-0130

pixel-parrot

pixverse-v5.6

ppl-sonar-reasoning-pro-high

prologue

pteronura

pulse

queen-bee

quiet\_sand

qwen-image-2.0

qwen-image-2.0-pro

qwen-image-2512

qwen-image-edit

qwen-image-edit-2511

qwen-image-prompt-extend

qwen-vl-max-2025-08-13

qwen3-235b-a22b

qwen3-235b-a22b-instruct-2507

qwen3-235b-a22b-no-thinking

qwen3-235b-a22b-thinking-2507

qwen3-30b-a3b

qwen3-30b-a3b-instruct-2507

qwen3-coder-480b-a35b-instruct

qwen3-max-2025-09-23

qwen3-max-2025-09-26

qwen3-max-2025-10-30

qwen3-max-preview

qwen3-max-thinking

qwen3-next-80b-a3b-instruct

qwen3-next-80b-a3b-thinking

qwen3-omni-flash

qwen3-vl-235b-a22b-instruct

qwen3-vl-235b-a22b-thinking

qwen3-vl-8b-instruct

qwen3-vl-8b-thinking

qwen3.5-122b-a10b

qwen3.5-122b-a10b-code

qwen3.5-27b

qwen3.5-27b-code

qwen3.5-35b-a3b

qwen3.5-35b-a3b-code

qwen3.5-397b-a17b

qwen3.5-flash

qwen3.6-plus

qwen3.6-plus-preview

qwq-32b

raptor-1.8-0120

raptor-1123

raptor-1124

ray-3

ray2

recraft-v3

recraft-v4

redwood

reve-v1.1

reve-v1.1-fast

ring-1t

ring-2.5-1t

ring-flash-2.0

rising-sun

robin

robin-high

rotten-apple

runway-gen-4.5

runway-gen4

runway-gen4-aleph

runway-gen4-turbo

scorch

seed-1.8

seedance-v1-lite

seedance-v1-pro

seedance-v1.5-pro

seededit-3.0

seedream-3

seedream-4-high-res-fal

seedream-4.5

seedream-5.0-lite

shakshouka

significant-otter

snowflake

soft-shell

solar-eclipse

sora

sora-2

sora-2-pro

spark

sphinx

spire

star-drift

steed-0217

step-3

step-3-mini-2511

step-3.5-flash

stephen-v2

stephen-vision-csfix

sungod

sunshine-ai

super-cara

super-gcp

tatertot

trinity-large

trinity-large-thinking

velo

veo-2

veo-3

veo-3-audio

veo-3-fast

veo-3-fast-audio

veo-3.1-audio

veo-3.1-audio-1080p

veo-3.1-audio-4k

veo-3.1-fast-audio

veo-3.1-fast-audio-1080p

veo-3.1-fast-audio-4k

vidu-q2-image

vierra

viper

vortex

vulcan

waffle

wan-v2.2-a14b

wan-vace

wan2.5-i2i-preview

wan2.5-i2v-preview

wan2.5-preview

wan2.5-t2i-preview

wan2.5-t2v-preview

wan2.6-i2v

wan2.6-image

wan2.6-t2i

wan2.6-t2v

wan2.7-i2v

wan2.7-image

wan2.7-image-pro

wan2.7-t2v

whisperfall

wild-bits

yivon-beta

yotta-nexus

z-image

zephyr

zero-prism

zeylu-alpha

zeylu-beta

zorik

Unfortunately, the list of models available for selection in direct and side-by-side mode is much smaller :(

Updated

models/gemini-2.5-flash

models/gemini-2.5-pro

models/gemini-2.0-flash

models/gemini-2.0-flash-001

models/gemini-2.0-flash-lite-001

models/gemini-2.0-flash-lite

models/gemini-2.5-flash-preview-tts

models/gemini-2.5-pro-preview-tts

models/gemma-3-1b-it

models/gemma-3-4b-it

models/gemma-3-12b-it

models/gemma-3-27b-it

models/gemma-3n-e4b-it

models/gemma-3n-e2b-it

models/gemma-4-26b-a4b-it

models/gemma-4-31b-it

models/gemini-flash-latest

models/gemini-flash-lite-latest

models/gemini-pro-latest

models/gemini-2.5-flash-lite

models/gemini-2.5-flash-image

models/gemini-3-pro-preview

models/gemini-3-flash-preview

models/gemini-3.1-pro-preview

models/gemini-3.1-pro-preview-customtools

models/gemini-3.1-flash-lite-preview

models/gemini-3-pro-image-preview

models/nano-banana-pro-preview

models/gemini-3.1-flash-image-preview

models/lyria-3-clip-preview

models/lyria-3-pro-preview

models/gemini-robotics-er-1.5-preview

models/gemini-2.5-computer-use-preview-10-2025

models/deep-research-pro-preview-12-2025

models/gemini-embedding-001

models/gemini-embedding-2-preview

models/aqa

models/imagen-4.0-generate-001

models/imagen-4.0-ultra-generate-001

models/imagen-4.0-fast-generate-001

models/veo-2.0-generate-001

models/veo-3.0-generate-001

models/veo-3.0-fast-generate-001

models/veo-3.1-generate-preview

models/veo-3.1-fast-generate-preview

models/veo-3.1-lite-generate-preview

models/gemini-2.5-flash-native-audio-latest

models/gemini-2.5-flash-native-audio-preview-09-2025

models/gemini-2.5-flash-native-audio-preview-12-2025

models/gemini-3.1-flash-live-preview

models/lyria-realtime-exp

# Reddit Post for r/CXAgentStudio

---

## Title:
**🏗️ The Complete Guide to CX Agent Studio Architecture — Multi-Agent Design Patterns, Tools, Callbacks & Everything You Need to Know**

---

## Post Body:

Hey r/CXAgentStudio 👋

I've been building production conversational AI agents on Google Cloud for 4+ years (started with Dialogflow CX flows/pages/intents era), and now that CX Agent Studio has landed as the evolution of DFCX — I wanted to share a comprehensive deep-dive on how it actually works under the hood and how to architect agents the right way.

If you're migrating from Dialogflow CX, or building your first agent application from scratch, this should save you weeks of trial and error.

---

### 🧠 What is CX Agent Studio, Really?

CX Agent Studio is **NOT** just Dialogflow CX with a new coat of paint. It's a fundamentally different architecture:

- **Built on ADK (Agent Development Kit)** — Google's open-source multi-agent framework
- **LLM-native** — No more intent classification + training phrases. The model *understands* instructions directly
- **Multi-agent by design** — Root agent → sub-agents hierarchy is the core pattern
- **Gemini-powered** — Uses Gemini models for reasoning, routing, and generation
- **XML-structured instructions** — Agents follow structured instruction templates, not fulfillment webhooks

Think of it as: **ADK for enterprises**, with a visual builder, enterprise integrations (Salesforce, ServiceNow, SAP), built-in evaluation, and production infrastructure out of the box.

---

### 🏛️ Core Concepts — The Agent Hierarchy

Every CX Agent Studio application follows this structure:

```
Agent Application (top-level container)
├── Root Agent (Steering Agent) — orchestrator, routes to sub-agents
│ ├── Sub-Agent A — handles domain A
│ │ └── Tools: tool_1, tool_2
│ ├── Sub-Agent B — handles domain B
│ │ └── Tools: tool_3, tool_4
│ ├── Sub-Agent C — handles domain C
│ │ └── Tools: data_store_search
│ └── Farewell Agent — always include this
│ └── Tools: end_session
└── Global Instructions — brand voice, persona across all agents
```

**Key mental model:**
- The **Root Agent** is the traffic cop. It greets users, classifies intent, and delegates using `{@AGENT: agent_name}`
- **Sub-Agents** are specialists. Each handles ONE domain and has its own tools, instructions, and callbacks
- **Tools** are the hands. Python code tools, OpenAPI specs, data stores, MCP servers — they do the actual work
- **Variables** are the memory. Session data flows through `{variable_name}` references, not LLM recall

---

### 🔧 4 Architecture Patterns You'll Use 90% of the Time

#### Pattern 1: Flat Router (Most Common)
Best for 3-5 distinct domains with no cross-dependencies.

```
Root (Router)
├── order_tracking_agent
├── returns_agent
├── faq_agent
└── farewell_agent
```

Simple, clean, easy to maintain. Start here.

#### Pattern 2: Tiered Delegation
When domains have sub-domains.

```
Root (Router)
├── sales_agent
│ ├── product_inquiry_agent
│ └── pricing_agent
├── support_agent
│ ├── technical_support_agent
│ └── billing_support_agent
└── farewell_agent
```

The root routes to domain agents, which further delegate to specialists.

#### Pattern 3: Sequential Pipeline
For mandatory step-by-step processes (auth → verify → action → confirm).

```
Root (Pipeline Orchestrator)
├── authentication_agent
├── verification_agent
├── action_agent
└── confirmation_agent
```

Root tracks progress using variables and advances through agents sequentially.

#### Pattern 4: Hub-and-Spoke with Shared Services
Enterprise pattern where multiple agents share common tools (CRM, auth).

```
Root (Hub)
├── Agent A (shared CRM tool + own tools)
├── Agent B (shared CRM tool + own tools)
├── Agent C (shared auth tool + own tools)
└── Application-level shared tools (accessible by ALL agents)
```

Tools defined at the **application level** are automatically available to every agent.

---

### 📝 How Instructions Work — The XML Structure

This is where CX Agent Studio really shines. Instead of intent-matching, you write **structured instructions** in XML:

```xml
<role>You are the Order Tracking Agent for Acme Corp.
Your ONLY job is to help customers track their orders.</role>

<persona>
<primary_goal>Retrieve and present order status accurately.</primary_goal>
Be professional, friendly, and concise.
Never guess order status — always use the tool.
</persona>

<constraints>
1. Always ask for {order_number} if not already known.
2. Use {@TOOL: get_order_status} with the order number.
3. Present results with estimated delivery date.
4. If the tool returns an error, apologize and offer alternatives.
5. Never fabricate tracking information.
</constraints>

<taskflow>
<subtask name="Track Order">
<step name="Collect Order Number">
<trigger>User asks about order status</trigger>
<action>If {order_number} is empty, ask the user for it.</action>
</step>
<step name="Fetch Status">
<trigger>Order number is available</trigger>
<action>Call {@TOOL: get_order_status}(order_number={order_number})</action>
</step>
<step name="Present Results">
<trigger>Tool returns successfully</trigger>
<response_template>
Your order {order_number} is currently **{order_status}**.
Estimated delivery: {estimated_delivery}.
</response_template>
</step>
</subtask>
</taskflow>
```

**Pro tips on instructions:**
- Always write in **English** even for multilingual agents (the platform handles language switching)
- Use `{@AGENT: name}` to delegate to sub-agents
- Use `{@TOOL: name}` to invoke tools
- Use `{variable_name}` to reference session variables
- The AI Augmentation feature can **restructure** your hand-written instructions into XML format automatically

---

### 🛠️ Tools — Your Agent's Hands

CX Agent Studio supports a rich tool ecosystem:

| Tool Type | When to Use | Example |
|---|---|---|
| **Python Code** | Inline logic, mocks, data transforms | Order lookup, calculations |
| **OpenAPI** | REST API integrations | CRM queries, payment APIs |
| **Data Store** | RAG/knowledge base | FAQ search, policy docs |
| **MCP** | Model Context Protocol servers | External service integration |
| **Salesforce** | CRM operations | Case creation, account lookup |
| **ServiceNow** | ITSM operations | Incident creation, KB search |
| **System** | Platform built-ins | `end_session` |
| **Client Function** | Client-side execution | UI actions, navigation |

**Golden rule:** Start with Python code tools with **mocked data** for prototyping. Once the conversation flow is solid, swap to real OpenAPI/connector tools.

Example Python Code Tool:

```python
def get_order_status(order_number: str) -> dict:
"""Retrieves the current status of an order.

Args:
order_number (str): The order number to look up.

Returns:
dict: Order status with delivery estimate.
"""
# Mocked — swap with real API call later
mock_orders = {
"ORD-001": {
"status": "success",
"order_status": "SHIPPED",
"estimated_delivery": "2026-03-20",
"tracking_number": "1Z999AA10123456784"
}
}

if order_number in mock_orders:
return mock_orders[order_number]

return {
"status": "error",
"error_message": f"Order {order_number} not found."
}
```

Always return `dict` with a `status` field. Always include docstrings (they become the tool description in the UI).

---

### 🔄 Callbacks — The Secret Weapon

Callbacks are Python functions that run at specific points in the conversation turn. This is where you implement **guardrails, logging, state management, and tool chaining**.

There are **6 callback types**:

| Callback | When It Fires | Use Case |
|---|---|---|
| `before_agent_callback` | Before agent starts processing | Context injection, variable setup |
| `after_agent_callback` | After agent finishes | Logging, counter tracking |
| `before_model_callback` | Before LLM call | Input validation, content filtering |
| `after_model_callback` | After LLM response | Response formatting, PII redaction |
| `before_tool_callback` | Before tool execution | Arg validation, caching, mocking |
| `after_tool_callback` | After tool returns | Response transformation, chaining |

**Key insight:** Return `None` from a callback = let normal execution proceed. Return a **value** = override/skip the default behavior.

Example — content filtering with `before_model_callback`:

```python
def before_model_callback(callback_context, llm_request):
"""Block prohibited topics before they reach the LLM."""
user_input = str(llm_request).lower()
banned_topics = ["competitor pricing", "internal salary"]

for topic in banned_topics:
if topic in user_input:
# Return content to SKIP the LLM call entirely
return LlmResponse(
text="I'm sorry, I'm not able to help with that topic. "
"Let me connect you with a team member."
)

# Return None = proceed normally
return None
```

Example — tracking agent invocations with `after_agent_callback`:

```python
def after_agent_callback(callback_context):
"""Count how many times this agent has been invoked."""
counter = callback_context.variables.get("counter", 0)
counter += 1
callback_context.variables["counter"] = int(counter)
return None # Let normal response through
```

---

### 📊 Real-World Architecture: E-Commerce Customer Service

Here's a production-ready architecture I've built:

```
Agent Application: ecommerce_support
│
├── Global Instructions: "You are a helpful assistant for ShopMart..."
│
├── Root Agent: customer_service_router (Gemini 2.0 Flash)
│ ├── Variables: customer_name, session_id, authenticated
│ ├── Callbacks: before_agent (inject customer context)
│ └── Instructions: Greet → Classify intent → Route
│
├── Sub-Agent: order_tracking_agent
│ ├── Tools: get_order_status (OpenAPI), get_shipping_info (OpenAPI)
│ ├── Variables: order_number, tracking_number
│ └── Callbacks: after_tool (format shipping dates)
│
├── Sub-Agent: returns_agent
│ ├── Tools: initiate_return (Python), get_return_policy (Data Store)
│ ├── Variables: return_reason, order_number
│ └── Callbacks: before_tool (validate return eligibility)
│
├── Sub-Agent: product_recommendation_agent
│ ├── Tools: search_products (OpenAPI), get_product_details (OpenAPI)
│ └── Variables: search_query, budget_range
│
├── Sub-Agent: faq_agent
│ ├── Tools: search_knowledge_base (Data Store)
│ └── Callbacks: after_model (add disclaimer for policy questions)
│
└── Sub-Agent: farewell_agent
├── Tools: end_session (System)
└── Instructions: Summarize conversation → Thank user → End
```

---

### ⚡ CX Agent Studio vs. Dialogflow CX — Migration Cheat Sheet

For those of us coming from the DFCX world:

| Dialogflow CX | CX Agent Studio |
|---|---|
| Flows + Pages + Intents | Agents + Sub-Agents + Instructions |
| State handlers | Callbacks (Python) |
| Webhooks (Cloud Functions) | Tools (Python, OpenAPI, MCP, etc.) |
| Playbooks | Agents with XML instructions |
| Session parameters | Variables + `callback_context.variables` |
| NLU intent detection | LLM-based understanding |
| Route groups | Agent routing via `{@AGENT: name}` |
| Training phrases | Instructions (no training needed) |

**Migration strategy:**
1. Each major **flow** → becomes a **sub-agent**
2. **Intents** → become routing logic in root agent instructions
3. **Webhooks** → become tools (OpenAPI or Python code)
4. **Session parameters** → become variables
5. **Page fulfillment** → becomes agent instructions + callbacks
6. **Complex deterministic flows** → keep as flow-based agents (CX Agent Studio supports importing existing DFCX flows!)

---

### 💡 10 Things I Wish I Knew Earlier

1. **One tool per turn** — Don't instruct agents to call multiple tools. Chain via `after_tool_callback`
2. **Variables over LLM memory** — Store everything in session variables. The model WILL forget
3. **Always include a farewell agent** — With `end_session` tool. Clean session termination matters
4. **Mock first, integrate later** — Python tools with fake data → validate flow → swap to real APIs
5. **Global instructions = brand voice** — Put persona/tone at the application level, domain logic in sub-agents
6. **Agent descriptions matter** — Other agents use the description to decide when to route. Be specific
7. **Use the AI Augmentation features** — "Restructure instructions" and "Refine instructions" save hours
8. **Test with the evaluator** — Golden tests and scenario-based tests catch regressions before deployment
9. **Voice ≠ Chat** — Voice agents need shorter responses, ambient sounds, and interrupt handling. Configure separately
10. **Callbacks are your guardrails** — Content filtering, PII redaction, compliance logging — all belong in callbacks, not instructions

---

### 🚀 What's Next

CX Agent Studio already supports:
- **A2A (Agent-to-Agent protocol)** — Bring your own external agents
- **UCP (Universal Commerce Protocol)** — Cart management, inventory, ordering
- **MCP (Model Context Protocol)** — Connect to any MCP server
- **40+ languages** with automatic language switching
- **Multimodal** — Text, voice, images (plant identification demo is in the sample app!)
- **Ultra-low latency voice** with bi-directional streaming

I'm working on a full tutorial series covering each of these topics in depth. Happy to answer questions in the comments!

---

**TL;DR:** CX Agent Studio is Google Cloud's next-gen platform for building AI agents. It replaces DFCX's intent-based approach with LLM-native multi-agent orchestration. Think: root agent routes → sub-agents handle domains → tools do work → callbacks add guardrails. Start with mocked Python tools, validate conversation flows, then swap to real integrations.

---

*Building on CX Agent Studio? Share your architecture in the comments — I'd love to see what patterns others are using!* 🙌