Function Calling com Gemini

Os Modelos de Linguagem Grandes (LLMs) como o Gemini estão revolucionando a forma como interagimos com a tecnologia e construímos nossas aplicações. No entanto, o seu verdadeiro poder é libertado quando conseguem interagir com o mundo exterior. É aqui que entra o function calling com Gemini (chamada de função). Este post irá guiá-lo na compreensão e implementação do “function calling” com o SDK do Google Gemini.

O que é Function Calling?

O Function calling permite que os LLMs solicitem a execução de funções externas. Em vez de apenas gerar texto, o LLM pode determinar que uma ação específica precisa ser realizada. Em seguida, estrutura uma chamada para uma função predefinida, incluindo os argumentos necessários para executá-la.

Pense desta forma: você pergunta ao Gemini: “Qual é o clima em Lagos hoje?”. O Gemini “percebe” que não possui dados meteorológicos em tempo real. Dai podemos especificar para o modelo quando essa tarefa for requisitada, o modelo deve chamar uma função específica para obter esses dados, e o processo será realizado da seguinte forma:

Identificar que existe uma função obter_clima.
Criar uma chamada para obter_clima com “Lagos, Portugal” como o argumento de localização.
Você executa obter_clima, obtém os dados meteorológicos e os fornece de volta ao Gemini.
O Gemini então gera uma resposta como: “O clima em Lagos é atualmente de 25°C e ensolarado.”

Essa capacidade é crucial para:

Acessar Dados em Tempo Real: Clima, preços de ações, notícias.
Automatizar Ações: Enviar e-mails, controlar dispositivos, fazer reservas.
Integrar com Ferramentas e APIs: Conectar-se a bancos de dados, sistemas CRM ou outros serviços.

O SDK do Gemini simplifica o processo de usar o “function calling”. Aqui está uma análise do fluxo de trabalho:

Declarar a Função: Você define o nome da função, descrição, parâmetros e seus tipos. Isso informa ao Gemini o que a função faz e como usá-la.
Fazer a Chamada à API: Você usa o método generateContent, fornecendo a consulta do usuário e a declaração da função. Você também configura o comportamento do “function calling” (por exemplo, se o Gemini deve ou pode chamar uma função).
Processar a Resposta: A resposta do Gemini conterá texto gerado ou um objeto functionCall. Se for um functionCall, ele incluirá o nome da função a ser chamada e os argumentos.
Executar a Função: Sua aplicação pega o functionCall e executa a função real.
Enviar o Resultado de Volta: O resultado da função é enviado de volta ao Gemini, permitindo que ele gere uma resposta final para o usuário.

Exemplo de Código

Vamos ilustrar com um exemplo simplificado de controle de uma luz inteligente:

import { FunctionCallingConfigMode, FunctionDeclaration, GoogleGenAI, Type } from '@google/genai';
import dotenv from 'dotenv';
import fetch from 'node-fetch';

dotenv.config();

const weatherApiKey = process.env.OPENWEATHER_API_KEY || '';
const genAI = new GoogleGenAI({ vertexai: false, apiKey: process.env.GOOGLE_API_KEY || '' });

interface WeatherResponse {
    main: {
        temp: number;
    };
    weather: Array<{
        description: string;
    }>;
}

async function getWeather(city: string, country: string): Promise<string> {
    try {
        const response = await fetch(
            `https://api.openweathermap.org/data/2.5/weather?q=${city},${country}&appid=${weatherApiKey}&units=metric`
        );
        const data = (await response.json()) as WeatherResponse;
        return `The current temperature in ${city} is ${data.main.temp}°C with ${data.weather[0].description}`;
    } catch (error) {
        console.error('Error fetching weather:', error);
        return "Sorry, I couldn't fetch the weather information.";
    }
}

