Pier Paolo Ippolito

Building AI Agents in 30 Minutes from Prototype to Production

Sat, 02 May 2026 00:00:00 +0000

Agents CLI in Agent Platform (Image by Author).

:memo: Please Note
This is a guest post originally published on Google Cloud - Community.

Building AI Agents in 30 Minutes from Prototype to Production

Building, evaluating and deploying production-ready AI agents using Agents CLI in Agent Platform

Introduction

If you’ve tried deploying an AI agent recently, you’ve probably run into the same problem. Your agent works perfectly in development: it answers questions, calls the right tools, makes sensible decisions. Then someone asks “when can we deploy this?” and suddenly you’re spending days configuring Docker, setting up authentication, implementing observability, and writing deployment pipelines.

The agent code itself? That took a few hours. The infrastructure around it? That’s taking weeks.

In this article, we are going to explore how to build and deploy a production-ready AI agent from scratch using Agents CLI: an open-source toolkit that handles all the deployment complexity. We’ll build a complete expense approval agent with business logic, evaluations, and cloud deployment in approximately 30 minutes.

The Agent Deployment Problem

Building an AI agent with the Agent Development Kit (ADK), LangChain, or LlamaIndex is straightforward. Getting that agent into production? That’s where the complexity lives.

Here’s what you typically need for a production agent:

Local Development:

Agent code (the interesting part)
Local testing environment
Mock data or API stubs

Testing & Evaluation:

Test case definitions
Evaluation metrics and rubrics
LLM-as-judge configuration
Regression test suite

Production Infrastructure:

Container image (Docker)
Cloud deployment config (Cloud Run/Kubernetes)
Authentication and authorization
Secret management
CI/CD pipeline

Observability:

Request tracing
Prompt/response logging
Cost tracking and analytics
Performance monitoring
Error alerting

Each piece requires learning new tools, reading documentation, and connecting disparate systems. Your coding assistant can help with agent logic, but struggles with deployment context: it doesn’t know your infrastructure patterns, leading to multiple debugging iterations.

What is Agents CLI?

Agents CLI in Agent Platform is a toolkit providing a unified interface to the full agent development lifecycle on Google Cloud.

It operates in two modes:

Agent Mode: Install “skills” into your coding assistant (Gemini CLI, Claude Code, Cursor). These skills teach your assistant the deployment patterns so it makes correct decisions.
Manual Mode: Run CLI commands directly. Every command works standalone: no AI assistant required.

The core innovation: instead of your AI assistant guessing at deployment patterns, it has direct access to machine-readable context about when to use different deployment targets, how to structure evaluations, and which observability patterns work best.

Building an Expense Approval Agent

We’ll build an agent that reviews employee expense reports and makes approval decisions based on company policy. The agent will use Gemini models through Vertex AI for its reasoning capabilities.

Requirements:

Auto-approve routine expenses under $50
Detect duplicate submissions
Flag suspicious patterns (weekend charges, unusual vendors)
Escalate uncertain cases to human reviewers
Hard safety constraint: never auto-approve anything over $50

Prerequisites

Before we start, make sure you have:

# Required tools
Python 3.11+
uv package manager
Node.js (for skills installation)
Google Cloud SDK (gcloud)

You’ll also need a Google Cloud project with billing enabled. If you don’t have one yet, you can create it at https://console.cloud.google.com/

Installation:

uvx google-agents-cli setup

Authentication:

Authenticate with Google Cloud and set your project:

# Authenticate with Google Cloud
gcloud auth application-default login
# Set your project ID
gcloud config set project YOUR_PROJECT_ID
# Enable required APIs
gcloud services enable aiplatform.googleapis.com
gcloud services enable run.googleapis.com
gcloud services enable artifactregistry.googleapis.com

This configures Vertex AI access for your agent, which will use Gemini models through the Vertex AI API.

Step 1: Project Scaffolding

Instead of manually creating directories and configuration files, we’ll use Agents CLI to scaffold the complete project structure.

With a coding assistant (Gemini CLI, Claude, Cursor):

Build an expense approval agent using agents-cli. 
Auto-approve under $50, flag duplicates, escalate suspicious cases. 
Start with a prototype.

Your assistant reads the installed skills and generates the project with the correct structure.

Manual approach:

agents-cli create expense-agent --prototype --yes
cd expense-agent
agents-cli install

The --prototype flag is important: it generates just the agent code and test structure, skipping deployment infrastructure (Docker, Terraform, CI/CD). We’ll add that later.

Generated structure:

expense-agent/
├── app/
│   ├── agent.py          # Agent definition
│   └── app_utils/        # Telemetry helpers
├── tests/
│   ├── eval/
│   │   ├── evalsets/     # Test cases for LLM-as-judge
│   │   └── eval_config.json
│   ├── integration/
│   └── unit/
├── pyproject.toml        # Dependencies managed by uv
└── GEMINI.md             # Guidance for coding agents

Step 2: Implementing Business Logic

Now we’ll implement the actual expense approval logic. Open app/agent.py.

In ADK (and most agent frameworks), tools are plain Python functions. The docstring is critical, the LLM reads it to determine when and how to call each tool.

Tool 1: Check Expense History

import json
from adk.models import Gemini
from adk.agents import Agent
def check_expense_history(
    employee_id: str,
    vendor: str,
    date: str,
    amount: float
) -> str:
    """Check if this expense was already submitted.
    Args:
        employee_id: Employee identifier
        vendor: Vendor name
        date: Expense date (YYYY-MM-DD)
        amount: Expense amount in USD
    Returns:
        JSON string with duplicate check results
    """
    # In production, this would query your expense database
    # Using mock data for demonstration
    mock_history = [        {"date": "2026-04-15", "vendor": "Coffee Shop", "amount": 8.50},
        {"date": "2026-04-15", "vendor": "Uber", "amount": 24.00},
    ]
    for past in mock_history:
        if (past["vendor"].lower() == vendor.lower() and 
            past["date"] == date and 
            abs(past["amount"] - amount) < 0.01):
            return json.dumps({
                "is_duplicate": True,
                "message": f"Duplicate found: ${amount} at {vendor} on {date}"
            })
    return json.dumps({
        "is_duplicate": False,
        "message": "No duplicate found"
    })

Tool 2: Get Company Policy

def get_company_policy(category: str) -> str:
    """Retrieve expense policy for a given category.Args:
        category: Expense category (meals, transport, lodging, etc.)
    Returns:
        JSON string with policy rules
    """
    policies = {
        "meals": {"auto_approve_threshold": 50.00},
        "transport": {"auto_approve_threshold": 50.00},
        "lodging": {"auto_approve_threshold": 0.00},  # Always escalate
        "default": {"auto_approve_threshold": 25.00}
    }
    policy = policies.get(category.lower(), policies["default"])
    return json.dumps(policy)

Tool 3: Escalate to Human

def escalate_to_human(
    expense_id: str, 
    reason: str, 
    context: str
) -> str:
    """Route expense to human approval queue.Args:
        expense_id: Unique expense identifier
        reason: Why this needs human review
        context: Additional context for reviewer
    Returns:
        Confirmation message
    """
    # In production, this creates a ticket or notification
    print(f"\n🚨 ESCALATED: {expense_id}")
    print(f"Reason: {reason}\n")
    return json.dumps({
        "status": "escalated",
        "ticket_id": f"REVIEW-{expense_id}"
    })

Agent Definition:

Now we wire these tools together into an agent with clear instructions and safety constraints:

root_agent = Agent(
    name="expense_approval_agent",
    model=Gemini(model="gemini-3.1-pro-preview"),  # Using Vertex AI
    instruction="""You are an expense approval agent. Review expenses and make 
    approval decisions based on company policy.
    Process for every expense:
    1. Call get_company_policy() to check the category threshold
    2. Call check_expense_history() to verify no duplicate exists
    3. Make a decision: AUTO_APPROVE, ESCALATE, or REJECT
    Auto-approve only if ALL of these conditions are true:
    - Amount is under the threshold for that category
    - No duplicate found in expense history
    - Expense is from a business day (Monday-Friday)
    - Vendor appears legitimate
    Escalate to human if ANY of these conditions are true:
    - Amount is over the category threshold
    - Duplicate submission detected
    - Weekend expense without clear business justification
    - Uncertain about vendor legitimacy
    - Category is "lodging" (always requires human review)
    Safety rules (NEVER violate these):
    - NEVER auto-approve any expense over $50
    - NEVER approve without checking for duplicates first
    - ALWAYS provide clear reasoning for your decision
    - When in doubt, ESCALATE (false escalation is better than false approval)
    Response format:
    Decision: [AUTO_APPROVE | ESCALATE | REJECT]
    Reasoning: [Clear explanation of why you made this decision]
    Tools called: [Which tools you used]
    """,
    tools=[check_expense_history, get_company_policy, escalate_to_human],
)

Notice the safety constraints in the instruction. Even if the policy permits approving up to $50 for meals, we enforce a hard limit, the agent will never auto-approve over $50 without human review. This prevents expensive mistakes.

Step 3: Local Testing

Start the ADK playground:

agents-cli playground

This launches the web interface at http://localhost:8080.

Test Case 1: Routine approval

Review this expense:
Employee: emp-123
Category: meals
Vendor: Coffee Shop
Date: 2026-04-18
Amount: $12.50

Expected behavior: Agent calls get_company_policy() (threshold is $50), calls check_expense_history() (no duplicate), and auto-approves.

Test Case 2: Over threshold

Review this expense:
Employee: emp-456
Category: meals  
Vendor: Restaurant
Date: 2026-04-18
Amount: $85.00

Expected behavior: Agent escalates because amount exceeds $50.

Test Case 3: Duplicate detection

Review this expense:
Employee: emp-789
Category: transport
Vendor: Uber
Date: 2026-04-15
Amount: $24.00

Expected behavior: Agent finds duplicate in mock history and escalates.

Manual testing covers the happy path, but we need systematic validation for production readiness.

Step 4: Writing Structured Evaluations

This is the part most developers skip, and it’s why agents break in production.

You need structured test cases with clear pass/fail criteria. Not “does this feel right?” but “does this meet policy requirements?”

Edit tests/eval/evalsets/basic.evalset.json:

{
  "eval_set_id": "expense_approval_eval",
  "name": "Expense Policy Validation",
  "eval_cases": [    {
      "eval_id": "routine_approval",
      "conversation": [        {
          "user_content": {
            "parts": [{
              "text": "Review: emp-101, meals, Coffee Shop, 2026-04-18, $15.00"
            }]
          }
        }
      ],
      "session_input": {
        "app_name": "app",
        "user_id": "eval_user",
        "state": {}
      },
      "expected_tool_calls": ["get_company_policy", "check_expense_history"],
      "expected_output_keywords": ["approve", "approved"]
    },
    {
      "eval_id": "escalate_over_threshold",
      "conversation": [        {
          "user_content": {
            "parts": [{
              "text": "Review: emp-102, meals, Restaurant, 2026-04-18, $85.00"
            }]
          }
        }
      ],
      "session_input": {
        "app_name": "app",
        "user_id": "eval_user",
        "state": {}
      },
      "expected_tool_calls": ["get_company_policy", "escalate_to_human"],
      "expected_output_keywords": ["escalate", "human review"]
    },
    {
      "eval_id": "reject_duplicate",
      "conversation": [        {
          "user_content": {
            "parts": [{
              "text": "Review: emp-103, transport, Uber, 2026-04-15, $24.00"
            }]
          }
        }
      ],
      "session_input": {
        "app_name": "app",
        "user_id": "eval_user",
        "state": {}
      },
      "expected_tool_calls": ["check_expense_history"],
      "expected_output_keywords": ["duplicate", "escalate"]
    }
  ]
}

Run the evaluation:

agents-cli eval run

Output:

Running expense_approval_eval...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ routine_approval       policy_compliance: 1.0  safety: 1.0  tool_usage: 1.0
✓ escalate_over_threshold   policy_compliance: 1.0  safety: 1.0  tool_usage: 1.0
✓ reject_duplicate       policy_compliance: 0.9  safety: 1.0  tool_usage: 0.9
Overall Pass Rate: 100% (3/3 cases)
Average Scores: policy_compliance=0.97, safety=1.0, tool_usage=0.97

The eval system uses LLM-as-judge to score responses against rubrics defined in eval_config.json. If any case fails, you iterate on the agent instruction or tool logic until all cases pass.

This is the eval-fix loop, the key to building reliable production agents. Without evals, you’re hoping your agent works. With evals, you know it works.

Step 5: Deploying to Production

Our agent works and passes all evaluations. Time to deploy.

Add deployment infrastructure:

agents-cli scaffold enhance --deployment-target cloud_run

This generates:

Dockerfile
Cloud Run deployment configuration
Terraform infrastructure files

Configure your project and deploy:

gcloud config set project YOUR_PROJECT_ID
agents-cli deploy

Deployment output:

Building container image...
Pushing to us-central1-docker.pkg.dev/your-project/agents/expense-agent...
Deploying to Cloud Run...
✓ Deployment successful!
Service URL: https://expense-agent-xyz123-uc.a.run.app
Logs: https://console.cloud.google.com/run/detail/.../logs

Total time from **agents-cli create** to deployed service: approximately 30 minutes.

Step 6: Observability

Cloud Trace is automatically enabled, no configuration required.

Test the deployed agent:

agents-cli run "Review expense: emp-501, transport, Uber, 2026-04-18, $15.00"
agents-cli run "Review expense: emp-502, meals, Restaurant, 2026-04-18, $95.00"
agents-cli run "Review expense: emp-503, lodging, Hilton, 2026-04-18, $200.00"

Open Cloud Trace to see:

Full request traces with latency breakdown
Individual LLM call durations
Tool execution times
End-to-end request timeline

Set up content logging for debugging and analysis:

agents-cli infra single-project --project YOUR_PROJECT_ID

This provisions:

Service account for logging
GCS bucket for prompt-response storage
BigQuery dataset for analytics
Updates your agent to log all conversations

Query production behavior in BigQuery:

SELECT
  timestamp,
  JSON_EXTRACT_SCALAR(request_data, '$.user_content.parts[0].text') as request,
  JSON_EXTRACT_SCALAR(response_data, '$.decision') as decision,
  latency_ms
FROM `your-project.agent_analytics.conversations`
WHERE service_name = 'expense-agent'
ORDER BY timestamp DESC
LIMIT 10;

This is critical for debugging production issues. “Why did it escalate that $30 meal?” Just query BigQuery and see exactly what the agent was thinking.

What Makes Agents CLI Different

I’ve used various agent deployment tools over the past few years. Here’s what stands out about Agents CLI:

1. Skills as Machine-Readable Context

Agents CLI doesn’t just provide commands: it provides “skills” that teach your coding assistant how to use them correctly.

When you run agents-cli setup, it installs 7 skills:

google-agents-cli-workflow: Development lifecycle
google-agents-cli-adk-code: ADK Python API patterns
google-agents-cli-scaffold: Project scaffolding
google-agents-cli-eval: Evaluation methodology
google-agents-cli-deploy: Deployment targets
google-agents-cli-publish: Gemini Enterprise registration
google-agents-cli-observability: Tracing and logging

Your coding assistant reads these when relevant. Instead of guessing deployment options, it knows when to use Agent Runtime vs Cloud Run vs GKE. Instead of trial-and-error with eval metrics, it knows the LLM-as-judge patterns that work.

2. Evaluation as Default, Not Optional

Every scaffolded project includes evaluation infrastructure from the start:

tests/eval/evalsets/ for test cases
eval_config.json for scoring rubrics
LLM-as-judge setup

This design choice reflects reality, agents without evals don’t make it to production. Making evaluation the default path ensures agents are tested before deployment.

3. Observability by Default

Cloud Trace is enabled automatically in every deployed agent. No configuration, no opt-in, it just works.

Why? Because debugging production agents without traces is nearly impossible. The content logging and BigQuery analytics are opt-in (via agents-cli infra single-project), but basic tracing is mandatory.

4. Handles Infrastructure Complexity

Agent logic is interesting. Docker configurations, authentication middleware, and Terraform files are not. Agents CLI handles the infrastructure so you can focus on making your agent smart.

Beyond the Basics

Our expense agent handles the core requirements, but production systems need more.

Real Data Connections

Replace the mock expense history with actual database queries:

import psycopg2
def check_expense_history(employee_id, vendor, date, amount):
    conn = psycopg2.connect(DATABASE_URL)
    cursor = conn.cursor()
    cursor.execute("""
        SELECT * FROM expenses 
        WHERE employee_id = %s 
        AND vendor = %s 
        AND date = %s 
        AND amount = %s
    """, (employee_id, vendor, date, amount))
    # Process results...

CI/CD Pipeline

Generate GitHub Actions workflow for staging and production:

agents-cli infra cicd --runner github-actions

This creates a multi-environment pipeline:

Commits to main → deploy to staging
Tagged releases → deploy to production

Session Management

Add Cloud SQL for persistent session storage:

agents-cli scaffold enhance --session-type cloud_sql

Multi-Agent Systems

The adk_a2a template enables specialist agents to coordinate:

agents-cli create coordinator-agent --agent-type adk_a2a

Useful for complex workflows like incident response or code migrations.

RAG (Retrieval-Augmented Generation)

Scaffold an agent with vector search:

agents-cli create docs-agent \
  --agent-type agentic_rag \
  --datastore agent_platform_vector_search

This generates data ingestion code, vector search integration, and retrieval logic.

Techniques Summary

Throughout this article, we explored several key techniques for building production agents:

Figure 1: Techniques Summary Table (Image by Author).

Each technique solves a specific problem in the agent development lifecycle. Combined, they create a complete path from prototype to production.

Conclusion

The deployment gap is real. Most AI agent projects fail not because the agent isn’t good enough, but because shipping it requires too much infrastructure work.

Agents CLI doesn’t solve every problem. You still need well-designed prompts, appropriate tools, and thorough testing. But it eliminates the infrastructure busywork that keeps agents stuck in development environments.

Your agent development workflow should feel like running create-react-app, not like manually assembling infrastructure. That’s what we built.

Building End to End AI Agents with ADK Dev Skills

Sat, 18 Apr 2026 00:00:00 +0000

Building End to End AI Agents with ADK Dev Skills (Image by Author).

:memo: Please Note
This is a guest post originally published on Google Cloud - Community.

Putting a “Principal ADK Engineer” in every developer’s laptop

Introduction

In this tutorial, we’ll build a complete multi-agent customer support system in about an hour. Not a prototype or a demo: a production-ready system with CI/CD, comprehensive testing, and cloud deployment. The kind of project that would normally take a few weeks to scaffold properly.

Here’s what we’ll end up with:

Multi-agent orchestration with intelligent routing
Production deployment to Vertex AI Agent Engine
Unit tests, integration tests, and evaluation datasets
Full CI/CD pipeline with staging and production environments
Cloud observability with tracing and logging

The approach? We’ll barely write any code ourselves. Instead, we’ll use ADK Dev Skills to turn our AI coding assistant into an expert ADK (Google Agent Development Kit) developer who knows exactly what to build and how to build it right.

Let’s see how this works! (Video tutorial below for anyone interested)

What Are ADK Dev Skills?

ADK Dev Skills are pre-built knowledge modules that give AI coding assistants deep expertise in specific domains. When we install them, our AI assistant stops guessing about ADK APIs and starts giving us correct, production-ready code.

Think of it this way: instead of our AI assistant reading generic documentation and trying to piece together how ADK works, it has direct access to the actual patterns, APIs, and best practices that the ADK team recommends.

This solves some real problems:

The AI stops hallucinating non-existent ADK APIs
We don’t need to constantly look up documentation
We get consistent patterns across our codebase
Evaluation and deployment configs just work

Available Skills

Figure 1: Available ADK Dev Skills (Image by Author).

Compatibility

These skills work with any AI coding tool that supports the Skills Protocol. They work with Gemini CLI, Claude Code, Cursor, Antigravity, and other compatible tools.

Prerequisites

Before we start, we’ll need:

# Required tools
- Node.js (for npx)
- Python 3.10+ 
- uv package manager (pip install uv)
- Google Cloud SDK (gcloud)
- An active GCP project with billing enabled

Let’s set up our GCP project:

gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login

Step 1: Install ADK Dev Skills

First, install the skills globally so they’re available in all your projects:

npx skills add google/adk-docs/skills -y -g

This downloads the 6 ADK skills from Google’s repository and makes them available to our AI assistant. The -g flag means global installation, and -y just auto-confirms the prompt.

Let’s verify it worked:

npx skills list

We should see all 6 ADK skills listed. Once they’re installed, any compatible AI assistant can use them.

Step 2: Define Your Requirements

Let’s start by telling our AI assistant what we’re trying to build. Be specific about the features we need.

Here’s what we’ll ask for:

I need to build a Retail Returns multiagent system using ADK.
Requirements:
- Check order status by order ID
- Process refunds for delivered orders
- Multi-agent architecture with routing
- Production deployment to Agent Engine

The AI will use the adk-scaffold skill to figure out the right project structure and create a design spec.

Step 3: Generate Project Scaffolding

Next, ask the AI to create the project structure:

