Neste artigo, vamos criar um assistente de vendas inteligente que pode registrar pedidos através de conversas naturais. Você aprenderá a usar chamadas de funções (function calling) com a API Gemini e a criar um chat interativo que mantém histórico de conversas.

Clique aqui para abrir o código deste artigo no Google Colab

O que é Function Calling?

Function calling é um recurso que permite ao modelo de IA executar funções específicas do seu código quando necessário. Por exemplo, quando um cliente diz “quero comprar 5 notebooks”, o modelo identifica que precisa chamar uma função de registro de pedidos e extrai automaticamente os parâmetros (produto: “notebooks”, quantidade: 5).

Existem duas formas de implementar function calling: uma mais trabalhosa (manual) e outra mais prática (automática). Vamos começar pela forma manual para entender como funciona por baixo dos panos, e depois mostraremos a forma simplificada que você realmente vai usar no dia a dia.

Configuração do Ambiente

Antes de executar o código dos exemplos, você precisa configurar algumas coisas:

Instalar as bibliotecas necessárias:

pip install google-generativeai python-dotenv

Obter uma API Key do Google:

  1. Acesse: https://makersuite.google.com/app/apikey
  2. Clique em “Create API Key”
  3. Copie a chave gerada

Criar um arquivo .env:

Crie um arquivo chamado .env na raiz do seu projeto:

GOOGLE_API_KEY=sua_chave_aqui

Adicionar ao .gitignore Importante: Nunca faça commit da sua API Key! Adicione ao .gitignore:

.env

1. Forma Manual (Entendendo o funcionamento)

Na forma manual, você precisa criar manualmente uma estrutura JSON (Notação de Objetos JavaScript) que descreve suas funções para a API. Embora seja mais trabalhosa, é importante entender essa estrutura para compreender o que acontece nos bastidores.

Veja o exemplo abaixo:

import json

# Definir a função manualmente em formato JSON
tools = [{
    "function_declarations": [{
        "name": "registrar_pedido",
        "description": "Registra um novo pedido de venda",
        "parameters": {
            "type": "object",
            "properties": {
                "cliente": {"type": "string", "description": "Nome do cliente"},
                "produto": {"type": "string", "description": "Produto solicitado"},
                "quantidade": {"type": "integer", "description": "Quantidade"}
            },
            "required": ["cliente", "produto", "quantidade"]
        }
    }]
}]

O que esse JSON representa?

Esse JSON contém todas as informações que a API precisa saber sobre sua função:

  • name: O nome da função que será chamada (registrar_pedido)
  • description: Uma descrição do que a função faz, usada pelo modelo para decidir quando chamá-la
  • parameters: Os parâmetros que a função aceita:
    • cliente (string): Nome do cliente
    • produto (string): Nome do produto
    • quantidade (integer/número inteiro): Quantidade desejada
  • required: Lista dos parâmetros obrigatórios

Além disso, você precisaria escrever código adicional para:

  1. Detectar quando o modelo quer chamar a função
  2. Extrair os parâmetros da resposta
  3. Executar a função manualmente
  4. Enviar o resultado de volta para o modelo

Como você pode imaginar, isso dá bastante trabalho! Felizmente, existe uma forma muito mais simples.

2. Forma Prática (Recomendada)

A boa notícia é que a biblioteca google-generativeai consegue extrair automaticamente todas essas informações de uma função Python comum! Você só precisa seguir algumas boas práticas:

Requisitos para a Forma Prática

Para que a biblioteca consiga criar o JSON automaticamente, sua função precisa ter:

  1. Type hints (anotações de tipo) nos parâmetros e no retorno
  2. Docstring bem escrita explicando o que a função faz
  3. Descrição dos parâmetros no formato correto

Veja o mesmo exemplo, agora na forma prática:

def registrar_pedido(cliente: str, produto: str, quantidade: int) -> str:
    """Registra um novo pedido de venda
    
    Args:
        cliente: Nome do cliente que está fazendo o pedido
        produto: Nome do produto solicitado
        quantidade: Quantidade de unidades do produto
    
    Returns:
        Mensagem de confirmação do pedido
    """
    # Código da função aqui
    pedido = {
        "cliente": cliente,
        "produto": produto,
        "quantidade": quantidade
    }
    # salvar o pedido
    return f"Pedido registrado com sucesso!"

Por que isso funciona?

A biblioteca lê sua função e extrai:

  • Nome da função: regitrar_pedido (diretamente do nome da função Python)
  • Descrição: “Registra um novo pedido de venda” (primeira linha da docstring)
  • Parâmetros e tipos:
    • cliente: str -> string
    • produto: str -> string
    • quantidade: int -> integer
  • Tipo de retorno: -> str (string)
  • Descrição dos parâmetros: Extraída da seção Args: da docstring

Com isso, a biblioteca cria automaticamente aquele JSON complicado que vimos antes.

Observação importante sobre Python: Embora Python não obrigue você a usar type hints (: str, : int, -> str), eles são essenciais aqui para que a API Gemini entenda que tipos de dados esperar. Sem eles, a biblioteca não consegue gerar o JSON corretamente.

