or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

built-in-tools.mdimage-generation.mdindex.mdlanguage-models.mdprovider-setup.mdtext-embeddings.md
tile.json

built-in-tools.mddocs/

Built-in Tools

Google-specific tool integrations including web search, code execution, and URL content analysis that extend model capabilities with real-time information and computational power.

Capabilities

Tools Access

Access built-in tools through the provider's tools property.

interface GoogleGenerativeAIProvider {
  tools: {
    googleSearch: (options?: GoogleSearchOptions) => Tool;
    urlContext: () => Tool;
    codeExecution: () => Tool;
  };
}

interface GoogleSearchOptions {
  /** Search mode configuration */
  mode?: "MODE_DYNAMIC" | "MODE_UNSPECIFIED";
  /** Dynamic retrieval threshold */
  dynamicThreshold?: number;
}

Usage Examples:

import { google } from "@ai-sdk/google";
import { generateText } from "ai";

// Use Google Search tool
const searchResult = await generateText({
  model: google("gemini-1.5-pro"),
  prompt: "What are the latest developments in quantum computing?",
  tools: {
    googleSearch: google.tools.googleSearch(),
  },
});

// Use URL Context tool
const urlResult = await generateText({
  model: google("gemini-1.5-pro"),
  prompt: "Summarize the content at https://example.com/article",
  tools: {
    urlContext: google.tools.urlContext(),
  },
});

// Use Code Execution tool
const codeResult = await generateText({
  model: google("gemini-2.0-flash"),
  prompt: "Calculate the Fibonacci sequence up to the 10th number",
  tools: {
    codeExecution: google.tools.codeExecution(),
  },
});

Google Search Tool

Provides the model with real-time access to web content through Google Search with grounding metadata.

Google Search Configuration

/**
 * Creates a Google search tool with real-time web access
 * @param options - Optional search configuration
 * @returns Tool for Google Search functionality
 */
googleSearch(options?: {
  /** Search mode configuration (default: "MODE_UNSPECIFIED") */
  mode?: "MODE_DYNAMIC" | "MODE_UNSPECIFIED";
  /** Dynamic retrieval threshold (default: 1) */
  dynamicThreshold?: number;
}): Tool;

Search Modes:

  • MODE_UNSPECIFIED: Always trigger retrieval (default behavior)
  • MODE_DYNAMIC: Run retrieval only when the system decides it's necessary

Usage Examples:

import { google } from "@ai-sdk/google";
import { generateText } from "ai";

// Default search behavior
const result1 = await generateText({
  model: google("gemini-1.5-pro"),
  prompt: "What's happening in the stock market today?",
  tools: {
    googleSearch: google.tools.googleSearch(),
  },
});

// Dynamic search mode
const result2 = await generateText({
  model: google("gemini-1.5-pro"),
  prompt: "Tell me about machine learning algorithms",
  tools: {
    googleSearch: google.tools.googleSearch({
      mode: "MODE_DYNAMIC",
      dynamicThreshold: 0.8,
    }),
  },
});

// Access search metadata
if (result1.responseMetadata?.groundingMetadata) {
  const metadata = result1.responseMetadata.groundingMetadata;
  console.log("Search queries used:", metadata.webSearchQueries);
  console.log("Retrieved sources:", metadata.groundingChunks?.length);
  
  metadata.groundingChunks?.forEach((chunk, index) => {
    if (chunk.web) {
      console.log(`Source ${index + 1}: ${chunk.web.title} - ${chunk.web.uri}`);
    }
  });
}

Search Metadata Types

interface GoogleGenerativeAIGroundingMetadata {
  webSearchQueries?: string[] | null;
  retrievalQueries?: string[] | null;
  searchEntryPoint?: { renderedContent: string } | null;
  groundingChunks?: GroundingChunk[] | null;
  groundingSupports?: GroundingSupport[] | null;
  retrievalMetadata?: RetrievalMetadata | null;
}

interface GroundingChunk {
  web?: { uri: string; title: string } | null;
  retrievedContext?: { uri: string; title: string } | null;
}

interface GroundingSupport {
  segment: {
    startIndex?: number | null;
    endIndex?: number | null;
    text?: string | null;
  };
  segment_text?: string | null;
  groundingChunkIndices?: number[] | null;
  supportChunkIndices?: number[] | null;
  confidenceScores?: number[] | null;
  confidenceScore?: number[] | null;
}

URL Context Tool

Gives the model direct access to web page content from URLs mentioned in prompts.

URL Context Configuration

/**
 * Creates a URL context tool for web content access
 * @returns Tool for URL content retrieval
 */
urlContext(): Tool;

Usage Examples:

import { google } from "@ai-sdk/google";
import { generateText } from "ai";

// URL context automatically extracts URLs from the prompt
const result = await generateText({
  model: google("gemini-1.5-pro"),
  prompt: `
    Please analyze and summarize the content from these websites:
    - https://example.com/news-article
    - https://blog.example.com/latest-post
    
    Focus on the main themes and key takeaways.
  `,
  tools: {
    urlContext: google.tools.urlContext(),
  },
});

// Access URL metadata
if (result.responseMetadata?.urlContextMetadata) {
  const urlMeta = result.responseMetadata.urlContextMetadata;
  console.log("URLs processed:");
  
  urlMeta.urlMetadata.forEach((meta, index) => {
    console.log(`${index + 1}. ${meta.retrievedUrl} - Status: ${meta.urlRetrievalStatus}`);
  });
}

// Compare content from multiple URLs
const comparisonResult = await generateText({
  model: google("gemini-1.5-pro"),
  prompt: `
    Compare the approaches discussed in these two articles:
    https://site1.com/approach-a
    https://site2.com/approach-b
    
    What are the pros and cons of each approach?
  `,
  tools: {
    urlContext: google.tools.urlContext(),
  },
});

