0
# Function Calling
1

2
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.
3

4
## Capabilities
5

6
### Tool Definition
7

8
Define tools and functions for the model to use.
9

10
```typescript { .api }
11
/**
12
 * Tool definition containing function declarations and built-in tools
13
 */
14
interface Tool {
15
  /** Custom function declarations */
16
  functionDeclarations?: FunctionDeclaration[];
17
  /** Code execution tool */
18
  codeExecution?: ToolCodeExecution;
19
  /** Google Search tool */
20
  googleSearch?: GoogleSearch;
21
  /** Google Search retrieval */
22
  googleSearchRetrieval?: GoogleSearchRetrieval;
23
  /** RAG retrieval */
24
  retrieval?: Retrieval;
25
  /** File search tool */
26
  fileSearch?: FileSearch;
27
  /** Computer use tool (experimental) */
28
  computerUse?: ComputerUse;
29
  /** Vertex RAG store */
30
  vertexRAGStore?: VertexRAGStore;
31
  /** Vertex AI Search */
32
  vertexAISearch?: VertexAISearch;
33
  /** External API integration */
34
  externalAPI?: ExternalAPI;
35
  /** Google Maps tool */
36
  googleMaps?: GoogleMaps;
37
  /** Enterprise web search */
38
  enterpriseWebSearch?: EnterpriseWebSearch;
39
  /** URL context tool */
40
  urlContext?: UrlContext;
41
}
42

43
/**
44
 * Function declaration for custom functions
45
 */
46
interface FunctionDeclaration {
47
  /** Function name (required) */
48
  name?: string;
49
  /** Function purpose and usage description */
50
  description?: string;
51
  /** Parameters schema (OpenAPI format) */
52
  parameters?: Schema;
53
  /** Alternative JSON schema for parameters */
54
  parametersJsonSchema?: unknown;
55
  /** Response schema */
56
  response?: Schema;
57
  /** Alternative JSON schema for response */
58
  responseJsonSchema?: unknown;
59
  /** Function behavior (BLOCKING or NON_BLOCKING) */
60
  behavior?: Behavior;
61
}
62
```
63

64
**Usage Examples:**
65

66
```typescript
67
import { GoogleGenAI, Tool, FunctionDeclaration, Type } from '@google/genai';
68

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

71
// Define a weather function
72
const weatherTool: Tool = {
73
  functionDeclarations: [{
74
    name: 'getWeather',
75
    description: 'Get the current weather for a location',
76
    parameters: {
77
      type: Type.OBJECT,
78
      properties: {
79
        location: {
80
          type: Type.STRING,
81
          description: 'City name or coordinates'
82
        },
83
        unit: {
84
          type: Type.STRING,
85
          enum: ['celsius', 'fahrenheit'],
86
          description: 'Temperature unit'
87
        }
88
      },
89
      required: ['location']
90
    }
91
  }]
92
};
93

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

103
// Check for function calls
104
if (response.functionCalls) {
105
  console.log('Model wants to call:', response.functionCalls);
106
}
107
```
108

109
### FunctionCall
110

111
Function call request from the model.
112

113
```typescript { .api }
114
/**
115
 * Function call from model
116
 */
117
interface FunctionCall {
118
  /** Function name */
119
  name?: string;
120
  /** Function arguments */
121
  args?: Record<string, unknown>;
122
  /** Call ID for tracking */
123
  id?: string;
124
}
125
```
126

127
### FunctionResponse
128

129
Function execution result to send back to model.
130

131
```typescript { .api }
132
/**
133
 * Function response from user
134
 */
135
interface FunctionResponse {
136
  /** Function name */
137
  name?: string;
138
  /** Response data */
139
  response?: Record<string, unknown>;
140
  /** Call ID */
141
  id?: string;
142
  /** Additional content parts */
143
  parts?: FunctionResponsePart[];
144
}
145

146
/**
147
 * Additional content in function response
148
 */
149
interface FunctionResponsePart {
150
  /** Inline data */
151
  inlineData?: Blob;
152
  /** File data */
153
  fileData?: FileData;
154
}
155
```
156

157
### CallableTool Interface
158

159
Interface for automatic function calling implementation.
160