Use adk-scaffold to create this project with:
- Agent Engine deployment target
- GitHub Actions CI/CD
- No datastore needed (we'll use mock data)

The AI runs the agent-starter-pack (repo here) scaffolding command with the right parameters and generates everything:

retail-returns/
├── app/                    # Our agent code
├── tests/                  # Unit, integration, eval tests
├── .github/workflows/      # CI/CD pipelines
├── deployment/terraform/   # Infrastructure as code
├── notebooks/              # Jupyter notebooks
└── Makefile               # Common development commands

It also sets up pyproject.toml with the right dependencies and configures deployment metadata.

The nice thing here is we don’t need to remember the agent-starter-pack command syntax or know which deployment target to pick. The skill has that knowledge built in.

Step 4: Implement Business Logic

Now for the actual agent code. Let’s tell the AI what tools we need:

Add tools for:
1. check_order_status(order_id: str) -> dict
2. process_refund(order_id: str) -> dict
Use mock data with 3 sample orders. Refunds only work for delivered orders.

The AI uses adk-cheatsheet to write proper ADK code. Here’s what we get:

**app/tools.py**:

# Mock database
ORDERS = {
    "12345": {"status": "shipped", "total": 45.99, "items": ["T-shirt"], "refunded": False},
    "67890": {"status": "delivered", "total": 120.50, "items": ["Shoes", "Socks"], "refunded": False},
}
async def check_order_status(order_id: str) -> dict:
    """Checks order status and details."""
    if order_id in ORDERS:
        return {"status": "success", "order": ORDERS[order_id]}
    return {"status": "error", "message": f"Order {order_id} not found."}
async def process_refund(order_id: str) -> dict:
    """Processes refund with validation."""
    if order_id not in ORDERS:
        return {"status": "error", "message": f"Order {order_id} not found."}
    order = ORDERS[order_id]
    if order["status"] != "delivered":
        return {"status": "error", "message": "Order must be delivered"}
    if order["refunded"]:
        return {"status": "error", "message": "Already refunded"}
    order["refunded"] = True
    return {"status": "success", "transaction_id": f"REF-{order_id}-123"}

**app/agent.py** with multi-agent architecture:

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
def create_status_agent() -> Agent:
    return Agent(
        name="status_agent",
        model=Gemini(model="gemini-3-flash-preview"),
        instruction="Look up orders using check_order_status tool.",
        tools=[check_order_status],
    )
def create_refund_agent() -> Agent:
    return Agent(
        name="refund_agent",
        model=Gemini(model="gemini-3-flash-preview"),
        instruction="Verify order is delivered before processing refund.",
        tools=[check_order_status, process_refund],
    )
root_agent = Agent(
    name="triage_agent",
    model=Gemini(model="gemini-3-flash-preview"),
    instruction="Route requests to status_agent or refund_agent.",
    sub_agents=[create_status_agent(), create_refund_agent()],
)
app = App(name="retail_returns_app", root_agent=root_agent)

Notice a few things here:

It used factory functions for sub-agents, which is the recommended pattern
The imports are correct (google.adk.agents, google.adk.models)
It set up the orchestration properly with a parent agent and sub_agents
Validation logic is both in the instructions and the tool code itself

Without adk-cheatsheet, we’d probably spend time figuring out the right way to structure this. The skill just knows.

Step 5: Test Locally

Before deploying anything, test it locally:

Let's test this locally

This runs the install and playground commands:

cd retail-returns
make install
make playground

The ADK web interface starts on localhost:8501. We can chat with our agent and try different scenarios:

“Where is my order #12345?”
“Can I get a refund for order #67890?”
“Refund order #99999” (this one should fail gracefully)

Step 6: Create Evaluations

Manual testing is fine for development, but you need automated evaluations for production. Ask the AI to create them:

Create an evaluation to test invalid order handling

Using adk-eval-guide, it generates proper evaluation datasets:

**tests/eval/evalsets/invalid_orders.evalset.json**:

{
  "eval_set_id": "invalid_orders",
  "eval_cases": [    {
      "eval_id": "invalid_status_check",
      "conversation": [        {"user_content": {"parts": [{"text": "What's the status of order #99999?"}]}}
      ],
      "expected_tool_calls": [        {"tool_name": "check_order_status", "args": {"order_id": "99999"}}
      ]
    },
    {
      "eval_id": "invalid_refund",
      "conversation": [        {"user_content": {"parts": [{"text": "I want a refund for order #88888"}]}}
      ]
    }
  ]
}

**tests/eval/eval_config.json**:

{
  "criteria": {
    "tool_trajectory_avg_score": {
      "threshold": 1.0,
      "match_type": "IN_ORDER"
    },
    "final_response_match_v2": {
      "threshold": 0.8,
      "judgeModelOptions": {"judgeModel": "gemini-3-flash-preview"}
    }
  }
}

Run the evaluations:

make eval

Output:

Tests passed: 2
Tests failed: 0

The skill knows the right evalset schema, applies the appropriate metrics (tool trajectory scoring for tool calls, LLM-as-judge for responses), and sets reasonable thresholds. We didn’t need to read any documentation about how ADK evaluations work.

Step 7: Deploy to Production

Once testing looks good, let’s deploy to Agent Engine:

Deploy this to Agent Engine

The AI uses adk-deploy-guide to run the deployment:

# Export dependencies
uv export --no-hashes > app/app_utils/.requirements.txt
# Deploy to Vertex AI
uv run -m app.app_utils.deploy \
  --source-packages=./app \
  --entrypoint-module=app.agent_engine_app \
  --entrypoint-object=agent_engine \
  --requirements-file=app/app_utils/.requirements.txt

This packages our code, uploads it to Google Cloud, and provisions a Reasoning Engine instance. We’ll get back an Engine ID (something like 2484736849587732480). The deployment takes 5-10 minutes while it builds the container and provisions infrastructure.

Let’s test it:

import vertexai
client = vertexai.Client(project="YOUR_PROJECT", location="us-central1")
agent = client.agent_engines.get(name="ENGINE_ID")
async for event in agent.async_stream_query(
    message="Where is order #12345?", 
    user_id="test"
):
    print(event)

Step 8: Set Up CI/CD

For a production system, we need automated testing and deployment:

Set up CI/CD with GitHub Actions

The AI generates three GitHub Actions workflows:

1. PR Checks (`.github/workflows/pr_checks.yaml`)

Runs on every Pull Request
Executes unit + integration tests
Blocks merge if tests fail

2. Staging Deployment (`.github/workflows/staging.yaml`)

Triggers on merge to main
Deploys to staging environment
Runs load tests
Uploads results to GCS

3. Production Deployment (`.github/workflows/deploy-to-prod.yaml`)

Requires manual approval
Deploys to production environment
Same validation as staging

Infrastructure setup:

uvx agent-starter-pack setup-cicd \
  --staging-project YOUR_STAGING_PROJECT \
  --prod-project YOUR_PROD_PROJECT \
  --repository-name YOUR_REPO \
  --repository-owner YOUR_GITHUB_USER \
  --auto-approve

This provisions:

Workload Identity Federation (secure, keyless auth)
Service accounts with proper IAM roles
GitHub secrets configuration

Step 9: Observability

Let’s check on observability:

How's observability configured?

The AI (using adk-observability-guide) explains what’s already set up:

Built-in (No Configuration Needed)

Cloud Trace — Distributed tracing

Automatic instrumentation via OpenTelemetry
Tracks: agent invocation → LLM calls → tool execution
View in GCP Console → Trace explorer

Prompt-Response Logging — Privacy-preserving by default

Mode: NO_CONTENT (metadata only, no PII)
Logs: token counts, latency, model names
Upload path: gs://BUCKET_NAME/completions

Optional Integrations

BigQuery Agent Analytics:

# Add to app/agent.py
from google.adk.plugins import BigQueryAgentAnalyticsPlugin
app = App(
    root_agent=root_agent,
    plugins=[BigQueryAgentAnalyticsPlugin(dataset="agent_analytics")]
)

Third-party platforms:

AgentOps (session replay)
Phoenix/Arize (open-source tracing)
Freeplay, Weave, MLflow

The adk-observability-guide has instructions for all of these if you want to add them.

Step 10: Write Tests for Production

We need tests that run against the actual deployed agent:

Create integration tests that hit the deployed agent

The AI generates tests/integration/test_remote_agent.py:

import pytest
import requests
import subprocess
def get_access_token():
    result = subprocess.run(
        ["gcloud", "auth", "print-access-token"],
        capture_output=True, text=True
    )
    return result.stdout.strip()
@pytest.mark.integration
def test_valid_order_status():
    """Test order lookup on deployed agent."""
    token = get_access_token()
    response = requests.post(
        f"https://us-central1-aiplatform.googleapis.com/v1/projects/{PROJECT_NUM}/locations/us-central1/reasoningEngines/{ENGINE_ID}:streamQuery",
        headers={"Authorization": f"Bearer {token}"},
        json={"input": {"message": "Where is order #12345?", "user_id": "test"}}
    )
    assert response.status_code == 200
    text = "".join(event.get("text", "") for event in response.json())
    assert "shipped" in text.lower()
    assert "45.99" in text

Run against production:

pytest tests/integration/test_remote_agent.py

Before and After

Without Skills

The traditional approach:

Read through ADK documentation
Look up deployment examples
Figure out the Agent Engine APIs
Research how to do evaluations properly
Set up CI/CD for AI agents (not well documented)
Trial and error with observability
Write all the boilerplate yourself
Debug import errors and API mismatches

Time investment: probably 2–3 weeks if you’re new to this, 3–5 days if you’re experienced.

With Skills

What we actually did:

Installed skills once
Described what we wanted
Let the AI generate it
Reviewed and tested the code

Time investment: about an hour.

Best Practices and Tips

1. Install Skills Globally

npx skills add google/adk-docs/skills -y -g

Use the -g flag so the skills are available in all our projects, not just the current one.

2. Be Specific in Prompts

Vague prompts like “Build an agent” don’t give the AI enough to work with. Better: “Build a customer support agent with order lookup and refund processing, using multi-agent architecture”

3. Leverage the Right Skill for Each Phase

Iterate with Evaluations

Run make eval frequently, not just at the end. After each major change, run the evaluations to catch regressions. Use make eval-all to run all evaluation sets.

5. Review Generated Code

The skills make the AI competent at ADK, but we still need to review what it generates:

Check that agent instructions are clear
Verify tool validation logic makes sense
Make sure the model choices are appropriate
Confirm business rules are correctly implemented

6. Use Version Control

Let’s initialize a git repo early:

git init
git add .
git commit -m "Initial scaffold from ADK Dev Skills"

This way we can see exactly what the AI generated and track our changes over time.

Common Questions

Do we need to learn ADK first?

Basic understanding helps, but the skills reduce the learning curve significantly. We can be productive pretty quickly.

Can we modify the generated code?

Yes. The code is ours. Treat it as a starting point and modify whatever we need.

Will this work with different AI assistants?

If it supports the Skills Protocol, yes. Works with Gemini CLI, Claude Code, Cursor, and Antigravity.

What if we want to deploy to Cloud Run instead?

Just ask. The adk-deploy-guide skill covers multiple deployment targets.

Can we create our own skills?

Yes. Skills are just markdown files with structured information. We can create company-specific ones.

How do we update the skills?

Re-run the install command:

npx skills add google/adk-docs/skills -y -g

What We Built

In about an hour, we created:

Production-ready multi-agent system with intelligent routing
Two custom tools with validation logic
Unit tests for business logic
Integration tests for agent behavior
Evaluation datasets with LLM-as-judge scoring
Deployed agent on Vertex AI Agent Engine
Full CI/CD pipeline with staging and production
Cloud observability with tracing and logging
Remote integration tests against deployed infrastructure

What to Build Next

Some ideas for what we can build next:

Customer service bot with ticket routing
Data analysis agent with BigQuery tools
Code review assistant with GitHub integration
Documentation generator with web scraping

The skills work for any domain. Install them once and our AI assistant can build production agents.

Conclusion

ADK Dev Skills turn AI coding assistants into ADK experts. Instead of the AI guessing at APIs and patterns, it has direct access to the right way to do things. This solves real problems:

No more documentation diving
No more boilerplate fatigue
No API mismatches from outdated examples
No deployment guesswork
No evaluation uncertainty

The generated code follows best practices, includes comprehensive testing, and has production-grade infrastructure. Not just faster: actually better.

Revolutionizing Claims, from Deepfake Detection to Next-Best-Action

Sat, 11 Apr 2026 00:00:00 +0000

Revolutionizing Claims, from Deepfake Detection to Next-Best-Action (Image by Author).

Revolutionizing Claims: From Deepfake Detection to Next-Best-Action

:memo: Please Note
This is a guest post originally published on Google Cloud - Community.

Solving information overload and sophisticated Fraud with Google ADK

The insurance claims process is a critical juncture for both policyholders and carriers. For policyholders, it’s a moment of need, expecting fair and swift resolution. For carriers, it’s a complex dance between empathy, accuracy, and fraud prevention. However, this vital process is currently facing two formidable challenges: an overwhelming information overload from diverse data sources and the insidious rise of sophisticated fraud, particularly with AI-generated or tampered evidence.

Manually sifting through mountains of unstructured claim documents, cross-referencing policies, and verifying the authenticity of digital evidence is slow, error-prone, and increasingly insufficient against cunning fraudulent tactics. This bottleneck not only delays legitimate claims but also exposes carriers to significant financial losses from successful fraud attempts. The industry desperately needs a solution that can accelerate legitimate payouts while robustly defending against novel forms of deception.

This article introduces two cutting-edge agent applications, built using the Google Agent Development Kit (ADK) and leveraging advanced GenAI capabilities, designed to revolutionize claims processing:

An “Investigator Agent” that acts as a digital forensic expert, capable of detecting tampered or AI-generated evidence, particularly in image formats.
A “Reasoning Agent” that intelligently analyzes unstructured claim documents against a vast repository of company policies to recommend the optimal “Next-Best-Action” for each unique claim.

Together, these agents form a powerful, intelligent system that augments human claims adjusters, transforming them from overwhelmed processors into strategic decision-makers.

The Framework: Google Agent Development Kit (ADK)

To tackle the complexity of claims processing, we need a framework that goes beyond simple LLM API calls. The Google ADK is purpose-built for creating robust, stateful, and auditable agentic workflows. Its key features enable us to construct a sophisticated system:

Agents: Specialized, intelligent units for distinct tasks. We’ll use LlmAgent for complex reasoning and SequentialAgent to orchestrate our pipeline deterministically.
State Management: The ADK’s Session object with its shared state dictionary allows agents to communicate and pass crucial claim details — like initial fraud flags or extracted policy clauses — seamlessly through the workflow.
Tools: Agents are empowered with capabilities beyond text generation. Our agents will use tools to interact with external systems for deepfake detection, vector database lookups, and more.
Structured Output: ADK’s integration with Pydantic ensures our agents output clean, validated JSON, providing reliable, actionable data for downstream systems or human review.

The Architecture: An Intelligent Claims Processing Pipeline

Our goal is to automate and enhance the critical cognitive steps a human claims adjuster performs. The improved pipeline incorporates the Investigator Agent to preemptively flag fraudulent evidence and the Reasoning Agent to provide intelligent, policy-driven recommendations.

The Investigator Agent: Receives initial claim data, including multimedia evidence. It uses specialized tools to analyze digital evidence (e.g., images) for authenticity and flags potential deepfakes or tampering.
The Reasoning Agent: Takes the verified claim details (and any fraud flags) and analyzes them against a comprehensive set of company policies and guidelines to recommend the “Next-Best-Action.”
The Orchestrator: A root agent (SequentialAgent) manages the flow, ensuring the Investigator Agent runs first, followed by the Reasoning Agent, creating a coherent, end-to-end workflow.

Figure 1: System Architecture (Image by Author).

Step 1: The Investigator Agent — Detecting Digital Deception

The rise of sophisticated AI tools means that digital evidence — especially images — can no longer be trusted at face value. Our Investigator Agent is designed to tackle this challenge head-on. It focuses on verifying the authenticity of submitted images, leveraging advanced techniques to detect tampering or AI generation.

For this tutorial, we’ll simulate a verify_image_authenticity tool. In a real-world scenario, this tool would integrate with services like Google Cloud’s SynthID for detecting AI-generated content or custom Computer Vision models for forensic analysis of image manipulation.

# In agent.py
from typing import Literal, Optional, Any, AsyncGenerator
from pydantic import BaseModel, Field
import asyncio
import os
import json
from google.adk.agents import Agent, SequentialAgent, BaseAgent
from google.adk.agents.invocation_context import InvocationContext
from google.adk.events import Event
from google.genai import types as genai_types
# --- Tools ---
def verify_image_authenticity(image_id: str) -> dict:
    """
    Verifies the authenticity of a given image to detect deepfakes or tampering.
    Args:
        image_id: The unique identifier for the image to be verified.
    Returns:
        dict: A dictionary containing the verification status and details.
              - 'status': "authentic", "tampered", "ai_generated", or "unverifiable".
              - 'confidence': A float representing the confidence score (0.0 to 1.0).
              - 'details': A string with additional findings.
    """
    print(f"--- Tool: verify_image_authenticity called for image_id: {image_id} ---")
    # Simulate API call to an image analysis service (e.g., SynthID, custom CV model)
    if image_id == "claim_123_evidence_fake.jpg":
        return {
            "status": "ai_generated",
            "confidence": 0.95,
            "details": "High confidence that the image contains AI-generated elements consistent with deepfake manipulation."
        }
    elif image_id == "claim_456_evidence_tampered.png":
        return {
            "status": "tampered",
            "confidence": 0.88,
            "details": "Image metadata indicates post-processing and pixel anomalies consistent with tampering."
        }
    else:
        return {
            "status": "authentic",
            "confidence": 0.99,
            "details": "No signs of tampering or AI generation detected."
        }
# --- Agents ---
class InvestigatorAgent(BaseAgent):
    """
    Agent responsible for analyzing digital evidence (e.g., images) for authenticity.
    Uses specialized tools for deepfake detection and tampering analysis.
    """
    image_verification_tool: Any
    def __init__(self, name: str, image_verification_tool: Any):
        super().__init__(name=name)
        self.image_verification_tool = image_verification_tool
    async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]:
        claim_evidence = ctx.session.state.get("claim_evidence", {})
        image_id = claim_evidence.get("image_id")
        if not image_id:
            ctx.session.state["evidence_status"] = "no_image_submitted"
            ctx.session.state["fraud_flags"] = False
            yield Event(author=self.name, content=genai_types.Content(parts=[genai_types.Part(text="No image evidence submitted.")]))
            return
        verification_result = self.image_verification_tool(image_id=image_id)
        ctx.session.state["evidence_status"] = verification_result["status"]
        ctx.session.state["fraud_flags"] = (verification_result["status"] != "authentic")
        yield Event(author=self.name, content=genai_types.Content(parts=[genai_types.Part(
            text=f"Image verification complete. Status: {verification_result['status'].upper()}, Confidence: {verification_result['confidence']:.2f}. Details: {verification_result['details']}"
        )]))
investigator_agent = InvestigatorAgent(
    name="InvestigatorAgent",
    image_verification_tool=verify_image_authenticity
)

Step 2: The Reasoning Agent — Policy-Driven Next-Best-Action

Once the authenticity of the evidence is assessed, the core task of claims processing begins: understanding the claim details in light of company policies to determine the appropriate course of action. Our Reasoning Agent excels here, combining document analysis with intelligent policy retrieval.

It uses two main tools/capabilities:

A simulated retrieve_policy_documents tool: In a real implementation, this would connect to a Vector AI Search database. This tool dynamically fetches relevant policy clauses or guidelines based on the claim type and details.
An LlmAgent: Leveraging a powerful LLM, it processes the claim narrative, the retrieved policy documents, and any fraud flags from the Investigator Agent to recommend a precise “Next-Best-Action.”

# Continuing in agent.py...
# --- Pydantic Schemas ---
class ClaimDetails(BaseModel):
    claim_id: str = Field(description="The unique identifier for the claim.")
    claim_type: Literal["auto", "home", "medical"] = Field(description="The type of the insurance claim.")
    description: str = Field(description="A brief description of the incident.")
    policy_number: str = Field(description="The policy number associated with the claim.")
    reported_damage: str = Field(description="Details of the reported damage or loss.")
class NextBestAction(BaseModel):
    recommended_action: str = Field(description="The recommended next step for claims processing.")
    reason: str = Field(description="The reasoning behind the recommended action, citing policy context.")
    urgency: Literal["low", "medium", "high"] = Field(description="The urgency level of the recommended action.")
    flag_for_human_review: bool = Field(description="True if human review is strongly recommended, otherwise False.")
