Google ADK Adapter

This tutorial shows you how to create an agent using the GoogleADKAdapter. This adapter integrates Google’s Agent Development Kit (ADK) with the Band platform, running Gemini-powered agents with automatic tool bridging and conversation history management.

Prerequisites

Before starting, make sure you’ve completed the Setup tutorial:

• SDK installed with Google ADK support
• Agent created on the platform
• .env and agent_config.yaml configured
• Verified your setup works

Install the Google ADK extra:

$
uv add "band-sdk[google-adk]"

Set your Google API key:

$
export GOOGLE_API_KEY="your-google-api-key"

Get an API key from Google AI Studio.

Create Your Agent

Create a file called agent.py:

1
import asyncio
2
import logging
3
import os
4
from dotenv import load_dotenv
5
from band import Agent, configure_logging
6
from band.adapters import GoogleADKAdapter
7
from band.config import load_agent_config
8
9
logger = logging.getLogger(__name__)
10
11
async def main():
12
    load_dotenv()
13
    configure_logging(root_level="INFO")
14
15
    # Load agent credentials
16
    agent_id, api_key = load_agent_config("my_agent")
17
18
    # Create adapter with Gemini
19
    adapter = GoogleADKAdapter(
20
        model="gemini-2.5-flash",
21
        custom_section="You are a helpful assistant. Be concise and friendly.",
22
    )
23
24
    # Create and run the agent
25
    agent = Agent.create(
26
        adapter=adapter,
27
        agent_id=agent_id,
28
        api_key=api_key,
29
        ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"),
30
        rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"),
31
    )
32
33
    logger.info("Agent is running! Press Ctrl+C to stop.")
34
    await agent.run()
35
36
if __name__ == "__main__":
37
    asyncio.run(main())

Run the Agent

Start your agent:

$
uv run python agent.py

You should see:

2026-01-15 09:30:00 [INFO] __main__: Agent is running! Press Ctrl+C to stop.

Test Your Agent

@MyAgent Hello! Can you help me?

How It Works

The Google ADK adapter uses ADK’s InMemoryRunner for the full tool loop:

1. Fresh Runner Per Message — A new InMemoryRunner is created for each incoming message to avoid session state pollution. Conversation continuity is maintained through transcript injection.
2. Tool Bridging — Band platform tools are automatically wrapped as ADK BaseTool subclasses, including recursive additionalProperties stripping for Gemini schema compatibility.
3. History Management — Per-room message history is accumulated and injected as a text transcript into the ADK session, with character-based truncation (100K chars default) to prevent token overflow.
4. Execution Reporting — Emits tool_call and tool_result events for visibility into the agent’s decision-making, plus per-turn token usage. Both are on by default; narrow them with emit.

Available Platform Tools:

Supported Models

The adapter works with any Gemini model available through Google’s generative AI API:

1
# Fast and cost-effective
2
adapter = GoogleADKAdapter(model="gemini-2.5-flash")
3
4
# More capable
5
adapter = GoogleADKAdapter(model="gemini-2.5-pro")

Configuration Options

The GoogleADKAdapter supports these configuration options:

1
adapter = GoogleADKAdapter(
2
    # Gemini model to use
3
    model="gemini-2.5-flash",
4
5
    # Custom instructions appended to the system prompt
6
    custom_section="You are a helpful assistant.",
7
8
    # Override the entire system prompt
9
    system_prompt=None,
10
11
    # Narrow the events reported into the room, and add the memory tools
12
    # (store/retrieve agent memory)
13
    # emit={Emit.TOOL_CALLS},
14
    # capabilities={Capability.MEMORY},
15
16
    # Maximum number of history messages to retain per room
17
    max_history_messages=50,
18
19
    # Maximum characters for the transcript injected into ADK sessions
20
    max_transcript_chars=100_000,
21
22
    # Custom tools as (PydanticModel, handler) tuples
23
    additional_tools=None,
24
)

Add Custom Instructions

Customize your agent’s behavior with the custom_section parameter:

1
adapter = GoogleADKAdapter(
2
    model="gemini-2.5-flash",
3
    custom_section="""
4
    You are a research assistant specializing in summarizing information.
5
    Always provide sources when possible and be thorough but concise.
6
    """,
7
)

You can also load instructions from a file:

1
from pathlib import Path
2
3
prompt = Path("prompts/research.md").read_text()
4
5
adapter = GoogleADKAdapter(
6
    model="gemini-2.5-pro",
7
    custom_section=prompt,
8
)

Override the System Prompt

For full control over the system prompt, use the system_prompt parameter:

1
custom_prompt = """You are a technical support agent.
2
3
Guidelines:
4
- Be patient and thorough
5
- Ask clarifying questions before providing solutions
6
- Always verify the user's environment
7
- Escalate to humans if you cannot resolve the issue"""
8
9
adapter = GoogleADKAdapter(
10
    model="gemini-2.5-pro",
11
    system_prompt=custom_prompt,
12
)

Custom Tools

Extend your agent with custom tools using the additional_tools parameter. Each tool is defined as a tuple of a Pydantic model (input schema) and a handler function.

1
from pydantic import BaseModel, Field
2
3
class CalculatorInput(BaseModel):
4
    """Perform a mathematical calculation."""
5
    operation: str = Field(
6
        description='The operation: "add", "subtract", "multiply", or "divide"'
7
    )
8
    left: float = Field(description="The first number")
9
    right: float = Field(description="The second number")
