Tool Calling

Give AI models the ability to take actions and access external data

Tool Calling

Tool calling (also known as function calling) allows AI models to interact with external systems, access real-time data, and perform actions. Models can decide when to use tools and how to call them based on the conversation context.

Defining Tools

Create tools that models can use:

TypeScript

import { genkit, z } from 'genkit';
import { googleAI } from '@genkit-ai/google-genai';

const ai = genkit({ plugins: [googleAI()] });

const menuTool = ai.defineTool(
  {
    name: 'todaysMenu',
    description: "Use this tool to retrieve all the items on today's menu",
    inputSchema: z.object({}),
    outputSchema: z.object({
      menuData: z.array(z.object({
        title: z.string(),
        price: z.string(),
        description: z.string(),
      })),
    }),
  },
  async () => {
    return { menuData: getMenuFromDatabase() };
  }
);

Using Tools

Pass tools to the model and let it decide when to use them:

Go

response, _ := genkit.Generate(ctx, g,
    ai.WithModelName("googleai/gemini-2.5-flash"),
    ai.WithPrompt("What's the weather like in San Francisco?"),
    ai.WithTools(weatherTool),
)
fmt.Println(response.Text())

Tool Choice Strategies

Control when and how the model uses tools:

Go

// Auto: Model decides whether to use tools
resp, _ := genkit.Generate(ctx, g,
    ai.WithModelName("googleai/gemini-2.5-flash"),
    ai.WithPrompt("What's the weather in Tokyo?"),
    ai.WithTools(weatherTool),
    ai.WithToolChoice(ai.ToolChoiceAuto),
)

// Required: Model must use a tool
resp, _ := genkit.Generate(ctx, g,
    ai.WithModelName("googleai/gemini-2.5-flash"),
    ai.WithPrompt("Get the weather data"),
    ai.WithTools(weatherTool),
    ai.WithToolChoice(ai.ToolChoiceRequired),
)

Structured Tool Output

Define complex return types for tools:

Go

type WeatherData struct {
    Location  string  `json:"location"`
    TempC     float64 `json:"temp_c"`
    TempF     float64 `json:"temp_f"`
    Condition string  `json:"condition"`
}

weatherTool := genkit.DefineTool(g, "weather", 
    "Get current weather for a location",
    func(ctx *ai.ToolContext, input WeatherInput) (WeatherData, error) {
        // Fetch weather data
        return simulateWeather(input.Location), nil
    },
)

Tool Interrupts (Human-in-the-Loop)

Pause execution for human approval before taking sensitive actions:

Go

type TransferInput struct {
    ToAccount string  `json:"toAccount" jsonschema:"description=destination account ID"`
    Amount    float64 `json:"amount" jsonschema:"description=amount in dollars (e.g. 50.00 for $50)"`
}

type TransferInterrupt struct {
    Reason    string  `json:"reason"` // "insufficient_balance" or "confirm_large"
    ToAccount string  `json:"toAccount"`
    Amount    float64 `json:"amount"`
    Balance   float64 `json:"balance,omitempty"`
}

transferTool := genkit.DefineTool(g, "transferMoney",
    "Transfers money to another account. Use this when the user wants to send money.",
    func(ctx *ai.ToolContext, input TransferInput) (TransferOutput, error) {
        // Check if this is a large transfer that needs confirmation
        if !ctx.IsResumed() && input.Amount > 100 {
            return TransferOutput{}, ai.InterruptWith(ctx, TransferInterrupt{
                "confirm_large", input.ToAccount, input.Amount, accountBalance,
            })
        }

        // Process the transfer
        accountBalance -= input.Amount
        return TransferOutput{"completed", "Transfer successful", accountBalance}, nil
    })

Handling Interrupts

Handle tool interrupts and resume execution:

Go

resp, err := genkit.Generate(ctx, g,
    ai.WithModelName("googleai/gemini-2.5-flash"),
    ai.WithPrompt("Transfer $5000 to account ABC123"),
    ai.WithTools(transferTool),
)

if resp.FinishReason == ai.FinishReasonInterrupted {
    for _, interrupt := range resp.Interrupts() {
        meta, _ := ai.InterruptAs[TransferInterrupt](interrupt)

        // Get user confirmation
        fmt.Printf("Confirm transfer of $%.2f? (yes/no): ", meta.Amount)
        if getUserConfirmation() {
            // Resume with approval
            part, _ := transferTool.RestartWith(interrupt)
            resp, _ = genkit.Generate(ctx, g,
                ai.WithMessages(resp.History()...),
                ai.WithTools(transferTool),
                ai.WithToolRestarts(part),
            )
        } else {
            // Cancel the transfer
            part, _ := transferTool.RespondWith(interrupt,
                TransferOutput{"cancelled", "Transfer cancelled by user.", accountBalance})
            resp, _ = genkit.Generate(ctx, g,
                ai.WithMessages(resp.History()...),
                ai.WithTools(transferTool),
                ai.WithToolResponses(part),
            )
        }
    }
}

