Eu estou de volta ao Agntbox: meu percurso com a ferramenta de IA até o momento

Olá a todos, sou a Nina, de volta ao agntbox.com!

Vocês sabem, parece que foi ontem que eu tentava explicar à minha tia Maria o que é uma “rede neural” (spoiler: não foi bem). Avançando até hoje, a IA está praticamente em todo lugar. Desde ajudar a escrever e-mails até gerar imagens para minhas campanhas ridículas de D&D, essas ferramentas tornam nossas vidas, bem, mais fáceis. Mas com tantas opções surgindo a cada dia, é fácil se perder no ruído. E, honestamente, muitas delas prometem o mundo, mas entregam… um balãozinho levemente murcho.

É por isso que hoje quero falar sobre algo com o qual tenho brincado há alguns meses, algo que realmente cumpriu suas promessas: API de Chamada de Função da OpenAI. Mais especificamente, como isso muda minha forma de pensar sobre a criação de aplicativos de IA realmente interativos, indo além da simples geração de texto para ações reais e úteis. Esqueça aqueles chatbots complicados de antigamente; estamos falando de IA que pode entender a intenção e então fazer coisas no mundo real (ou pelo menos, no mundo do seu aplicativo).

Eu me lembro de ter tentado criar um simples bot de clima há alguns anos. Isso envolvia regex sem fim, instruções condicionais e uma oração para que o usuário digitasse exatamente o que eu esperava. Foi um pesadelo. A API de Chamada de Função? É mágica em comparação. Vamos lá.

Além da Simples Conversa: Por Que a Chamada de Função é Importante

Pense nisso: a maioria dos modelos de IA é excelente em entender linguagem natural e gerar texto que parece humano. Isso é fantástico para escrever posts de blog (não este, obviamente, isso é tudo meu!), resumir documentos ou até mesmo gerar ideias. Mas e se você quiser que sua IA interaja realmente com sistemas externos? E se você quiser que ela:

• Pesquise um voo?
• Peça um café?
• Recupere dados específicos de um banco de dados?
• Envie um e-mail?

É aí que os modelos de texto para texto tradicionais alcançam um limite. Eles podem lhe dizer como fazer algo, mas não conseguem realmente fazer isso sozinhos. Essa lacuna é precisamente o que a API de Chamada de Função da OpenAI busca preencher. Ela permite que você descreva as funções disponíveis para o modelo, e então o modelo decide se e quando chamar uma dessas funções, com base na entrada do usuário.

A beleza disso é que a IA não executa a função em si. Em vez disso, ela gera um objeto JSON estruturado que indica a sua aplicação qual função chamar e com quais argumentos. Sua aplicação pega esse JSON, executa a função real e retorna o resultado para a IA. Isso cria um poderoso ciclo: Usuário -> IA (identifica a função) -> Seu App (executa a função) -> IA (processa o resultado) -> Usuário (recebe uma resposta/confirmação).

Meu Momento “Aha!”: Um Cenário de Casa Inteligente

Meu momento “aha!” com a Chamada de Função veio quando eu estava tentando tornar minha configuração de casa inteligente um pouco mais inteligente. Tenho um monte de luzes Philips Hue, um termostato inteligente e algumas tomadas inteligentes. Criei um aplicativo Flask simples que expõe esses dispositivos como pontos de extremidade de API. Antes da Chamada de Função, eu tinha um sistema instável de palavras-chave que desencadeava ações específicas. “Acenda as luzes da sala” funcionava, mas “Ei, está um pouco escuro aqui, pode deixar a sala mais clara?” só me rendeu um olhar vazio do meu app.

Com a Chamada de Função, defini funções como set_light_brightness(room: str, brightness: int) ou adjust_thermostat(temperature: int). Depois, descrevi essas funções para o modelo da OpenAI. Agora, quando digo: “Está um pouco escuro aqui, você pode deixar a sala mais clara?”, o modelo identifica corretamente que quero usar set_light_brightness para a “sala” e poderia até inferir um valor padrão de “luminosidade” ou pedir esclarecimentos. É uma mudança sutil, mas profunda na forma como a interação parece natural.

Como Funciona: Um Mergulho Rápido (Sem Profundidade, Eu Prometo)

A ideia básica é bem simples. Você fornece ao modelo da OpenAI uma lista de funções que seu aplicativo pode realizar, bem como seus parâmetros. Você descreve essas funções usando um Esquema JSON, que é uma forma padrão de descrever a estrutura dos dados JSON. Pense nisso como um projeto para suas funções.

