Agentes de IA e uso de ferramentas — Agentes RAG e IA

Ganhos:

Definir um agente como ‘modelo + ferramentas + loop’ e decidir quando ele é necessário
Escrevendo a definição da ferramenta com nome, descrição e input_schema
Monitorando o fluxo e o tratamento de erros do loop tool_use e tool_result

Até agora, o modelo sempre fez uma tarefa: receber entrada de texto, produzir respostas de texto. Mas o trabalho real muitas vezes exige mais do que texto; realizar um cálculo, consultar um banco de dados, chamar uma API, descobrir a taxa de câmbio atual. A modelo não pode fazer essas coisas sozinha – mas ela pode decidir quando elas precisam ser feitas e pedir a alguém para fazê-las. Isso é o que o uso de ferramentas proporciona ao modelo, e essa é a base dos agentes de IA. Nesta unidade, aprenderemos o que é um agente, como a ferramenta é definida e como funciona o loop tool_use.

O que é um agente? Modelo + Ferramentas + Loop

Um agente de IA consiste em três partes: o modelo (o cérebro que toma a decisão), as ferramentas (as funções que o modelo pode chamar: previsão do tempo, consulta ao banco de dados, envio de e-mail) e o loop (o loop; o modelo chama a ferramenta, obtém o resultado, decide novamente o que fazer e assim por diante).

Distinção crítica: uma chamada de padrão único não é um agente. Agente é um processo no qual o modelo avança passo a passo, em cada etapa escolhendo o próximo movimento com base no resultado da ferramenta. “Pense como um humano, use as mãos, veja o resultado, pense novamente.”

Um fato importante: o modelo em si não opera o veículo. O modelo apenas diz “Quero chamar esta ferramenta com essas entradas”. Seu aplicativo (chamado de chicote) executa a ferramenta e retorna o resultado ao modelo. Isto é vital para a segurança: o modelo não toca diretamente no seu sistema; Cada ação está sob seu controle.

Dica: não tente resolver todos os problemas com o agente. Agente; aumenta o risco de atrasos, custos e erros. Pergunte primeiro: “Isso será resolvido com uma única chamada ou um fluxo de trabalho fixo?” Se a resposta for sim, não há necessidade de agente. Agente é para tarefas abertas onde as etapas não podem ser conhecidas antecipadamente.

Definição da ferramenta: nome, descrição, input_schema

Para introduzir uma ferramenta no modelo, você dá três coisas:

nome: Identidade do veículo, por ex. obter_clima.
descrição: O que a ferramenta faz e quando chamá-la. Esta é a área mais importante que permite ao modelo escolher a ferramenta certa no momento certo. Escreva não apenas “o que faz”, mas também “ligue quando”.
input_schema (esquema de entrada): esquema JSON que define quais parâmetros a ferramenta espera, em qual tipo.

# Definição do veículo (conceitual - esquema JSON){ "name": "get_order_status", "description": "Recupera o status atual de envio de um pedido. Chama quando o usuário pergunta onde está o número do pedido ou quando ele chegará.", "input_schema": { "type": "object", "properties": { "order_no": {"type": "string", "description": "Número do pedido, por exemplo SP-1024"} }, "obrigatório": ["order_no"] }}

Regras para uma boa descrição de ferramenta: nome claro e conciso, descrição com “quando usar”, descrição de cada parâmetro, colocando os verdadeiramente obrigatórios em obrigatórios. Mantenha o número de veículos focado; Dezenas de modelos de veículos semelhantes são surpreendentes.

área

O que isso faz?

bom exemplo

mau exemplo

nome

ID do veículo

pedido_status_getir

trazer

descrição

O que faz + quando ligar

"Retorna o status da carga; liga quando o usuário perguntar onde está o pedido"

"busca dados"

esquema_de entrada

Tipo de parâmetro e requisito

{order_no: string, anotado}

sem diagrama / sem descrição

tool_use → loop de resultado_ferramenta

O ciclo funciona assim, passo a passo:

Você envia a pergunta do usuário + as descrições das ferramentas para o modelo.
O modelo responde diretamente ou gera um bloco tool_use: "chame order_durumu_getir com order_no=SP-1024."
Seu aplicativo realmente executa a ferramenta (consulta o banco de dados).
Você envia o resultado de volta ao modelo como tool_result.
Com esse resultado, o modelo produz a resposta final ou chama outra ferramenta. O ciclo continua até que o modelo diga “Terminei”.

# Mensagens de loop de agente (conceitual) = [user_question]while True: resposta = model.uret(messages, tools=tool_definitions) if response.tur == "tool_use": resultado = chicote.run(response.tool_name, response.entries) # APPLICATION executa mensagens += [response, tool_result(result)] # retorna resultado else: break # resposta final; fim do laço

Os SDKs modernos oferecem executores de ferramentas que executam esse loop para você; você acabou de escrever as funções da ferramenta. Mas é exatamente isso que está acontecendo nos bastidores.

