0
# Tools and Function Calling
1

2
Use tools like Google Search, code execution, and custom function calling with automatic or manual execution.
3

4
## Core Imports
5

6
```java
7
import com.google.genai.types.Tool;
8
import com.google.genai.types.FunctionDeclaration;
9
import com.google.genai.types.FunctionCall;
10
import com.google.genai.types.FunctionResponse;
11
import com.google.genai.types.ToolConfig;
12
import com.google.genai.types.FunctionCallingConfig;
13
import com.google.genai.types.AutomaticFunctionCallingConfig;
14
import com.google.genai.types.Schema;
15
import com.google.genai.types.GoogleSearch;
16
import com.google.genai.types.CodeExecution;
17
import java.lang.reflect.Method;
18
```
19

20
## Tool Type
21

22
```java { .api }
23
package com.google.genai.types;
24

25
public final class Tool {
26
  public static Builder builder();
27

28
  public Optional<List<FunctionDeclaration>> functionDeclarations();
29
  public Optional<GoogleSearchRetrieval> googleSearchRetrieval();
30
  public Optional<GoogleSearch> googleSearch();
31
  public Optional<GoogleMaps> googleMaps();
32
  public Optional<CodeExecution> codeExecution();
33
  public Optional<FileSearch> fileSearch();
34
  public Optional<ComputerUse> computerUse();
35
  public Optional<Retrieval> retrieval();
36
  public Optional<UrlContext> urlContext();
37
}
38
```
39

40
## Function Declaration
41

42
```java { .api }
43
package com.google.genai.types;
44

45
public final class FunctionDeclaration {
46
  public static Builder builder();
47

48
  public Optional<String> name();
49
  public Optional<String> description();
50
  public Optional<Schema> parameters();
51
}
52
```
53

54
## Tool Configuration
55

56
```java { .api }
57
package com.google.genai.types;
58

59
public final class ToolConfig {
60
  public static Builder builder();
61

62
  public Optional<FunctionCallingConfig> functionCallingConfig();
63
  public Optional<RetrievalConfig> retrievalConfig();
64
}
65
```
66

67
```java { .api }
68
package com.google.genai.types;
69

70
public final class FunctionCallingConfig {
71
  public static Builder builder();
72

73
  public Optional<String> mode();
74
  public Optional<List<String>> allowedFunctionNames();
75
  public Optional<Boolean> streamFunctionCallArguments();
76
}
77
```
78

79
```java { .api }
80
package com.google.genai.types;
81

82
public final class AutomaticFunctionCallingConfig {
83
  public static Builder builder();
84

85
  public Optional<Boolean> disable();
86
  public Optional<Integer> maxRemoteCalls();
87
  public Optional<Boolean> appendHistory();
88
}
89
```
90

91
## Automatic Function Calling
92

93
### Step 1: Enable Parameter Names
94

95
Add to `pom.xml`:
96

97
```xml
98
<plugin>
99
  <groupId>org.apache.maven.plugins</groupId>
100
  <artifactId>maven-compiler-plugin</artifactId>
101
  <version>3.14.0</version>
102
  <configuration>
103
    <compilerArgs>
104
      <arg>-parameters</arg>
105
    </compilerArgs>
106
  </configuration>
107
</plugin>
108
```
109

110
### Step 2: Define Function
111

112
```java
113
public class WeatherService {
114
    public static String getCurrentWeather(String location, String unit) {
115
        // Implementation
116
        return "The weather in " + location + " is sunny, 72 degrees " + unit;
117
    }
118
}
119
```
120

121
### Step 3: Use with Generation
122

123
```java
124
import java.lang.reflect.Method;
125

126
Method weatherMethod = WeatherService.class.getMethod(
127
    "getCurrentWeather", String.class, String.class);
128

129
GenerateContentConfig config = GenerateContentConfig.builder()
130
    .tools(Tool.builder()
131
        .functions(weatherMethod)
132
        .build())
133
    .build();
134

135
GenerateContentResponse response = client.models.generateContent(
136
    "gemini-2.0-flash",
137
    "What's the weather in Vancouver?",
138
    config
139
);
140

141
System.out.println("Response: " + response.text());
142
System.out.println("Function calling history: " +
143
    response.automaticFunctionCallingHistory().orElse(null));
144
```
145

146
### Multiple Functions
147