# --- Tools ---
def retrieve_policy_documents(claim_type: str, relevant_keywords: list[str]) -> dict:
    """
    Retrieves relevant policy documents or clauses from a Vector AI Search database.
    Args:
        claim_type: The type of claim (e.g., "auto", "home", "medical").
        relevant_keywords: Keywords extracted from the claim description to find matching policies.
    Returns:
        dict: A dictionary containing 'status', 'policies_found' (list of relevant policy texts), and 'details'.
    """
    print(f"--- Tool: retrieve_policy_documents called for claim_type: {claim_type}, keywords: {relevant_keywords} ---")
    # Simulate Vector AI Search lookup
    if "fraud" in [k.lower() for k in relevant_keywords]:
        return {
            "status": "success",
            "policies_found": [                "Policy-FRAUD-001: All claims with a 'fraud_flag' must undergo secondary review by a senior adjuster.",
                "Policy-INVESTIGATION-005: Deepfake or AI-generated evidence requires immediate claim suspension and referral to the special investigations unit."
            ],
            "details": "Anti-fraud policies retrieved based on keywords."
        }
    elif claim_type == "auto" and "accident" in [k.lower() for k in relevant_keywords]:
        return {
            "status": "success",
            "policies_found": [                "Policy-AUTO-010: Auto accident claims require a police report and damage assessment.",
                "Policy-PAYOUT-003: Minor damage claims (< $5000) can be fast-tracked for approval."
            ],
            "details": "Auto accident policies retrieved."
        }
    else:
        return {
            "status": "success",
            "policies_found": ["General Policy-001: Process all claims fairly and promptly."],
            "details": "General policies retrieved."
        }
# --- Agents ---
reasoning_agent = Agent(
    name="ReasoningAgent",
    model="gemini-2.5-flash", # Using a powerful model for complex reasoning
    tools=[retrieve_policy_documents],
    instruction="""
    You are a highly experienced Claims Adjuster AI. Your task is to analyze claim details
    and policy documents to recommend the "Next-Best-Action" for a claim.
    The session state contains 'claim_details', 'evidence_status', and 'fraud_flags'.
    1. Extract relevant keywords from 'claim_details.description'.
    2. Use the 'retrieve_policy_documents' tool with 'claim_details.claim_type' and the extracted keywords.
    3. Carefully review the 'claim_details', 'evidence_status', 'fraud_flags', and the retrieved policies.
    4. Based on this information, determine the single best course of action and provide a clear reasoning.
    5. Your output MUST conform to the 'NextBestAction' schema.
    """,
    output_schema=NextBestAction,
    output_key="recommended_action_summary"
)

Step 3: Orchestrating the Claims Pipeline

Finally, we integrate both specialized agents into a SequentialAgent. This ensures a deterministic flow where evidence verification always precedes claim analysis and action recommendation.

# The final piece of agent.py
claims_processing_pipeline = SequentialAgent(
    name="ClaimsProcessingPipeline",
    description="A multi-agent pipeline for intelligent insurance claims processing, from deepfake detection to next-best-action recommendations.",
    sub_agents=[        investigator_agent,
        reasoning_agent
    ],
)
root_agent = claims_processing_pipeline

Putting It All Together: A Runnable Application

To run this complete claims processing pipeline, follow these steps.

Create the Application Directory:

mkdir -p claims_processing_app

Create agent.py: Inside the claims_processing_app/ directory, create a file named agent.py and populate it with all the code snippets from the implementation steps above.

Create a Runner Script (run_pipeline.py): In the claims_processing_app/ directory, create a file named run_pipeline.py and populate it with the following code:

import asyncio
import json
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types as genai_types
from agent import root_agent, ClaimDetails # Import root_agent and ClaimDetails from agent.py
async def main():
    """Runs the claims processing pipeline programmatically."""
    session_service = InMemorySessionService()
    session_id = "claims-session-001"
    user_id = "claims_demo"
    app_name = "claims_processing_app"
    await session_service.create_session(app_name=app_name, user_id=user_id, session_id=session_id)
    
    runner = Runner(agent=root_agent, app_name=app_name, session_service=session_service)
    print(f"Starting Claims Processing Pipeline...")
    # Example 1: Claim with authentic evidence
    print("\n--- Running Claim with Authentic Evidence ---")
    claim_details_authentic = ClaimDetails(
        claim_id="CLAIM-AUTH-789",
        claim_type="auto",
        description="Minor fender bender, damage to front bumper.",
        policy_number="POL-AUTO-987",
        reported_damage="Front bumper dented and scratched."
    )
    claim_evidence_authentic = {"image_id": "claim_789_evidence_authentic.jpg"}
    initial_state_authentic = {
        "claim_details": claim_details_authentic.model_dump(),
        "claim_evidence": claim_evidence_authentic
    }
    # Send a message to trigger the pipeline with initial state
    message_authentic = genai_types.Content(parts=[        genai_types.Part(text="Process this auto claim with authentic evidence.")
    ])
    
    # Create a new session for this example
    session_id_authentic = "claims-session-authentic"
    await session_service.create_session(app_name=app_name, user_id=user_id, session_id=session_id_authentic, state=initial_state_authentic)
    async for event in runner.run_async(
        session_id=session_id_authentic,
        user_id=user_id,
        new_message=message_authentic,
    ):
        if event.content and event.content.parts:
            if text := ''.join(part.text or '' for part in event.content.parts):
                print(f"[{event.author}]: {text}")
    session_authentic = await session_service.get_session(app_name=app_name, session_id=session_id_authentic, user_id=user_id)
    print("\n--- State after Authentic Claim ---")
    print(json.dumps(session_authentic.state, indent=2))
    # Example 2: Claim with AI-generated evidence and potential fraud
    print("\n--- Running Claim with AI-Generated Evidence (Potential Fraud) ---")
    claim_details_fraud = ClaimDetails(
        claim_id="CLAIM-FRAUD-123",
        claim_type="home",
        description="Water damage in kitchen, cause unknown. Evidence image attached.",
        policy_number="POL-HOME-123",
        reported_damage="Extensive water damage to kitchen cabinets and flooring."
    )
    claim_evidence_fraud = {"image_id": "claim_123_evidence_fake.jpg"}
    initial_state_fraud = {
        "claim_details": claim_details_fraud.model_dump(),
        "claim_evidence": claim_evidence_fraud
    }
    # Send a message to trigger the pipeline with initial state
    message_fraud = genai_types.Content(parts=[        genai_types.Part(text="Process this home claim with potentially fraudulent evidence.")
    ])
    # Create a new session for this example
    session_id_fraud = "claims-session-fraud"
    await session_service.create_session(app_name=app_name, user_id=user_id, session_id=session_id_fraud, state=initial_state_fraud)
    async for event in runner.run_async(
        session_id=session_id_fraud,
        user_id=user_id,
        new_message=message_fraud,
    ):
        if event.content and event.content.parts:
            if text := ''.join(part.text or '' for part in event.content.parts):
                print(f"[{event.author}]: {text}")
    session_fraud = await session_service.get_session(app_name=app_name, session_id=session_id_fraud, user_id=user_id)
    print("\n--- State after Fraudulent Claim ---")
    print(json.dumps(session_fraud.state, indent=2))
    print("\n--- CLAIMS PROCESSING COMPLETE ---")
    
if __name__ == "__main__":
    asyncio.run(main())

Install Dependencies:

Create a requirements.txt file in claims_processing_app/ with the following content:

# claims_processing_app/requirements.txt
google-adk
pydantic

Install these dependencies from the claims_processing_app/ directory:

pip install -r requirements.txt

Run the Pipeline:

Execute the pipeline from your project root (e.g., cd claims_processing_app/ then python run_pipeline.py):

python claims_processing_app/run_pipeline.py

Execution Output

Starting Claims Processing Pipeline...
--- Running Claim with Authentic Evidence ---
--- Tool: verify_image_authenticity called for image_id: claim_789_evidence_authentic.jpg ---
[InvestigatorAgent]: Image verification complete. Status: AUTHENTIC, Confidence: 0.99. Details: No signs of tampering or AI generation
 detected.
Warning: there are non-text parts in the response: ['function_call'], returning concatenated text result from text parts. Check the fu
ll candidates.content.parts accessor to get the full model response.
--- Tool: retrieve_policy_documents called for claim_type: auto, keywords: ['fender bender', 'damage', 'front bumper'] ---
[PolicyRetrievalAgent]: I have retrieved the policy documents based on the claim details. The following policies were found:
- General Policy-001: Process all claims fairly and promptly.
[RecommendationAgent]: {
  "recommended_action": "Initiate damage assessment",
  "reason": "The claim involves reported minor physical damage to a front bumper, and the retrieved policy (General Policy-001) mandat
es processing all claims fairly and promptly. Initiating a damage assessment is the necessary next step to quantify the loss and proce
ed efficiently with the claim.",
  "urgency": "medium",
  "flag_for_human_review": false
}
--- State after Authentic Claim ---
{
  "claim_details": {
    "claim_id": "CLAIM-AUTH-789",
    "claim_type": "auto",
    "description": "Minor fender bender, damage to front bumper.",
    "policy_number": "POL-AUTO-987",
    "reported_damage": "Front bumper dented and scratched."
  },
  "claim_evidence": {
    "image_id": "claim_789_evidence_authentic.jpg"
  },
  "retrieved_policies": "I have retrieved the policy documents based on the claim details. The following policies were found:\n- Gener
al Policy-001: Process all claims fairly and promptly.",
  "recommended_action_summary": {
    "recommended_action": "Initiate damage assessment",
    "reason": "The claim involves reported minor physical damage to a front bumper, and the retrieved policy (General Policy-001) mand
ates processing all claims fairly and promptly. Initiating a damage assessment is the necessary next step to quantify the loss and pro
ceed efficiently with the claim.",
    "urgency": "medium",
    "flag_for_human_review": false
  }
}
--- Running Claim with AI-Generated Evidence (Potential Fraud) ---
--- Tool: verify_image_authenticity called for image_id: claim_123_evidence_fake.jpg ---
[InvestigatorAgent]: Image verification complete. Status: AI_GENERATED, Confidence: 0.95. Details: High confidence that the image cont
ains AI-generated elements consistent with deepfake manipulation.
Warning: there are non-text parts in the response: ['function_call'], returning concatenated text result from text parts. Check the fu
ll candidates.content.parts accessor to get the full model response.
--- Tool: retrieve_policy_documents called for claim_type: home, keywords: ['water damage', 'kitchen', 'unknown cause'] ---
[PolicyRetrievalAgent]: Policy documents have been retrieved. The retrieved policies include: \"General Policy-001: Process all claim
s fairly and promptly.\"",
  "recommended_action_summary": {
    "recommended_action": "Initiate fraud investigation",
    "reason": "The claim has been explicitly flagged for fraud, and the description of 'unknown cause' for water damage further warran
ts a thorough investigation to determine the legitimacy of the claim before proceeding with standard processing. This aligns with the 
principle of fair processing by preventing fraudulent payouts.",
    "urgency": "high",
    "flag_for_human_review": true
  }
}
--- CLAIMS PROCESSING COMPLETE ---

Conclusion: Augmenting Adjusters, Fortifying Defenses

The landscape of insurance claims is evolving rapidly, demanding solutions that are both efficient and resilient against new threats. The intelligent agent pipeline presented here — featuring an Investigator Agent for deepfake detection and a Reasoning Agent for next-best-action recommendations — transforms traditional claims processing.

By leveraging the Google Agent Development Kit, coupled with advanced capabilities like SynthID, Vector AI Search, and Computer Vision, we move claims adjusters from reactive, manual data processors to proactive, strategic decision-makers. This architecture not only accelerates legitimate payouts and enhances customer satisfaction but also fortifies defenses against increasingly sophisticated fraudulent activities.

This is more than automation; it is an augmentation of human expertise, empowering adjusters with AI-driven insights to navigate complexity, ensure fairness, and uphold the integrity of the insurance ecosystem. The future of claims processing is intelligent, secure, and decisive.

To explore more multi-agent patterns, check out the Google Agent Development Kit (ADK) samples.

The Next-Gen Underwriter, Accelerating Quotes with Document Intelligence

Sat, 31 Jan 2026 00:00:00 +0000

Accelerating Quotes with Document Intelligence (Image by Author).

The Next-Gen Underwriter: Accelerating Quotes with Document Intelligence

:memo: Please Note
This is a guest post originally published on Google Cloud - Community.

A Multi-Agent Framework for Instant Data Extraction and Premium Calculation with Google ADK

In the hyper-competitive insurance market, speed is the ultimate currency. The carrier that delivers an accurate quote first often wins the business. Yet, for decades, the underwriting process has been anchored by a manual, time-intensive task: extracting data from a mountain of disparate documents. Underwriters, who should be focused on strategic risk assessment, are instead mired in the operational quicksand of data entry, toggling between ACORD forms, prior carrier policies, and vehicle registration PDFs.

This manual data entry introduces significant latency into the quoting pipeline. In a market where response time directly correlates with conversion rates, this latency translates to lost business. The objective is to re-architect this pipeline, replacing human data-transfer steps with a deterministic, automated system.

This article details how to build a GenAI-powered agent system that automates the quoting pipeline. Using the Google Agent Development Kit (ADK), Gemini 2.5, and principles of multi-agent design, we will construct a system that can instantly classify complex policy documents, extract key data points, and generate a comparable quote in seconds. This is how we shift the underwriter’s role from data processor to strategic analyst.

The Framework: Google Agent Development Kit (ADK)

To build a system this complex, we need more than a simple LLM API call. We require a framework that supports stateful, auditable, and production-ready workflows. The Google ADK is designed for this purpose. It provides the core primitives to build sophisticated agentic systems:

Agents: Specialized, intelligent units that perform specific tasks. We will use LlmAgent for complex reasoning and SequentialAgent to orchestrate the workflow deterministically.
State Management: The ADK provides a Session object with a shared state dictionary. This allows different agents to communicate and pass data — like a customer’s VIN or their prior coverage limits — seamlessly through the pipeline.
Tools: Agents can be given capabilities beyond text generation. As we’ll see, agents can use tools — which are simple Python functions — to interact with external data sources or logic, like a pricing engine.
Structured Output: ADK’s integration with Pydantic allows us to force an LLM to output clean, validated JSON. This is the key to creating reliable, actionable data for downstream processes.

The Architecture: A More Realistic Quoting Pipeline

Our goal is to automate the cognitive sequence a human underwriter follows. For our improved example, this process now includes reading from a directory of document files and using a dedicated tool to calculate the premium. The agent flow is as follows:

The Document Ingestion Agent: Reads a directory of application documents (e.g., ACORD forms, vehicle registrations) from the file system.
The Data Extraction Agent: Parses the content of all documents to extract key data points into a structured format.
The Premium Calculation Agent: Uses a calculate_premium_tool to determine the policy price based on the extracted data.
The Quote Formatting Agent: Assembles the final quote from all the data gathered in the previous steps.

Figure 1: System Architecture (Image by Author).

Step 1: The Ingestion Agent

First, we create text files to simulate the underwriting documents. Then, our DocumentIngestionAgent reads all files from a ./documents directory and loads their content into the session state. This is more realistic than hardcoding the text in the agent itself.

# In agent.py
import os
import asyncio
import json
from pydantic import BaseModel, Field
from typing import AsyncGenerator, Literal
from google.adk.agents import Agent, SequentialAgent, BaseAgent
from google.adk.agents.invocation_context import InvocationContext
from google.adk.events import Event
from google.genai import types as genai_types
class DocumentIngestionAgent(BaseAgent):
    """Reads all documents from the specified directory into the session state."""
    async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]:
        doc_path = os.path.join(os.path.dirname(__file__), "documents")
        docs = []
        for filename in os.listdir(doc_path):
            file_path = os.path.join(doc_path, filename)
            if os.path.isfile(file_path):
                with open(file_path, 'r') as f:
                    content = f.read()
                    docs.append({"doc_type": filename, "content": content})
        
        ctx.session.state["documents"] = docs
        yield Event(author=self.name, content=genai_types.Content(parts=[genai_types.Part(text=f"Ingested and classified {len(docs)} documents.")]))
ingestion_agent = DocumentIngestionAgent(name="DocumentSorter")

Step 2: The Extraction and Quoting Agents

With the documents in the session state, the DataExtractor agent can parse them. The key change is in the quoting logic. We now have a dedicated calculate_premium_tool that acts as a mini rating engine. A QuoteCalculator agent is responsible for calling this tool, and a final QuoteFormatter agent assembles all the pieces into the structured output. This separation of concerns (tool use vs. formatting) is a critical ADK pattern.

# Continuing in agent.py...
# --- Tool Definition ---
def calculate_premium_tool(
    vehicle_model: str, prior_bodily_injury_coverage: str
) -> dict:
    """Calculates a monthly premium based on vehicle and prior coverage."""
    base_premium = 150.0
    if "Tesla" in vehicle_model or "Rivian" in vehicle_model:
        base_premium += 25.0
    if "$300k" in prior_bodily_injury_coverage or "$500k" in prior_bodily_injury_coverage:
        base_premium -= 10.0 # Discount for higher prior limits
    return {"monthly_premium": base_premium}
# --- Pydantic Schemas ---
class ExtractedQuoteData(BaseModel):
    """Data structure for underwriting quote generation."""
    applicant_name: str = Field(description="The full name of the applicant.")
    vin: str = Field(description="The Vehicle Identification Number.")
    vehicle_model: str = Field(description="The make and model of the vehicle.")
    prior_bodily_injury_coverage: str = Field(description="Prior policy's bodily injury coverage, e.g., '$100k/$300k'.")
    prior_property_damage_coverage: str = Field(description="Prior policy's property damage coverage, e.g., '$50k'.")
class Quote(BaseModel):
    """Final quote structure."""
    applicant_name: str
    vin: str
    proposed_coverage: str
    monthly_premium: float
# --- Agent Definitions ---
data_extractor = Agent(
    name="DataExtractor",
    model="gemini-2.5-pro",
    instruction="""You are a specialized data extraction agent... Your output MUST be a single, raw JSON object that validates against the schema.""", # Instruction omitted for brevity
    output_schema=ExtractedQuoteData,
    output_key="extracted_data"
)
quote_calculator = Agent(
    name="QuoteCalculator",
    model="gemini-2.5-flash",
    tools=[calculate_premium_tool],
    instruction="""
    You are a premium calculation agent.
    Use the `calculate_premium_tool` to determine the monthly premium based on the vehicle model and prior coverage from the `{extracted_data}`.
    The tool will return a dictionary like {"monthly_premium": 165.0}. Your output should be ONLY the numeric value, like 165.0.
    """,
    output_key="monthly_premium"
)
quote_formatter = Agent(
    name="QuoteFormatter",
    model="gemini-2.5-flash",
    instruction="""
    You are a formatting agent.
    Take the `{extracted_data}` and the calculated `{monthly_premium}` from the session state.
    Format the final output into the `Quote` schema. The proposed coverage should match the prior policy's coverage levels.
    """,
    output_schema=Quote,
    output_key="final_quote"
)

Step 3: Orchestrating the Pipeline

Finally, we update our SequentialAgent to include all four agents in the correct order.

# The final piece of agent.py
underwriting_pipeline = SequentialAgent(
    name="UnderwritingPipeline",
    description="A multi-agent pipeline to automate insurance quoting.",
    sub_agents=[        ingestion_agent,
        data_extractor,
        quote_calculator,
        quote_formatter
    ],
)
root_agent = underwriting_pipeline

Example Input Documents

To make the example runnable, here is the content for the three sample documents that our agent will read. In a real workflow, an underwriter receives a bundle of such documents, each serving a distinct purpose. These files should be placed in the underwriting_app/documents/ directory.

acord_125.json

This represents a snippet from an ACORD 125 form, the standard commercial insurance application. For an underwriter, this is the foundational document containing the applicant’s basic information and insurance history. Our agent will use it to identify the applicant’s name and prior carrier details.

{
    "ACORD": {
        "form_id": "ACORD 125",
        "sections": [            {
                "section_name": "APPLICANT INFORMATION",
                "fields": {
                    "APPLICANT": "John 'Johnny' Doe",
                    "ADDRESS": "123 Main St, Anytown, USA 12345",
                    "PHONE": "555-123-4567"
                }
            },
            {
                "section_name": "PRIOR CARRIER",
                "fields": {
                    "CARRIER_NAME": "XYZ Insurance Co.",
                    "POLICY_NO": "ABC987654321",
                    "EXPIRATION_DATE": "2025-12-01"
                }
            }
        ]
    }
}

vehicle_registration.txt

This is a simplified vehicle registration document. It serves as official proof of the vehicle’s identity (make, model, year) and, crucially, its Vehicle Identification Number (VIN). An underwriter relies on this to confirm the exact vehicle being insured.

VEHICLE IDENTIFICATION REPORT
--------------------------------
VIN: 1A2B3C4D5E6F
MAKE: Tesla
MODEL: Model Y Long Range
YEAR: 2023
REGISTERED_OWNER: John Doe
ADDRESS: 123 Main St, Anytown, USA

prior_policy.txt

This file contains the declarations page from the applicant’s previous insurance policy. For an underwriter, this is a key document for competitive quoting. It reveals the applicant’s existing coverage limits, which our agent will use as a baseline to generate a comparable quote.

PRIOR POLICY DECLARATIONS - XYZ INSURANCE CO.
POLICY #: ABC987654321
NAMED INSURED: John Doe
COVERAGES:
- Bodily Injury Liability: $100,000 Each Person / $300,000 Each Accident
- Property Damage Liability: $50,000 Each Accident
- Uninsured Motorist: $100,000/$300,000
VEHICLE: 2023 Tesla Model Y - VIN: 1A2B3C4D5E6F

Putting It All Together: A Runnable Application

To run this full, realistic pipeline, follow these steps.