Gerenciamento de erros

As ferramentas podem falhar: pedido não encontrado, API expira, entrada é inválida. Se você não conseguir executar a ferramenta, retorne o erro ao modelo como um tool_result descritivo ("erro: Número do pedido SP-9999 não encontrado") e o sinalizador de erro. O modelo pode ver isso e explicar gentilmente ao usuário ou tentar uma maneira diferente. Não engula o erro e retorne resultados vazios; O modelo deve saber o que deu errado.

Descrição do veículo fraco/forte

Fraco (substantivo indefinido, sem "quando"):

nome: "dados", descrição: "busca dados"# O modelo não sabe quando e como chamar; Ele não liga ou liga incorretamente.

Forte (nome da rede + quando + descrição do parâmetro):

name: "musteri_bakiyesi_getir"description: "Retorna o saldo da conta corrente de um cliente. Chama quando o usuário pede débito, crédito ou saldo. NÃO efetua pagamento."input_schema: {custeri_id: string ("Customer ID")}# O modelo chama na hora certa, com os parâmetros certos, sabendo seu limite.

Três Mini Estojos

Caso 1 — Agente desnecessário. Uma equipe construiu o negócio de “resumir texto” com um agente multiferramenta; Cada recapitulação leva 4 chamadas de modelo e 9 segundos. O trabalho era na verdade um trabalho de uma chamada. Quando retiramos o agente e reduzimos para uma única chamada, o tempo diminuiu para 1,5 segundos e o custo diminuiu para um quarto. Lição: use o agente quando for realmente necessário.

Caso 2 — Explicação fraca, decisão errada. Em um agente de suporte, uma ferramenta obscura chamada fetch foi chamada aleatoriamente pelo modelo tanto na questão de saldo quanto na questão de envio. Quando os veículos foram divididos em balance_getir e cargo_durumu_getir e as explicações "chamar quando" foram adicionadas, a seleção errada de veículos diminuiu de 18 para 1 em 50 exemplos.

Caso 3 — Erro engolido. Um agente estava retornando resultados vazios quando o pedido não foi encontrado; O modelo interpretou isso como “o pedido foi entregue” e enganou o cliente. Quando a mensagem de erro é escrita explicitamente em tool_result ("pedido não encontrado"), o modelo diz corretamente "Não consegui encontrar este número, você pode verificar?" ele começou a dizer.

Erros comuns

Entregar tudo a um agente: embora uma chamada seja suficiente, o agente acrescenta custos e atrasos.
Descrição vaga do veículo: O modelo não sabe quando ligar; escolhe errado.
Pensar que o modelo dirige o veículo: O arnês dirige o veículo; o modelo só quer.
Engolindo o erro: O modelo deve saber o que deu errado; Dê o erro como open tool_result.
Muitos veículos semelhantes: o modelo fica confuso; Mantenha o conjunto de ferramentas focado e mínimo.

Atenção: Só porque o modelo diz “ligue para aquele veículo” não significa que uma ação deva ser tomada. Em ferramentas destrutivas (delete, checkout, email) sua aplicação não deve executar cegamente a chamada — este é o núcleo do tópico de segurança na próxima unidade.

Em resumo

Agente = modelo (decisão) + ferramentas (funções) + loop (chamar ferramenta, obter resultado, decidir novamente).
Uma chamada de padrão único não é um agente; agente é um processo passo a passo.
O modelo não dirige o veículo; Seu aplicativo é executado (harness) e retorna o resultado como tool_result.
A ferramenta é identificada por nome, descrição (especificamente "chamar quando") e esquema_de_entrada.
O loop continua enquanto tool_use → execuções de chicote → tool_result → modelo continua até que o modelo diga "concluído"; os erros são explicitamente relatados ao modelo.

Tarefa de aplicativo

Projete 3 ferramentas do seu próprio negócio que podem ser entregues ao agente. (1) Escreva o nome, a descrição com "chamar quando" e o esquema_de entrada para cada um; Deixe pelo menos um ser uma ferramenta de leitura não destrutiva e outro um cálculo. (2) Escolha uma pergunta de usuário realista e escreva manualmente, passo a passo (em um loop), quais dessas ferramentas o modelo chamará com quais entradas e o que fará após a chegada do tool_result. (3) Configure um cenário em que uma das ferramentas falhe e mostre como a mensagem de erro retornará ao modelo.

lista de verificação

[ ] Posso definir o agente como “modelo + ferramentas + loop” e decidir quando é necessário.
[ ] Eu sei que o chicote dirige o veículo, o modelo só quer.
Posso escrever uma descrição sólida do veículo com [] nome, descrição ("chamar quando") e esquema_de_entrada.
Posso seguir o ciclo [] tool_use → tool_result passo a passo.
[] Eu relato erros de ferramenta ao modelo como tool_result aberto.