Quando você envia uma mensagem de usuário para o modelo, também envia essa lista de funções. O modelo analisa a mensagem do usuário e decide se alguma de suas funções seria útil para atender à intenção do usuário. Se decidir chamar uma função, retorna uma mensagem contendo o nome da função a ser chamada e os argumentos a serem passados, tudo em um formato JSON estruturado.

Exemplo Prático: Uma Ferramenta de Clima Simples

Vamos revisar um exemplo super simples: uma ferramenta de clima. Imagine que você tem um ponto de extremidade de API que pode recuperar dados meteorológicos para uma cidade específica.

Primeiro, você definiria sua função. Em Python, isso poderia ser assim:

def get_current_weather(location: str, unit: str = "fahrenheit"):
 """
 Recupera a temperatura atual em um local dado.

 Args:
 location (str): A cidade e o estado, por exemplo San Francisco, CA
 unit (str, opcional): A unidade de temperatura. Pode ser 'celsius' ou 'fahrenheit'. Padrão 'fahrenheit'.

 Returns:
 dict: Um dicionário contendo informações meteorológicas.
 """
 # Em um aplicativo real, você chamaria uma API meteorológica externa aqui
 if location == "Boston, MA":
 return {"location": "Boston, MA", "temperature": "50", "unit": unit, "forecast": "cloudy"}
 elif location == "San Francisco, CA":
 return {"location": "San Francisco, CA", "temperature": "68", "unit": unit, "forecast": "sunny"}
 else:
 return {"location": location, "temperature": "N/A", "unit": unit, "forecast": "unknown"}

Em seguida, você descreve essa função para a OpenAI usando um Esquema JSON. Isso informa ao modelo o que a função faz, quais argumentos ela recebe e seus tipos.

functions = [
 {
 "name": "get_current_weather",
 "description": "Recupera a temperatura atual em um local dado",
 "parameters": {
 "type": "object",
 "properties": {
 "location": {
 "type": "string",
 "description": "A cidade e o estado, por exemplo San Francisco, CA",
 },
 "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
 },
 "required": ["location"],
 },
 }
]

Agora, quando um usuário pergunta, “Qual é o clima em Boston?”, você enviaria isso para a API da OpenAI:

import openai

# Supondo que você tenha configurado sua chave de API da OpenAI

messages = [{"role": "user", "content": "Qual é o clima em Boston?"}]

response = openai.chat.completions.create(
 model="gpt-3.5-turbo-0613", # Ou gpt-4-0613 para melhores resultados
 messages=messages,
 functions=functions,
 function_call="auto", # Isso indica ao modelo chamar uma função se achar apropriado
)

response_message = response.choices[0].message

O objeto response_message conterá um atributo function_call. Não será uma resposta textual direta. Em vez disso, parecerá algo assim:

{
 "role": "assistant",
 "function_call": {
 "name": "get_current_weather",
 "arguments": "{\n \"location\": \"Boston, MA\"\n}"
 }
}

Sua aplicação então analisa isso, chama sua função get_current_weather com location="Boston, MA", e obtém o resultado. Em seguida, você retorna esse resultado para o modelo da OpenAI:

# Supondo que 'response_message' é o mencionado acima
if response_message.function_call:
 function_name = response_message.function_call.name
 function_args = json.loads(response_message.function_call.arguments)

 # Execute a função
 function_response = get_current_weather(
 location=function_args.get("location"),
 unit=function_args.get("unit")
 )

 # Adicione a chamada de função e sua resposta ao histórico de mensagens
 messages.append(response_message) # A chamada de função do assistente
 messages.append(
 {
 "role": "function",
 "name": function_name,
 "content": json.dumps(function_response),
 }
 )

 # Obtenha uma nova resposta do modelo, agora com a saída da função
 second_response = openai.chat.completions.create(
 model="gpt-3.5-turbo-0613",
 messages=messages,
 )
 print(second_response.choices[0].message.content)

E é nesse momento que você receberá uma resposta em linguagem natural como: “O tempo atual em Boston, MA é de 50 graus Fahrenheit e nublado.”

Minha Experiência: O Bom, os Quirks e o Que Aprendi

Usar a Chamada de Função realmente mudou minha maneira de abordar a construção de recursos alimentados por IA. Parece menos como adivinhar o que o usuário quer e mais como guiar a IA para entender e agir.

O Bom:

