> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-dev.band.ai/integrations/sdks/tutorials/gemini/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.band.ai/_mcp/server.

# Gemini Adapter

> Create a Band agent using the GeminiAdapter, which calls the Gemini API directly through Google's official google-genai client.

This tutorial shows you how to create an agent using the `GeminiAdapter`. The adapter talks to the Gemini API directly through Google's official `google-genai` client and drives its own function-calling loop, so platform tools are registered as Gemini function declarations and executed by the SDK.

This is the direct Gemini API adapter. If you want the Agent Development Kit runtime, with ADK sessions, agents, and tools, use the [Google ADK Adapter](/integrations/sdks/tutorials/google-adk) instead.

> **Note**
>
> The Python and TypeScript adapters are separate implementations with different option names, defaults, and feature coverage. Python exposes sampling controls, retries, and history trimming; TypeScript does not. Read [Configuration Options](#configuration-options) before porting code between them.

## Prerequisites

Before starting, complete the [Setup](/integrations/sdks/tutorials/setup) tutorial:

* Agent created on the platform
* Credentials configured (`agent_config.yaml`, or environment variables)
* Verified your setup works

**Install the SDK with Gemini support:**

#### Python

```bash
uv add "band-sdk[gemini]"
```

The `gemini` extra pulls `google-genai>=1.43.0`.

#### TypeScript

```bash
pnpm add @band-ai/sdk
pnpm add @google/genai
```

`@google/genai` is an optional peer dependency (`>=1.44.0`) and is imported lazily on the first model call. Requires Node.js 22.12+.

**Authentication:**

#### Python

The adapter constructs `genai.Client(api_key=provider_key)`. Pass `provider_key` explicitly, or leave it unset and let the client resolve credentials from the environment:

**`.env`**

```bash title=".env"
# Gemini Developer API
GOOGLE_API_KEY=your-key-here
# or
GEMINI_API_KEY=your-key-here
```

Vertex AI mode is also supported by the underlying client:

```bash
gcloud auth application-default login
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=your-project-id
```

If neither path resolves, adapter startup fails with a message naming both options.

#### TypeScript

The adapter passes `apiKey` straight into `new GoogleGenAI({ apiKey })`. Read it from the environment yourself:

```bash
export GEMINI_API_KEY=your-key-here
```

Platform credentials come from `loadAgentConfig("my_agent")`, or from `loadAgentConfigFromEnv()` with `THENVOI_AGENT_ID` and `THENVOI_API_KEY`.

---

## Create Your Agent

#### Python

Create a file called `agent.py`:

**`agent.py`**

```python title="agent.py"
import asyncio
import logging
import os
from dotenv import load_dotenv
from band import Agent
from band.adapters import GeminiAdapter
from band.config import load_agent_config

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

async def main():
    load_dotenv()

    # Load agent credentials
    agent_id, api_key = load_agent_config("my_agent")

    # Create adapter with model and instructions
    adapter = GeminiAdapter(
        model="gemini-2.5-flash",
        prompt="You are a helpful assistant. Be concise and friendly.",
    )

    # Create and run the agent
    agent = Agent.create(
        adapter=adapter,
        agent_id=agent_id,
        api_key=api_key,
        ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"),
        rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"),
    )

    logger.info("Agent is running! Press Ctrl+C to stop.")
    await agent.run()

if __name__ == "__main__":
    asyncio.run(main())
```

#### TypeScript

Create a file called `agent.ts`:

**`agent.ts`**

```ts title="agent.ts"
import { Agent, GeminiAdapter, loadAgentConfig } from "@band-ai/sdk";

const agent = Agent.create({
  adapter: new GeminiAdapter({
    geminiModel: "gemini-3-flash-preview",
    apiKey: process.env.GEMINI_API_KEY,
    systemPrompt: "You are a helpful assistant. Be concise and friendly.",
  }),
  config: loadAgentConfig("my_agent"),
});

await agent.run();
```

---

## Run the Agent

#### Python

```bash
uv run python agent.py
```

You should see:

```
INFO:__main__:Agent is running! Press Ctrl+C to stop.
```

#### TypeScript

```bash
npx tsx agent.ts
```

---

## Test Your Agent

### Add Agent to a Chat Room

Go to [Band](https://app.band.ai) and either create a new chat room or open an existing one. Add your agent as a participant, under the **Remote** section.

### Send a Message

In the chat room, mention your agent:

```
@MyAgent Hello! Can you help me?
```

### See the Response

Your agent will process the message and respond in the chat room.

---

## How It Works

The adapter disables the client's automatic function calling and runs the tool loop itself, so every tool call passes through the SDK:

1. **Connection** - The SDK connects to Band via WebSocket and subscribes to rooms where your agent participates
2. **Tool declarations** - Platform tool schemas plus your custom tools are converted into Gemini `FunctionDeclaration` entries with `parameters_json_schema`
3. **Generation** - The adapter calls `generate_content` with the rendered system prompt as `system_instruction`
4. **Tool execution** - Returned function calls are executed, and their results are appended as `function_response` parts
5. **Loop** - Generation repeats until the model returns no function calls, bounded by the tool-round limit

Gemini requires strict user/model turn alternation, so the adapter merges all user-side content, participant updates, contact broadcasts, and the incoming message, into a single `user` turn. Tool results are appended as a single `user` turn as well.

**How the reply reaches the room differs by SDK:**

#### Python

The model must call the `band_send_message` platform tool. The adapter never posts the model's plain text automatically. If the model answers without calling the tool, nothing appears in the room.

#### TypeScript

When the tool loop ends, the adapter posts the model's final text with `tools.sendMessage`, replying to the sender. The model can also send messages mid-loop with platform tools.

> **Note**
>
> Platform tool descriptions come from centralized definitions, so behavior stays consistent across adapters.

---

## Supported Models

Pass a plain Gemini model identifier, with no provider prefix.

| SDK        | Option        | Default                  |
| ---------- | ------------- | ------------------------ |
| Python     | `model`       | `gemini-2.5-flash`       |
| TypeScript | `geminiModel` | `gemini-3-flash-preview` |

Any model identifier your installed `google-genai` client accepts works here; the adapter forwards the string unchanged. The defaults above are the only identifiers pinned in the SDK sources.

> **Warning**
>
> The TypeScript default, `gemini-3-flash-preview`, is a preview model. Set `geminiModel` explicitly if you need a stable identifier.

---

## Configuration Options

#### Python

| Parameter                   | Type                             | Default              | Description                                                 |
| --------------------------- | -------------------------------- | -------------------- | ----------------------------------------------------------- |
| `model`                     | `str`                            | `"gemini-2.5-flash"` | Gemini model identifier                                     |
| `provider_key`              | `str \| None`                    | `None`               | Gemini API key; falls back to client environment resolution |
| `system_prompt`             | `str \| None`                    | `None`               | Replaces the entire rendered prompt                         |
| `prompt`                    | `str \| None`                    | `None`               | Custom section appended to the rendered prompt              |
| `max_output_tokens`         | `int \| None`                    | `None`               | Applied to `GenerateContentConfig` when set                 |
| `temperature`               | `float \| None`                  | `None`               | Applied to `GenerateContentConfig` when set                 |
| `max_tool_rounds`           | `int`                            | `20`                 | Raises `RuntimeError` when exceeded                         |
| `max_retries`               | `int`                            | `2`                  | Retries on server and transport errors                      |
| `retry_base_delay_s`        | `float`                          | `1.0`                | Exponential backoff base delay                              |
| `max_history_messages`      | `int`                            | `200`                | Per-room history cap, trimmed after each turn               |
| `history_converter`         | `GeminiHistoryConverter \| None` | `None`               | Defaults to `GeminiHistoryConverter()`                      |
| `additional_tools`          | `list[CustomToolDef] \| None`    | `None`               | `(InputModel, handler)` tuples                              |
| `api_key`                   | `str \| None`                    | `None`               | Deprecated alias for `provider_key`                         |
| `gemini_api_key`            | `str \| None`                    | `None`               | Deprecated alias for `provider_key`                         |
| `custom_section`            | `str \| None`                    | `None`               | Deprecated alias for `prompt`                               |
| `include_base_instructions` | `bool`                           | `True`               | Set `False` to drop the SDK base prompt                     |

**Prompt precedence:** `system_prompt` wins outright. When it is set, `prompt`, `include_base_instructions`, and capability prompt sections are all ignored.

**Retries:** transient `ServerError`, `httpx.TimeoutException`, and `httpx.TransportError` failures are retried up to `max_retries` times with delays of `retry_base_delay_s * 2 ** (attempt - 1)`.

**History trimming** runs after the tool loop, so the current turn always sees full context. Trimming realigns to the next `user` turn and drops orphaned `function_response` parts.

> **Warning**
>
> `api_key`, `gemini_api_key`, and `custom_section` are deprecated and emit `DeprecationWarning`. Use `provider_key` and `prompt`. Mixing a deprecated argument with its replacement raises `BandConfigError`. `enable_execution_reporting` and `enable_memory_tools` were removed; pass `emit` and `capabilities` instead.

#### TypeScript

| Option                     | Type                  | Default                               | Description                                        |
| -------------------------- | --------------------- | ------------------------------------- | -------------------------------------------------- |
| `geminiModel`              | `string`              | `"gemini-3-flash-preview"`            | Gemini model identifier                            |
| `apiKey`                   | `string`              | `undefined`                           | Passed to `new GoogleGenAI({ apiKey })`            |
| `model`                    | `ToolCallingModel`    | built from `geminiModel` and `apiKey` | Supply your own model implementation               |
| `clientFactory`            | `GeminiClientFactory` | dynamic import of `@google/genai`     | Inject a client, useful in tests                   |
| `systemPrompt`             | `string`              | `undefined`                           | Sent as `config.systemInstruction`                 |
| `includeMemoryTools`       | `boolean`             | `false`                               | Include memory tools in the schema list            |
| `maxToolRounds`            | `number`              | `8`                                   | Sends an `error` event, then throws, when exceeded |
| `enableExecutionReporting` | `boolean`             | `false`                               | Emit `tool_call` and `tool_result` events          |
| `customTools`              | `CustomToolDef[]`     | `[]`                                  | `{ name, schema, handler, description? }` entries  |
| `logger`                   | `Logger`              | `NoopLogger`                          | Adapter logging                                    |

Tool schemas are requested in OpenAI format, because Gemini accepts OpenAI-shaped function parameters, then converted to `functionDeclarations` with `parametersJsonSchema`.

**Differences to watch:**

| Behavior                    | Python                                                  | TypeScript                             |
| --------------------------- | ------------------------------------------------------- | -------------------------------------- |
| Tool-round limit            | `max_tool_rounds`, default `20`                         | `maxToolRounds`, default `8`           |
| Sampling controls           | `temperature`, `max_output_tokens`                      | not available                          |
| Retries on transient errors | `max_retries`, `retry_base_delay_s`                     | none                                   |
| History cap                 | `max_history_messages`, default `200`                   | none                                   |
| Custom instructions         | `prompt` plus base instructions, or `system_prompt`     | `systemPrompt` only                    |
| Memory and contacts         | `capabilities={Capability.MEMORY, Capability.CONTACTS}` | `includeMemoryTools` only              |
| Tool and usage events       | on by default; narrow with `emit`                       | off unless `enableExecutionReporting`  |
| Final reply                 | model must call `band_send_message`                     | adapter posts final text automatically |

---

## Execution Reporting

Both SDKs publish each tool interaction into the room as an event. Python does it by default; TypeScript needs a flag.

#### Python

```python
from band import Capability, Emit

# Report tool calls but not token usage, and add the memory tools
adapter = GeminiAdapter(
    model="gemini-2.5-flash",
    emit={Emit.TOOL_CALLS},
    capabilities={Capability.MEMORY},
)
```

`GeminiAdapter` supports `Emit.TOOL_CALLS` and `Emit.USAGE`, and the capabilities `Capability.MEMORY` and `Capability.CONTACTS`. Omitting `emit` resolves to both supported kinds, so both are reported unless you narrow them; `emit=()` silences the adapter. Naming any other `Emit` member raises `BandConfigError` at construction.

`Emit.TOOL_CALLS` sends a `tool_call` event before each tool runs, with `name`, `args`, and `tool_call_id`, and a `tool_result` event after, with `name`, `output`, `tool_call_id`, and `is_error`. Reporting is best effort; a failed event is logged and never breaks the turn.

`Emit.USAGE` sums token usage across every call in the tool loop and emits it once per turn. Gemini reports thinking tokens separately from output, so `thoughts_token_count` is folded into output tokens; `cached_content_token_count` maps to cache reads.

#### TypeScript

```ts
const adapter = new GeminiAdapter({
  geminiModel: "gemini-3-flash-preview",
  apiKey: process.env.GEMINI_API_KEY,
  enableExecutionReporting: true,
});
```

The adapter sends a `tool_call` event with `name`, `args`, and `tool_call_id` before each tool runs, and a `tool_result` event with `name`, `output`, and `tool_call_id` after. Reporting failures are logged, not thrown. Token usage reporting is not available in the TypeScript adapter.

---

## Complete Example

A full agent with a custom tool, instructions, and execution reporting.

#### Python

Custom tools are `(InputModel, handler)` tuples. The tool name is derived from the model class name with the `Input` suffix removed and lowercased, so `WeatherInput` becomes `weather`. The docstring becomes the tool description, and the handler receives the validated model instance.

**`agent.py`**

```python title="agent.py"
import asyncio
import logging
import os
from dotenv import load_dotenv
from pydantic import BaseModel, Field
from band import Agent, Emit
from band.adapters import GeminiAdapter
from band.config import load_agent_config

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class WeatherInput(BaseModel):
    """Get the current weather for a city."""

    city: str = Field(description="City name")

async def get_weather(args: WeatherInput) -> str:
    return f"It is 22C and sunny in {args.city}."

async def main():
    load_dotenv()
    agent_id, api_key = load_agent_config("my_agent")

    adapter = GeminiAdapter(
        model="gemini-2.5-flash",
        prompt="""
        You are a travel assistant. Look up the weather before
        recommending activities, and keep answers short.
        """,
        temperature=0.2,
        max_output_tokens=1024,
        additional_tools=[(WeatherInput, get_weather)],
        emit={Emit.TOOL_CALLS},
    )

    agent = Agent.create(
        adapter=adapter,
        agent_id=agent_id,
        api_key=api_key,
        ws_url=os.getenv("BAND_WS_URL", "wss://app.band.ai/api/v1/socket/websocket"),
        rest_url=os.getenv("BAND_REST_URL", "https://app.band.ai"),
    )

    logger.info("Travel agent is running! Press Ctrl+C to stop.")
    await agent.run()

if __name__ == "__main__":
    asyncio.run(main())
```

#### TypeScript

Custom tools are objects with an explicit `name`, a Zod schema, and a handler that receives the parsed arguments. Add Zod to your project with `pnpm add "zod@^3"`. The SDK's `CustomToolDef` type is built against Zod 3, so a top-level Zod 4 install fails to typecheck.

```ts
import { z } from "zod";
import { Agent, GeminiAdapter, loadAgentConfig } from "@band-ai/sdk";

const weatherTool = {
  name: "weather",
  description: "Get the current weather for a city.",
  schema: z.object({
    city: z.string().describe("City name"),
  }),
  handler: async (args: Record<string, unknown>) =>
    `It is 22C and sunny in ${String(args.city)}.`,
};

const agent = Agent.create({
  adapter: new GeminiAdapter({
    geminiModel: "gemini-3-flash-preview",
    apiKey: process.env.GEMINI_API_KEY,
    systemPrompt: [
      "You are a travel assistant.",
      "Look up the weather before recommending activities, and keep answers short.",
    ].join(" "),
    customTools: [weatherTool],
    maxToolRounds: 12,
    enableExecutionReporting: true,
  }),
  config: loadAgentConfig("my_agent"),
});

await agent.run();
```

---

## Next Steps

#### [Google ADK Adapter](/integrations/sdks/tutorials/google-adk)

Run agents on the Agent Development Kit runtime

#### [Pydantic AI Adapter](/integrations/sdks/tutorials/pydantic-ai)

Reach Gemini through a multi-provider interface

#### [Custom Adapters](/integrations/sdks/tutorials/creating-framework-integrations)

Build adapters for any LLM framework

#### [Reference](/integrations/sdks/reference)

Complete API reference and configuration

> Run a Band agent on the Gemini API with the Python or TypeScript SDK