161
```typescript { .api }
162
/**
163
 * Interface for automatic function calling
164
 */
165
interface CallableTool {
166
  /** Get tool declaration */
167
  tool(): Promise<Tool>;
168
  /** Execute function calls */
169
  callTool(functionCalls: FunctionCall[]): Promise<Part[]>;
170
}
171
```
172

173
### Tool Configuration
174

175
Configure how the model uses tools.
176

177
```typescript { .api }
178
/**
179
 * Tool configuration
180
 */
181
interface ToolConfig {
182
  /** Function calling configuration */
183
  functionCallingConfig?: FunctionCallingConfig;
184
}
185

186
/**
187
 * Function calling configuration
188
 */
189
interface FunctionCallingConfig {
190
  /** Function calling mode */
191
  mode?: FunctionCallingConfigMode;
192
  /** Restrict to specific functions */
193
  allowedFunctionNames?: string[];
194
  /** Stream function call arguments */
195
  streamFunctionCallArguments?: boolean;
196
}
197

198
enum FunctionCallingConfigMode {
199
  MODE_UNSPECIFIED = 'MODE_UNSPECIFIED',
200
  /** Model decides whether to call functions */
201
  AUTO = 'AUTO',
202
  /** Model must call at least one function */
203
  ANY = 'ANY',
204
  /** Disable function calling */
205
  NONE = 'NONE',
206
  /** Validated function calling */
207
  VALIDATED = 'VALIDATED'
208
}
209
```
210

211
### Automatic Function Calling Config
212

213
Configuration for automatic function execution.
214

215
```typescript { .api }
216
/**
217
 * Automatic function calling configuration
218
 */
219
interface AutomaticFunctionCallingConfig {
220
  /** Disable automatic function calling */
221
  disable?: boolean;
222
  /** Maximum number of remote calls (default: 10) */
223
  maximumRemoteCalls?: number;
224
  /** Include AFC history in response */
225
  shouldAppendHistory?: boolean;
226
}
227
```
228

229
## Built-in Tools
230

231
### Code Execution
232

233
Built-in Python code execution.
234

235
```typescript { .api }
236
interface ToolCodeExecution {
237
  /** Enable code execution */
238
  enabled?: boolean;
239
}
240
```
241

242
**Usage Example:**
243

244
```typescript
245
const response = await client.models.generateContent({
246
  model: 'gemini-2.0-flash',
247
  contents: 'Calculate the 100th fibonacci number',
248
  config: {
249
    tools: [{
250
      codeExecution: { enabled: true }
251
    }]
252
  }
253
});
254
```
255

256
### Google Search
257

258
Google Search integration.
259

260
```typescript { .api }
261
interface GoogleSearch {
262
  /** Dynamic retrieval configuration */
263
  dynamicRetrievalConfig?: DynamicRetrievalConfig;
264
}
265

266
interface DynamicRetrievalConfig {
267
  /** Dynamic threshold */
268
  dynamicThreshold?: number;
269
  /** Mode for dynamic retrieval */
270
  mode?: DynamicRetrievalMode;
271
}
272
```
273

274
### File Search
275

276
Search through uploaded files or corpora.
277

278
```typescript { .api }
279
interface FileSearch {
280
  /** File search store reference */
281
  fileSearchStore?: string;
282
}
283
```
284

285
## Types
286

287
### Schema
288

289
OpenAPI-style schema for parameters and responses.
290

291
```typescript { .api }
292
interface Schema {
293
  /** Data type */
294
  type?: Type;
295
  /** Format specifier */
296
  format?: string;
297
  /** Description */
298
  description?: string;
299
  /** Can be null */
300
  nullable?: boolean;
301
  /** Enumerated values */
302
  enum?: string[];
303
  /** Array item schema */
304
  items?: Schema;
305
  /** Object properties */
306
  properties?: Record<string, Schema>;
307
  /** Required properties */
308
  required?: string[];
309
  /** Maximum items */
310
  maxItems?: string;
311
  /** Minimum items */
312
  minItems?: string;
313
  /** Property ordering */
314
  propertyOrdering?: string[];
315
}
316

317
enum Type {
318
  TYPE_UNSPECIFIED = 'TYPE_UNSPECIFIED',
319
  STRING = 'STRING',
320
  NUMBER = 'NUMBER',
321
  INTEGER = 'INTEGER',
322
  BOOLEAN = 'BOOLEAN',
323
  ARRAY = 'ARRAY',
324
  OBJECT = 'OBJECT'
325
}
326
```
327

