CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-google--genai

Google Gen AI JavaScript SDK for building applications powered by Gemini with content generation, image/video generation, function calling, caching, and real-time live sessions

Overview
Eval results
Files

function-calling.mddocs/

Function Calling

Function calling enables models to interact with external APIs and tools, with support for manual function execution, automatic function calling (AFC), and various tool types including code execution, search, and retrieval.

Capabilities

Tool Definition

Define tools and functions for the model to use.

/**
 * Tool definition containing function declarations and built-in tools
 */
interface Tool {
  /** Custom function declarations */
  functionDeclarations?: FunctionDeclaration[];
  /** Code execution tool */
  codeExecution?: ToolCodeExecution;
  /** Google Search tool */
  googleSearch?: GoogleSearch;
  /** Google Search retrieval */
  googleSearchRetrieval?: GoogleSearchRetrieval;
  /** RAG retrieval */
  retrieval?: Retrieval;
  /** File search tool */
  fileSearch?: FileSearch;
  /** Computer use tool (experimental) */
  computerUse?: ComputerUse;
  /** Vertex RAG store */
  vertexRAGStore?: VertexRAGStore;
  /** Vertex AI Search */
  vertexAISearch?: VertexAISearch;
  /** External API integration */
  externalAPI?: ExternalAPI;
  /** Google Maps tool */
  googleMaps?: GoogleMaps;
  /** Enterprise web search */
  enterpriseWebSearch?: EnterpriseWebSearch;
  /** URL context tool */
  urlContext?: UrlContext;
}

/**
 * Function declaration for custom functions
 */
interface FunctionDeclaration {
  /** Function name (required) */
  name?: string;
  /** Function purpose and usage description */
  description?: string;
  /** Parameters schema (OpenAPI format) */
  parameters?: Schema;
  /** Alternative JSON schema for parameters */
  parametersJsonSchema?: unknown;
  /** Response schema */
  response?: Schema;
  /** Alternative JSON schema for response */
  responseJsonSchema?: unknown;
  /** Function behavior (BLOCKING or NON_BLOCKING) */
  behavior?: Behavior;
}

Usage Examples:

import { GoogleGenAI, Tool, FunctionDeclaration, Type } from '@google/genai';

const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

// Define a weather function
const weatherTool: Tool = {
  functionDeclarations: [{
    name: 'getWeather',
    description: 'Get the current weather for a location',
    parameters: {
      type: Type.OBJECT,
      properties: {
        location: {
          type: Type.STRING,
          description: 'City name or coordinates'
        },
        unit: {
          type: Type.STRING,
          enum: ['celsius', 'fahrenheit'],
          description: 'Temperature unit'
        }
      },
      required: ['location']
    }
  }]
};

// Use tool in generation
const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'What is the weather in Paris?',
  config: {
    tools: [weatherTool]
  }
});

// Check for function calls
if (response.functionCalls) {
  console.log('Model wants to call:', response.functionCalls);
}

FunctionCall

Function call request from the model.

/**
 * Function call from model
 */
interface FunctionCall {
  /** Function name */
  name?: string;
  /** Function arguments */
  args?: Record<string, unknown>;
  /** Call ID for tracking */
  id?: string;
}

FunctionResponse

Function execution result to send back to model.

/**
 * Function response from user
 */
interface FunctionResponse {
  /** Function name */
  name?: string;
  /** Response data */
  response?: Record<string, unknown>;
  /** Call ID */
  id?: string;
  /** Additional content parts */
  parts?: FunctionResponsePart[];
}

/**
 * Additional content in function response
 */
interface FunctionResponsePart {
  /** Inline data */
  inlineData?: Blob;
  /** File data */
  fileData?: FileData;
}

CallableTool Interface

Interface for automatic function calling implementation.

/**
 * Interface for automatic function calling
 */
interface CallableTool {
  /** Get tool declaration */
  tool(): Promise<Tool>;
  /** Execute function calls */
  callTool(functionCalls: FunctionCall[]): Promise<Part[]>;
}

Tool Configuration

Configure how the model uses tools.

/**
 * Tool configuration
 */
interface ToolConfig {
  /** Function calling configuration */
  functionCallingConfig?: FunctionCallingConfig;
}

/**
 * Function calling configuration
 */
interface FunctionCallingConfig {
  /** Function calling mode */
  mode?: FunctionCallingConfigMode;
  /** Restrict to specific functions */
  allowedFunctionNames?: string[];
  /** Stream function call arguments */
  streamFunctionCallArguments?: boolean;
}