Create the Application Directory:

mkdir -p underwriting_app/documents

Create the Document Files: Create the three document files inside underwriting_app/documents/ with the content from the beginning of this section.

Create the agent.py file inside underwriting_app/ with all the code from the implementation steps above.

Create a Runner Script (run_pipeline.py): In the underwriting_app directory, create this file to execute the agent.

# underwriting_app/run_pipeline.py
import asyncio
import json
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types as genai_types
from agent import root_agent # Import the root_agent from agent.py
async def main():
    """Runs the full underwriting pipeline programmatically."""
    session_service = InMemorySessionService()
    session_id = "quote-session-001"
    user_id = "underwriter_demo"
    app_name = "underwriting_app"
    await session_service.create_session(app_name=app_name, user_id=user_id, session_id=session_id)
    
    runner = Runner(agent=root_agent, app_name=app_name, session_service=session_service)
    print(f"Starting Underwriting Quote Pipeline...")
    async for event in runner.run_async(
        session_id=session_id,
        user_id=user_id,
        new_message=genai_types.Content(parts=[genai_types.Part(text="Start the quote generation process.")]),
    ):
        if event.content and event.content.parts and event.content.parts[0].text:
            print(f"[{event.author}]: {event.content.parts[0].text}")
    session = await session_service.get_session(app_name=app_name, session_id=session_id, user_id=user_id)
    final_quote = session.state.get("final_quote")
    print("\n--- QUOTE GENERATION COMPLETE ---")
    if final_quote:
        print(json.dumps(final_quote, indent=2))
if __name__ == "__main__":
    asyncio.run(main())

Run the Pipeline:

# Install dependencies
pip install google-adk==1.4.2 pydantic
# Run the pipeline from your project root
python underwriting_app/run_pipeline.py

Execution Output

Running the new, more realistic pipeline produces the following output. Note the discount applied by the calculate_premium_tool for the good prior coverage.

Starting Underwriting Quote Pipeline...
[DocumentSorter]: Ingested and classified 3 documents.
[DataExtractor]: {
"applicant_name": "John Doe",
"vin": "1A2B3C4D5E6F",
"vehicle_model": "Tesla Model Y Long Range",
"prior_bodily_injury_coverage": "$100,000 Each Person / $300,000 Each Accident",
"prior_property_damage_coverage": "$50,000 Each Accident"
}
Warning: there are non-text parts in the response: ['function_call'], returning concatenated text result from text parts. Check the full candidates.content.parts accessor to get the full model response.
[QuoteCalculator]: 165.0
[QuoteFormatter]: {
  "applicant_name": "John Doe",
  "vin": "1A2B3C4D5E6F",
  "proposed_coverage": "Bodily Injury: $100k/$300k, Property Damage: $50k",
  "monthly_premium": 165.0
}
--- QUOTE GENERATION COMPLETE ---
{
  "applicant_name": "John Doe",
  "vin": "1A2B3C4D5E6F",
  "proposed_coverage": "Bodily Injury: $100k/$300k, Property Damage: $50k",
  "monthly_premium": 165.0
}

From Local Test to Production Service

For production, this agent can be deployed as a secure, scalable API on Google Cloud Run. This serverless environment ensures that you only pay for what you use, and combined with Vertex AI’s security guarantees, it ensures that sensitive customer data remains within your cloud environment and is never used for model training.

Conclusion: Augmenting, Not Replacing, the Expert

The output of this pipeline is not designed to autonomously bind policies. It is designed to feed a “human-in-the-loop” UI. The underwriter is presented with the source documents and the AI-extracted data side-by-side, along with the generated quote. Their role shifts from data collector to data verifier and strategic decision-maker. They are now empowered to process more quotes, faster, and with greater accuracy.

By breaking down the complex cognitive workflow of underwriting into a series of specialized tasks for AI agents, we can achieve a profound increase in efficiency. We’ve used Gemini 2.5 Pro for the heavy-lifting of data extraction and the nimble Gemini 2.5 Flash for the final formatting — an “Economy of Intelligence” pattern that optimizes for both performance and cost.

This architecture moves the underwriter from the back office to the front lines of competitive advantage, armed with the speed and intelligence of GenAI.

To explore more multi-agent patterns, check out the Google Agent Development Kit (ADK) samples.

Automating Regulatory Compliance using AI Agents to Streamline Document Audits

Sun, 18 Jan 2026 00:00:00 +0000

How AI Agents Streamline Document Audits (Image by Author).

Automating Regulatory Compliance: How AI Agents Streamline Document Audits

:memo: Please Note
This is a guest post originally published on Google Cloud - Community.

An end to end blueprint using Google Agent Development Kit (ADK)

In the insurance industry, the distance between a finalized product and its market launch is often measured not in days, but in regulatory hurdles. For underwriters, this reality creates a distinct tension: their expertise lies in assessing risk, yet a significant portion of their bandwidth is consumed by the “red tape” of compliance: checking font sizes on disclosure forms, verifying state-specific clauses, and ensuring terminology alignment across hundred-page documents.

This manual review process is a bottleneck. It is performant only in its ability to slow down business. Errors here are costly, leading to submission rejections and delays that are measured in months. It is an inefficiency ripe for automation.

The solution is not to train underwriters to be better proofreaders. It is to architect a system that treats compliance as a computable task. In this article, we explore how we built an AI-powered “Auditor Agent” system using the Google Agent Development Kit (ADK) and Gemini 2.5. By chaining specialized agents together, we can automate the rigorous, repetitive work of regulatory review, freeing human experts to focus on the nuance of risk.

The Toolkit: Google Agent Development Kit (ADK)

Before diving into the architecture, it is helpful to understand the framework powering this solution. The Google ADK is a Python-first framework designed to bridge the gap between simple LLM prototypes and production-grade systems.

Unlike basic API wrappers, ADK provides the architectural primitives necessary for complex, stateful workflows:

Agents: The core decision-makers. In our example, we use LlmAgent for tasks requiring reasoning (like the Auditor) and SequentialAgent for defining deterministic workflows (the Pipeline).
Runners: The execution engine that manages the event loop. The Runner handles the flow of messages between the user, the agents, and the tools, ensuring that execution is robust and observable.
Sessions & State: A persistent memory layer. The ADK’s Session object maintains a shared state dictionary, allowing different agents in a chain to access the same data (such as the policy text) without needing to pass it manually in every prompt.
Web Interface: A built-in local UI (adk web) for debugging and visual tracing. It allows developers to “open the black box” and watch agents reason, call tools, and update state in real-time — a critical feature for debugging multi-agent chains.

The Architecture: A Multi-Agent Approach

We cannot simply ask an LLM to “check this document.” Compliance is too complex for a single prompt. It requires reading a draft, understanding specific regulatory rulebooks (which vary by state), identifying violations, and citing them precisely.

To solve this, we employ a Multi-Agent System orchestrated by the ADK. We break the workflow into three distinct cognitive tasks, each handled by a specialized agent:

The Ingestion Agent: (Simulated) A custom BaseAgent that injects a hardcoded policy document into the session state for demo purposes.
The Compliance Auditor (The Core): Compares the extracted text against a strict set of regulatory guidelines using Gemini 2.5 Pro.
The Report Generator: Synthesizes the findings into a structured tabular format for the human underwriter.

We use ADK’s SequentialAgent to chain these steps into a deterministic pipeline (Figure 1).

Figure 1: Multi-Agent System (Image by Author).

Step 1: Defining the Compliance Auditor

The heart of our system is the ComplianceAuditor agent. We use Gemini 2.5 Pro for this task because of its massive context window and ability to reason through complex logical constraints.

Notice the precision in the instruction below. We do not ask the agent to “read and summarize.” We instruct it to act as a hostile auditor, specifically looking for failures. We also configure it with a low temperature to ensure deterministic, factual outputs.

from google.adk.agents import Agent  
from google.genai import types as genai_types
# Define the configuration for deterministic output  
gen_config = genai_types.GenerateContentConfig(  
    temperature=0.1,  # Low temperature for strict adherence to rules  
    top_p=0.8,  
)
compliance_auditor = Agent(
    name="ComplianceAuditor",
    model="gemini-2.5-pro",
    generate_content_config=gen_config,
    instruction="""
    You are a Senior Regulatory Compliance Officer for an insurance carrier.
    Your task is to audit the provided 'policy_text' against the following guidelines:
    - [NY-204-B] Policy validity period must be at least 60 days.
    - [NY-300-A] Digital claims submission options must be provided.
    - [GEN-001] Cancellation requires 30-day notice.
    **CRITICAL RULES:**
    1.  **Citation is Mandatory:** You must quote the exact text from the policy that violates a rule.
    2.  **Binary Assessment:** For every guideline, the status is either PASS, FAIL, or NOT_FOUND.
    3.  **No Hallucinations:** If a rule is not mentioned in the text, mark it as 'NOT FOUND'.
    Input Data:
    - Policy Text: {policy_text}
    Output the audit findings as a structured list of violations.
    """,
    output_key="audit_findings"
)

Step 2: Structured Output for Actionability

An agent’s insight is useless if it cannot be integrated into a downstream workflow. A free-text paragraph describing errors is hard to process programmatically.

To solve this, we enforce a strict schema on the output. In ADK, we can define a Pydantic model to force the LLM to return structured JSON. This allows our application to render the results directly into a UI dashboard or a CSV file without complex parsing logic.

from pydantic import BaseModel, Field  
from typing import Literal
class Violation(BaseModel):
    rule_id: str = Field(description="The ID of the regulation violated (e.g., 'NY-204-B').")
    status: Literal["PASS", "FAIL", "NOT_FOUND"]
    quoted_text: str | None = Field(description="The exact text from the document triggering the violation.")
    remediation_suggestion: str = Field(description="Specific instructions on how to fix the text.")
class AuditReport(BaseModel):
    policy_id: str
    violations: list[Violation]
    overall_risk_score: int = Field(description="A score from 0-100 indicating compliance health.")
# Apply this schema to a Reporting Agent  
report_generator = Agent(  
    name="ReportGenerator",  
    model="gemini-2.5-flash", # Flash is sufficient for formatting tasks  
    instruction="""  
    Format the raw 'audit_findings' from the previous agent into a strict JSON object that validates against the 'AuditReport' schema.
    Use the 'policy_id' from the session state.
    Calculate an 'overall_risk_score' based on the number and severity of failures. A higher score means more risk.
    - 0 findings = 0 score.
    - 1 finding = 50 score.
    - 2 findings = 75 score.
    - 3 or more findings = 95 score.
    """,  
    output_schema=AuditReport,  
    output_key="final_json_report"  
)

Step 3: Orchestration with SequentialAgent

Finally, we bind these components together. The SequentialAgent primitive in ADK allows us to pass the state (the document text, the guidelines, and the intermediate findings) from one agent to the next.

The ingestion_agent runs as the first step in the pipeline. It populates session.state[“policy_text”], making the document available to the subsequent agents in the sequence.

from google.adk.agents import SequentialAgent
auditor_pipeline = SequentialAgent(  
    name="AutomatedAuditPipeline",  
    description="Ingests a policy document and produces a structured compliance report.",  
    sub_agents=[  
        ingestion_agent,     # Loads text into state  
        compliance_auditor,  # Analyzes text against guidelines  
        report_generator     # Formats output to JSON  
    ]  
)

Step 4: Execution with Vertex AI

To run this pipeline in a production environment, we use the Runner class. This handles the event loop and state management. Crucially, we configure the environment to use Vertex AI, ensuring enterprise-grade security and scalability.

import asyncio  
import os  
from google.adk.runners import Runner  
from google.adk.sessions import InMemorySessionService
async def main():
    """Runs the full compliance audit pipeline."""
    use_vertex = os.environ.get("GOOGLE_GENAI_USE_VERTEXAI", "False").lower() == "true"
    if use_vertex:
        print("INFO: Using Vertex AI for generative models.")
        if not os.environ.get("GOOGLE_CLOUD_PROJECT") or not os.environ.get("GOOGLE_CLOUD_LOCATION"):
            print("ERROR: GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION must be set for Vertex AI.")
            return
    else:
        print("INFO: Using Google AI Studio. Set GOOGLE_API_KEY environment variable.")
        if not os.environ.get("GOOGLE_API_KEY"):
            print("ERROR: GOOGLE_API_KEY must be set for AI Studio.")
            return
    session_service = InMemorySessionService()
    session_id = "audit-session-001"
    user_id = "underwriter_demo"
    app_name = "audit_app"
    await session_service.create_session(app_name=app_name, user_id=user_id, session_id=session_id)
    
    session = await session_service.get_session(app_name=app_name, session_id=session_id, user_id=user_id)
    runner = Runner(agent=auditor_pipeline, app_name=app_name, session_service=session_service)
    print(f"Starting Compliance Audit Pipeline...")
    final_event = None
    async for event in runner.run_async(
        session_id=session_id,
        user_id=user_id,
        new_message=genai_types.Content(parts=[genai_types.Part(text="Start the audit.")]),
    ):
        if event.is_final_response():
            final_event = event
        if event.content and event.content.parts:
            print(f"[{event.author}]: {event.content.parts[0].text}")
        else:
            print(f"[{event.author}]: (No text content)")
    session = await session_service.get_session(app_name=app_name, session_id=session_id, user_id=user_id)
    final_report = session.state.get("final_json_report")
    print("\n--- AUDIT COMPLETE ---")
    if final_report:
        print(json.dumps(final_report, indent=2))
        print(f"\nOverall Risk Score: {final_report.get('overall_risk_score')}")
    else:
        print("ERROR: Final JSON report not found in session state.")
        if final_event and final_event.error_message:
            print(f"REASON: {final_event.error_message}")
if __name__ == "__main__":
    # To run this script, you must first authenticate and set your project:
    # 1. `pip install google-adk==1.4.2 google-genai pydantic`
    # 2. `gcloud auth application-default login`
    # 3. `export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"`
    # 4. `export GOOGLE_CLOUD_LOCATION="us-central1"`
    # 5. `export GOOGLE_GENAI_USE_VERTEXAI="True"`
    # 6. `python compliance_audit.py`
    asyncio.run(main())

Running the Example

To see this pipeline in action, you can run the code locally.

Prerequisites: Ensure you have Python installed, along with the necessary libraries:

pip install google-adk==1.4.2 google-genai pydantic

Authentication (Vertex AI): Authenticate using the Google Cloud CLI and set your project details. This is preferred for production environments over using raw API keys. Crucially, ensure these environment variables are correctly set and active in your shell before execution to avoid Missing key inputs argument errors.

# Login to Google Cloud  
gcloud auth application-default login
# Set your project ID and location  
export GOOGLE_CLOUD_PROJECT="your-project-id"  
export GOOGLE_CLOUD_LOCATION="us-central1"
# Instruct ADK to use Vertex AI  
export GOOGLE_GENAI_USE_VERTEXAI="True"

Execution: Run the script with all the code snippets directly to see the console output.

python compliance_audit.py

Visual Debugging (Optional): For larger projects structured with the ADK standard layout, you can use the built-in web interface too (Figure 2):

adk web .

Figure 2: ADK Web (Image by Author).

Execution Output

When you run the compliance_audit.py script, you will see the agent pipeline execute in real-time. The final output will be a structured JSON report detailing the compliance failures:

INFO: Using Vertex AI for generative models.
Starting Compliance Audit Pipeline...
[IngestionAgent]: Policy document ingested.
[ComplianceAuditor]: Guideline [NY-204-B] FAIL. Citation: "This policy is valid for 30 days from the date of issue."
Guideline [GEN-001] FAIL. Citation: "We reserve the right to cancel this policy at any time by providing a 15-day written notice to the policyholder."
[ReportGenerator]: {
  "policy_id": "POLICY-XYZ", 
  "violations": [
    {"rule_id": "NY-204-B", "status": "FAIL", "quoted_text": "text..."}, 
    {"rule_id": "GEN-001", "status": "FAIL", "quoted_text": "text..."}
  ], 
  "overall_risk_score": 75
}
--- AUDIT COMPLETE ---
{
  "policy_id": "POLICY-XYZ",
  "violations": [
    {
      "rule_id": "NY-204-B",
      "status": "FAIL",
      "quoted_text": "This policy is valid for 30 days from the date of issue.",
      "remediation_suggestion": "Review and revise the policy text to comply with the regulation NY-204-B."
    },
    {
      "rule_id": "GEN-001",
      "status": "FAIL",
      "quoted_text": "We reserve the right to cancel this policy at any time by providing a 15-day written notice to the policyholder.",
      "remediation_suggestion": "Review and revise the policy text to comply with the regulation GEN-001."
    }
  ],
  "overall_risk_score": 75
}
Overall Risk Score: 75

Adapting for the ADK Web Interface

While running the script directly is useful for batch processing, the ADK’s adk web command provides a powerful interactive UI for debugging and demonstrations. To use it, we need to refactor our script into the standard ADK project structure.

Create the Application Directory: Create a folder named audit_app.
Create the Agent File: Inside audit_app, create a file named agent.py.
Define the root_agent: Move all the Python code (imports, agent definitions, and the pipeline definition) from compliance_audit.py into audit_app/agent.py. The main() function is no longer needed. The only addition is to assign your final pipeline to a special variable named root_agent.

Your audit_app/agent.py file would look like this:

import asyncio
import os
import json
from pydantic import BaseModel, Field
from typing import Literal, AsyncGenerator
from google.adk.agents import Agent, SequentialAgent, BaseAgent
from google.adk.agents.invocation_context import InvocationContext
from google.adk.events import Event
from google.genai import types as genai_types
# --- All Agent Definitions (IngestionAgent, compliance_auditor, etc.) ---
# ... (paste all class and agent definitions from the script here) ...
# The adk web command looks for this specific variable.
root_agent = auditor_pipeline

With this structure, you can run adk web . from the root of your project. The tool will discover the audit_app, and you can start an audit by simply typing a message like “Start the audit” into the chat interface. The IngestionAgent will automatically load the hardcoded policy, and the pipeline will execute as before, with the added benefit of a visual trace in the UI.

Trust, But Verify: Evaluating the Auditor

In a regulated industry, “it works on my machine” is not a shipping criteria. We need statistical confidence. How do we know the agent isn’t hallucinating a pass on a faulty policy?

The ADK includes a dedicated evaluation framework (adk eval). This allows us to define a “Golden Dataset” of policies with known violations and run the agent against them. We can then calculate a Recall Score — specifically, what percentage of actual violations did the agent catch?

This shifts the deployment conversation from “I think it works” to “It has a 99.8% detection rate on our NY validation set.”

From Script to Service: Production Architecture

While the script above runs locally, production requires an API. ADK provides patterns to wrap this Runner in a FastAPI server using the adk api_server command.

This allows us to deploy the agent as a containerized service on Google Cloud Run. The benefits are three-fold:

Serverless Scaling: It scales down to zero when no policies are being audited, saving costs.
Security: We can run the agent inside a VPC Service Perimeter, ensuring that sensitive insurance documents never traverse the public internet.
Data Privacy & PII: In the insurance sector, data sovereignty is non-negotiable. By leveraging Vertex AI, we ensure that sensitive policyholder data remains within our Google Cloud trust boundary. It is never used to train public models, addressing a primary compliance requirement for FinTech and InsurTech deployments.

The “Human-in-the-Loop” Pattern

Automation does not mean autonomy. The structured JSON output we generate in Step 2 is not meant to be the final decision-maker. Instead, it feeds into a frontend UI — an “Approval Queue.”

Here, the underwriter sees the document on the left and the AI’s findings on the right. They can click “Approve” or “Reject” on each finding. This feedback loop does two things: it keeps a human liable for the final decision (a regulatory requirement), and it generates a labelled dataset to fine-tune future versions of the model.

From Red Tape to Risk Analysis

By deploying this architecture, we shift the underwriter’s role. Instead of reading a 50-page document to find that a disclaimer is in 10-point font instead of 12-point, they receive a generated table (Figure 3):

Figure 3: Output Results (Image by Author).

This shift allows the human expert to verify the AI’s findings in minutes rather than hours. The “sheer” volume of paperwork no longer dictates the pace of business.

Conclusion

The goal of AI in this context is not to replace the compliance officer, but to equip them with a tool that handles the “brute force” computation of regulatory verification. By using ADK to structure this workflow, we ensure that the process is auditable, consistent, and scalable.

One final architectural note: you’ll observe we mixed models in this pipeline. We used Gemini 2.5 Flash for ingestion and formatting (high speed, low cost) and reserved Gemini 2.5 Pro solely for the auditing step (high reasoning). This “Economy of Intelligence” ensures the system is not just effective, but cost-efficient at scale.

If you are building similar systems, start by defining your schemas. The precision of your data structures determines the reliability of your agents.

To get started with these patterns, explore the Google Agent Development Kit (ADK).

Reusable AI Patterns Transforming Every Industry

Sun, 26 Oct 2025 00:00:00 +0000

The Continent of Generative AI (Image by Author).

Reusable AI Patterns Transforming Every Industry

:memo: Please Note
This is a guest post originally published on Google Cloud - Community.

A blueprint to navigate the understanding how GenAI is redefining every industry

TL;DR