async function generateContentFromWeatherAPI() {
    const weatherFunctionDeclaration: FunctionDeclaration = {
        name: 'getWeather',
        description: 'Gets the current weather for a requested city',
        parameters: {
            type: Type.OBJECT,
            properties: {
                city: {
                    type: Type.STRING,
                    description: 'The city to get the weather information for',
                },
                country: {
                    type: Type.STRING,
                    description: 'The country of the city in country code',
                },
            },
            required: ['city', 'country'],
        },
    };

    const chat = await genAI.chats.create({
        model: 'gemini-2.0-flash',
        history: [],
        config: {
            tools: [{ functionDeclarations: [weatherFunctionDeclaration] }],
            toolConfig: {
                functionCallingConfig: {
                    mode: FunctionCallingConfigMode.ANY,
                    allowedFunctionNames: ['getWeather'],
                },
            },
        },
    });

    const result = await chat.sendMessage({
        message: 'What is the weather in Lagos, Portugal?',
    });

    if (result.candidates?.[0]?.content?.parts) {
        for (const part of result.candidates[0].content.parts) {
            if (part.functionCall) {
                console.log('Function called:', part.functionCall.name);
                console.log('Arguments:', part.functionCall.args);

                const args = part.functionCall.args as { city: string; country: string };
                const weatherInfo = await getWeather(args.city, args.country);
                console.log('\nWeather information:', weatherInfo);

                const followUp = await chat.sendMessage({ message: weatherInfo });
                console.log(
                    '\nAI Response:',
                    followUp.candidates?.[0]?.content?.parts?.[0]?.text || 'No response'
                );
            }
        }
    }
}

generateContentFromWeatherAPI();Code language: JavaScript (javascript)

Explicação

FunctionDeclaration: Este objeto define nossa função getWeather. Ele especifica os parâmetros (city, country) e seus tipos. A description é vital; ajuda o Gemini a entender o propósito da função.
toolConfig: Esta configuração informa ao Gemini como lidar com o “function calling”. mode: FunctionCallingConfigMode.ANY permite que o Gemini decida se deve ou não chamar a função. allowedFunctionNames restringe o Gemini a chamar apenas as funções que permitimos explicitamente.
Executando a função: Os comentários do código destacam onde você integraria com seu sistema de controle de luz real. É aqui que a ação do “mundo real” acontece.
Enviando o resultado de volta: Para conversas mais complexas, você normalmente enviaria o resultado da chamada de função de volta ao Gemini em uma chamada de API subsequente. Isso permite que o Gemini incorpore a saída da função em sua resposta ao usuário.

Melhores Práticas

Descrições de Função Claras: Escreva descrições detalhadas e inequívocas de suas funções. Isso é crucial para o Gemini entender seu propósito.
Definições de Parâmetros Precisas: Defina os tipos e descrições dos parâmetros com precisão. Isso ajuda o Gemini a gerar chamadas de função corretas.
Segurança: Seja extremamente cauteloso sobre as funções que você expõe ao LLM. Evite dar-lhe acesso a operações sensíveis, a menos que seja absolutamente necessário e com autorização estrita.
Tratamento de Erros: Implemente um tratamento de erros robusto na execução de sua função e forneça resultados informativos de volta ao Gemini.
Feedback do Usuário: Considere como fornecer feedback ao usuário sobre as chamadas de função, especialmente se envolverem ações externas.

Conclusão

O “Function calling” é um recurso revolucionário que preenche a lacuna entre os LLMs e o mundo real. O novo SDK do Gemini capacita os desenvolvedores a integrar sistemas externos de forma integrada, criando aplicações de IA poderosas e versáteis.

Um dos novos benefícios no novo SDK é a unificação entre a API do Gemini e do Vertext AI. Ao projetar cuidadosamente suas funções e seguir as melhores práticas, você pode desbloquear um novo nível de interatividade e automação com o Gemini.

Para mais conteúdo sobre o Gemini Confira:

Function Calling com Gemini

O que é Function Calling?