148
```java
149
public class ToolBox {
150
    public static String getCurrentWeather(String location) {
151
        return "Sunny, 75°F";
152
    }
153

154
    public static int add(int a, int b) {
155
        return a + b;
156
    }
157

158
    public static String searchWeb(String query) {
159
        return "Search results for: " + query;
160
    }
161
}
162

163
// Load all methods
164
Method weatherMethod = ToolBox.class.getMethod("getCurrentWeather", String.class);
165
Method addMethod = ToolBox.class.getMethod("add", int.class, int.class);
166
Method searchMethod = ToolBox.class.getMethod("searchWeb", String.class);
167

168
Tool tool = Tool.builder()
169
    .functions(weatherMethod, addMethod, searchMethod)
170
    .build();
171

172
GenerateContentConfig config = GenerateContentConfig.builder()
173
    .tools(tool)
174
    .build();
175
```
176

177
## Manual Function Calling
178

179
### Define Function Declaration
180

181
```java
182
FunctionDeclaration function = FunctionDeclaration.builder()
183
    .name("getCurrentWeather")
184
    .description("Get the current weather in a location")
185
    .parameters(Schema.builder()
186
        .type(Type.Known.OBJECT)
187
        .properties(ImmutableMap.of(
188
            "location", Schema.builder()
189
                .type(Type.Known.STRING)
190
                .description("The city and state, e.g. San Francisco, CA")
191
                .build(),
192
            "unit", Schema.builder()
193
                .type(Type.Known.STRING)
194
                .enum_(ImmutableList.of("celsius", "fahrenheit"))
195
                .build()
196
        ))
197
        .required(ImmutableList.of("location"))
198
        .build())
199
    .build();
200

201
Tool tool = Tool.builder()
202
    .functionDeclarations(ImmutableList.of(function))
203
    .build();
204
```
205

206
### Use in Generation
207

208
```java
209
GenerateContentConfig config = GenerateContentConfig.builder()
210
    .tools(tool)
211
    .build();
212

213
GenerateContentResponse response = client.models.generateContent(
214
    "gemini-2.0-flash",
215
    "What's the weather in Boston?",
216
    config
217
);
218

219
// Process function call
220
response.candidates().ifPresent(candidates -> {
221
    if (!candidates.isEmpty()) {
222
        Content content = candidates.get(0).content().orElse(null);
223
        if (content != null && content.parts().isPresent()) {
224
            for (Part part : content.parts().get()) {
225
                part.functionCall().ifPresent(functionCall -> {
226
                    // Execute function
227
                    String functionName = functionCall.name().orElse("");
228
                    JsonNode args = functionCall.args().orElse(null);
229

230
                    // Call your function
231
                    String result = executeFunction(functionName, args);
232

233
                    // Send result back
234
                    sendFunctionResponse(functionCall, result);
235
                });
236
            }
237
        }
238
    }
239
});
240
```
241

242
### Send Function Response
243

244
```java
245
private void sendFunctionResponse(FunctionCall call, String result) {
246
    FunctionResponse response = FunctionResponse.builder()
247
        .name(call.name().orElse(""))
248
        .response(objectMapper.valueToTree(ImmutableMap.of("result", result)))
249
        .id(call.id().orElse(null))
250
        .build();
251

252
    Content responseContent = Content.fromParts(
253
        Part.fromFunctionResponse(response)
254
    );
255

256
    GenerateContentResponse finalResponse = client.models.generateContent(
257
        "gemini-2.0-flash",
258
        responseContent,
259
        null
260
    );
261

262
    System.out.println(finalResponse.text());
263
}
264
```
265

266
## Google Search Tool
267

268
```java
269
import com.google.genai.types.GoogleSearch;
270

271
Tool searchTool = Tool.builder()
272
    .googleSearch(GoogleSearch.builder().build())
273
    .build();
274

275
GenerateContentConfig config = GenerateContentConfig.builder()
276
    .tools(searchTool)
277
    .build();
278

279
GenerateContentResponse response = client.models.generateContent(
280
    "gemini-2.0-flash",
281
    "What are the latest developments in quantum computing?",
282
    config
283
);
284
```
285

286
## Code Execution Tool
287

288
```java
289
import com.google.genai.types.CodeExecution;
290

291
Tool codeExecTool = Tool.builder()
292
    .codeExecution(CodeExecution.builder().build())
293
    .build();
294

295
GenerateContentConfig config = GenerateContentConfig.builder()
296
    .tools(codeExecTool)
297
    .build();
298

299
GenerateContentResponse response = client.models.generateContent(
300
    "gemini-2.0-flash",
301
    "Calculate the first 10 fibonacci numbers",
302
    config
303
);
304
```
305

306
## Function Calling Modes
307