328
### Behavior
329

330
Function execution behavior.
331

332
```typescript { .api }
333
enum Behavior {
334
  BEHAVIOR_UNSPECIFIED = 'BEHAVIOR_UNSPECIFIED',
335
  /** Function must complete before continuing */
336
  BLOCKING = 'BLOCKING',
337
  /** Function can execute asynchronously */
338
  NON_BLOCKING = 'NON_BLOCKING'
339
}
340
```
341

342
## Complete Examples
343

344
### Manual Function Calling
345

346
```typescript
347
import { GoogleGenAI, FunctionCall, Part } from '@google/genai';
348

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

351
// Define tools
352
const tools = [{
353
  functionDeclarations: [
354
    {
355
      name: 'getWeather',
356
      description: 'Get current weather',
357
      parameters: {
358
        type: Type.OBJECT,
359
        properties: {
360
          location: { type: Type.STRING }
361
        },
362
        required: ['location']
363
      }
364
    },
365
    {
366
      name: 'getTime',
367
      description: 'Get current time',
368
      parameters: {
369
        type: Type.OBJECT,
370
        properties: {
371
          timezone: { type: Type.STRING }
372
        },
373
        required: ['timezone']
374
      }
375
    }
376
  ]
377
}];
378

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

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

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

393
    let result;
394
    if (fc.name === 'getWeather') {
395
      // Execute function
396
      result = { temperature: 22, condition: 'sunny' };
397
    }
398

399
    functionResults.push({
400
      functionResponse: {
401
        name: fc.name,
402
        response: result,
403
        id: fc.id
404
      }
405
    });
406
  }
407

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

419
  console.log('Final response:', response2.text);
420
}
421
```
422

423
### Automatic Function Calling with CallableTool
424

425
```typescript
426
import { CallableTool, Tool, FunctionCall, Part } from '@google/genai';
427

428
// Implement CallableTool interface
429
class WeatherTool implements CallableTool {
430
  async tool(): Promise<Tool> {
431
    return {
432
      functionDeclarations: [{
433
        name: 'getWeather',
434
        description: 'Get current weather for a location',
435
        parameters: {
436
          type: Type.OBJECT,
437
          properties: {
438
            location: {
439
              type: Type.STRING,
440
              description: 'City name'
441
            }
442
          },
443
          required: ['location']
444
        }
445
      }]
446
    };
447
  }
448

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

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

456
        // Simulate API call
457
        const weatherData = {
458
          temperature: 22,
459
          condition: 'sunny',
460
          humidity: 65
461
        };
462

463
        results.push({
464
          functionResponse: {
465
            name: fc.name,
466
            response: weatherData,
467
            id: fc.id
468
          }
469
        });
470
      }
471
    }
472

473
    return results;
474
  }
475
}
476

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

480
const response = await client.models.generateContent({
481
  model: 'gemini-2.0-flash',
482
  contents: 'What is the weather in London?',
483
  config: {
484
    tools: [weatherTool],
485
    automaticFunctionCalling: {
486
      maximumRemoteCalls: 5
487
    }
488
  }
489
});
490

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

494
// Check AFC history
495
if (response.automaticFunctionCallingHistory) {
496
  console.log('Function calls made:', response.automaticFunctionCallingHistory);
497
}
498
```
499

500
### Multiple Functions
501

502
```typescript
503
const tools = [{
504
  functionDeclarations: [
505
    {
506
      name: 'searchDatabase',
507
      description: 'Search product database',
508
      parameters: {
509
        type: Type.OBJECT,
510
        properties: {
511
          query: { type: Type.STRING },
512
          category: { type: Type.STRING },
513
          maxResults: { type: Type.INTEGER }
514
        },
515
        required: ['query']
516
      }
517
    },
518
    {
519
      name: 'getProductDetails',
520
      description: 'Get detailed product information',
521
      parameters: {
522
        type: Type.OBJECT,
523
        properties: {
524
          productId: { type: Type.STRING }
525
        },
526
        required: ['productId']
527
      }
528
    },
529
    {
530
      name: 'checkInventory',
531
      description: 'Check product availability',
532
      parameters: {
533
        type: Type.OBJECT,
534
        properties: {
535
          productId: { type: Type.STRING },
536
          location: { type: Type.STRING }
537
        },
538
        required: ['productId']
539
      }
540
    }
541
  ]
542
}];
543

544
const response = await client.models.generateContent({
545
  model: 'gemini-2.0-flash',
546
  contents: 'Find laptops under $1000 and check availability in New York',
547
  config: {
548
    tools,
549
    toolConfig: {
550
      functionCallingConfig: {
551
        mode: FunctionCallingConfigMode.AUTO
552
      }
553
    }
554
  }
555
});
556
```
557