• Redução da Engenharia de Prompt: Sério, esse é um ponto importante. Em vez de escrever prompts elaborados tentando forçar a IA a um formato de saída específico ou esperando que ela entenda o que fazer, você simplesmente lhe dá as ferramentas (suas funções) e a deixa decidir.
• Precisão Aumentada para a Intenção: O modelo é surpreendentemente bom em determinar qual função chamar, mesmo com formulações ambíguas. Isso torna a experiência do usuário muito mais fluida.
• Saídas Estruturadas: Receber um objeto JSON para as chamadas de função é um sonho para os desenvolvedores. Não há mais necessidade de tentar transformar linguagem natural em dados estruturados.
• Extensibilidade: À medida que sua aplicação cresce, você simplesmente adiciona mais definições de funções. A lógica básica para interagir com a IA permanece amplamente a mesma.

Os Quirks (e Como Eu Lidei com Isso):

• Chamadas de funções excessivas: Às vezes, o modelo pode estar um pouco apressado em chamar uma função, mesmo quando uma simples resposta textual seria suficiente. Descobri que sendo muito preciso nas minhas descrições de função e adicionando exemplos claros no primeiro prompt do modelo (se necessário), ajudava. Você também pode definir function_call="none" para impedir explicitamente as chamadas de função, ou function_call={"name": "my_function"} para forçar uma chamada de função específica.
• Incompatibilidade dos argumentos: O modelo pode às vezes tentar chamar uma função com argumentos que não correspondem realmente ao seu esquema, ou inventar argumentos. Isso geralmente acontece quando a descrição da função não está perfeitamente clara. Iterar na description da função e seus parameters é essencial.
• A dança de múltiplas rodadas: Lembre-se, você está construindo uma conversa. Depois que sua aplicação executa uma função, você deve devolver o resultado ao modelo na forma de uma mensagem de papel “função”. Esquecer isso quebra o fluxo da conversa e a IA não saberá o que aconteceu. Essa era uma erro comum para mim no início.
• Considerações de custo: Cada rodada de conversa, especialmente quando se trata de funções, consome tokens. Se você tem muitas funções ou resultados de função muito verbosos, isso pode se acumular. Fique atento ao comprimento de suas descrições de função e aos dados que você retorna de suas funções.

Uma aprendizagem específica: quando você descreve suas funções, não se limite a listar os parâmetros. Explique por que alguém usaria essa função e que tipo de entrada ela espera. Por exemplo, em vez de simplesmente location: str, diga location: A cidade e o estado, por exemplo 'San Francisco, CA' ou 'New York City, NY'. Esses pequenos detalhes fazem uma grande diferença na forma como o modelo interpreta a intenção do usuário.

Feedback para seu próximo projeto de IA

Se você está construindo algo que vai além da simples geração de texto, recomendo fortemente explorar a API de Chamada de Funções da OpenAI. Aqui está o que eu sugeriria:

1. Comece simples: Não tente integrar todos os pontos de extremidade da API ao mesmo tempo. Escolha uma ou duas ações principais que sua IA deve ser capaz de realizar e defina funções para isso.
2. Seja explícito em suas descrições de função: Pense em suas descrições de função como mini-prompts para a IA. Quanto mais clara você descrever o que a função faz, seus parâmetros e exemplos de entradas válidas, melhor o modelo funcionará.
3. Gerencie os erros com graça: Suas funções externas podem falhar. Certifique-se de que sua aplicação possa capturar esses erros e devolver uma mensagem útil de erro para a IA (e, por consequência, para o usuário). A IA pode então se desculpar ou sugerir alternativas.
4. Atenção à janela de contexto: Lembre-se de que todo o histórico da conversa, incluindo chamadas de função e seus resultados, conta para a janela de contexto do modelo. Para interações longas e complexas, você pode precisar de estratégias para gerenciar o contexto (por exemplo, resumir as rodadas anteriores).
5. Teste, teste, teste: Teste suas funções com diversos prompts de usuário, incluindo os ambíguos, para ver como o modelo os interpreta. Esse processo iterativo é crucial para aprimorar suas descrições de função.

A chamada de função é um passo significativo para tornar os assistentes de IA verdadeiramente úteis e interativos. Isso nos aproxima de um futuro onde a IA não é apenas um parceiro de conversa, mas um agente capaz que pode nos ajudar a realizar tarefas. Experimente – você pode descobrir que isso também muda sua abordagem ao desenvolvimento de IA.

Até a próxima vez, continue criando coisas incríveis!

Nina

🕒 Published: April 3, 2026