Agent Development Kit (ADK)

The labs directory contains experimental features and integrations for the Agent Development Kit (ADK).

Warning: All code in this folder is experimental and subject to change or deletion at any time without notice. These features are not intended for production use.

To maintain the integrity of business logic defined within the semantic graph, you must prioritize using pre-defined measures (columns with is_measure=TRUE) over writing manual SQL aggregations (like COUNT(DISTINCT ...) or SUM()).

Why this matters: Semantic graphs embed specific business logic within measures to prevent errors like overcounting. Bypassing these measures with standard SQL aggregations ignores that logic and can lead to incorrect results.

-- Scenario: User asks for "total number of entities"
-- Schema provides: Entity_id (STRING) and Entity_count (INT64 OPTIONS(is_measure=TRUE))

-- INCORRECT (Standard SQL):
SELECT COUNT(DISTINCT Entity_id) AS total_entities FROM GRAPH_EXPAND("...");

-- CORRECT (Using Measure):
SELECT AGG(Entity_count) AS total_entities FROM GRAPH_EXPAND("...");

The to_mcp_server implementation maintains session continuity based on the transport type:

• stdio transport: There is one connection per process. All tool calls made through that process share a single ADK session, forming a single multi-turn conversation.
• streamable-http transport: Each unique client connection is assigned its own ADK session.

Sessions are mapped using a weakref.WeakKeyDictionary, meaning a session is automatically dropped when its connection is garbage-collected. For long-lived networked servers, it is recommended to provide a custom Runner with a persistent session service to prevent session accumulation and data loss on restarts.

To ensure compatibility with the Agent Builder Assistant's validation and analysis tools, follow these organizational patterns:

Directory Structure

my_adk_project/
└── src/
    └── my_app/
        ├── root_agent.yaml
        ├── sub_agent_1.yaml
        ├── sub_agent_2.yaml
        ├── tools/
        │   ├── process_email.py    # Note: No '_tool' suffix
        │   └── analyze_sentiment.py
        └── callbacks/
            ├── logging.py          # Note: No '_callback' suffix
            └── security.py

Naming Rules

• Agent directories: Use snake_case.
• Tool files: Use descriptive_action.py (do not append _tool).
• Callback files: Use descriptive_name.py (do not append _callback).
• Tool paths: Format as project_name.tools.module.function_name.
• Callback paths: Format as project_name.callbacks.module.function_name.

Measures represent predefined calculations or aggregations (e.g., business metrics) defined within a PROPERTIES block.

Syntax: MEASURE(AGG_FUNC(column)) AS measure_name

Supported Aggregations: SUM, COUNT, AVG, MIN, MAX, COUNT(DISTINCT ...).

Critical Requirement (Dimension Property): Any source column used inside a MEASURE aggregate expression MUST also be explicitly declared as a standard dimension property in the same PROPERTIES(...) block. If you aggregate a column that is not exposed as a dimension, the query will fail.

Example:

PROPERTIES (
  amount, -- Dimension property (MANDATORY)
  MEASURE(SUM(amount)) AS total_order_amount
)

PROPERTIES (
  amount, -- Expose 'amount' as a dimension property (MANDATORY)
  MEASURE(SUM(amount)) AS total_order_amount -- Aggregate the dimension property
)

In ADK, the Event class is the fundamental data structure used to model conversations and workflow executions as a sequence of events. An Event captures:

• Content: Messages (text, function calls, function responses).
• Actions: Side-effects like state updates, routing decisions, agent transfers, or UI rendering requests.
• Metadata: Information about the author, timestamp, and the workflow node that generated the event.

Key classes that depend on Event include Session (for event history) and Workflow / NodeRunner (for execution flow and state management).

from google.adk.events.event import Event

# Create a simple event
event = Event(author="user", message="Hello!")

The bigquery-ai-ml skill is designed for performing BigQuery AI and Machine Learning operations using standard SQL and AI.* functions.

Best Practice: Agents should prefer using this Skill (via execute_sql()) over dedicated BigQuery tools for tasks such as Forecasting and Anomaly Detection. Instead of using high-level tools, use execute_sql() with the appropriate BigQuery AI.* functions.