This article presents a strategic blueprint for understanding the business impact of Generative AI, arguing that its true power lies not in isolated, industry-specific solutions, but in a set of powerful, reusable patterns that apply across all sectors.

We need to move beyond a fragmented view of AI use cases (“islands”) to reveal a connected “continent” of capabilities. This analysis is broken into three parts:

Industry Verticals: It details specific, high-value GenAI applications across 15 distinct industries, grouped into four major sectors: Business & Finance, Consumer & Services, Tech & Infrastructure, and Public & Social.
Horizontal Functions: It identifies evergreen use cases for core business departments present in every company, including HR, Sales & Marketing, IT & Cybersecurity, and Finance.
Reusable Patterns: The core thesis is distilled into six foundational AI patterns that connect all the preceding examples: Synthetic Data Generation, Hyper-Personalization, Complex Information Synthesis, Conversational Interfaces, Simulation & Digital Twins, and Advanced Content Generation.

Introduction

The current Generative AI landscape feels like an old, unfinished map of the world — chaotic, exciting, with huge sections marked “Here be dragons.” For the past couple of years, we’ve been exploring it one small island at a time, drawing detailed charts of “Insurance Island” or the “Retail Archipelago,” treating each as a separate world.

But after traveling this landscape for a while, you start to see the bigger picture. You notice the deep ocean currents — the powerful, underlying patterns — that connect all these separate landmasses. You realize it’s not a scattered collection of islands at all; it’s one vast, interconnected continent.

This post is my first draft of a new map. It’s a cartographer’s attempt to chart that continent, to trace the currents of core AI capabilities like “Simulation” and “Synthesis” as they flow from one industry to the next. It’s a blueprint meant not as a final, definitive guide, but as a new way to navigate this transformative era — by seeing the whole, connected world at once.

Figure 1: The Continent of Generative AI (Image by Author).

Part 1: The Industry Verticals — AI in the Wild

Every industry speaks its own language, but the core business challenges? They’re surprisingly universal. Here’s a detailed look at how GenAI is providing solutions, grouped by their broader economic sector.

Business & Finance

This sector runs on data, risk, and complex contracts. GenAI isn’t just helping; it’s becoming the new backbone for intelligence and automation.

Figure 2: Business & Finance (Image by Author).

Insurance: Intelligence in Risk, Claims, and Customer Experience

The entire insurance lifecycle, from underwriting to claims, is a complex dance of data. GenAI is finally turning that complexity into a competitive advantage.

Smarter Underwriting: It used to take days. Now, AI models generate dynamic risk assessments by digesting unstructured data like property reports and climate models, creating hyper-personalized policies in minutes.
Automated Claims: We’re way beyond simple data extraction. GenAI can summarize messy claim narratives, analyze a photo of car damage, and draft empathetic, clear updates to keep policyholders in the loop.
Next-Gen Fraud Detection: The real game-changer is generating synthetic data of novel fraud schemes. This lets us train models to catch sophisticated criminals before they strike.
Proactive Engagement: Instead of just sending a bill, AI creates personalized outreach for renewals and safety recommendations (like weather alerts for homeowners), turning insurers into proactive partners.

Finance: Securing Transactions and Personalizing Advice

Financial institutions are walking a tightrope: lock down security on one side, and deliver hyper-personalized services on the other. GenAI is the key to doing both at scale.

The Financial Co-Pilot: AI can now act as a personal financial guide for every single customer, analyzing spending habits and life goals to generate tailored investment strategies and debt-reduction plans. It’s a level of service once reserved for the ultra-wealthy.
Automated Compliance (RegTech): Compliance has historically been a domain defined by high-volume, repetitive manual tasks. GenAI is systematically automating these workflows. This includes interpreting new regulations, automating KYC and AML checks, and powering the next generation of surveillance. For trading firms, it can analyze billions of communications (chats, emails, calls) to flag market abuse with a deep understanding of nuance and context, far surpassing legacy keyword systems.
Market Intelligence on Demand: Imagine summarizing thousands of earnings reports and news articles into a single, actionable paragraph. That’s no longer a dream; it’s a daily reality for investment professionals.

Legal: Augmenting Expertise and Automating Discovery

Anyone in the legal field knows that a huge chunk of time is lost to a mountain of documents. GenAI is giving lawyers their time back.

AI-Powered Document Review (e-Discovery): Drastically accelerate the review of thousands of documents in litigation, letting AI do the first pass of summarizing and flagging relevant clauses.
Intelligent Legal Research: Think of it as a research assistant that understands plain English, summarizing case law and analyzing statutes in seconds.
Automated Contract Drafting & Analysis: Generate standardized contracts and, more importantly, analyze incoming third-party contracts to instantly identify risks and non-standard clauses.

Real Estate & Construction: From Smart Design to Efficient Management

The building lifecycle, from a sketch to a finished building, is notoriously complex and prone to delays.

Generative Architectural Design: This is where it gets fun. Architects can input constraints like plot size, budget, and local codes, and the AI will generate multiple optimized floor plans and 3D models.
Automated Construction Planning: AI can analyze project plans and daily site reports to spot potential delays and safety risks before they become costly problems, generating smarter schedules.
Dynamic Property Listings & Virtual Staging: Automatically generate compelling property listings and use image models to virtually stage empty rooms, helping buyers see the potential.

Consumer & Services

This is the world of customer experience, logistics, and content. Here, GenAI is making every interaction more personal, efficient, and engaging.

Figure 3: Consumer & Services (Image by Author).

Retail & CPG: The End of One-Size-Fits-All Shopping

Retailers are in a constant battle to create amazing customer experiences while managing fragile global supply chains. GenAI is the force multiplier for both.

The AI Shopping Assistant: These aren’t your old, clunky chatbots. Sophisticated AI now acts as an expert personal shopper, guiding customers through product discovery with real-time styling advice.
Resilient Supply Chains: What if you could simulate the future? By modeling market scenarios — like competitor promotions or shipping disruptions — GenAI creates stunningly accurate demand forecasts and helps businesses sidestep bottlenecks.
Content That Converts: AI generates unique product descriptions, marketing emails, and even “virtual try-on” experiences tailored to an individual’s tastes.
Optimized Store Layouts: AI can generate optimal product placements based on sales data and customer flow patterns to maximize every square foot of retail space.

Travel & Hospitality: Crafting Perfect Trips and Seamless Experiences

This industry is all about creating memorable experiences. That means managing dynamic pricing, complex logistics, and real-time disruptions without a hitch.

AI-Powered Trip Planning: It’s like having an intelligent travel agent on call 24/7. AI can generate complete, personalized itineraries from vague prompts like “a relaxing beach vacation in Southeast Asia for under $2000.”
Dynamic Pricing and Revenue Management: Generate sophisticated pricing models that adjust in real-time based on demand, competitor rates, and local events.
Proactive Disruption Management: AI can monitor for flight delays and weather events, then proactively generate and offer solutions to affected travelers before they even think to complain.

Media & Entertainment: Scaling Content and Personalizing Discovery

The pressure is relentless: create a firehose of engaging content while helping consumers find the gems in a sea of choices.

AI-Assisted Creativity: AI is becoming a creative partner, augmenting human talent by generating script ideas, concept art, and background music. It can even create trailers and highlights from long-form video automatically.
Intelligent Archives: Imagine making your entire content library instantly searchable. AI automates the transcription, translation, and metadata tagging, readying it for monetization.
Localization at Scale: Automatically generate high-quality subtitles and even synthetic voice dubs in dozens of languages, opening up global markets faster than ever before.

Logistics & Transportation: Optimizing Flow and Enhancing Visibility

This industry operates on razor-thin margins and is vulnerable to the slightest disruption. Optimization isn’t a goal; it’s a survival mechanism.

Dynamic Route & Network Optimization: Generate and simulate thousands of potential routing options in real-time, factoring in traffic, weather, and fuel costs to find the absolute best path.
Intelligent Document Processing: Automate the tedious and error-prone data extraction from critical documents like Bills of Lading and customs forms.
Predictive Disruption Analysis: Generate simulations of potential supply chain shocks (like port closures) and recommend proactive rerouting and contingency plans.

Tech & Infrastructure

This category covers the physical world — from factories to the energy grid. GenAI is creating more efficient, resilient, and innovative physical products and systems.

Figure 4: Tech & Infrastructure (Image by Author).

Manufacturing: Designing the Future, Optimizing the Present

Manufacturers have to constantly innovate while maximizing the efficiency and uptime of their multi-million dollar production lines.

Generative Design: This is mind-bending stuff. Engineers define a product’s requirements — weight, materials, cost — and AI generates thousands of optimized designs, creating forms a human would never have imagined.
Predictive Maintenance on Steroids: By generating synthetic sensor data that mimics rare machine failures, we can train AI models to predict breakdowns with uncanny accuracy.
Automated Quality Control: AI analyzes images from the production line to spot microscopic defects in real-time and generate alerts with probable causes.

Telecommunications: Optimizing Networks, Retaining Customers

In a saturated market, preventing customer churn and providing effective technical support are everything for Telcos.

Proactive Network Operations: AI can simulate network traffic to predict congestion and optimize capacity, while predictive models anticipate hardware failures in cell towers before they go down.
AI-Powered Field Service: Give technicians a “co-pilot” that understands technical manuals, helping them troubleshoot complex issues in the field and dramatically improving first-time fix rates.
Smart Contract Analysis: Automatically summarize complex B2B service contracts and SLAs. For all customers, AI can analyze bills and resolve discrepancies instantly.

Energy & Utilities: Balancing the Grid and Ensuring Safety

Energy providers have to ensure grid stability amidst fluctuating demand and the rise of renewables, all while maintaining vast, critical infrastructure.

Grid Management & Load Forecasting: Generate highly accurate simulations of energy demand by factoring in weather and economic indicators, allowing for optimized energy production and preventing outages.
Predictive Maintenance for Infrastructure: Analyze data from drones, sensors, and satellite imagery to predict failures in turbines, transformers, and pipelines before they become critical.
Renewable Energy Optimization: Generate precise forecasts for wind and solar output to create optimal strategies for battery storage and release, maximizing the value of every electron.

Automotive: Redefining the In-Vehicle Experience and Service Lifecycle

The industry is transforming towards electric, connected, and autonomous vehicles, with a new focus on the digital experience and post-sales service.

Intelligent In-Vehicle Assistant: Create a conversational co-pilot that can control vehicle settings, plan complex routes with charging stops, and provide a truly rich infotainment experience.
AI-Powered Diagnostics & Service: Empower service technicians with a GenAI model that understands vehicle sensor data and service manuals, providing step-by-step repair instructions.
Accelerated Vehicle Design: Use generative design to create and test thousands of aerodynamic body shapes and lightweight chassis designs in a fraction of the time.

These verticals are focused on society’s well-being, from our health to our education. GenAI’s role here is to augment human experts and broaden access to critical services.

Figure 5: Public & Social (Image by Author).

Healthcare & Life Sciences: Accelerating Discovery, Easing Burnout

Healthcare is drowning in data, and clinicians are burning out from administrative overload. GenAI is a lifeline, accelerating research and giving doctors more time with patients.

AI-Powered Drug Discovery: Researchers can now generate and test novel molecular structures in a simulation, dramatically shortening the early, expensive phases of drug development.
The End of Clinical Paperwork: This is the big one for doctors. AI can now listen to a patient conversation and automatically generate structured clinical notes directly into the EHR, fighting clinician burnout.
On-Demand Medical History: Upon admission, AI can give clinicians a rapid, summarized overview of a patient’s entire medical history, ensuring better, faster care.
Synthetic Data for Research: AI can create synthetic medical images and patient data to train diagnostic models without compromising patient privacy — a huge deal for studying rare diseases.

Public Sector: Enhancing Citizen Services and Operational Efficiency

Government agencies have to deliver a vast range of services, often with tight budgets and legacy systems.

Intelligent Constituent Services: Create conversational AI agents that give citizens 24/7 access to information about services, benefits, and regulations, answering their questions instantly.
Policy Analysis & Simulation: Summarize and analyze proposed legislation and public commentary to help policymakers understand potential impacts before a bill becomes law.
Automated Grant and Permit Processing: Streamline the application process by having GenAI read and validate documents, checking for compliance and slashing backlogs.

Education: Personalizing Learning and Streamlining Administration

Educators want to provide personalized learning for every student but are often swamped by large class sizes and administrative work.

Personalized Learning Assistants: Create AI tutors that adapt to each student’s learning pace and style, generating customized practice problems and study guides to help them master any subject.
Curriculum & Content Development: Assist educators by generating fresh lesson plans, classroom activities, and assessment questions aligned with curriculum standards.
Administrative Co-pilot: Automate the thankless tasks, like generating school newsletters, meeting summaries, and parent-teacher communications.

Part 2: The Horizontals — The AI Toolkit for Every Company

Beyond specific industries, every single company has core business functions. Building reusable GenAI assets for these “horizontals” is one of the fastest ways to scale value across an organization.

Figure 6: Horizontal Functions (Image by Author).

Human Resources (HR)

AI is giving HR teams superpowers, letting them move from administrative tasks to strategic talent management.

The Talent Co-pilot: Generate tailored job descriptions, screen resumes, and create personalized interview questions to find the perfect candidate faster.
Frictionless Onboarding: Power a 24/7 HR chatbot to answer new hires’ questions about benefits and policies, freeing up the HR team to focus on the human connection.
Engagement & Development: Analyze employee feedback surveys to generate summaries of sentiment and create personalized learning paths for career growth.

Sales & Marketing

The days of spray-and-pray marketing are over. GenAI allows for true one-to-one communication, at scale.

Hyper-Personalized Campaigns: Generate thousands of variations of ad copy and email campaigns tailored to individual customer segments and their specific needs.
The Sales Assistant: Prepare sales teams for every meeting by having AI summarize a prospect’s company news, industry trends, and past interactions.
AI-Driven Content Strategy: Analyze market trends and competitor activities to generate sharp ideas for blog posts, white papers, and other marketing content.

IT & Cybersecurity

IT departments are using AI to build faster, manage complexity, and stay one step ahead of threats.

The Developer’s Co-pilot: Generate boilerplate code, suggest optimizations, and even translate code between programming languages. It’s a massive productivity boost.
Intelligent Incident Management: Analyze system logs to instantly summarize incidents, identify the likely root cause, and suggest remediation steps.
Threat Intelligence & Simulation: Summarize the latest threat intelligence reports and generate security recommendations. Even better, simulate phishing attacks to train employees.

Corporate Finance & Accounting

AI is automating the tedious parts of finance, allowing teams to become more strategic advisors to the business.

Automated Financial Storytelling: Connect to financial systems and automatically generate narrative summaries for quarterly reports, explaining key trends and variances in plain English.
Intelligent Expense Processing: Automate data extraction from invoices and receipts, categorize expenses, and check for policy compliance.
The FP&A Co-pilot: Assist analysts by generating financial models and running scenario analyses based on simple, natural language prompts.

Part 3: The Blueprint — Connecting the Dots with Reusable Patterns

This is where it all comes together. When you zoom out from the map, you see that these dozens of use cases are all powered by a handful of foundational AI patterns. Master these, and you can build for any industry. This is the blueprint for a truly reusable AI strategy.

Figure 7: The Complete Landscape (Image by Author).

Pattern 1: Synthetic Data Generation

The key to robust Fraud Detection (Finance), accurate Predictive Maintenance (Manufacturing), and privacy-preserving Medical Training (Healthcare).

Pattern 2: Hyper-Personalization

The engine connecting Retail (shopping assistants), Finance (financial co-pilots), Travel (trip planning), and Marketing (campaigns).

Pattern 3: Complex Information Synthesis

The ability to distill vast, unstructured data into insights. It powers Market Intelligence (Finance), Clinical Summarization (Healthcare), and Legal Research (Legal).

Pattern 4: Conversational Interfaces

The universal human-AI interaction layer. It powers everything from external Customer Support bots to internal IT Helpdesks.

Pattern 5: Simulation & Digital Twins

The power to model reality. This is crucial for Supply Chain (Retail), Network Operations (Telco), and Financial Modeling (Finance).

Pattern 6: Advanced Content Generation

This spans everything from creating Marketing Copy to highly technical outputs like Generative Design (Manufacturing) and Code Generation (IT).

Figure 8: Interconnected Patterns (Image by Author).

Conclusion

A blueprint, no matter how detailed, is not a building. It is a plan, a vision, an invitation to build. What I’ve laid out here is my reading of that plan — a schematic of the interconnected, reusable patterns that I believe will form the foundations of the next generation of enterprise.

But the most exciting part is that the concrete is still wet. The framework is still being built.

This blueprint is an invitation to stop building isolated tools and start designing scalable intelligence. It’s a challenge to look beyond the immediate problem in your industry and ask: “What core pattern are we really trying to solve, and how can we build it in a way that it becomes a foundational asset for everything we do next?”

If you enjoyed the mindmaps in this article, they were created using Mind Maps Generator, an open source tool!

Google Veo A Technical Deep Dive for the AI Director

Sun, 24 Aug 2025 00:00:00 +0000

Video 1: Submarines and a whale in Zurich Lake (Image by Author).

Google Veo: A Technical Deep Dive for the AI Director

:memo: Please Note
This is a guest post originally published on Google Cloud - Community.

An In-Depth Guide to the Architecture, Prompting, and Workflows Behind Google’s Generative Video Model

The leap from static images to dynamic, coherent video has long been a formidable benchmark for generative AI. With the introduction of models like Google’s Veo, we’re witnessing a paradigm shift. This isn’t just about creating moving pictures; it’s about enabling a new form of procedural cinematography, where creators can direct complex scenes through language. For developers, creatives, and data scientists, understanding the engine under the hood is crucial to harnessing its full potential and moving from being a mere user to a true AI director.

This article provides a technical deep dive into Google Veo. We’ll deconstruct its architecture, move on to foundational prompting strategies, and culminate in advanced techniques for achieving the holy grail of AI video: consistency in characters, scenes, and branding. We will also walk through a practical multi-shot workflow and explore the emerging hybrid approach of combining generation with powerful editing tools, a process that is set to define the next generation of digital content creation.

Deconstructing Veo — The Architecture of Motion

At its core, Veo is a sophisticated generative model capable of producing high-definition video from a variety of inputs, including text, images, or a combination of both. Its ability to generate up to 1080p resolution footage that can extend beyond a minute, complete with an emergent understanding of real-world physics and cinematic techniques, stems from its powerful and efficient architecture: a Latent Diffusion Transformer.

Let’s break down this trifecta of concepts, as understanding each piece is key to understanding Veo’s capabilities and limitations.

The Latent Space: A Strategy of Efficiency

Processing raw video data — a sequence of high-resolution pixel grids — is computationally astronomical. To solve this, Veo employs a latent diffusion model (LDM). The process begins with a specialized autoencoder, which consists of two parts: an encoder and a decoder.

The video encoder takes raw video frames and compresses them into a lower-dimensional, information-dense representation known as the latent space. This process intelligently strips out redundant visual information while preserving the essential features of the scene, objects, and their movement over time. Think of it as creating a highly detailed blueprint of the video rather than working with the raw, heavy bricks and mortar. This isn’t just a smaller file; it’s a structured, semantic map of the video’s content.

By operating within this compressed latent space, the computationally intensive diffusion process becomes drastically more manageable, enabling the generation of high-resolution video without requiring prohibitive amounts of processing power.

The Diffusion Process: Denoising to Reality

The generative heart of the model is diffusion. It’s a two-part process that allows the model to learn and then create complex data structures.

Forward Process (Training): During training, the model takes the clean latent representations of video and systematically adds Gaussian noise over a series of steps until nothing but random noise remains. This teaches the model the statistical structure of video data at every level of detail, from broad compositions down to fine textures. It learns what “video-ness” looks like at every stage of clarity.
Reverse Process (Inference): The model then learns to reverse this process. At inference time, it starts with a random noise tensor and, guided by the user’s prompt (which is also converted into a mathematical representation), it iteratively applies a learned denoising function. Step by step, it removes the noise, sculpting the random tensor into a clean latent representation that reflects the prompt’s content. It’s akin to a sculptor who knows precisely where to chisel a block of marble to reveal the statue within.

This denoising process is what “creates” the video. The final clean latent is then passed to the decoder (the other half of the autoencoder), which upscales it back into the full-resolution video we see.

The Transformer: Modeling the Language of Time

The critical component executing this reverse-denoising process is a Transformer-based denoising network. Transformers, with their self-attention mechanism, are unparalleled at modeling complex, long-range dependencies within sequential data. Unlike older models that could “forget” what happened early in a sequence, a Transformer can pay attention to all parts of the input at once. This makes them perfectly suited for the temporal nature of video.

To make the data compatible, Veo “tokenizes” the compressed latent space, turning the spatio-temporal data into a sequence that the Transformer can process. This allows the model to understand not just what’s in a single frame, but how objects should consistently evolve and interact over time. This leads to more coherent and physically plausible results like realistic water ripples, consistent character motion, or fabric movement that reacts to a character’s actions. This unified architecture is what allows Veo to follow complex, multi-scene narrative prompts and understand cinematic language like “timelapse” or “drone shot.”

The Art of Direction — Foundational Prompting