Modifying Tool Input on Resume

Adjust tool parameters when resuming after an interrupt:

Go

if meta.Reason == "insufficient_balance" {
    fmt.Printf("You requested $%.2f but only have $%.2f\n", meta.Amount, meta.Balance)
    
    // Restart with adjusted amount
    part, err := transferTool.RestartWith(interrupt,
        ai.WithNewInput(TransferInput{meta.ToAccount, meta.Balance}))
    
    resp, _ = genkit.Generate(ctx, g,
        ai.WithMessages(resp.History()...),
        ai.WithTools(transferTool),
        ai.WithToolRestarts(part),
    )
}

Multi-Step Tool Workflows

Models can use multiple tools in sequence to accomplish complex tasks:

Go

// Define multiple tools
searchTool := genkit.DefineTool(g, "search", "Search the web", searchFunc)
calculatorTool := genkit.DefineTool(g, "calculator", "Perform calculations", calcFunc)
weatherTool := genkit.DefineTool(g, "weather", "Get weather data", weatherFunc)

// Model can use them in sequence
resp, _ := genkit.Generate(ctx, g,
    ai.WithModelName("googleai/gemini-2.5-flash"),
    ai.WithPrompt("What's the temperature difference between Tokyo and Paris?"),
    ai.WithTools(searchTool, calculatorTool, weatherTool),
)
// Model will:
// 1. Call weatherTool for Tokyo
// 2. Call weatherTool for Paris
// 3. Call calculatorTool to find the difference
// 4. Return the answer

Best Practices

Write Clear Tool Descriptions

Help the model understand when and how to use tools:

Go

genkit.DefineTool(g, "searchProducts",
    "Search for products in the catalog. Use this when the user asks about product availability, features, or pricing.",
    searchFunc,
)

Use Structured Input and Output

Define clear schemas for tool parameters:

Go

type SearchInput struct {
    Query    string   `json:"query" jsonschema:"description=The search query"`
    Category string   `json:"category,omitempty" jsonschema:"enum=electronics,enum=clothing,enum=books"`
    MaxPrice float64  `json:"maxPrice,omitempty" jsonschema:"description=Maximum price filter"`
}

Handle Errors Gracefully

Return meaningful error messages:

Go

func(ctx *ai.ToolContext, input SearchInput) (SearchResult, error) {
    results, err := searchAPI(input.Query)
    if err != nil {
        return SearchResult{}, fmt.Errorf("search failed: %w", err)
    }
    return results, nil
}

Use Tool Interrupts for Sensitive Actions

Always require human approval for:

• Financial transactions
• Data deletion
• Sending emails or messages
• Making purchases
• Modifying important settings

Complete Example

Here’s a complete payment agent with tool interrupts:

Go

paymentAgent := genkit.DefineFlow(g, "paymentAgent", 
    func(ctx context.Context, request string) (string, error) {
        resp, err := genkit.Generate(ctx, g,
            ai.WithModelName("googleai/gemini-2.5-flash"),
            ai.WithSystem("You are a helpful payment assistant."),
            ai.WithPrompt(request),
            ai.WithTools(transferMoney),
        )
        if err != nil {
            return "", err
        }

        // Handle interrupts
        for resp.FinishReason == ai.FinishReasonInterrupted {
            var restarts, responses []*ai.Part

            for _, interrupt := range resp.Interrupts() {
                meta, _ := ai.InterruptAs[TransferInterrupt](interrupt)

                if meta.Reason == "confirm_large" {
                    if getUserConfirmation() {
                        part, _ := transferMoney.RestartWith(interrupt)
                        restarts = append(restarts, part)
                    } else {
                        part, _ := transferMoney.RespondWith(interrupt,
                            TransferOutput{"cancelled", "Cancelled by user", balance})
                        responses = append(responses, part)
                    }
                }
            }

            resp, err = genkit.Generate(ctx, g,
                ai.WithMessages(resp.History()...),
                ai.WithTools(transferMoney),
                ai.WithToolRestarts(restarts...),
                ai.WithToolResponses(responses...),
            )
        }

        return resp.Text(), nil
    })

Next Steps

• Learn about RAG for knowledge retrieval
• Explore Chat Interfaces for conversational AI
• Check out Evaluation for testing tool usage