URL Context Metadata Types

interface GoogleGenerativeAIUrlContextMetadata {
  urlMetadata: UrlMetadata[];
}

interface UrlMetadata {
  retrievedUrl: string;
  urlRetrievalStatus: string;
}

Code Execution Tool

Enables the model to generate and execute Python code with output capture and error handling.

Code Execution Configuration

/**
 * Creates a code execution tool for Python code generation and execution
 * @returns Tool for code execution functionality
 */
codeExecution(): Tool;

Note: Code execution requires Gemini models version 2.0 or higher for optimal compatibility.

Usage Examples:

import { google } from "@ai-sdk/google";
import { generateText } from "ai";

// Mathematical calculations
const mathResult = await generateText({
  model: google("gemini-2.0-flash"),
  prompt: "Calculate the area under the curve y = x^2 from x = 0 to x = 5 using numerical integration",
  tools: {
    codeExecution: google.tools.codeExecution(),
  },
});

// Data analysis
const dataResult = await generateText({
  model: google("gemini-2.0-flash"),
  prompt: `
    Create a dataset of 100 random numbers, calculate statistics (mean, median, std dev),
    and create a simple visualization. Show the code and results.
  `,
  tools: {
    codeExecution: google.tools.codeExecution(),
  },
});

// Algorithm implementation
const algoResult = await generateText({
  model: google("gemini-2.0-flash"),
  prompt: "Implement and test a binary search algorithm. Show it working with an example.",
  tools: {
    codeExecution: google.tools.codeExecution(),
  },
});

console.log("Generated code output:", mathResult.text);

Code Execution Schema

interface CodeExecutionInput {
  /** The programming language of the code */
  language: string;
  /** The code to be executed */
  code: string;
}

interface CodeExecutionOutput {
  /** The outcome of the execution (e.g., "OUTCOME_OK") */
  outcome: string;
  /** The output from the code execution */
  output: string;
}

Code Execution Examples:

import { google } from "@ai-sdk/google";
import { generateText } from "ai";

// Complex data processing
const processingResult = await generateText({
  model: google("gemini-2.0-flash"),
  prompt: `
    Create a Python program that:
    1. Generates sample sales data for 12 months
    2. Calculates monthly growth rates
    3. Identifies the best and worst performing months
    4. Creates a summary report
    
    Run the code and show the results.
  `,
  tools: {
    codeExecution: google.tools.codeExecution(),
  },
});

// Scientific computation
const scientificResult = await generateText({
  model: google("gemini-2.0-flash"),
  prompt: `
    Solve this physics problem with code:
    A projectile is launched at 45 degrees with initial velocity 20 m/s.
    Calculate and plot the trajectory, find the maximum height and range.
    Use g = 9.81 m/s².
  `,
  tools: {
    codeExecution: google.tools.codeExecution(),
  },
});

// Machine learning example
const mlResult = await generateText({
  model: google("gemini-2.0-flash"),
  prompt: `
    Create a simple linear regression model:
    1. Generate synthetic data with some noise
    2. Fit a linear model
    3. Calculate R-squared and show predictions
    4. Plot the data and regression line
  `,
  tools: {
    codeExecution: google.tools.codeExecution(),
  },
});

Multi-Tool Usage

Combine multiple tools for comprehensive analysis and problem-solving.

import { google } from "@ai-sdk/google";
import { generateText } from "ai";

// Combine search and code execution
const combinedResult = await generateText({
  model: google("gemini-2.0-flash"),
  prompt: `
    Research the current Bitcoin price and then create a Python program to:
    1. Track price movements over the last hour (simulate with random data)
    2. Calculate volatility metrics
    3. Generate a simple trend analysis
    
    Use real current price data from your search.
  `,
  tools: {
    googleSearch: google.tools.googleSearch(),
    codeExecution: google.tools.codeExecution(),
  },
});

// Combine URL context and code execution
const urlCodeResult = await generateText({
  model: google("gemini-2.0-flash"),
  prompt: `
    Analyze the API documentation at https://api.example.com/docs
    and then write Python code to:
    1. Make sample API calls
    2. Parse the responses
    3. Demonstrate error handling
  `,
  tools: {
    urlContext: google.tools.urlContext(),
    codeExecution: google.tools.codeExecution(),
  },
});

// All tools together
const allToolsResult = await generateText({
  model: google("gemini-2.0-flash"),
  prompt: `
    Research the latest trends in renewable energy (search),
    analyze the technical specifications from https://energy-stats.gov/report (URL),
    and create a Python analysis tool to:
    1. Model energy production scenarios
    2. Calculate cost-benefit ratios
    3. Generate recommendations
  `,
  tools: {
    googleSearch: google.tools.googleSearch(),
    urlContext: google.tools.urlContext(),
    codeExecution: google.tools.codeExecution(),
  },
});

Best Practices

Google Search Tool

  • Use specific, focused queries for better results
  • Check grounding metadata to understand source reliability
  • Prefer MODE_DYNAMIC for efficiency when search isn't always needed

URL Context Tool

  • Ensure URLs are publicly accessible
  • Include multiple relevant URLs for comprehensive analysis
  • Check urlRetrievalStatus in metadata for successful retrieval

Code Execution Tool

  • Use with Gemini 2.0+ models for best compatibility
  • Include clear requirements and expected outputs in prompts
  • Handle both successful execution and error cases
  • Be mindful of execution time and resource constraints

Multi-Tool Workflows

  • Chain tools logically (search → analyze → code → validate)
  • Use clear, structured prompts when combining tools
  • Validate intermediate results before proceeding to next steps
  • Consider rate limits and API costs when using multiple tools