558
### Function Calling Modes
559

560
```typescript
561
// AUTO mode - model decides when to call
562
const autoResponse = await client.models.generateContent({
563
  model: 'gemini-2.0-flash',
564
  contents: 'What is the capital of France?',
565
  config: {
566
    tools: [calculatorTool],
567
    toolConfig: {
568
      functionCallingConfig: {
569
        mode: FunctionCallingConfigMode.AUTO
570
      }
571
    }
572
  }
573
});
574

575
// ANY mode - model must call at least one function
576
const anyResponse = await client.models.generateContent({
577
  model: 'gemini-2.0-flash',
578
  contents: 'Calculate something',
579
  config: {
580
    tools: [calculatorTool],
581
    toolConfig: {
582
      functionCallingConfig: {
583
        mode: FunctionCallingConfigMode.ANY
584
      }
585
    }
586
  }
587
});
588

589
// NONE mode - disable function calling
590
const noneResponse = await client.models.generateContent({
591
  model: 'gemini-2.0-flash',
592
  contents: 'Tell me about Paris',
593
  config: {
594
    tools: [calculatorTool],
595
    toolConfig: {
596
      functionCallingConfig: {
597
        mode: FunctionCallingConfigMode.NONE
598
      }
599
    }
600
  }
601
});
602

603
// Restrict to specific functions
604
const restrictedResponse = await client.models.generateContent({
605
  model: 'gemini-2.0-flash',
606
  contents: 'What is the weather?',
607
  config: {
608
    tools: [multiTool],
609
    toolConfig: {
610
      functionCallingConfig: {
611
        mode: FunctionCallingConfigMode.AUTO,
612
        allowedFunctionNames: ['getWeather', 'getTime']
613
      }
614
    }
615
  }
616
});
617
```
618

619
### Function with Response Schema
620

621
```typescript
622
const functionWithResponse: FunctionDeclaration = {
623
  name: 'analyzeImage',
624
  description: 'Analyze image and return structured data',
625
  parameters: {
626
    type: Type.OBJECT,
627
    properties: {
628
      imageUrl: { type: Type.STRING }
629
    },
630
    required: ['imageUrl']
631
  },
632
  response: {
633
    type: Type.OBJECT,
634
    properties: {
635
      objects: {
636
        type: Type.ARRAY,
637
        items: {
638
          type: Type.OBJECT,
639
          properties: {
640
            name: { type: Type.STRING },
641
            confidence: { type: Type.NUMBER },
642
            boundingBox: {
643
              type: Type.OBJECT,
644
              properties: {
645
                x: { type: Type.NUMBER },
646
                y: { type: Type.NUMBER },
647
                width: { type: Type.NUMBER },
648
                height: { type: Type.NUMBER }
649
              }
650
            }
651
          }
652
        }
653
      }
654
    }
655
  }
656
};
657
```
658

659
### Code Execution Tool
660

661
```typescript
662
// Enable code execution
663
const response = await client.models.generateContent({
664
  model: 'gemini-2.0-flash',
665
  contents: 'Generate a plot of y = x^2 for x from -10 to 10',
666
  config: {
667
    tools: [{
668
      codeExecution: { enabled: true }
669
    }]
670
  }
671
});
672

673
// Check for code execution results
674
response.candidates?.[0]?.content?.parts?.forEach(part => {
675
  if (part.executableCode) {
676
    console.log('Code:', part.executableCode.code);
677
    console.log('Language:', part.executableCode.language);
678
  }
679
  if (part.codeExecutionResult) {
680
    console.log('Result:', part.codeExecutionResult.output);
681
    console.log('Outcome:', part.codeExecutionResult.outcome);
682
  }
683
});
684
```
685

686
### File Search Tool
687