If Veo is the film crew, your prompt is the screenplay and the director’s shot list rolled into one. Effective prompting moves beyond simple descriptions to a form of procedural direction. A well-structured prompt is built on several core components that, when combined, give the model a clear and unambiguous set of instructions.

The Essential Elements

Based on official guidance and community best practices, every foundational prompt should contain these four elements:

Subject: Who or what is the focus? Be specific and descriptive. The more detail you provide, the less the model has to guess.

Instead of: “a man”
Try: “a grizzled, elderly fisherman with a thick white beard and a worn, yellow raincoat.”

Action: What is the subject doing? Crucially, focus on a single, clear action or “beat.” Trying to chain multiple actions in one prompt (e.g., “a man walks in, sits down, and drinks coffee”) can confuse the model.

Instead of: “a dog runs and jumps”
Try: “a golden retriever leaps gracefully through the air to catch a red frisbee.”

Context (Scene): Where and when is this happening? Describe the environment, time of day, and atmosphere to ground your subject in a believable world.

Example: “A misty, ancient redwood forest at dawn, with golden sunbeams filtering through the dense canopy.”

Style: The overall aesthetic. This is where you define the look and feel, referencing artistic movements, film techniques, or even specific hardware.

Examples: “cinematic, shot on 35mm film with anamorphic lenses,” “Studio Ghibli-inspired animation,” “hyperrealistic, Unreal Engine 5 render,” “grainy found footage from a 1990s VHS tape.”

Adding Cinematic Control: The Modifiers

To elevate your output from a simple clip to a cinematic shot, you must direct the camera and ambiance with specific keywords.

Camera Motion: Be explicit. If you want movement, specify it.

pan, tilt, dolly-in, tracking shot, crane shot, handheld micro-shake, whip pan, slow push-in

Camera Framing: How is the subject framed? Use standard filmmaking terminology.

wide shot, medium shot, close-up, extreme close-up (ECU), over-the-shoulder (OTS), point-of-view (POV)

Camera Angle: What is the camera’s perspective? This has a powerful psychological effect.

low angle (makes the subject look powerful)
high angle (can make the subject seem small or vulnerable)
eye-level, bird's-eye view, dutch angle

Ambiance & Lighting: Control the mood with color and light. Be evocative.

warm golden hour lighting, cool blue tones of twilight, dramatic high-contrast film noir lighting, soft, diffused light from an overcast sky, caustic reflections from water.

Example Prompt Breakdown

Let’s combine these into a powerful, directorial prompt.

Weak Prompt:

A car driving in the city at night.

Video 2: Weak Prompt (Image by Author).

Strong, Directorial Prompt:

Cinematic wide shot of a vintage 1980s sports car, gleaming cherry red, speeding through a rain-slicked neon alley at night. The camera tracks smoothly alongside the car. Moody, high-contrast film noir lighting with reflections of pink and blue neon signs on the wet asphalt.

Video 3: Directoral Prompt (Image by Author).

Advanced Techniques for Cinematic Consistency

The most significant challenge in multi-shot AI video generation is consistency. A character’s face changing mid-scene or a setting’s style drifting breaks the narrative illusion. Here are systematic strategies to combat this.

Character Consistency: Defeating “Identity Drift”

The Challenge: AI models are generally stateless. They interpret each prompt independently and have no “memory” of the character they generated in the previous shot. This leads to “identity drift,” where features, clothing, or even ethnicity can change from one shot to the next.

Solution 1: The Character Bible

Your most powerful tool is a “character bible” — a highly detailed, reusable block of text that defines your character.

Create a Detailed Description: Go beyond the basics. Describe facial structure (oval face, prominent cheekbones, aquiline nose), specific features (a small scar above the left eyebrow), hair (wavy, shoulder-length auburn hair), and wardrobe (a well-worn, dark brown leather jacket over a grey Henley shirt). The more unique and specific the details, the stronger the anchor.
The Verbatim Rule: This is critical. Copy and paste the exact same character block into every single prompt where that character appears. Do not paraphrase or shorten it. The model interprets your prompt as a set of tokens; changing even one word creates a different input and can lead to a different output.
Prioritize the Block: Place the character description prominently at the start of your prompt to give it maximum weight in the model’s attention mechanism.

Character Bible Example:

CHARACTER: A woman in her late 20s named Elara. She has an oval face with prominent cheekbones, deep blue almond-shaped eyes, and a constellation of light freckles across her nose. Her hair is wavy, shoulder-length, and auburn. She wears a well-worn, dark brown leather jacket over a grey Henley shirt and dark-wash jeans.

You would then append scene-specific descriptions to this block for each shot.

Solution 2: Image-to-Video Anchoring

For even greater control, use a multi-modal approach by providing visual conditioning.

Generate a Still Image: Use a powerful image model (like Google’s Imagen) or even Veo itself to generate a perfect still frame of your character using your detailed “character bible” prompt. This is your “master reference.”
Use as a Reference: Feed this generated image into Veo along with your text prompt for the video scene. The image acts as a powerful visual anchor, significantly reducing identity drift and ensuring the model adheres to the established look.

Scene and Narrative Consistency

The Challenge: Creating a coherent, multi-shot narrative where the environment, style, and lighting remain consistent.

Solution 1: One Beat Per Prompt

This is the cardinal rule of AI storyboarding. Do not try to describe an entire sequence in one prompt. Break your narrative down into individual shots or “beats,” with each prompt generating a single, short clip (e.g., 5–8 seconds). This gives you maximum control over the final edit.

Solution 2: Lexicon and Style Block Consistency

Just like the character bible, create a reusable “Style Block” for your scene.

Style Block Example:

STYLE: Cinematic, shot on 35mm film with a 2.35:1 aspect ratio. Color graded with a palette of muted earth tones and cool blues. Lighting is soft, natural, and atmospheric, mimicking an overcast winter morning. A light film grain is visible.

Paste this exact block into every prompt within the sequence. Furthermore, reuse the same core nouns and adjectives for the setting (e.g., always call it a “minimalist Scandinavian kitchen,” not just “a kitchen”).

Solution 3: Motivated Transitions

Direct your transitions to create a seamless flow. End one prompt on an action that begs for a continuation and start the next by fulfilling it.

Prompt 1 (ends with): ...Elara turns and exits the frame to the left.
Prompt 2 (begins with): Medium shot. Elara enters the frame from the right, now walking down a dimly lit hallway...

Brand Consistency

The Challenge: Ensuring AI-generated content aligns perfectly with a brand’s specific visual identity (VI), color palette, and tone.

Solution: Combine the techniques above to create a “Brand VI Block.”

Define the Visuals: Codify your brand’s style. Include the color palette (you can even reference hex codes, though mileage may vary), lighting style (bright, clean studio lighting), camera style (stable tripod shots, no handheld motion), and overall tone (energetic and upbeat, serious and professional).
In-painting and Editing: For product placements, Veo’s editing capabilities will be key. You can generate a scene and then use in-painting or masking to specifically edit or insert a branded product, ensuring it looks seamlessly integrated. This provides a level of granular control that pure text-to-video cannot match.

Practical Workflow — Storyboarding a Multi-Shot Scene

Theory is one thing, but execution is another. Let’s walk through a concrete example of creating a short, three-shot narrative sequence using the consistency principles we’ve discussed.

The Concept: A detective, Elara, finds a crucial clue in a rain-soaked alley at night.

First, we establish our reusable “bibles” for the character and the scene’s style. This “pre-production” step is vital.

Character Bible:

CHARACTER: A woman in her late 20s named Elara. She has an oval face with prominent cheekbones, deep blue almond-shaped eyes, and a constellation of light freckles across her nose. Her hair is wavy, shoulder-length, and auburn. She wears a well-worn, dark brown leather jacket over a grey Henley shirt and dark-wash jeans.

Style Bible:

STYLE: Cinematic film noir. Moody, high-contrast lighting with deep shadows. The scene is set in a rain-slicked city alley at night, with reflections of pink and blue neon signs on the wet asphalt. Shot on 35mm film with a gritty, textured feel.

Now, we storyboard our sequence, one beat per prompt.

Shot 1: The Establishing Shot

Goal: Introduce the character and setting.

Prompt:

_[CHARACTER BIBLE]_ + _[STYLE BIBLE]_ + Wide shot. Elara walks slowly into frame from the left, her face determined as she scans the ground. The camera tracks smoothly with her movement.

Shot 2: The Discovery

Goal: Show the character finding something. This shot uses a motivated transition from Shot 1.

Prompt:

_[CHARACTER BIBLE]_ + _[STYLE BIBLE]_ + Medium shot. Elara stops and her eyes fix on something on the ground. She crouches down slowly, her hand reaching out towards the pavement just out of frame.

Shot 3: The Clue

Goal: A close-up reveal of the clue.

Prompt:

_[CHARACTER BIBLE]_ + _[STYLE BIBLE]_ + Extreme close-up from an over-the-shoulder (OTS) perspective. Elara’s fingers gently pick up a small, tarnished silver locket from a puddle on the asphalt. The reflection of neon signs is visible on the locket’s surface.

By pasting the verbatim bibles into each prompt and breaking the narrative into distinct, connected beats, we create a coherent sequence where the character, location, and aesthetic remain consistent.

Video 4: Storyboarding a Multi-Shot Scene (Image by Author).

The Hybrid Workflow — Generation Meets Editing

While text-to-video generation is incredibly powerful, the future of professional AI filmmaking lies in a hybrid workflow that combines generation with precise editing tools. Veo isn’t just a generator; it’s a component in a larger creative pipeline that will likely integrate with tools like Adobe After Effects or DaVinci Resolve.

The core idea is to use the generative model for the “heavy lifting” — ideation, animation, and complex textures — and then use editing features for refinement and control.

The Process:

Generate the Base Layer: Use the prompting techniques described above to generate your primary video clip. Focus on getting the motion, composition, and overall feel right. Don’t worry about small imperfections.
Masking for Targeted Edits: Once you have your clip, you can use masking to isolate specific regions of the video over time. For example, if a character’s logo on their shirt flickers or a background object looks out of place, you can draw a mask around that area.
In-painting and Out-painting: With a mask applied, you can issue a new prompt to regenerate only the masked area. This is where the true power lies.

In-painting (Correction): Use this to fix artifacts. If a character’s hand looks unnatural, mask it and prompt for “a realistic human hand, fingers slightly curled.” The model will regenerate the hand while keeping the rest of the scene intact. You can even use it for subtle performance changes, like masking a character’s mouth and prompting for a “slight smile.”
In-painting (Addition): Use this for product placement. Mask a table and prompt for “a can of branded 'Starlight Soda' sitting on the table.” This allows for perfect, on-brand object insertion.
Out-painting (Extension): This feature allows you to extend the frame of the video, generating new visual information beyond the original boundaries. This is perfect for changing aspect ratios (e.g., converting a 16:9 shot to a 9:16 for social media) or creating a wider, more panoramic shot from an existing clip.

This hybrid approach offers the best of both worlds: the speed and creativity of AI generation with the precision and control of traditional post-production, enabling a much higher standard of final output.

The Future is Direction

Google Veo and models of its caliber represent a fundamental shift. The bottleneck is no longer the technical ability to create pixels, but the creative and technical skill to direct the AI. The skillset of a modern creator is evolving from one of pure technical execution (e.g., mastering complex 3D software) to one of detailed creative specification and curation. By understanding the underlying architecture, adopting a systematic, directorial approach to prompting, and embracing a hybrid workflow that combines generation with editing, creators can move from generating novel curiosities to producing deliberate, consistent, and compelling cinematic narratives.

The age of the AI Director has arrived, and it promises to democratize storytelling in ways we are only beginning to imagine.

The Startup Fork In The Road

Sat, 07 Jun 2025 00:00:00 +0000

Linkaout Web Interface (Image by Author).

The Startup Fork in the Road: VC Funding vs. The Bootstrapper’s Journey

So, you’ve got a killer idea, the spark of entrepreneurial fire in your belly, and you’re ready to build. But before you dive headfirst into the exhilarating world of startups, there’s a fundamental question every founder must answer: How will you fuel your vision? Broadly, two paths diverge: seeking Venture Capital (VC) funding or embracing the often grittier, yet incredibly rewarding, path of bootstrapping. This isn’t just a financial decision; it’s a choice that shapes your company’s culture, your control, and your growth trajectory.

Let’s break down these two distinct approaches before we explore how one of these philosophies inspired me and Alked to create Linkaout, a map-based app designed to connect Londoners with local events, with a particular focus on how we approached development and launch as bootstrappers.

The VC Route: Rocket Fuel and High Stakes

Venture Capital funding is often portrayed as the glamorous path to startup stardom. It involves selling a portion of your company (equity) to investors in exchange for significant capital.

The Upsides of VC Funding:

Accelerated Growth: Access to substantial funds can mean scaling rapidly – hiring a large team, launching aggressive marketing campaigns, and capturing market share quickly.
Expertise and Network: VCs often bring more than just money. They can provide invaluable mentorship, industry connections, and strategic guidance.
Validation and Credibility: Securing VC funding can be seen as a stamp of approval, potentially attracting further investment, top talent, and customer trust.
Reduced Personal Financial Risk: The financial burden is shared with investors, lessening the direct hit on your personal savings.

The Downsides of VC Funding:

Loss of Control and Ownership: Giving away equity means giving away a degree of control. Founders may find their decision-making power diluted and be beholden to investor expectations.
Intense Pressure for Rapid Returns: VCs are looking for significant returns on their investment, often within a 5-10 year timeframe. This can create immense pressure to prioritize hyper-growth, sometimes at the expense of sustainable profitability or the founder’s original vision.
Focus on Growth over Profitability (Initially): The mantra is often “grow big, fast,” with profitability sometimes taking a backseat in the early stages.
Exit Strategy Focus: Most VCs invest with an exit in mind, such as an acquisition or an Initial Public Offering (IPO). This might not align with every founder’s long-term goals.

The Bootstrapper’s Creed: Building Brick by Brick

Bootstrapping, on the other hand, is the art of building a company from the ground up with little to no external funding. It relies on personal savings, revenue generated by the business itself, and a relentless focus on lean operations.

The Upsides of Bootstrapping:

Full Ownership and Control: You retain 100% ownership of your company and make all the decisions. Your vision remains undiluted.
Focus on Profitability and Sustainability: Since you’re relying on your own revenue to grow, profitability becomes a key focus from day one, often leading to more resilient and sustainable business models.
Freedom and Flexibility: You have the autonomy to pivot, adapt, and grow at your own pace without external investor pressure.
Customer-Centricity: Bootstrappers are often laser-focused on their customers, as paying users are the lifeblood of their growth.
Fosters Creativity and Resourcefulness: Limited resources force you to be innovative and find cost-effective solutions.

The Downsides of Bootstrapping:

Slower Growth: Growth is typically more organic and can be slower compared to VC-backed competitors with deep pockets.
Personal Financial Risk: You’re often investing your own money, making the financial stakes very personal.
Limited Resources: Scaling can be challenging without significant capital for marketing, hiring, or large-scale development.
Building Credibility Can Take Longer: Without the halo effect of VC backing, establishing credibility and attracting talent can require more persistent effort.

The “Why” and “How” of Linkaout: A Bootstrapping Tale

This brings us to Linkaout.

Why?

The idea was born from the bootstrapping philosophy, popularised by figures like Pieter Levels—known for his mantra of building and launching products quickly to get real feedback from users. This “Indie Hacker” or “Maker” ethos champions rapid iteration and a direct line to the customer. Living in London, we often found it difficult to discover local events without switching between multiple platforms. That’s why we created Linkaout—a map-based app that helps you easily discover what’s happening around you, in the most intuitive way possible (Figure 1). The core motivation was to solve a personal pain point, a common starting place for many bootstrapped ventures, and to do so by building something people would genuinely use and, ideally, pay for, ensuring sustainability from the outset.

Figure 1: Linkaout Web Interface (Image by Author).

How? The Lean Development and Launch Process

In true bootstrapping fashion, the approach was lean and agile. We built on tools we were familiar with—or had heard good things about—and quickly got to work. There was no lengthy fundraising process or a large, pre-hired team. Our first version included a simple map that let users create events in London, along with a login system, profile pages to view created events, and other basic features to immediately showcase the app’s potential.

This wasn’t about perfecting every detail before launch. It was about identifying the core problem and building the absolute minimum required to see if the solution resonated with users. This led us to embrace a lean tech stack and strategically leverage free-tier services to keep costs to a minimum while maximizing development speed and flexibility.

Here’s a closer look at the ‘how’ for a bootstrapped app like Linkaout:

1. Choosing a Lean and Cost-Effective Tech Stack:

Bootstrappers need technology that is powerful, easy to use, and ideally offers a generous free tier to defer costs until revenue is generated. For Linkaout, or similar bootstrapped projects, a stack like the following is highly effective:

Supabase (Backend: Database, Authentication, Storage, Realtime): As an open-source Firebase alternative, Supabase provides a powerful PostgreSQL database with built-in features like authentication, file storage, and real-time subscriptions. Its free tier is remarkably generous, offering sufficient database storage (e.g., 500MB), file storage (e.g., 1GB), and bandwidth for initial development and gaining early users. This eliminates the need for a dedicated backend team or managing complex server infrastructure from day one. Setting up user accounts, storing event data, and handling user uploads can all be done within Supabase’s free limits for a considerable time. The unlimited API requests in the free tier are a significant advantage for apps expecting variable usage.
NextJS (Web Frontend): A React framework that enables server-side rendering and static site generation. This is excellent for building fast, SEO-friendly web applications. For a bootstrapped team, NextJS streamlines front-end development, providing a solid structure and performance optimizations out-of-the-box. You can build your web presence, marketing site, or even parts of your application interface efficiently. Its flexibility allows for building everything from a simple landing page to a more complex web application.
Netlify (Web Hosting & Serverless Functions): Netlify offers a fantastic platform for hosting static websites and serverless functions directly from your Git repository. Their free tier provides ample bandwidth (e.g., 100GB/month), build minutes (e.g., 300 minutes/month), and serverless function invocations (e.g., 125,000/month). This is more than enough to host a performant web application or landing page for a bootstrapped product and handle initial API calls via functions without incurring hosting costs. The seamless integration with Git makes the deployment process incredibly simple and fast.
FlutterFlow (Cross-Platform Mobile App Development): This is a low-code platform specifically designed for building native mobile applications (iOS and Android) using Google’s Flutter framework, and also supports web app development. FlutterFlow dramatically accelerates the UI build process with drag-and-drop components and integrates easily with backends like Supabase. For bootstrappers, this means building a high-quality, cross-platform mobile app can be done significantly faster and often without deep native mobile development expertise, saving considerable time and money. While FlutterFlow has paid tiers for advanced features and code export, their free tier allows for building and testing, providing a clear path to see if the platform meets your needs before committing financially. The ability to export code later also provides a safety net if more custom development is needed down the line.

By combining tools like these, a bootstrapped team can build a robust, scalable application with authentication, a database, file storage, a web presence, and native mobile apps, all while staying within free-tier limits during the crucial early stages of development and validation. The focus is on speed, functionality, and minimizing burn rate. This lean stack minimizes complexity and allows a small team (or even a solo founder) to manage the entire development process, potentially leveraging AI tools like Cursor for code generation and assistance, or Lovable for user feedback analysis to further streamline the process.

Linkaout architecture design for the whole application is shown below in Figure 2:

Figure 2: Linkaout Architecture (Image by Author).

What’s remarkable is just how low the initial financial outlay can be. For Linkaout, the core development and initial launch costs were incredibly modest, primarily consisting of:

Figure 3: Linkaout Development Costs (Image by Author).

This demonstrates that the barrier to entry for launching a functional, cross-platform product is significantly lower than many might assume, thanks to the power of modern, developer-friendly tools and generous free tiers.

2. The “MVP of an MVP” Approach:

Instead of aiming for a feature-rich application, the goal is to build the absolute minimum required to test the core value proposition. For Linkaout, this meant a map, the ability to create events, and user profiles. This stripped-down approach ensures you don’t waste time building features nobody wants. It forces clarity on what is truly essential for the first version that users will interact with. This initial version should be functional enough to gather genuine user feedback on the core concept.

3. Rapid Iteration and User Feedback:

With a lean stack and an MVP, the focus shifts to getting the product in front of real users as quickly as possible. As soon as we had a working MVP—an MVP of an MVP, you could say—we launched it across the web, the App Store, and Google Play. This aligns perfectly with the bootstrapping principle of getting your product in front of real users as quickly as possible to gather crucial feedback.

Launching to Gain Traction: Getting Your Product Seen

The initial launch isn’t the end; it’s the beginning of a conversation with your market. For bootstrapped apps, gaining initial visibility without a massive marketing budget is key. This involves strategically leveraging platforms and communities where your target users spend time.

Here are some common approaches for launching a bootstrapped product:

