Skip to main content
Craft Agents supports Google’s Gemini models through the Google AI Studio API. This connection includes native Google Search grounding - allowing Gemini to answer questions using real-time web search results.

​
Why Google AI Studio?

Native Search Grounding

Gemini can search the web and cite sources in its responses

Generous Free Tier

15 requests/minute and 1,500 requests/day at no cost

Latest Gemini Models

Access to Gemini 2.5 Pro, Flash, and Flash Lite

Multimodal Support

Native image, video, and audio understanding

​
Setup

1

Get your API key

  1. Go to Google AI Studio
  2. Click Get API key or Create API key
  3. Select a Google Cloud project (or create a new one)
  4. Copy your API key
The API key is free to generate and includes a generous free tier. No credit card required.
2

Add connection in Craft Agents

  1. Open Settings → AI Connections
  2. Click Add Connection
  3. Select Google AI Studio
  4. Paste your API key
  5. Choose your default model (e.g., gemini-2.5-pro)
  6. Click Save
3

Verify connection

The connection will be automatically validated. You’ll see a green checkmark when it’s ready to use.

​
Available Models

Craft Agents automatically detects Gemini models available on your API key: 
'gemini-2.5-pro'        // Most capable, 2M token context
'gemini-2.5-flash'      // Fast and efficient
'gemini-2.5-flash-lite' // Ultra-fast for simple tasks
Legacy models (1.5-series and 2.0-flash) do not support Google Search grounding or all function calling features.
Source: packages/shared/src/config/models-pi.ts:45-55

​
Native Google Search Grounding

Gemini models have built-in access to Google Search. When you ask a question requiring current information, Gemini automatically searches the web and cites sources.

​
How It Works

1

Ask a question

Simply ask the agent a question that requires real-time data:
"What's the latest news about Claude Opus 4.6?"
"What's the weather in Tokyo today?"
"Find documentation for the Stripe API"
2

Agent uses web_search tool

When connected to Google AI Studio, Craft Agents exposes a web_search tool that makes a separate Gemini API call with { googleSearch: {} } grounding enabled.
The Gemini API doesn’t allow combining Google Search grounding with function calling in the same request. So we expose it as an explicit tool instead.
3

Get grounded results with citations

The response includes:
  • A natural language answer synthesized by Gemini
  • Source citations with clickable links
  • Grounding metadata (search queries, web chunks)

​
Implementation Details

The Google Search tool is implemented in the Pi Agent Server: 
// packages/pi-agent-server/src/tools/google-search.ts

const GROUNDING_MODEL = 'gemini-2.5-flash';
const API_BASE = 'https://generativelanguage.googleapis.com/v1beta/models';

const response = await fetch(`${API_BASE}/${GROUNDING_MODEL}:generateContent`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-goog-api-key': apiKey,
  },
  body: JSON.stringify({
    contents: [{ role: 'user', parts: [{ text: query }] }],
    tools: [{ googleSearch: {} }], // Enable grounding
  }),
});

// Extract grounded text and source citations
const text = candidate.content.parts.map(p => p.text).join('');
const sources = metadata.groundingChunks
  .map((c, i) => `${i + 1}. [${c.web.title}](${c.web.uri})`)
  .join('\n');
Source: packages/pi-agent-server/src/tools/google-search.ts:20-106
Google Search grounding is only available when the Pi auth provider is google. It replaces the default DuckDuckGo web_search tool.

​
Pricing

Google AI Studio offers a generous free tier:
ModelFree TierPaid Pricing (Input/Output)
Gemini 2.5 Pro15 RPM / 1,500 RPD1.25/1.25 / 5.00 per 1M tokens
Gemini 2.5 Flash15 RPM / 1,500 RPD0.30/0.30 / 1.20 per 1M tokens
Gemini 2.5 Flash Lite15 RPM / 1,500 RPD0.15/0.15 / 0.60 per 1M tokens
RPM = Requests per minute
RPD = Requests per dayGoogle Search grounding is included at no extra cost.
For higher limits, upgrade to Google Cloud AI.

​
Multimodal Support

Gemini models natively support images, videos, and audio. In Craft Agents:
  • Images: Drag and drop PNG, JPEG, WebP files
  • Videos: MP4, MOV (up to 10 minutes)
  • Audio: MP3, WAV, OGG
  • Documents: PDF (automatically converted to images)
Gemini will analyze the content and respond accordingly.

​
Troubleshooting

Error: Authentication failed. Check your API key or OAuth token.Solutions:
  • Verify you copied the full API key from Google AI Studio
  • Ensure the API key is associated with an active Google Cloud project
  • Check that the Google AI API is enabled in your project
Error: Rate limited or quota exceeded. Try again later.Free tier limits:
  • 15 requests per minute
  • 1,500 requests per day
Wait until the rate limit resets, or upgrade to a paid plan for higher limits.
Problem: The web_search tool isn’t being used or returns generic results.Check:
  • Ensure your connection’s piAuthProvider is set to google (this should happen automatically)
  • Verify you’re using a Gemini 2.5 model (not 1.5 or 2.0)
  • Try explicitly asking the agent to “search the web” or “look up current information”
The Google Search tool is only injected when the Pi auth provider is google. Other providers use DuckDuckGo instead.
Error: Model not found. Check the connection configuration.Some models may not be available in all regions:
  • Check Google AI Studio for model availability
  • Try switching to gemini-2.5-flash (most widely available)
Here’s a sample conversation demonstrating native Google Search grounding: 
What's the latest release of Bun, and what are the key features?

​
Next Steps

Add More Providers

Connect to OpenRouter, Ollama, or custom endpoints

Configure Workspaces

Set per-workspace default models

Build docs developers (and LLMs) love

Get started for freeTalk to us