enum FunctionCallingConfigMode {
  MODE_UNSPECIFIED = 'MODE_UNSPECIFIED',
  /** Model decides whether to call functions */
  AUTO = 'AUTO',
  /** Model must call at least one function */
  ANY = 'ANY',
  /** Disable function calling */
  NONE = 'NONE',
  /** Validated function calling */
  VALIDATED = 'VALIDATED'
}

Automatic Function Calling Config

Configuration for automatic function execution.

/**
 * Automatic function calling configuration
 */
interface AutomaticFunctionCallingConfig {
  /** Disable automatic function calling */
  disable?: boolean;
  /** Maximum number of remote calls (default: 10) */
  maximumRemoteCalls?: number;
  /** Include AFC history in response */
  shouldAppendHistory?: boolean;
}

Built-in Tools

Code Execution

Built-in Python code execution.

interface ToolCodeExecution {
  /** Enable code execution */
  enabled?: boolean;
}

Usage Example:

const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Calculate the 100th fibonacci number',
  config: {
    tools: [{
      codeExecution: { enabled: true }
    }]
  }
});

Google Search

Google Search integration.

interface GoogleSearch {
  /** Dynamic retrieval configuration */
  dynamicRetrievalConfig?: DynamicRetrievalConfig;
}

interface DynamicRetrievalConfig {
  /** Dynamic threshold */
  dynamicThreshold?: number;
  /** Mode for dynamic retrieval */
  mode?: DynamicRetrievalMode;
}

File Search

Search through uploaded files or corpora.

interface FileSearch {
  /** File search store reference */
  fileSearchStore?: string;
}

Types

Schema

OpenAPI-style schema for parameters and responses.

interface Schema {
  /** Data type */
  type?: Type;
  /** Format specifier */
  format?: string;
  /** Description */
  description?: string;
  /** Can be null */
  nullable?: boolean;
  /** Enumerated values */
  enum?: string[];
  /** Array item schema */
  items?: Schema;
  /** Object properties */
  properties?: Record<string, Schema>;
  /** Required properties */
  required?: string[];
  /** Maximum items */
  maxItems?: string;
  /** Minimum items */
  minItems?: string;
  /** Property ordering */
  propertyOrdering?: string[];
}

enum Type {
  TYPE_UNSPECIFIED = 'TYPE_UNSPECIFIED',
  STRING = 'STRING',
  NUMBER = 'NUMBER',
  INTEGER = 'INTEGER',
  BOOLEAN = 'BOOLEAN',
  ARRAY = 'ARRAY',
  OBJECT = 'OBJECT'
}

Behavior

Function execution behavior.

enum Behavior {
  BEHAVIOR_UNSPECIFIED = 'BEHAVIOR_UNSPECIFIED',
  /** Function must complete before continuing */
  BLOCKING = 'BLOCKING',
  /** Function can execute asynchronously */
  NON_BLOCKING = 'NON_BLOCKING'
}

Complete Examples

Manual Function Calling

import { GoogleGenAI, FunctionCall, Part } from '@google/genai';

const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

// Define tools
const tools = [{
  functionDeclarations: [
    {
      name: 'getWeather',
      description: 'Get current weather',
      parameters: {
        type: Type.OBJECT,
        properties: {
          location: { type: Type.STRING }
        },
        required: ['location']
      }
    },
    {
      name: 'getTime',
      description: 'Get current time',
      parameters: {
        type: Type.OBJECT,
        properties: {
          timezone: { type: Type.STRING }
        },
        required: ['timezone']
      }
    }
  ]
}];

// Initial request
const response1 = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'What is the weather in Tokyo?',
  config: { tools }
});

// Handle function calls
if (response1.functionCalls) {
  const functionResults: Part[] = [];

  for (const fc of response1.functionCalls) {
    console.log(`Calling ${fc.name} with args:`, fc.args);

    let result;
    if (fc.name === 'getWeather') {
      // Execute function
      result = { temperature: 22, condition: 'sunny' };
    }

    functionResults.push({
      functionResponse: {
        name: fc.name,
        response: result,
        id: fc.id
      }
    });
  }

  // Send results back
  const response2 = await client.models.generateContent({
    model: 'gemini-2.0-flash',
    contents: [
      { role: 'user', parts: [{ text: 'What is the weather in Tokyo?' }] },
      { role: 'model', parts: response1.candidates![0].content!.parts! },
      { role: 'user', parts: functionResults }
    ],
    config: { tools }
  });

  console.log('Final response:', response2.text);
}

Automatic Function Calling with CallableTool