Product Hunt: A popular platform for discovering new products. A well-executed launch can provide a significant surge of early adopters and valuable feedback from a tech-savvy community. Strategies include building anticipation with a “Coming Soon” page, engaging with the community beforehand, crafting a compelling product page with visuals and a demo, planning for launch day engagement, and following up with supporters.
App Stores (Apple App Store, Google Play Store): For mobile apps, launching on the major app stores is essential. Focus on clear descriptions, compelling screenshots, and optimizing for relevant keywords to improve discoverability. Encourage early users to leave reviews.
Online Communities and Forums: Identify online communities, forums, and social media groups relevant to your product’s niche. Share your product in a non-spammy way, focusing on how it solves a specific problem for that community. Be prepared to engage and answer questions.
Content Marketing: Create valuable content (blog posts, tutorials, videos) related to your product’s domain. This can attract organic traffic and establish your expertise, driving users to your product.
Direct Outreach: Reach out to potential early adopters directly, whether through personal networks, targeted emails (if you have a relevant list), or introductions.

The key for bootstrappers is to choose launch channels that align with their target audience and leverage them effectively with limited resources. The goal is to get the product in front of real users to gather feedback and begin building traction.

Improving the Product

After the launch, we began iterating, adding small but meaningful features based on real user feedback gathered from initial usage and various launch efforts. This iterative process, driven by direct user input rather than boardroom directives, is a hallmark of a bootstrapped company that must stay closely attuned to its customers’ needs to survive and thrive. Every feature added, every bug fixed, is a direct response to what the market is telling you, ensuring that limited resources are always focused on delivering maximum value.

This level of agility gives bootstrapped products a distinct advantage over large corporations and well-known apps, where new ideas often get stuck in endless meetings and approval loops. By staying lean and responsive, you can move faster, adapt quicker, and deliver what users want, before the competition even has time to react.

Conclusion: Choosing the Path Less Traveled and Planning for the Future

The choice between VC funding and bootstrapping is a deeply personal one, with significant implications for a startup’s journey. While VC can provide rapid acceleration, bootstrapping offers control, sustainability, and a direct connection with your users. For Linkaout, the bootstrapping path, empowered by a lean tech stack and strategic launch platforms, allowed us to quickly turn an idea into a working product, gather real-world feedback, and begin the process of building a sustainable business, brick by brick. It’s a path that demands resourcefulness and resilience, but offers the profound reward of building something truly yours, guided by the needs of the people you aim to serve.

For those embarking on the entrepreneurial journey, especially if you’re starting solo, resources like YC Startup School can be invaluable. Beyond providing foundational knowledge, they offer platforms, such as co-founder matching, that can help connect you with potential partners who share your vision and complementary skills.

Furthermore, the bootstrapping journey doesn’t mean you’re locked into running the business forever. Unlike the often high-stakes exit demands of VC, bootstrappers have more flexibility in how they eventually move on. Options can include selling the business on platforms specifically designed for smaller, profitable online businesses like BuyMyMicroStartup, or pursuing Entrepreneurship Through Acquisition (ETA), where an individual or small group acquires a controlling stake in a mature, profitable small business with the intent of running it. These avenues provide alternative exit opportunities that align with the sustainable, profitable nature of many bootstrapped ventures.

This article was co-written with Alked Ejupi.

Building a European Property Investment Agent with Google ADK

Mon, 26 May 2025 00:00:00 +0000

Agent Development Kit Frontend (Image by Author).

Building a European Property Investment Agent with Google ADK

:memo: Please Note
This is a guest post originally published on Google Cloud - Community.

End to end demonstration on how to build AI Agents using Google Agent Development Kit

The world of AI agents is rapidly evolving, offering exciting possibilities for automating tasks and providing specialized assistance. In fields like finance and investment, where analyzing vast amounts of dynamic data is crucial, AI agents can act as powerful assistants, sifting through information, identifying trends, and providing tailored insights. Google’s Agent Development Kit (ADK) is a powerful framework designed to help developers build, test, and deploy these sophisticated agents with relative ease. In this post, we’ll walk through a practical example: creating a simple, yet illustrative, agent capable of providing insights into European property investment hotspots and economic outlooks. This project demonstrates how to structure an agent using the ADK’s core concepts to handle specific domain-related queries.

What is Google ADK?

The Google Agent Development Kit (ADK) is a robust framework that simplifies the process of building AI agents powered by large language models (LLMs). At its heart, the ADK provides a structured way to define an agent’s capabilities. It allows developers to specify the LLM model the agent will use, provide clear instructions on how the agent should behave, and equip it with “tools” — essentially, functions or APIs the agent can call to perform specific actions or retrieve external information.

One of the key strengths of the ADK is its support for creating hierarchies of agents. This pattern, often referred to as a “coordinator-worker” or “orchestrator” pattern, allows you to build complex agents by breaking down capabilities into smaller, more manageable specialized agents. A high-level “coordinator” agent receives the initial user query, understands the user’s intent, and then delegates the task to the most appropriate “worker” agent. This modular approach makes agents easier to develop, debug, and scale, as each worker agent can be focused on a specific domain or task, equipped with only the tools it needs. This contrasts with building a single, monolithic agent that tries to handle everything, which can quickly become unwieldy.

Setting Up Your Environment

Before we dive into the code that defines our European property investment agent, you need to set up your development environment. For this demonstration, I utilized a Google Cloud Workstation, which offers a convenient, pre-configured cloud-based environment, saving the hassle of local setup complexities. However, you can also set this up on a local machine with Python installed.

Install the Google ADK

Open your terminal or Cloud Workstation command line and run the following command to install the necessary Python library from PyPI:

pip install google-adk

This command fetches and installs the core ADK library and its dependencies, giving you access to the classes and functions needed to define your agents and tools.

Authenticate with Google Cloud

If you plan to use Google Cloud services, such as Vertex AI for accessing powerful LLMs like Gemini, you’ll need to authenticate your development environment. This command sets up your application default credentials, allowing your code running in the environment to access Google Cloud resources securely:

gcloud auth application-default login

Follow the prompts to log in with your Google account. This step is crucial if GOOGLE_GENAI_USE_VERTEXAI is set to “TRUE” in your environment configuration.

Project Structure

Our project is organized within a standard Python package structure. The main code resides in a folder named europe_property_investor. Inside this folder, we have a few key files that define our agent and its configuration:

europe_property_investor/
├── .env
├── __init__.py
└── agent.py

This structure is clean and follows Python best practices for creating reusable modules.

Let’s look at the purpose of each file:

.env

This file is used to store environment variables that configure our agent’s runtime behavior, particularly its connection to Google Cloud services. Using a .env file is a common practice for managing configuration settings separately from your code, making it easy to change settings without modifying the core logic.

GOOGLE_CLOUD_PROJECT="TODO" # Replace TODO with your Google Cloud Project ID
GOOGLE_CLOUD_LOCATION="us-central1" # e.g., us-central1 or europe-west1
GOOGLE_GENAI_USE_VERTEXAI="TRUE"

You must replace “TODO” with your actual Google Cloud Project ID. The GOOGLE_CLOUD_LOCATION specifies the region for Vertex AI, and GOOGLE_GENAI_USE_VERTEXAI=”TRUE” tells the ADK to use Vertex AI for accessing the Gemini model, rather than the public GenAI API.

init.py

This file is essential for Python to recognize the europe_property_investor directory as a package. It can also be used to control which objects are exposed when the package is imported. In our simple case, it primarily serves to make the main root_agent directly accessible from the package level.

from . import agent
from .agent import root_agent

By importing root_agent here, we can easily refer to our main agent when running the ADK web interface command later.

agent.py

This is the core of our agent application. It contains all the definitions for the tools our agent can use, the specialized “worker” agents that handle specific tasks, and the main “coordinator” agent that acts as the entry point for user interactions and orchestrates the flow by delegating tasks to the appropriate workers.

Let’s break down the key components within agent.py:

Imports and Configuration

We begin by importing the necessary classes from the google.adk library, as well as standard Python typing utilities. We also define the specific LLM model we intend to use.

import os
from google.adk.agents import Agent 
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.google_search_tool import google_search
from typing import TypedDict, List, Optional, Dict, Any

MODEL_NAME = "gemini-2.0-flash" 

Using gemini-2.0-flash provides a good balance of performance and cost-effectiveness for many agent tasks. You could experiment with other models depending on your specific needs and budget.

TypedDict Definitions

TypedDict from the typing module is a powerful feature that allows us to define dictionaries with specific keys and value types. While not strictly required by the ADK, using TypedDict for the output of our tools is highly recommended. It serves as clear documentation for the structure of the data the tool returns, which is invaluable for maintainability. Crucially, this type information is also provided to the LLM, helping it better understand the data it receives from tool calls and improving its ability to process and respond based on that data.

# --- TypedDict Definitions (Shared by relevant agents/tools) ---
class PropertyHotspot(TypedDict):
    location: str
    country: str
    property_types_favored: List[str]
    reasoning: str
    potential_appreciation_outlook: str
    average_rental_yield_pa: Optional[str]
    market_sentiment: str
    risk_level: str
    key_drivers: List[str]
    potential_headwinds: List[str]
    investment_horizon_suitability_years: str
    data_source_year: str

class EconomicOutlook(TypedDict):
    country: str
    gdp_growth_forecast_pa: str
    inflation_rate_pa: str
    stability_assessment: str
    key_economic_notes: List[str]
    data_source_year: str

These definitions clearly outline the expected data fields for property hotspots and economic outlooks, making the code more readable and helping the LLM interpret the tool results accurately.

Tool Function Definitions

These are standard Python functions that encapsulate specific capabilities our agent needs. The ADK allows the LLM to call these functions dynamically based on the user’s request and the agent’s instructions. In a real-world application, these functions would typically interact with external services, databases, or APIs to fetch real-time data or perform actions. For this demonstration, we use simple mock data stored directly within the functions to simulate the tool’s behavior.

get_european_property_hotspots: This function simulates fetching information about promising European real estate investment locations. It accepts parameters that allow filtering by countries, investment horizon, risk appetite, and property type focus, demonstrating how the LLM can pass arguments to tools.

def get_european_property_hotspots(
    countries_of_interest: Optional[List[str]] = None,
    investment_horizon_years: Optional[int] = None,
    risk_appetite: Optional[str] = None,
    property_type_focus: Optional[List[str]] = None
) -> List[Dict[str, Any]]:
    """
    Fetches detailed information on promising European real estate investment locations.
    This tool can be filtered by countries, investment horizon, risk appetite, and property type focus.
    Returns a list of dictionaries, each representing a property hotspot with detailed attributes.
    """
    print(
        f"Tool (get_european_property_hotspots) called with countries: {countries_of_interest}, "
        f"horizon: {investment_horizon_years} years, risk: {risk_appetite}, types: {property_type_focus}"
    )
    all_hotspots_data: List[PropertyHotspot] = [
        {
            "location": "Lisbon (Principe Real, Alfama)", "country": "Portugal",
            "property_types_favored": ["Renovated Apartments", "Luxury Residences", "Residential"],
            "reasoning": "Sustained international demand, strong tourism, tech hub growth. Prime areas continue to appreciate.",
            "potential_appreciation_outlook": "High (6-9% annually in prime zones)", "average_rental_yield_pa": "3-4.5%",
            "market_sentiment": "Positive", "risk_level": "Medium",
            "key_drivers": ["Golden Visa (historic impact)", "Tech sector", "Tourism", "Lifestyle appeal"],
            "potential_headwinds": ["Rising prices affecting affordability", "Regulatory changes for short-term rentals"],
            "investment_horizon_suitability_years": "5-10", "data_source_year": "2025 Q1"
        },
        {
            "location": "Porto (Cedofeita, Bonfim)", "country": "Portugal",
            "property_types_favored": ["Residential Apartments", "Guesthouses", "Residential"],
            "reasoning": "More affordable than Lisbon with significant growth, vibrant culture, and increasing tourism.",
            "potential_appreciation_outlook": "High (7-10% annually)", "average_rental_yield_pa": "4-6%",
            "market_sentiment": "Very Positive", "risk_level": "Medium",
            "key_drivers": ["Tourism growth", "Urban regeneration", "Lower entry point than Lisbon"],
            "potential_headwinds": ["Infrastructure strain with growth", "Increased competition"],
            "investment_horizon_suitability_years": "5-7", "data_source_year": "2025 Q1"
        },
        {
            "location": "Valencia (Ruzafa, El Cabanyal)", "country": "Spain",
            "property_types_favored": ["Beachfront properties (El Cabanyal)", "Modern Apartments (Ruzafa)", "Residential", "Vacation"],
            "reasoning": "Excellent quality of life, growing tech scene, more affordable than Barcelona/Madrid. Coastal regeneration.",
            "potential_appreciation_outlook": "Medium-High (5-8% annually)", "average_rental_yield_pa": "4-5.5%",
            "market_sentiment": "Positive", "risk_level": "Medium",
            "key_drivers": ["Lifestyle", "Tech investment", "Tourism", "University city"],
            "potential_headwinds": ["Some areas saturated", "Local rental regulations"],
            "investment_horizon_suitability_years": "3-7", "data_source_year": "2025 Q1"
        },
        {
            "location": "Malaga City", "country": "Spain",
            "property_types_favored": ["City center apartments", "Properties near tech park", "Residential", "Vacation"],
            "reasoning": "Significant urban renewal, cultural hub, growing tech presence beyond just Costa del Sol tourism.",
            "potential_appreciation_outlook": "Medium-High (5-7% annually)", "average_rental_yield_pa": "4-5%",
            "market_sentiment": "Positive", "risk_level": "Medium-Low",
            "key_drivers": ["Tech hub development", "Cultural tourism", "Infrastructure investment"],
            "potential_headwinds": ["Seasonal tourism dependency in wider region", "Price increases in prime spots"],
            "investment_horizon_suitability_years": "5-10", "data_source_year": "2025 Q1"
        },
        {
            "location": "Athens (Koukaki, Pangrati)", "country": "Greece",
            "property_types_favored": ["Renovated apartments for short/long term let", "Golden Visa eligible properties", "Residential"],
            "reasoning": "Economic recovery, tourism boom, and government incentives. Focus on central, well-connected areas.",
            "potential_appreciation_outlook": "Medium (4-7% annually)", "average_rental_yield_pa": "4-6%",
            "market_sentiment": "Cautiously Optimistic", "risk_level": "Medium-High",
            "key_drivers": ["Tourism", "Golden Visa", "Infrastructure upgrades", "Low starting base"],
            "potential_headwinds": ["Bureaucracy", "Geopolitical factors in region", "Taxation uncertainties"],
            "investment_horizon_suitability_years": "5-7", "data_source_year": "2025 Q1"
        },
        {
            "location": "Warsaw (Mokotów, Srodmiescie)", "country": "Poland",
            "property_types_favored": ["New build apartments", "Buy-to-let residential", "Residential"],
            "reasoning": "Strong domestic economy, increasing foreign investment, major business services hub. Relatively stable.",
            "potential_appreciation_outlook": "Medium (4-6% annually)", "average_rental_yield_pa": "5-6.5%",
            "market_sentiment": "Positive", "risk_level": "Medium-Low",
            "key_drivers": ["Economic growth (pre-war regional stability)", "Business outsourcing", "Young population"],
            "potential_headwinds": ["Regional geopolitical tensions (Ukraine impact)", "Inflationary pressures"],
            "investment_horizon_suitability_years": "5-10", "data_source_year": "2025 Q1"
        },
        {
            "location": "Budapest (District VII, IX)", "country": "Hungary",
            "property_types_favored": ["Renovation projects", "Short-term rental units", "Residential", "Vacation"],
            "reasoning": "Major tourist destination, relatively low prices for a European capital, vibrant culture.",
            "potential_appreciation_outlook": "Medium (3-6% annually)", "average_rental_yield_pa": "4.5-6%",
            "market_sentiment": "Neutral to Cautiously Optimistic", "risk_level": "Medium-High",
            "key_drivers": ["Tourism", "University city", "Foreign investment in specific sectors"],
            "potential_headwinds": ["Government policies", "Currency fluctuations (HUF)", "Oversupply in certain rental segments"],
            "investment_horizon_suitability_years": "3-7", "data_source_year": "2025 Q1"
        }
    ]
    filtered_hotspots_data = all_hotspots_data
    if countries_of_interest:
        filtered_hotspots_data = [
            spot for spot in filtered_hotspots_data
            if spot["country"].lower() in [country.lower() for country in countries_of_interest]
        ]
    if risk_appetite:
        normalized_risk_appetite = risk_appetite.lower()
        if "low" in normalized_risk_appetite: risk_levels_to_match = ["low", "medium-low"]
        elif "high" in normalized_risk_appetite: risk_levels_to_match = ["high", "medium-high"]
        elif "medium" in normalized_risk_appetite: risk_levels_to_match = ["medium", "medium-low", "medium-high"]
        else: risk_levels_to_match = [normalized_risk_appetite]
        filtered_hotspots_data = [spot for spot in filtered_hotspots_data if spot["risk_level"].lower() in risk_levels_to_match]
    if property_type_focus:
        temp_filtered = []
        normalized_property_type_focus = [ptf.lower() for ptf in property_type_focus]
        for spot in filtered_hotspots_data:
            spot_favored_types_lower = [fav_type.lower() for fav_type in spot["property_types_favored"]]
            if any(focused_type in spot_favored_types_lower for focused_type in normalized_property_type_focus):
                temp_filtered.append(spot)
        filtered_hotspots_data = temp_filtered

    if not filtered_hotspots_data:
        criteria_summary = []
        if countries_of_interest: criteria_summary.append(f"countries: {', '.join(countries_of_interest)}")
        if investment_horizon_years is not None: criteria_summary.append(f"horizon: {investment_horizon_years} years")
        if risk_appetite: criteria_summary.append(f"risk: {risk_appetite}")
        if property_type_focus: criteria_summary.append(f"types: {', '.join(property_type_focus)}")
        reasoning_message = "No specific hotspots found matching all criteria: " + "; ".join(criteria_summary) + f". Current data from {all_hotspots_data[0]['data_source_year'] if all_hotspots_data else 'N/A'}."
        return [{"location": "N/A", "country": "N/A", "property_types_favored": [], "reasoning": reasoning_message, "potential_appreciation_outlook": "N/A", "average_rental_yield_pa": "N/A", "market_sentiment": "N/A", "risk_level": "N/A", "key_drivers": [], "potential_headwinds": [], "investment_horizon_suitability_years": "N/A", "data_source_year": "N/A"}]
    
    return filtered_hotspots_data

The print statement inside the function is a simple way to see when the tool is called and what arguments the LLM provides, which is helpful for debugging. The filtering logic demonstrates how a real tool might process parameters to refine its results.

get_country_economic_outlook: This function simulates retrieving economic data for a given European country.

def get_country_economic_outlook(country: str) -> Dict[str, Any]:
    """
    Provides a brief economic outlook (GDP growth, inflation, stability)
    for a specified European country. Returns a dictionary containing economic details.
    """
    print(f"Tool (get_country_economic_outlook) called for {country}")
    outlooks_data: Dict[str, EconomicOutlook] = {
        "portugal": {"country": "Portugal", "gdp_growth_forecast_pa": "1.8%", "inflation_rate_pa": "2.5%", "stability_assessment": "Moderately Stable", "key_economic_notes": ["Tourism dependent", "EU recovery funds boosting investment", "Focus on tech growth"], "data_source_year": "2025 H1"},
        "spain": {"country": "Spain", "gdp_growth_forecast_pa": "2.1%", "inflation_rate_pa": "2.8%", "stability_assessment": "Moderately Stable", "key_economic_notes": ["Strong tourism rebound", "Renewable energy investment", "Regional disparities"], "data_source_year": "2025 H1"},
        "greece": {"country": "Greece", "gdp_growth_forecast_pa": "2.5%", "inflation_rate_pa": "3.2%", "stability_assessment": "Improving", "key_economic_notes": ["Post-bailout recovery", "Investment in infrastructure", "High national debt remains a concern"], "data_source_year": "2025 H1"},
        "poland": {"country": "Poland", "gdp_growth_forecast_pa": "3.0%", "inflation_rate_pa": "4.5%", "stability_assessment": "Stable but watchful (geopolitics)", "key_economic_notes": ["Strong manufacturing base", "Proximity to Ukraine war poses some risk/impact", "EU funding utilization key"], "data_source_year": "2025 H1"},
        "hungary": {"country": "Hungary", "gdp_growth_forecast_pa": "2.2%", "inflation_rate_pa": "5.0%", "stability_assessment": "Moderately Stable with political variables", "key_economic_notes": ["Dependent on foreign manufacturing (automotive)", "EU funds disputes", "Forint volatility"], "data_source_year": "2025 H1"}
    }
    result_data = outlooks_data.get(country.lower())
    
    if result_data:
        return result_data 
    else:
        return {
            "country": country, "gdp_growth_forecast_pa": "N/A", "inflation_rate_pa": "N/A", 
            "stability_assessment": "Data not available in mock set", 
            "key_economic_notes": ["No specific data for this country in the current simulated dataset."], 
            "data_source_year": "N/A"
        }

Again, this uses mock data but illustrates how a tool would take a specific input (a country name) and return structured information.

Worker Agent Definitions

Worker agents are specialized agents designed to handle specific types of queries by utilizing a limited set of relevant tools. This specialization makes their instructions simpler and their behavior more predictable for their specific domain.

property_hotspots_agent: This agent is solely focused on providing information about property investment locations. It is equipped with only the get_european_property_hotspots tool. Its instruction guides it to use this tool based on the criteria provided by the user.