Implementação Completa do Assistente

Agora que entendemos as duas formas, vamos criar nosso assistente completo usando a forma prática:

from dotenv import load_dotenv

load_dotenv()  # Carrega variáveis do .env

import google.generativeai as genai
import os

# Configurar a API
genai.configure(api_key=os.environ.get("GOOGLE_API_KEY"))

# Lista para armazenar pedidos
pedidos = []

# Definir a função de registro de pedidos
def registrar_pedido(cliente: str, produto: str, quantidade: int) -> str:
    """Registra um novo pedido de venda
    
    Args:
        cliente: Nome do cliente que está fazendo o pedido
        produto: Nome do produto solicitado
        quantidade: Quantidade de unidades do produto
    
    Returns:
        Mensagem de confirmação do pedido
    """
    pedido = {
        "cliente": cliente,
        "produto": produto,
        "quantidade": quantidade
    }
    pedidos.append(pedido)
    
    return f"Pedido registrado com sucesso! Cliente: {cliente}, Produto: {produto}, Quantidade: {quantidade}"

# Criar o modelo com a função disponível
model = genai.GenerativeModel(
    model_name="gemini-2.5-flash",
    tools=[registrar_pedido]  # Forma prática: apenas passar a função!
)

# Iniciar o chat
chat = model.start_chat(enable_automatic_function_calling=True)

print("Assistente de Vendas Iniciado!")
print("Digite 'sair' para encerrar\n")

# Loop principal do chat
while True:
    # Ler mensagem do usuário
    mensagem_usuario = input("Você: ")
    
    # Verificar se quer sair
    if mensagem_usuario.lower() == "sair":
        print("\nResumo dos pedidos:")
        for i, pedido in enumerate(pedidos, 1):
            print(f"{i}. {pedido['cliente']} - {pedido['quantidade']}x {pedido['produto']}")
        break
    
    # Enviar mensagem e receber resposta
    response = chat.send_message(mensagem_usuario)
    print(f"Assistente: {response.text}\n")

Como funciona na Prática?

1. Chat com Histórico Automático

Quando você cria um chat com model.start_chat(), a API Gemini mantém automaticamente todo o histórico da conversa:

chat = model.start_chat(enable_automatic_function_calling=True)

Cada mensagem enviada com chat.send_message() é adicionada ao histórico, permitindo que o modelo:

  • Lembre informações mencionadas anteriormente
  • Mantenha contexto entre múltiplas mensagens
  • Entenda referências como “também quero isso” ou “adicione mais 3”

2. Execução Automática de Funções

Com enable_automatic_function_calling=True, o processo acontece automaticamente:

  1. Você envia: “Quero comprar 5 notebooks”
  2. O modelo analisa: Identifica que precisa registrar um pedido
  3. Extrai parâmetros: produto=”notebooks”, quantidade=5
  4. Chama a função: registrar_pedido
  5. Recebe o retorno: “Pedido registrado com sucesso”
  6. Responde ao usuário: Incorpora o resultado na resposta natural

3. Armazenamento em Lista Python

Os pedidos são salvos em uma lista Python simples na memória:

pedidos = []  # Lista global

def registrar_pedido(cliente: str, produto: str, quantidade: int) -> str:
    pedido = {
        "cliente": cliente,
        "produto": produto,
        "quantidade": quantidade
    }
    pedidos.append(pedido)  # Adicionar à lista
    return f"Pedido registrado..."

Nota: Em uma aplicação real, você provavelmente salvaria em um banco de dados ao invés de uma lista na memória.

Exemplo de Uso Real

Veja como fica uma conversa real com o assistente:

Assistente de Vendas Iniciado!
Digite 'sair' para encerrar

Você: Olá, me chamo Sarah! Gostaria de fazer o pedido de 5 notebooks
Assistente: Olá Sarah! Para registrar seu pedido, preciso saber o seu nome completo e o nome do produto. Você poderia me confirmar essas informações, por gentileza?

Você: Sarah Pereira de Araújo Lima e Lenovo ThinkPad E14
Assistente: Seu pedido de 5 unidades do Lenovo ThinkPad E14 foi registrado com sucesso em nome de Sarah Pereira de Araújo Lima.

Você: Gostaria de 5 mouses também
Assistente: Seu pedido de 5 mouses foi registrado com sucesso em nome de Sarah Pereira de Araújo Lima.

Você: sair

Resumo dos pedidos:
1. Sarah Pereira de Araújo Lima - 5.0x Lenovo ThinkPad E14
2. Sarah Pereira de Araújo Lima - 5.0x mouse

Conclusão

Com a API Gemini, criar assistentes inteligentes ficou muito mais simples. A forma prática de function calling reduz drasticamente o código necessário, enquanto o sistema de chat automático cuida do histórico de conversas. Agora você tem uma base sólida para criar seus próprios agentes de IA personalizados!

Recursos Adicionais