308
```java
309
import com.google.genai.types.FunctionCallingMode;
310

311
// AUTO: Model decides when to call functions
312
ToolConfig autoConfig = ToolConfig.builder()
313
    .functionCallingConfig(FunctionCallingConfig.builder()
314
        .mode(FunctionCallingMode.Known.AUTO)
315
        .build())
316
    .build();
317

318
// ANY: Model must call at least one function
319
ToolConfig anyConfig = ToolConfig.builder()
320
    .functionCallingConfig(FunctionCallingConfig.builder()
321
        .mode(FunctionCallingMode.Known.ANY)
322
        .build())
323
    .build();
324

325
// NONE: Model cannot call functions
326
ToolConfig noneConfig = ToolConfig.builder()
327
    .functionCallingConfig(FunctionCallingConfig.builder()
328
        .mode(FunctionCallingMode.Known.NONE)
329
        .build())
330
    .build();
331

332
GenerateContentConfig config = GenerateContentConfig.builder()
333
    .tools(tool)
334
    .toolConfig(autoConfig)
335
    .build();
336
```
337

338
## Restrict Functions
339

340
```java
341
// Only allow specific functions
342
ToolConfig config = ToolConfig.builder()
343
    .functionCallingConfig(FunctionCallingConfig.builder()
344
        .mode(FunctionCallingMode.Known.ANY)
345
        .allowedFunctionNames(ImmutableList.of("getCurrentWeather", "searchWeb"))
346
        .build())
347
    .build();
348

349
GenerateContentConfig genConfig = GenerateContentConfig.builder()
350
    .tools(tool)
351
    .toolConfig(config)
352
    .build();
353
```
354

355
## Configure Automatic Function Calling
356

357
```java
358
// Customize automatic function calling behavior
359
AutomaticFunctionCallingConfig afcConfig = AutomaticFunctionCallingConfig.builder()
360
    .maxRemoteCalls(5) // Limit remote calls
361
    .appendHistory(true) // Include in history
362
    .build();
363

364
GenerateContentConfig config = GenerateContentConfig.builder()
365
    .tools(tool)
366
    .automaticFunctionCalling(afcConfig)
367
    .build();
368

369
// Or disable AFC
370
AutomaticFunctionCallingConfig disableAFC = AutomaticFunctionCallingConfig.builder()
371
    .disable(true)
372
    .build();
373

374
GenerateContentConfig manualConfig = GenerateContentConfig.builder()
375
    .tools(tool)
376
    .automaticFunctionCalling(disableAFC)
377
    .build();
378
```
379

380
## Multi-Turn Function Calling
381

382
```java
383
List<Content> conversationHistory = new ArrayList<>();
384

385
// Initial query
386
conversationHistory.add(Content.builder()
387
    .role("user")
388
    .parts(ImmutableList.of(Part.fromText("What's the weather in Paris and Berlin?")))
389
    .build());
390

391
GenerateContentResponse response1 = client.models.generateContent(
392
    "gemini-2.0-flash",
393
    conversationHistory,
394
    config
395
);
396

397
// Process function calls and add to history
398
response1.candidates().ifPresent(candidates -> {
399
    Content modelResponse = candidates.get(0).content().orElse(null);
400
    if (modelResponse != null) {
401
        conversationHistory.add(modelResponse);
402

403
        // Execute function calls and add responses
404
        for (Part part : modelResponse.parts().orElse(ImmutableList.of())) {
405
            part.functionCall().ifPresent(call -> {
406
                String result = executeFunct(call);
407
                conversationHistory.add(Content.fromParts(
408
                    Part.fromFunctionResponse(FunctionResponse.builder()
409
                        .name(call.name().orElse(""))
410
                        .response(objectMapper.valueToTree(result))
411
                        .build())
412
                ));
413
            });
414
        }
415
    }
416
});
417

418
// Continue conversation
419
GenerateContentResponse finalResponse = client.models.generateContent(
420
    "gemini-2.0-flash",
421
    conversationHistory,
422
    config
423
);
424
```
425

426
## Best Practices
427

428
### Type-Safe Function Parameters
429

430
```java
431
public static class WeatherParams {
432
    public String location;
433
    public String unit;
434
}
435

436
public static String getCurrentWeather(WeatherParams params) {
437
    return "Weather in " + params.location + ": sunny";
438
}
439
```
440

441
### Error Handling in Functions
442

443
```java
444
public static String safeFunction(String input) {
445
    try {
446
        // Function logic
447
        return performOperation(input);
448
    } catch (Exception e) {
449
        return "Error: " + e.getMessage();
450
    }
451
}
452
```
453

454
### Validate Function Results
455

456
```java
457
FunctionCall call = /* ... */;
458
String result = executeFunction(call);
459

460
// Validate result before sending
461
if (result == null || result.isEmpty()) {
462
    result = "Function returned no result";
463
}
464

465
FunctionResponse response = FunctionResponse.builder()
466
    .name(call.name().orElse(""))
467
    .response(objectMapper.valueToTree(ImmutableMap.of("result", result)))
468
    .build();
469
```
470