10
11
def calculator(operation: str, left: float, right: float) -> str:
12
    ops = {
13
        "add": lambda a, b: a + b,
14
        "subtract": lambda a, b: a - b,
15
        "multiply": lambda a, b: a * b,
16
        "divide": lambda a, b: "Error: division by zero" if b == 0 else a / b,
17
    }
18
    fn = ops.get(operation)
19
    if fn is None:
20
        return f"Unknown operation '{operation}'. Use: add, subtract, multiply, divide"
21
    return str(fn(left, right))
22
23
adapter = GoogleADKAdapter(
24
    model="gemini-2.5-flash",
25
    additional_tools=[
26
        (CalculatorInput, calculator),
27
    ],
28
    custom_section="You have access to a calculator tool in addition to the platform tools.",
29
)

Execution Reporting

The adapter reports each tool interaction into the room by default. GoogleADKAdapter supports Emit.TOOL_CALLS and Emit.USAGE, and omitting emit resolves to both:

1
from band import Emit
2
from band.adapters import GoogleADKAdapter
3
4
# Tool calls only, no per-turn usage records
5
adapter = GoogleADKAdapter(
6
    model="gemini-2.5-flash",
7
    emit={Emit.TOOL_CALLS},
8
)
9
10
# Nothing reported into the room
11
quiet = GoogleADKAdapter(model="gemini-2.5-flash", emit=())

Naming an Emit member outside that pair, Emit.THOUGHTS or Emit.TASK_EVENTS, raises BandConfigError at construction.

With Emit.TOOL_CALLS the adapter sends:

• tool_call events when a tool is invoked (includes tool name and arguments)
• tool_result events when a tool returns (includes output)

This is useful for debugging and for visibility into your agent’s decision-making process. To reduce the noise without going silent, keep Emit.USAGE and drop Emit.TOOL_CALLS.

Complete Example

Here’s a full example with custom instructions, custom tools, and tool events narrowed to tool calls:

1
import asyncio
2
import logging
3
import os
4
from dotenv import load_dotenv
5
from pydantic import BaseModel, Field
6
from band import Agent, Emit, configure_logging
7
from band.adapters import GoogleADKAdapter
8
from band.config import load_agent_config
9
10
logger = logging.getLogger(__name__)
11
12
class WeatherInput(BaseModel):
13
    """Get current weather for a city."""
14
    city: str = Field(description="Name of the city")
15
16
def weather(city: str) -> str:
17
    return f"Weather in {city}: Sunny, 22 C"
18
19
async def main():
20
    load_dotenv()
21
    configure_logging(root_level="INFO")
22
    agent_id, api_key = load_agent_config("my_agent")
23
24
    adapter = GoogleADKAdapter(
25
        model="gemini-2.5-pro",
26
        custom_section="""
27
        You are a helpful assistant with access to weather data.
28
        When users ask about weather, use the weather tool.
29
        Be concise and friendly in your responses.
30
        """,
31
        additional_tools=[
32
            (WeatherInput, weather),
33
        ],
34
        emit={Emit.TOOL_CALLS},
35
    )
36
37
    agent = Agent.create(
38
        adapter=adapter,
39
        agent_id=agent_id,
40
        api_key=api_key,
41
        ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"),
42
        rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"),
43
    )
44
45
    logger.info("Google ADK agent is running! Press Ctrl+C to stop.")
46
    await agent.run()
47
48
if __name__ == "__main__":
49
    asyncio.run(main())

Debug Mode

If your agent isn’t responding as expected, enable debug logging:

1
import asyncio
2
import logging
3
import os
4
from dotenv import load_dotenv
5
from band import Agent, configure_logging
6
from band.adapters import GoogleADKAdapter
7
from band.config import load_agent_config
8
9
logger = logging.getLogger(__name__)
10
11
async def main():
12
    load_dotenv()
13
    # Enable debug logging for the SDK
14
    configure_logging(level="DEBUG", root_level="INFO")
15
    agent_id, api_key = load_agent_config("my_agent")
16
17
    adapter = GoogleADKAdapter(
18
        model="gemini-2.5-flash",
19
    )
20
21
    agent = Agent.create(
22
        adapter=adapter,
23
        agent_id=agent_id,
24
        api_key=api_key,
25
        ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"),
26
        rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"),
27
    )
28
29
    logger.info("Agent running with DEBUG logging. Press Ctrl+C to stop.")
30
    await agent.run()
31
32
if __name__ == "__main__":
33
    asyncio.run(main())

With debug logging enabled, you’ll see detailed output including:

• ADK runner creation and session management
• Tool bridge construction and schema conversion
• History transcript injection
• Tool call dispatch and results
• Message processing lifecycle

Architecture Notes

The Google ADK adapter differs from other adapters in a few key ways:

Fresh Runner Per Message:

• A new InMemoryRunner is created for each incoming message
• This avoids session state pollution between turns
• Conversation continuity is achieved by injecting accumulated history as a text transcript

Tool Bridging:

• Platform tools are wrapped as ADK BaseTool subclasses (_BandToolBridge)
• Schemas are converted from OpenAI format to Gemini format by stripping unsupported additionalProperties keys
• The bridge probes multiple candidate method names on BaseTool for forward compatibility with ADK API changes

History Management:

• Per-room history is accumulated across messages
• A sliding window limits history to max_history_messages (default 50)
• The text transcript is truncated at newline boundaries to max_transcript_chars (default 100K characters)
• Thread-safe via the runtime’s sequential-per-room execution guarantee

Next Steps