688
```typescript
689
// Create file search store
690
const store = await client.fileSearchStores.create({
691
  displayName: 'Product Documentation'
692
});
693

694
// Upload documents to store
695
await client.fileSearchStores.uploadToFileSearchStore({
696
  fileSearchStore: store.name!,
697
  file: './docs/manual.pdf',
698
  mimeType: 'application/pdf'
699
});
700

701
// Use in generation with file search
702
const response = await client.models.generateContent({
703
  model: 'gemini-2.0-flash',
704
  contents: 'How do I reset the device?',
705
  config: {
706
    tools: [{
707
      fileSearch: {
708
        fileSearchStore: store.name
709
      }
710
    }]
711
  }
712
});
713
```
714

715
### Parallel Function Calling
716

717
```typescript
718
const response = await client.models.generateContent({
719
  model: 'gemini-2.0-flash',
720
  contents: 'What is the weather in Paris, London, and Tokyo?',
721
  config: {
722
    tools: [weatherTool]
723
  }
724
});
725

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

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

736
      return {
737
        functionResponse: {
738
          name: fc.name,
739
          response: weather,
740
          id: fc.id
741
        }
742
      };
743
    })
744
  );
745
}
746
```
747

748
### Function Responses with Media
749

750
```typescript
751
import { createFunctionResponsePartFromUri } from '@google/genai';
752

753
// Function that returns image
754
class ChartTool implements CallableTool {
755
  async tool(): Promise<Tool> {
756
    return {
757
      functionDeclarations: [{
758
        name: 'generateChart',
759
        description: 'Generate a chart image',
760
        parameters: {
761
          type: Type.OBJECT,
762
          properties: {
763
            data: { type: Type.ARRAY },
764
            chartType: { type: Type.STRING }
765
          }
766
        }
767
      }]
768
    };
769
  }
770

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

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

778
      results.push({
779
        functionResponse: {
780
          name: fc.name,
781
          response: { success: true },
782
          id: fc.id,
783
          parts: [
784
            createFunctionResponsePartFromUri(
785
              chartUrl,
786
              'image/png'
787
            )
788
          ]
789
        }
790
      });
791
    }
792

793
    return results;
794
  }
795

796
  private async generateChartImage(args: any): Promise<string> {
797
    // Generate and upload chart, return URI
798
    return 'gs://bucket/chart.png';
799
  }
800
}
801
```
802

803
### Error Handling in Functions
804

805
```typescript
806
class RobustTool implements CallableTool {
807
  async callTool(functionCalls: FunctionCall[]): Promise<Part[]> {
808
    const results: Part[] = [];
809

810
    for (const fc of functionCalls) {
811
      try {
812
        const result = await this.executeFunction(fc);
813
        results.push({
814
          functionResponse: {
815
            name: fc.name,
816
            response: { success: true, data: result },
817
            id: fc.id
818
          }
819
        });
820
      } catch (error) {
821
        // Return error information to model
822
        results.push({
823
          functionResponse: {
824
            name: fc.name,
825
            response: {
826
              success: false,
827
              error: error.message
828
            },
829
            id: fc.id
830
          }
831
        });
832
      }
833
    }
834

835
    return results;
836
  }
837
}
838
```
839

840
### AFC Configuration
841

842
```typescript
843
// Control automatic function calling behavior
844
const response = await client.models.generateContent({
845
  model: 'gemini-2.0-flash',
846
  contents: 'Plan a trip to Paris with weather and flights',
847
  config: {
848
    tools: [weatherTool, flightTool, hotelTool],
849
    automaticFunctionCalling: {
850
      // Limit iterations to prevent long chains
851
      maximumRemoteCalls: 3,
852
      // Include history in response for debugging
853
      shouldAppendHistory: true
854
    }
855
  }
856
});
857

858
// AFC history shows all function calls made
859
if (response.automaticFunctionCallingHistory) {
860
  console.log('AFC made these calls:');
861
  response.automaticFunctionCallingHistory.forEach((content, i) => {
862
    console.log(`Turn ${i}:`, content.role);
863
    content.parts?.forEach(part => {
864
      if (part.functionCall) {
865
        console.log('  Called:', part.functionCall.name);
866
      }
867
      if (part.functionResponse) {
868
        console.log('  Response:', part.functionResponse.response);
869
      }
870
    });
871
  });
872
}
873
```
874