import { CallableTool, Tool, FunctionCall, Part } from '@google/genai';

// Implement CallableTool interface
class WeatherTool implements CallableTool {
  async tool(): Promise<Tool> {
    return {
      functionDeclarations: [{
        name: 'getWeather',
        description: 'Get current weather for a location',
        parameters: {
          type: Type.OBJECT,
          properties: {
            location: {
              type: Type.STRING,
              description: 'City name'
            }
          },
          required: ['location']
        }
      }]
    };
  }

  async callTool(functionCalls: FunctionCall[]): Promise<Part[]> {
    const results: Part[] = [];

    for (const fc of functionCalls) {
      if (fc.name === 'getWeather') {
        const location = fc.args?.location as string;

        // Simulate API call
        const weatherData = {
          temperature: 22,
          condition: 'sunny',
          humidity: 65
        };

        results.push({
          functionResponse: {
            name: fc.name,
            response: weatherData,
            id: fc.id
          }
        });
      }
    }

    return results;
  }
}

// Use with automatic function calling
const weatherTool = new WeatherTool();

const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'What is the weather in London?',
  config: {
    tools: [weatherTool],
    automaticFunctionCalling: {
      maximumRemoteCalls: 5
    }
  }
});

// Response already includes function call results
console.log('Response:', response.text);

// Check AFC history
if (response.automaticFunctionCallingHistory) {
  console.log('Function calls made:', response.automaticFunctionCallingHistory);
}

Multiple Functions

const tools = [{
  functionDeclarations: [
    {
      name: 'searchDatabase',
      description: 'Search product database',
      parameters: {
        type: Type.OBJECT,
        properties: {
          query: { type: Type.STRING },
          category: { type: Type.STRING },
          maxResults: { type: Type.INTEGER }
        },
        required: ['query']
      }
    },
    {
      name: 'getProductDetails',
      description: 'Get detailed product information',
      parameters: {
        type: Type.OBJECT,
        properties: {
          productId: { type: Type.STRING }
        },
        required: ['productId']
      }
    },
    {
      name: 'checkInventory',
      description: 'Check product availability',
      parameters: {
        type: Type.OBJECT,
        properties: {
          productId: { type: Type.STRING },
          location: { type: Type.STRING }
        },
        required: ['productId']
      }
    }
  ]
}];

const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Find laptops under $1000 and check availability in New York',
  config: {
    tools,
    toolConfig: {
      functionCallingConfig: {
        mode: FunctionCallingConfigMode.AUTO
      }
    }
  }
});

Function Calling Modes

// AUTO mode - model decides when to call
const autoResponse = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'What is the capital of France?',
  config: {
    tools: [calculatorTool],
    toolConfig: {
      functionCallingConfig: {
        mode: FunctionCallingConfigMode.AUTO
      }
    }
  }
});

// ANY mode - model must call at least one function
const anyResponse = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Calculate something',
  config: {
    tools: [calculatorTool],
    toolConfig: {
      functionCallingConfig: {
        mode: FunctionCallingConfigMode.ANY
      }
    }
  }
});

// NONE mode - disable function calling
const noneResponse = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Tell me about Paris',
  config: {
    tools: [calculatorTool],
    toolConfig: {
      functionCallingConfig: {
        mode: FunctionCallingConfigMode.NONE
      }
    }
  }
});

// Restrict to specific functions
const restrictedResponse = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'What is the weather?',
  config: {
    tools: [multiTool],
    toolConfig: {
      functionCallingConfig: {
        mode: FunctionCallingConfigMode.AUTO,
        allowedFunctionNames: ['getWeather', 'getTime']
      }
    }
  }
});

Function with Response Schema

const functionWithResponse: FunctionDeclaration = {
  name: 'analyzeImage',
  description: 'Analyze image and return structured data',
  parameters: {
    type: Type.OBJECT,
    properties: {
      imageUrl: { type: Type.STRING }
    },
    required: ['imageUrl']
  },
  response: {
    type: Type.OBJECT,
    properties: {
      objects: {
        type: Type.ARRAY,
        items: {
          type: Type.OBJECT,
          properties: {
            name: { type: Type.STRING },
            confidence: { type: Type.NUMBER },
            boundingBox: {
              type: Type.OBJECT,
              properties: {
                x: { type: Type.NUMBER },
                y: { type: Type.NUMBER },
                width: { type: Type.NUMBER },
                height: { type: Type.NUMBER }
              }
            }
          }
        }
      }
    }
  }
};

Code Execution Tool

// Enable code execution
const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Generate a plot of y = x^2 for x from -10 to 10',
  config: {
    tools: [{
      codeExecution: { enabled: true }
    }]
  }
});

