Como Usar Function Calling na API do Claude em Python: Guia Prático

Integrar modelos de linguagem a sistemas legados sempre foi um desafio de parsing de texto. Com o Function Calling na API do Claude, você permite que o modelo determine quando e como chamar funções externas no seu código Python de maneira estruturada.

Em vez de confiar em gambiarras com expressões regulares ou prompts frágeis, a Anthropic disponibiliza uma especificação nativa para definição de ferramentas. Neste guia, você verá a estrutura necessária para conectar a API do Claude às suas funções locais em Python.

O Que É Function Calling na API do Claude e Por Que Usar

O recurso de tool use (Function Calling) permite declarar funções Python no parâmetro tools do cliente da Anthropic. O modelo analisa a conversa, percebe a necessidade de uma ação externa e retorna um JSON estruturado contendo o nome da função e seus argumentos.

Isso transforma o Claude de um mero gerador de texto em um agente operacional, capaz de consultar bancos de dados SQL, consumir APIs REST de terceiros ou executar rotinas de negócios em tempo real com precisão determinística.

Os 4 Passos para Implementar Function Calling com Claude em Python

Siga esta estrutura padrão para conectar qualquer função interna ao ciclo de resposta da API do Claude.

1. Defina o schema da ferramenta em JSON Schema

Descreva a função criando um dicionário Python contendo name, description e input_schema. Forneça descrições detalhadas em cada campo para que o modelo saiba quando acionar a ferramenta.

2. Converta a chamada da API enviando a lista de ferramentas

Passe a lista de esquemas no parâmetro tools da chamada ao modelo. Defina o modelo desejado, como o Claude 3.5 Sonnet, juntamente com a mensagem do usuário.

3. Inspecione o stop_reason e extraia a tool_use

Verifique se a resposta retornou o motivo de parada correto. Se sim, itere sobre os blocos de conteúdo para localizar o bloco de uso de ferramenta e capturar os argumentos JSON.

4. Execute a função local e devolva o tool_result

Execute a função Python real com os argumentos fornecidos e envie o resultado de volta ao Claude em um novo objeto, permitindo que ele sintetize a resposta final.

Exemplo Prático: Consulta de Estoque em Tempo Real

Imagine um assistente de e-commerce que precisa verificar a disponibilidade de produtos em um banco de dados interno.

• Definição do contrato:: Você declara a ferramenta consultar_estoque indicando que o parâmetro obrigatório sku deve ser uma string de identificação.
• Interceptação da intenção:: O usuário pergunta 'Temos o item SKU-99 em estoque?'. O Claude identifica a intenção e responde com um bloco tool_use solicitando a execução da busca.
• Retorno e conclusão:: Sua aplicação executa a busca SQL local, devolve o resultado formatado e o Claude responde ao usuário final de forma natural e precisa.

Esse ciclo de ida e volta garante que a resposta final contenha dados reais e atualizados do seu sistema.

Erros Comuns ao Usar Function Calling no Claude

• Descrições vagas nos parâmetros:. Deixar a descrição do campo genérica faz o modelo alucinar argumentos incorretos ou errar o tipo do dado esperado.
• Esquecer de tratar tool_result:. Não enviar o resultado da execução de volta à API trava o histórico de conversa e impede o modelo de concluir o raciocínio.
• Ignorar validação de tipos em Python:. Confiar cegamente nos dados retornados pelo JSON sem validar os tipos pode gerar exceções de runtime na sua aplicação.

Próximos Passos para Elevar Suas Integrações

Dominar o Function Calling na API do Claude é a base para construir agentes autônomos e sistemas com interações avançadas. O próximo passo é combinar essas ferramentas com chamadas em tempo real e arquiteturas orientadas a eventos.