Function calling na prática: o segredo por trás dos agentes de IA

O que é function calling, sem o mistério

Como o fluxo funciona na prática

1. Você descreve para o modelo quais funções estão disponíveis, incluindo nome, descrição e os parâmetros que cada uma espera.

2. O usuário envia uma mensagem, por exemplo "qual o status do meu pedido 123?".

3. O modelo responde não com texto, mas com uma instrução estruturada dizendo qual função chamar e com quais argumentos, no caso, a função de consulta de pedido com o número 123.

4. Seu código executa essa função de verdade, busca a informação no seu sistema, e envia o resultado de volta para o modelo.

5. O modelo usa esse resultado para gerar a resposta final em linguagem natural para o usuário.

Definindo uma função para o modelo

# Define o "contrato" de uma função disponível para o modelo
# O modelo usa essa descrição para decidir quando chamar essa função

ferramenta_consulta_pedido = {
    "name": "consultar_status_pedido",
    "description": "Consulta o status atual de um pedido a partir do número dele",
    "parameters": {
        "type": "object",
        "properties": {
            "numero_pedido": {
                "type": "integer",
                "description": "Número do pedido a ser consultado",
            }
        },
        "required": ["numero_pedido"],
    },
}

Executando a função escolhida pelo modelo

# Recebe a decisão do modelo e executa a função correspondente de verdade
# O modelo nunca executa código, só decide qual função chamar e com quais dados

def consultar_status_pedido(numero_pedido: int) -> dict:
    """Busca o status do pedido no sistema real da aplicação."""
    # aqui entraria uma consulta real ao banco de dados
    pedidos_simulados = {123: "em transporte", 456: "entregue"}
    status = pedidos_simulados.get(numero_pedido, "pedido não encontrado")
    return {"numero_pedido": numero_pedido, "status": status}

def executar_funcao_escolhida(nome_funcao: str, argumentos: dict) -> dict:
    """Roteia a decisão do modelo para a função real correspondente."""
    funcoes_disponiveis = {
        "consultar_status_pedido": consultar_status_pedido,
    }

    if nome_funcao not in funcoes_disponiveis:
        raise ValueError(f"Função desconhecida: {nome_funcao}")

    return funcoes_disponiveis[nome_funcao](**argumentos)

# exemplo de uso, simulando a decisão que o modelo retornaria
resultado = executar_funcao_escolhida("consultar_status_pedido", {"numero_pedido": 123})
print(resultado)

Onde os primeiros agentes costumam falhar

• Descrever funções de forma ambígua, fazendo o modelo confundir qual função chamar quando existem várias parecidas.

• Confiar cegamente nos argumentos gerados pelo modelo, sem validar tipos e valores antes de executar a função, especialmente em ações irreversíveis.

• Não tratar o caso em que o modelo decide chamar uma função que não existe ou que não deveria estar disponível naquele contexto.

• Deixar de limitar quais funções cada tipo de usuário pode acionar, tratando o agente como se ele tivesse acesso irrestrito ao sistema.

Function calling é a base dos agentes de IA

Próximos passos