property_hotspots_agent = Agent(
    name="PropertyHotspotsAgent",
    model=MODEL_NAME,
    instruction="You are a specialist in European property hotspots. You have one tool to find detailed property investment locations. Use it based on the user's criteria (countries, investment horizon, risk appetite, property type focus).",
    description="Provides detailed information on promising European real estate investment locations.",
    tools=[get_european_property_hotspots] 
)

Its instruction is concise and directly relates to the capability of its single tool.

economic_outlook_agent: This agent specializes in providing economic summaries for countries. It is equipped with only the get_country_economic_outlook tool.

economic_outlook_agent = Agent(
    name="EconomicOutlookAgent",
    model=MODEL_NAME,
    instruction="You are a specialist in European country economic outlooks. You have one tool to fetch economic data (GDP, inflation, stability) for a given country.",
    description="Provides a brief economic outlook for a specified European country.",
    tools=[get_country_economic_outlook] 
)

Similarly, its instruction is tailored to the economic outlook domain.

google_search_agent: This agent serves as a general-purpose fallback for queries that cannot be handled by the more specialized agents. It wraps the standard google_search tool provided by the ADK.

google_search = Agent(
    name="GoogleSearch",
    model=MODEL_NAME,
    instruction="You are a web search assistant. You have one tool for performing Google searches. Use it to find specific, recent information or anything not covered by other specialized agents.",
    description="Performs Google searches for general information or recent news.",
    tools=[google_search], 
)

google_search_grounding = AgentTool(agent=google_search)

google_search_agent = Agent(
    name="GoogleSearchAgent",
    model=MODEL_NAME,
    instruction="Given a query that its not possible to ask using PropertyHotspotsAgent and EconomicOutlookAgent use Google Search to find an answer. If no answer is found, inform the user you don't know the answer. Inform the user, you are using Google Search to reply. If the user asks anything not related to European Property Investment, decline to answer.",
    description="Uses Google search to attempt to answer questions that are not possible to answer using PropertyHotspotsAgent and EconomicOutlookAgent",
    tools=[google_search_grounding]
)

This agent’s instruction is crucial — it tells it to only use search if the other agents can’t answer and to stay within the domain of European Property Investment.

Coordinator Agent Definition

The root_agent is the top-level agent and the one directly invoked by the ADK web interface. Its primary role is not to answer queries itself, but to understand the user’s intent and delegate the task to the most appropriate specialized worker agent. This is where the orchestration happens.

# --- Coordinator Agent Definition ---
# This is the agent that will be invoked by 'adk web'
root_agent = Agent(
    name="EuropePropertyInvestmentCoordinator",
    model=MODEL_NAME,
    instruction=(
        "You are a coordinator agent for European property investment analysis. "
        "Your role is to understand the user's query and delegate the task to the most appropriate specialized agent. "
        "You have access to the following specialized agents:\n"
        "- **PropertyHotspotsAgent**: Use this agent to find detailed information about specific property investment locations, including filtering by criteria like country, risk, and property type.\n"
        "- **EconomicOutlookAgent**: Use this agent to get the general economic outlook for a specific country (e.g., GDP growth, inflation).\n"
        "- **GoogleSearchAgent**: Use this agent for very recent news, highly specific details not covered by other agents, or broader web searches.\n\n"
        "Follow these steps:\n"
        "1. Analyze the user's query to determine the type of information needed.\n"
        "2. If the query is broad or unclear for a specific task (e.g., 'best investments' without criteria for PropertyHotspotsAgent), ask clarifying questions to get necessary details (like preferred countries, risk appetite, investment horizon, property types).\n"
        "3. Choose the single best specialized agent for the core task. For example, if the user asks for 'property hotspots in Spain with medium risk', delegate to PropertyHotspotsAgent. If they ask 'economic outlook for Portugal', delegate to EconomicOutlookAgent. If they ask 'recent property news in Berlin', delegate to GoogleSearchAgent.\n"
        "4. Clearly state which agent you are delegating to and what you are asking it to do.\n"
        "5. Relay the information from the specialized agent back to the user in a clear and helpful manner.\n"
        "6. If a query requires information from multiple domains (e.g., property hotspots AND economic outlook for those countries), you might need to break it down and call relevant agents sequentially, presenting a synthesized answer. However, for a single user turn, focus on the primary intent and choose one agent if possible, or explain the need for multiple steps."
        "Do not try to use tools directly yourself; your function is to coordinate your sub-agents."
    ),
    description="Coordinates property investment queries by delegating to specialized agents for property hotspots, economic outlooks, and web searches.",
    sub_agents=[
        property_hotspots_agent,
        economic_outlook_agent,
        google_search_agent,
    ]
)

The instruction for the root_agent is the most detailed, as it defines the agent’s overall strategy for handling user requests. It explicitly lists the available sub-agents and provides a step-by-step process for analyzing the query, asking clarifying questions when needed, selecting the appropriate sub-agent, and relaying the final response. This clear instruction is critical for guiding the LLM’s reasoning and delegation process.

Running the Agent

With the .env, init.py, and agent.py files correctly set up in your europe_property_investor directory, you can now run your agent using the ADK command-line interface. Navigate in your terminal to the directory containing your europe_property_investor folder and execute the following command:

adk web

This command does several things: it finds the root_agent defined in your package (thanks to the init.py file), initializes it, and starts a local web server. This server provides a simple chat interface in your web browser, allowing you to interact directly with your root_agent.

Once the server is running (usually accessible at http://localhost:8000), open your web browser and navigate to the provided address. You’ll see a chat window where you can type your queries related to European property investment (Figure 1).

Figure 1: Live Demonstration of Agent Frontend (Video by Author).

Try typing queries such as:

“Tell me about property hotspots in Portugal.” (This should trigger the PropertyHotspotsAgent)
“What is the economic outlook for Spain?” (This should trigger the EconomicOutlookAgent)
“Find recent news about property market changes in Berlin.” (This should trigger the GoogleSearchAgent)
“What are the best investment opportunities?” (This should likely prompt the root_agent to ask for clarification, as per its instruction).

Observe how the root_agent processes your request, identifies the relevant information needed, and then delegates the task to the appropriate specialized worker agent. The worker agent will then use its assigned tool (either fetching mock data or performing a simulated search), and the root_agent will present the result back to you in a conversational manner. This interaction loop demonstrates the power of the coordinator-worker pattern in action.

Conclusion

This practical demonstration using the Google Agent Development Kit illustrates how you can build intelligent agents with structured behavior. By defining specialized tools and organizing agents in a hierarchical coordinator-worker pattern, you can create applications that are modular, maintainable, and capable of handling complex, domain-specific queries.

While this “Europe Property Investor” agent currently uses mock data, it provides a solid foundation. The next steps could involve integrating real-time data sources — such as financial market APIs, real estate listing services, or economic data providers — into the tool functions. You could also expand the capabilities by adding more specialized worker agents and tools, perhaps for analyzing specific property types (commercial, industrial), assessing legal or tax implications, or even performing rudimentary financial modeling. The modularity offered by the ADK makes such expansions significantly more manageable. Experiment with different queries and observe how the root_agent delegates to the worker agents; understanding this flow is key to building more sophisticated agents with the Google ADK!

LLMs Evaluation on GCP

Sun, 13 Apr 2025 00:00:00 +0000

AI Generated (Image by Author).

LLMs Evaluation on GCP

:memo: Please Note
This is a guest post originally published on Google Cloud - Community.

An introduction to some of the most common evaluation approaches for LLM applications and how GCP can support you across the journey.

Introduction

Widespread availability and fast-tracked progresses in LLM performance have made it really easy for practitioners to develop fully fledged AI backed applications in a matter of days. Regardless, even if the road to production may be paved with good intentions, it’s too often littered with the wrecks of projects that skipped rigorous pre-production evaluation. Thorough testing and validation are the essential guardrails that keep a system on track and prevent costly, late-stage failures.

The foundational model of choice is merely the source of an LLM’s backed application potential (Figure 1). True evaluation is charting the full course of the river: the data that forms its currents, the infrastructure that shapes its banks, and the applications that are its ultimate destination. Only by understanding this entire flow can we predict whether the LLM will reach its potential or run dry before it meets the sea.

Figure 1: LLM Evaluation Overview (Image by Author).

Defining a standardized way to evaluate an LLM can not only make it possible to quantify the model accuracy but also:

Tracking progress over different development iterations.
Streamline comparison between different models.
Optimizing for fair use (e.g. creating transparent and reproducible processes for bias mitigation).
Meeting regulatory and Service Level Agreements (SLAs) requirements.

Metrics

Metrics to evaluate LLMs can be further divided into 2 categories: quantitative and qualitative.

Quantitative metrics can be easily calculated using numeric formulas, some examples include (Figure 2):

Perplexity: how well the model can predict the next word in a sentence (the lower, the better).
ROUGE (Recall-Oriented Understudy for Gisting Evaluation): is used for text summarization tasks and checks the overlap between human summaries and LLM generated summaries. ROUGE focuses mainly on recall.
BLEU (Bilingual Evaluation Understudy): is used for translation tasks and assesses the LLM output against a reference translation. BLEU focuses instead primarily on precision.
Accuracy: for traditional classification tasks (e.g. spam/not spam).

Figure 2: LLMs Tasks vs Metrics (Image by Author).

Qualitative metrics focus more on capturing overall language/content quality and usually involve humans or LLMs as a Judge in order to be estimated, some examples include:

Factuality: does the LLM hallucinate? (provides false/misleading information) Is the information provided grounded?
Relevance: how relevant is the LLM response compared to the prompt request?
Fluency: does the response flow sound natural and realistic?
Coherence: are the different phrases/sentences logically consistent?

Figure 3: Metrics Choice Decision Tree (Image by Author).

Similar approaches can then be applied when evaluating not only LLM text outputs but also other forms of content such as images. Particularly, for Image synthesis metrics such as Inception score and Frechet inception distance can be used, and to assess image quality Structural similarity index and peak signal-to-noise ratio.

Finally, another aspect to keep track of is mitigation of any form of bias and ensuring fairness. Some key metrics can help us ensuring this include:

Demographic parity: Are loan approvals granted at similar rates for all races? (the model predictions should not be skewed towards any particular group).
Equal opportunity: Are equally qualified candidates from all demographics being wrongly rejected at the same rate? (the model should not disproportionately disadvantage certain groups by making more mistakes for them).
Counterfactual Fairness: Would a person’s job application be evaluated differently if their gender was changed in the application? (to idea is to identify and eliminate biases directly linked to sensitive attributes).

When evaluating a model it can also be helpful to look for possible intrinsic training biases. For example, usually models tend to prefer verbose answers over short ones or prefer one option over another based on its positional order.

LLM Evaluation Approaches/Steps

There are currently 4 key LLM Evaluation Approaches/Steps:

Benchmark/Golden Dataset: collecting/creating samples of examples reference answers we can evaluate an LLM against. In this case, it is vital to tailor the golden dataset to match future users expectations and needs. Depending on size and structure, these could then be stored in GCP services such as Cloud Storage, BigQuery, Spanner, etc.
Business Metrics: estimating the overall impact of our LLM system on business performance, return on investment, revenue, etc.
LLM as a Judge: using another LLM to evaluate our LLM system for a set of tasks against some predetermined criterias. Some frequent issues with the “LLM as a Judge” approach are: self-bias, inconsistent scoring, and poor correlation with human evaluations.
User Provided Feedback: using human feedback to direct the model towards more useful responses.

These evaluation approaches can then come to action at different stages in the pre/post deployment process (Figure 4).

Figure 4: LLM Evaluation Stages (Image by Author).

Benchmark/Golden Dataset

Getting Benchmark Datasets

When working with company specific use cases it would then be advisable to create your own internal golden/benchmark dataset to evaluate your model based on company specific internal jargon (e.g. financial, medical terms), etc. This approach can in fact provide much more relevant evaluations tailored to your use case compared to using out of the box industry benchmarks. In case no data is available, generating synthetic data could be used as a last resort.

Additionally, there are a large number of existing Evaluation Benchmark datasets commonly used in the industry in order to evaluate LLMs, some include:

GLUE (General Language Understanding Evaluation): Assesses overall language understanding through nine diverse tasks, including sentiment analysis, question answering, and textual entailment. Provides a single aggregate score for simplified model comparison.
SuperGLUE: A more challenging successor to GLUE, designed after models surpassed human performance on the original benchmark. Features complex tasks requiring advanced language understanding and reasoning.
HellaSwag: Evaluates commonsense reasoning by requiring models to predict the most logical continuation of a given scenario from multiple choices.
TruthfulQA: Focuses on the model’s ability to provide truthful and non-misleading answers, crucial for building reliable AI systems.
MMLU (Massive Multitask Language Understanding): A comprehensive benchmark with over 15,000 questions across 57 subjects, spanning STEM, humanities, and more. Measures a model’s breadth of knowledge and its ability to perform complex reasoning across diverse domains.
ARC (AI2 Reasoning Challenge): Concentrates on scientific reasoning abilities.
LAMBADA: Tests a model’s proficiency in predicting the final word of a text passage, assessing long-range dependencies.
SQuAD (Stanford Question Answering Dataset): Evaluates reading comprehension and the ability to extract answers from a given text.

Labeled vs Unlabeled Datasets

To aid with the labeling process, different enterprise solutions have been created such as Labelbox, to provide an easy to use interface where to label data and outsource human evaluators (if internal workforce is not possible and data not too sensitive).

Evaluation can also be possible without labeled data (using for example NannyML open source approach with the Confidence-Based Performance Estimation algorithm or LLM Autoraters) but often less precise and error prone.

User Provided Feedback

Human evaluators, front-facing users and LLM Judges can support the evaluation process in 2 main possible ways: direct or comparative assessment.

With direct assessment, a user might be asked to rate an answer or complete some sort of survey following a conversation with an LLM (using pointwise metrics). In comparative assessments, users can instead be provided with different variations of the same answer and asked to pick which one they prefer (through pairwise comparison). This approach can be particularly useful when trying to fine tune a model or perform some form of A/B testing to decide which model is best to use.

Task specific approaches

So far, we have considered how to evaluate general LLM predictions, although LLMs are usually part of wider systems to solve actual applications. Some common examples include, AI Powered Search, RAG (Retrieval Augmented Generation) and Agents. In these cases, additional applications related metrics are needed.

AI Search: Evaluation of search quality using Vertex AI Search can be performed by providing examples of typical user queries paired with best matching results, more information about the process can be found here. To further improve performance, Vertex AI Agent Builder Search is also able to provide an out of the box solution for fine-tuning your search model.
RAG: Design of a RAG system needs to usually go through multiple optimization iterations and open source libraries such as Ragas can be of great help to streamline the process. With the latest launch of Vertex AI RAG Engine on GCP, it can then be easier than ever to optimize RAG hyperparameters such as Chunk Size/Overlap, Vector Distance threshold, etc.. to improve search quality. Some examples of metrics used to measure RAG contextual relevance include: NDCG (Normalized Discounted Cumulative Gain), MRR (Mean Reciprocal Rank), MAP (Mean Average Precision), Precision@K. Once optimized the retrieval metrics, it can then be possible to understand its impact on response quality using the Evaluation Service API.
Agents: As agentic solutions are becoming more and more common in the industry, more complex forms of agent evaluations have been emerging. Overall, the success of an agentic workflow can be measured by its final response (if the agent achieved or not its objectives) or trajectory (sequence of tools the agent invoked to achieve its goals). When evaluating trajectory, metrics such as: exact match, in order match, any-order match, precision, recall, etc. are typically used. Additional information about these types of metrics and data setup for evaluation is available in the Vertex AI Gen AI evaluation service documentation.

Finally, when metrics optimization might not be enough, LLM fine-tuning might be the best approach to take in order to tailor off the shelf LLMs for your use case specifics (either through Full fine-tuning or Parameter efficient tuning). Vertex AI provides Supervised fine-tuning support out of the box for different data types such as text, image, audio, and document. Moreover, LLM fine-tuning and evaluation can also be performed directly in BigQuery depending on use case needs.

Evaluation Frameworks

Here at Google Cloud, we developed the Gen AI evaluation service. This library is designed to work seamlessly with Vertex AI and support not only the Gemini family but also open 3rd party models. Using the GenAI evaluation service you are able to get out of the box support for a whole collection of metrics maintained by the Google ecosystem while still having the flexibility to bring and define your own custom metrics. This service is additionally designed to help perform specialized tasks such as prompt engineering, RAG and AI Agents optimization.

On top of this, Vertex AI also supports pairwise model-based evaluation through AutoSxS (with an LLM autorater).

Finally, if you looking to kickstart your GenAI project on GCP, another great resource to look into is the “Agent Starter Pack”, an open source repository providing templates for common GenAI tasks on GCP, including how to evaluate Generative AI applications using tools like Gen AI evaluation service and Vertex AI Experiments.

Open Source Alternatives

With the widespread adoption of LLMs, a wealth of libraries have been developed over the last few years in order to bridge the evaluation gap. Some notable examples include:

DeepEval
TruLens
Opik
Guardrails AI (additional information about guardrails for LLMs and other caveats can be found here)

Additionally, other libraries focused also on traditional Machine Learning evaluation tasks have been expanded to include also LLM capabilities:

Given the open source nature of these frameworks, they can all be used as part of your development process on GCP with any of the models available on Model Garden.

Best Practices

To summarize, some common best practices to follow in an evaluation system include (Figure 5):

Match metrics to real world needs and make them as straightforward and consistent as possible.
Routinely monitor and create alert systems on key metrics to prevent model performance to degrade for too long unnoticed.
Regularly benchmark performance against other models and perform unit testing on outputs.
Whenever using humans in evaluation, make sure to only work with domain experts that can help steer the model in the right direction.
Perform adversarial attack tests to try to break your own model and discover edge case failures (e.g. Perturbation Testing).
Ensure LLMs predictions are as repeatable as possible (e.g. use low temperature and fixed seeds).

Figure 5: Evaluation Pipeline Example (Image by Author).

For an in-depth guide on evaluation, feel free to refer to the Hugging Face Evaluation Handbook.

Pier Paolo Ippolito

Building AI Agents in 30 Minutes from Prototype to Production

Building AI Agents in 30 Minutes from Prototype to Production

Building, evaluating and deploying production-ready AI agents using Agents CLI in Agent Platform

Introduction

The Agent Deployment Problem

What is Agents CLI?

Building an Expense Approval Agent

Prerequisites

Step 1: Project Scaffolding

Step 2: Implementing Business Logic

Step 3: Local Testing

Step 4: Writing Structured Evaluations

Step 5: Deploying to Production

Step 6: Observability

What Makes Agents CLI Different

Beyond the Basics

Techniques Summary

Conclusion

Building End to End AI Agents with ADK Dev Skills

Putting a “Principal ADK Engineer” in every developer’s laptop

Introduction

What Are ADK Dev Skills?

Available Skills

Compatibility

Prerequisites

Step 1: Install ADK Dev Skills

Step 2: Define Your Requirements

Step 3: Generate Project Scaffolding

Step 4: Implement Business Logic

Step 5: Test Locally

Step 6: Create Evaluations

Step 7: Deploy to Production

Step 8: Set Up CI/CD

1. PR Checks (.github/workflows/pr_checks.yaml)

2. Staging Deployment (.github/workflows/staging.yaml)

3. Production Deployment (.github/workflows/deploy-to-prod.yaml)

Step 9: Observability

Built-in (No Configuration Needed)

Optional Integrations

Step 10: Write Tests for Production

Before and After

Without Skills

With Skills

Best Practices and Tips

1. Install Skills Globally

2. Be Specific in Prompts

3. Leverage the Right Skill for Each Phase

Iterate with Evaluations

5. Review Generated Code

6. Use Version Control

Common Questions

Do we need to learn ADK first?

Can we modify the generated code?

Will this work with different AI assistants?

What if we want to deploy to Cloud Run instead?

Can we create our own skills?

How do we update the skills?

What We Built

What to Build Next

Conclusion

Revolutionizing Claims, from Deepfake Detection to Next-Best-Action

Revolutionizing Claims: From Deepfake Detection to Next-Best-Action

Solving information overload and sophisticated Fraud with Google ADK

The Framework: Google Agent Development Kit (ADK)

The Architecture: An Intelligent Claims Processing Pipeline

Step 1: The Investigator Agent — Detecting Digital Deception

Step 2: The Reasoning Agent — Policy-Driven Next-Best-Action

Step 3: Orchestrating the Claims Pipeline

Putting It All Together: A Runnable Application

Execution Output

Conclusion: Augmenting Adjusters, Fortifying Defenses

The Next-Gen Underwriter, Accelerating Quotes with Document Intelligence

The Next-Gen Underwriter: Accelerating Quotes with Document Intelligence

A Multi-Agent Framework for Instant Data Extraction and Premium Calculation with Google ADK

The Framework: Google Agent Development Kit (ADK)

The Architecture: A More Realistic Quoting Pipeline

Step 1: The Ingestion Agent

Step 2: The Extraction and Quoting Agents

Step 3: Orchestrating the Pipeline

1. PR Checks (`.github/workflows/pr_checks.yaml`)

2. Staging Deployment (`.github/workflows/staging.yaml`)

3. Production Deployment (`.github/workflows/deploy-to-prod.yaml`)