> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Gemini

> Use Google Gemini models (Gemini 2.5 Flash, Gemini 2.5 Pro) with Agentium. Setup, factory, config, and multi-modal support.

# Google Gemini

Use Google's Gemini models with Agentium through the unified `ModelProvider` interface. Gemini offers strong multi-modal capabilities—vision, audio, and native file handling.

***

## Setup

<Tabs>
  <Tab title="Install">
    Install the Google GenAI SDK (required by Agentium for Gemini support):

    ```bash theme={null}
    npm install @google/genai
    ```
  </Tab>

  <Tab title="Environment">
    Set your API key via environment variable:

    ```bash theme={null}
    export GOOGLE_API_KEY="..."
    ```

    Or pass it in config (see below).
  </Tab>
</Tabs>

***

## Factory

```typescript theme={null}
import { google } from "@agentium/core";

const model = google("gemini-2.5-flash");
```

<ParamField path="modelId" type="string" required>
  The Gemini model identifier.
</ParamField>

<ParamField path="config" type="object" required={false}>
  Optional configuration. See Config below.
</ParamField>

***

## Supported Models

| Model ID           | Description                                                            |
| ------------------ | ---------------------------------------------------------------------- |
| `gemini-2.5-flash` | Fast, efficient. Great for high-throughput and latency-sensitive apps. |
| `gemini-2.5-pro`   | Highest capability. Best for complex reasoning and long-context tasks. |

***

## Config

<ParamField path="apiKey" type="string" required={false}>
  Google API key. If omitted, uses `GOOGLE_API_KEY` environment variable.
</ParamField>

### Example

```typescript theme={null}
const model = google("gemini-2.5-flash", {
  apiKey: process.env.GOOGLE_API_KEY,
});
```

***

## Multi-Modal Support

Gemini supports **vision**, **audio**, and **file** content. Pass multi-modal content via `ContentPart[]` in messages:

<CodeGroup>
  <CodeGroup.Item title="Vision (image)">
    ```typescript theme={null}
    const messages: ChatMessage[] = [
      {
        role: "user",
        content: [
          { type: "text", text: "What's in this image?" },
          {
            type: "image",
            data: base64ImageData,
            mimeType: "image/png",
          },
        ],
      },
    ];
    const response = await model.generate(messages);
    ```
  </CodeGroup.Item>

  <CodeGroup.Item title="Audio">
    ```typescript theme={null}
    const messages: ChatMessage[] = [
      {
        role: "user",
        content: [
          { type: "text", text: "Transcribe this audio." },
          {
            type: "audio",
            data: base64AudioData,
            mimeType: "audio/mp3",
          },
        ],
      },
    ];
    const response = await model.generate(messages);
    ```
  </CodeGroup.Item>
</CodeGroup>

### Files & Documents

Gemini handles files natively — including PDF, CSV, XLSX, and more. It's the only provider that supports XLSX directly:

```typescript theme={null}
import { Agent, google, type ContentPart } from "@agentium/core";
import { readFileSync } from "node:fs";

const agent = new Agent({
  name: "file-analyzer",
  model: google("gemini-2.5-flash"),
  instructions: "Analyze documents and data files thoroughly.",
});

// PDF analysis
const pdfResult = await agent.run([
  { type: "text", text: "Summarize the key findings." },
  {
    type: "file",
    data: readFileSync("report.pdf").toString("base64"),
    mimeType: "application/pdf",
    filename: "report.pdf",
  },
] as ContentPart[]);

// Excel file (XLSX) — only Gemini supports this natively
const xlsxResult = await agent.run([
  { type: "text", text: "What are the total sales by region?" },
  {
    type: "file",
    data: readFileSync("sales.xlsx").toString("base64"),
    mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    filename: "sales.xlsx",
  },
] as ContentPart[]);

// CSV file
const csvResult = await agent.run([
  { type: "text", text: "Find the outliers in this dataset." },
  {
    type: "file",
    data: readFileSync("data.csv").toString("base64"),
    mimeType: "text/csv",
    filename: "data.csv",
  },
] as ContentPart[]);
```

### Supported File Types

| Format     | MIME Type                                                           | Support                 |
| ---------- | ------------------------------------------------------------------- | ----------------------- |
| PDF        | `application/pdf`                                                   | Full                    |
| CSV        | `text/csv`                                                          | Full                    |
| XLSX       | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | Full (unique to Gemini) |
| Plain text | `text/plain`                                                        | Full                    |
| HTML       | `text/html`                                                         | Full                    |
| JSON       | `application/json`                                                  | Full                    |

Gemini processes file content natively via `inlineData`, making it the most versatile provider for document analysis tasks.

***

## Realtime / Voice (Gemini Live)

For real-time voice agents, use `googleLive()` to create a Google Gemini Live provider:

```typescript theme={null}
import { VoiceAgent, googleLive } from "@agentium/core";

const agent = new VoiceAgent({
  name: "assistant",
  provider: googleLive("gemini-2.5-flash-native-audio-preview-12-2025"),
  instructions: "You are a voice assistant.",
});
```

`googleLive()` is a shorthand for `new GoogleLiveProvider()`. It accepts the same config:

```typescript theme={null}
googleLive("gemini-2.5-flash-native-audio-preview-12-2025", {
  apiKey: "...", // optional, defaults to GOOGLE_API_KEY env
});
```

Requires: `npm install @google/genai`

See the [Voice Agents](/voice/overview) docs for full details.

***

## Full Example

```typescript theme={null}
import { Agent, google } from "@agentium/core";

const agent = new Agent({
  name: "Gemini Assistant",
  model: google("gemini-2.5-flash", {
    apiKey: process.env.GOOGLE_API_KEY,
  }),
  instructions: "You are a helpful assistant with strong multi-modal capabilities.",
});

const output = await agent.run("Summarize the key points of this document.");
console.log(output.text);
```