// Check for code execution results
response.candidates?.[0]?.content?.parts?.forEach(part => {
  if (part.executableCode) {
    console.log('Code:', part.executableCode.code);
    console.log('Language:', part.executableCode.language);
  }
  if (part.codeExecutionResult) {
    console.log('Result:', part.codeExecutionResult.output);
    console.log('Outcome:', part.codeExecutionResult.outcome);
  }
});

File Search Tool

// Create file search store
const store = await client.fileSearchStores.create({
  displayName: 'Product Documentation'
});

// Upload documents to store
await client.fileSearchStores.uploadToFileSearchStore({
  fileSearchStore: store.name!,
  file: './docs/manual.pdf',
  mimeType: 'application/pdf'
});

// Use in generation with file search
const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'How do I reset the device?',
  config: {
    tools: [{
      fileSearch: {
        fileSearchStore: store.name
      }
    }]
  }
});

Parallel Function Calling

const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'What is the weather in Paris, London, and Tokyo?',
  config: {
    tools: [weatherTool]
  }
});

// Model may request multiple function calls
if (response.functionCalls && response.functionCalls.length > 0) {
  console.log(`Model requested ${response.functionCalls.length} function calls`);

  // Execute all in parallel
  const results = await Promise.all(
    response.functionCalls.map(async fc => {
      const location = fc.args?.location as string;
      const weather = await fetchWeather(location);

      return {
        functionResponse: {
          name: fc.name,
          response: weather,
          id: fc.id
        }
      };
    })
  );
}

Function Responses with Media

import { createFunctionResponsePartFromUri } from '@google/genai';

// Function that returns image
class ChartTool implements CallableTool {
  async tool(): Promise<Tool> {
    return {
      functionDeclarations: [{
        name: 'generateChart',
        description: 'Generate a chart image',
        parameters: {
          type: Type.OBJECT,
          properties: {
            data: { type: Type.ARRAY },
            chartType: { type: Type.STRING }
          }
        }
      }]
    };
  }

  async callTool(functionCalls: FunctionCall[]): Promise<Part[]> {
    const results: Part[] = [];

    for (const fc of functionCalls) {
      // Generate chart and upload
      const chartUrl = await this.generateChartImage(fc.args);

      results.push({
        functionResponse: {
          name: fc.name,
          response: { success: true },
          id: fc.id,
          parts: [
            createFunctionResponsePartFromUri(
              chartUrl,
              'image/png'
            )
          ]
        }
      });
    }

    return results;
  }

  private async generateChartImage(args: any): Promise<string> {
    // Generate and upload chart, return URI
    return 'gs://bucket/chart.png';
  }
}

Error Handling in Functions

class RobustTool implements CallableTool {
  async callTool(functionCalls: FunctionCall[]): Promise<Part[]> {
    const results: Part[] = [];

    for (const fc of functionCalls) {
      try {
        const result = await this.executeFunction(fc);
        results.push({
          functionResponse: {
            name: fc.name,
            response: { success: true, data: result },
            id: fc.id
          }
        });
      } catch (error) {
        // Return error information to model
        results.push({
          functionResponse: {
            name: fc.name,
            response: {
              success: false,
              error: error.message
            },
            id: fc.id
          }
        });
      }
    }

    return results;
  }
}

AFC Configuration

// Control automatic function calling behavior
const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Plan a trip to Paris with weather and flights',
  config: {
    tools: [weatherTool, flightTool, hotelTool],
    automaticFunctionCalling: {
      // Limit iterations to prevent long chains
      maximumRemoteCalls: 3,
      // Include history in response for debugging
      shouldAppendHistory: true
    }
  }
});

// AFC history shows all function calls made
if (response.automaticFunctionCallingHistory) {
  console.log('AFC made these calls:');
  response.automaticFunctionCallingHistory.forEach((content, i) => {
    console.log(`Turn ${i}:`, content.role);
    content.parts?.forEach(part => {
      if (part.functionCall) {
        console.log('  Called:', part.functionCall.name);
      }
      if (part.functionResponse) {
        console.log('  Response:', part.functionResponse.response);
      }
    });
  });
}

Install with Tessl CLI

npx tessl i tessl/npm-google--genai

docs

auth-tokens.md

batch.md

caching.md

chat.md

client.md

content-generation.md

embeddings.md

file-search-stores.md

files.md

function-calling.md

image-generation.md

index.md

live.md

mcp.md

models.md

operations.md

tuning.md

video-generation.md

tile.json