# Skill: Configure Google Gemini (Vertex AI)

Use when you want to use Google's Gemini models as your LLM provider via Google Cloud Vertex AI.
Gemini's standout feature is its 1M token context window, making it ideal for
long-document processing agents.

## How It Works

arccrew uses `langchain-google-vertexai` which authenticates via Google's Application Default
Credentials (ADC). There is no separate API key — access is controlled by your GCP project and
IAM permissions.

## Setup

### Step 1: Authenticate

**Local development:**

If you don't have the Google Cloud SDK installed:
```bash
brew install --cask google-cloud-sdk
```
Then restart your terminal (or run `source "$(brew --prefix)/share/google-cloud-sdk/path.zsh.inc"`), and authenticate:
```bash
gcloud auth application-default login
```

**CI / production:**
```bash
# Set path to a service account JSON with Vertex AI permissions
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

### Step 2: Add to `.env`

```bash
# .env
GOOGLE_CLOUD_PROJECT=my-gcp-project

# For CI/prod — local dev uses ADC from gcloud, so this can be omitted there
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

### Step 3: Set the model

```bash
AGENT_MODEL=google_vertexai/gemini-2.0-flash
```

`langchain-google-vertexai` reads `GOOGLE_CLOUD_PROJECT` from the environment. arccrew exports
this from your `.env` at startup — no code changes needed.

## Model Strings

```bash
AGENT_MODEL=google_vertexai/gemini-2.5-flash           # Fast, cheap, 1M context — recommended default
AGENT_MODEL=google_vertexai/gemini-2.5-pro             # Most capable, best reasoning
```

> **Note:** `gemini-2.0-flash` is restricted to existing GCP customers (as of March 2026) and will be shut down June 2026. Use `gemini-2.5-flash` for all new projects — it's faster, cheaper, and more capable.

## Model Comparison

### Gemini 2.5 Flash ← recommended default
```
google_vertexai/gemini-2.5-flash
```
- **Speed/cost profile**: equivalent to Claude Haiku or GPT-4o-mini
- **Context window**: 1,000,000 tokens (1M)
- **Best for**: tool-calling agents, research agents, fast iteration
- **Available**: all GCP projects, no special access required

### Gemini 2.5 Pro
```
google_vertexai/gemini-2.5-pro
```
- **Speed/cost profile**: equivalent to Claude Sonnet or GPT-4o
- **Context window**: 1,000,000 tokens (1M)
- **Best for**: complex reasoning, long-form synthesis, agentic tasks
- **Key advantage**: strongest reasoning at Gemini-class speed

## Flash vs Pro Decision Guide

| Scenario | Use |
|----------|-----|
| Research agent calling `web_search` many times | Flash — speed matters more than reasoning depth |
| Writer agent producing long structured content | Pro — better at multi-step composition |
| Reviewer agent checking output quality | Flash — short task, judgment over speed |
| Long-document analysis (>100K tokens of input) | Either — both have 1M context |
| Code generation and explanation | Pro — stronger code reasoning |
| Prototyping a new pipeline | Flash — cheap iteration |

## Using Gemini's 1M Context Window

Gemini's biggest differentiator is the context window. Use it for agents that need to
process large documents:

```python
class DocumentAnalystAgent(BaseAgent):
    def __init__(self):
        super().__init__(name="doc_analyst", prompts_dir=PROMPTS_DIR)

    @track_timing
    async def execute(self, state: dict) -> Command:
        # Read a large document into the task directly
        large_doc = Path(state.get("workspace_dir", "tmp")) / "large_report.txt"
        content = large_doc.read_text() if large_doc.exists() else ""

        result = await self.generate(
            f"Analyze this entire document and extract key themes:\n\n{content}"
        )
        data = self.extract_json(result) or {"raw": result}
        return Command(goto="next", update={"result": data})
```

Set `DOC_ANALYST_MODEL=google_vertexai/gemini-2.5-flash` in `.env` — only this agent uses Gemini
while others use your default model.

## Per-Agent Gemini Override

To use Gemini for only one specific agent while others use Claude:

```bash
# .env
AGENT_MODEL=anthropic/claude-haiku-4-5-20251001        # default
DOC_ANALYST_MODEL=google_vertexai/gemini-2.5-flash     # this agent uses Gemini
```

No code changes needed — `get_model("doc_analyst")` picks up `DOC_ANALYST_MODEL` automatically.

## GCP Integrations in arccrew

arccrew has two distinct Google Cloud integrations. Both use the same GCP auth (`google-auth`):

| Integration | Purpose | Auth |
|---|---|---|
| **Vertex AI** (`google_vertexai/`) | LLM — powers your agents | ADC or service account |
| **Google Sheets** (`arccrew[sheets]`) | Data tools — read/write spreadsheets | OAuth2 or service account |

They are independent — you can use Vertex AI without Sheets and vice versa.
See `/add-google-sheets` for the Sheets integration.

## Verify Configuration

```bash
arccrew check
```

If it prints a model initialization error mentioning `google_vertexai`, check:
1. `GOOGLE_CLOUD_PROJECT` is in `.env`
2. You have run `gcloud auth application-default login` (or set `GOOGLE_APPLICATION_CREDENTIALS`)
3. Your GCP project has the Vertex AI API enabled
