Adicionando ferramentas

A página anterior mostrou como encapsular uma LLM em um agente fornece uma identidade persistente, instruções e gerenciamento de sessão. Mas, mesmo com tudo isso, o agente só pode gerar conteúdo (texto, imagens etc.) – ele não pode pesquisar o preço das ações de hoje, enviar um email ou consultar seu banco de dados. Ele responde com qualquer conhecimento incorporado durante o treinamento e com o contexto que você fornece no prompt.

As ferramentas superam essa lacuna. Eles dão ao agente a capacidade de agir – para alcançar além de seus dados de treinamento e interagir com o mundo real. Adicionar ferramentas é a única etapa mais impactante que você pode tomar para tornar um agente genuinamente útil.

Quando usar

Adicione ferramentas ao seu agente quando:

• O agente precisa de acesso a dados em tempo real ou externos — preços dinâmicos, clima, registros de banco de dados, resultados da pesquisa — que não estão nos dados de treinamento do modelo.
• O agente precisa executar ações – enviar emails, criar tíquetes, chamar APIs, gravar arquivos – em vez de apenas produzir conteúdo.

Considerações

Consideração	Detalhes
Latência	Cada chamada de ferramenta adiciona uma viagem de ida e volta – o modelo gera uma solicitação de ferramenta, seu código a executa e o resultado é enviado de volta antes que o modelo possa continuar. Uma ferramenta multifuncional transforma isso em algo composto.
Sobrecarga de token	Definições de ferramenta (nomes, descrições, esquemas de parâmetro) são incluídas em cada prompt. Mais ferramentas significa menos tokens disponíveis para o histórico de conversas e a resposta do modelo.
Depurando a complexidade	Quando algo dá errado, a causa pode estar na seleção de ferramentas do modelo, nos argumentos escolhidos ou na execução da ferramenta. Você está depurando o raciocínio e o código juntos.
Confiabilidade	O modelo pode chamar ferramentas incorretamente, passar argumentos incorretos ou invocar uma ferramenta quando não deveria. Boas descrições e aprovação de ferramenta reduzem isso, mas não o eliminem.

Por que os agentes precisam de ferramentas

Conforme abordado nos conceitos básicos da LLM, uma LLM é treinada para gerar tokens, incluindo um formato estruturado especial que representa uma chamada de ferramenta. Mas o modelo em si nunca executa nada. É seu aplicativo (ou Agent Framework) que analisa a saída do modelo, executa a função real e alimenta o resultado de volta.

Isso significa que as ferramentas não alteram o que é o modelo. Elas alteram o que o agente pode fazer. Sem ferramentas, um agente é um conversacionalista. Com as ferramentas, ele se torna um operador.

Considere um agente de reserva de viagens. Sem ferramentas, ele pode discutir voos e sugerir itinerários com base no conhecimento geral. Com as ferramentas, é possível:

• Buscar uma API de voo para disponibilidade e preços em tempo real
• Reservar um voo em nome do usuário

Cada uma dessas ações requer uma ferramenta – uma parte do código que o agente pode invocar para interagir com o mundo exterior.

Como funciona o loop de chamada de ferramentas

Quando você fornece ferramentas de agente, o Agent Framework gerencia automaticamente um loop de chamada de ferramentas:

┌──────────────────────────────────────────────────────┐
│  User: "What's the weather in Seattle?"              │
└──────────────┬───────────────────────────────────────┘
               ▼
┌──────────────────────────────────────────────────────┐
│  Agent sends messages + tool definitions to LLM      │
└──────────────┬───────────────────────────────────────┘
               ▼
       ┌───────────────┐
       │ LLM responds  │
       └───┬───────┬───┘
           │       │
     Tool call?    No ──────────────────────────┐
           │                                    │
           ▼                                    ▼
┌─────────────────────────────┐   ┌─────────────────────────────┐
│  Agent Framework executes   │   │  Final response:            │
│  the tool (e.g.,            │   │  "It's cloudy in Seattle    │
│  get_weather("Seattle"))    │   │   with a high of 15°C."     │
└──────────────┬──────────────┘   └─────────────────────────────┘
               │
               ▼
┌─────────────────────────────┐
│  Agent sends tool result    │
│  back to the LLM            │
└──────────────┬──────────────┘
               │
               └──────► (back to "LLM responds")

Pontos principais:

1. Você não precisa escrever o loop. O Agent Framework lida com a detecção de chamadas de ferramenta na resposta do modelo, executando as ferramentas e alimentando os resultados de volta. Você define as ferramentas; a estrutura orquestra o restante.
2. Várias chamadas de ferramenta por turno. O modelo pode chamar várias ferramentas (potencialmente em paralelo) antes de produzir uma resposta final — ou encadear chamadas de ferramentas, onde a saída de uma informa a próxima.
3. O modelo decide quando chamar ferramentas. Com base na solicitação do usuário e nas descrições da ferramenta que você fornece, o modelo avalia se uma ferramenta é necessária. Boas descrições de ferramentas levam a uma melhor seleção de ferramentas.

Dica

Para obter um passo a passo prático sobre como adicionar sua primeira ferramenta e ver esse loop em ação, consulte a Etapa 2: Adicionar Ferramentas no tutorial Introdução.

Tipos de ferramentas

O Agent Framework dá suporte a várias categorias de ferramentas. Escolher o certo depende do que você precisa que o agente faça e onde a funcionalidade reside.

Ferramentas para funções

Ferramentas de função são funções personalizadas que você escreve e registra no agente. Eles são executados em seu processo, oferecendo controle total sobre a lógica, os limites de segurança e o tratamento de erros.

Utilize ferramentas funcionais quando:

• Você tem uma lógica de negócios personalizada que o agente precisa invocar (consultar um banco de dados, chamar uma API interna, executar um cálculo)
• Você precisa da ferramenta para executar em seu ambiente com acesso aos seus recursos
• Você deseja segurança de tipos e testabilidade em tempo de compilação

As ferramentas de função são o tipo de ferramenta mais comum e flexível. A maioria dos agentes começa aqui.

Referência das Ferramentas Funcionais

Ferramentas MCP (Protocolo de Contexto de Modelo)

O MCP é um padrão aberto que define como os aplicativos fornecem ferramentas para LLMs. Em vez de escrever a lógica da ferramenta por conta própria, você se conecta a um servidor MCP que expõe um conjunto de ferramentas em um protocolo padrão, semelhante à forma como uma API REST expõe pontos de extremidade.

O Agent Framework dá suporte a dois tipos:

Sabor	O que é	Quando usar isso
Ferramentas MCP hospedadas	Servidores MCP hospedados e gerenciados por Microsoft Foundry ou outros provedores	Você deseja acesso turnkey a recursos comuns (por exemplo, pesquisa de arquivo, execução de código) sem gerenciar a infraestrutura
Ferramentas MCP locais	Servidores MCP que você gerencia ou aos quais se conecta de qualquer provedor	Você tem um servidor MCP personalizado ou de terceiros ou precisa de ferramentas que são executadas em seu próprio ambiente

Use ferramentas MCP quando:

• Um servidor MCP predefinido já fornece a funcionalidade necessária
• Você deseja reutilizar ferramentas em vários agentes ou aplicativos por meio de um servidor compartilhado
• Você está se integrando a um serviço de terceiros que expõe um endpoint MCP

Referência de Ferramentas MCP HospedadasReferência de Ferramentas MCP Locais

Ferramentas hospedadas pelo provedor

Alguns provedores oferecem ferramentas internas que são executadas na infraestrutura do provedor — nenhum código local é necessário. Elas incluem:

Tool	O que faz
Interpretador de códigos	Executa código em um ambiente em área restrita na infraestrutura do provedor
Pesquisa de Arquivos	Pesquisas através de arquivos que você faz upload no provedor
Pesquisa na Web	Pesquisa informações em tempo real na Web

Use ferramentas hospedadas pelo provedor quando:

• Você precisa de recursos como execução de código ou pesquisa na Web sem criar ou hospedar a ferramenta por conta própria
• O provedor já oferece uma versão gerenciada que atende aos seus requisitos

Observação

A disponibilidade da ferramenta hospedada pelo provedor varia de acordo com o provedor. Confira a visão geral de ferramentas para a matriz de suporte completa do provedor.

Observação

Alguns provedores de LLM podem executar ferramentas hospedadas em sua infraestrutura durante a inferência, como a API de Respostas da OpenAI. Pense nesses serviços de inferência como um serviço sem agente que combina inferência com execução de ferramentas. Ele não altera como o modelo subjacente funciona, mas significa que a execução da ferramenta pode acontecer como parte da geração de resposta do serviço. Esses serviços não podem executar ferramentas locais, que devem ser executadas em sua própria infraestrutura.

Escolhendo o tipo de ferramenta correto

Pergunta	Recomendação
Tenho lógica de negócios personalizada?	Ferramentas de função – escrever e registrar suas próprias funções
Há um servidor MCP que já faz o que eu preciso?	MCP tools — conecte-se a ela em vez de criar do zero, como o servidor MCP GitHub
Preciso de execução de código, pesquisa de arquivo ou pesquisa na Web?	Ferramentas hospedadas pelo provedor – verifique se o provedor dá suporte a elas
Preciso de ferramentas de várias categorias?	Misture-os – os agentes podem usar ferramentas de função, ferramentas MCP e ferramentas hospedadas pelo provedor simultaneamente

As descrições da ferramenta são importantes

O modelo seleciona ferramentas com base em seus nomes e descrições. Uma descrição vaga leva a uma seleção de ferramentas ruim– o modelo pode chamar a ferramenta errada, ignorar uma ferramenta que deve usar ou passar argumentos incorretos.

Escreva descrições da ferramenta da mesma maneira que você escreveria um documento de API: diga o que a ferramenta faz, o que cada parâmetro significa e o que ela retorna. Quanto mais clara a descrição, melhor o julgamento do modelo.

Dica

Definições de ferramenta (nomes, descrições, esquemas de parâmetro) são incluídas no prompt e consomem tokens na janela de contexto. Se você cadastrar muitas ferramentas, a sobrecarga poderá ser significativa. Registre apenas as ferramentas de que o agente realmente precisa.

Aprovação da ferramenta: human-in-the-loop

Algumas ações são confidenciais: transferir dinheiro, excluir registros, enviar emails. Talvez você não queira que o agente execute essas ferramentas de forma autônoma. A aprovação da ferramenta permite que você exija confirmação humana antes que uma ferramenta seja executada.

Quando uma ferramenta é marcada como exigindo aprovação, o agente pausa antes da execução e retorna uma resposta indicando que a aprovação é necessária. Seu aplicativo é responsável por apresentar isso ao usuário e passar sua decisão de volta.

Esse padrão geralmente é chamado de humano-no-loop e é essencial para a criação de agentes confiáveis que lidam com ações consequentes.

Referência de aprovação da ferramenta

Armadilhas comuns

Perigo oculto	Orientações
Muitas ferramentas	Cada definição de ferramenta consome tokens. Registre apenas as ferramentas relevantes para a finalidade do agente.
Descrições vagas	"Faz coisas com dados" não ajudará o modelo. Seja específico: "Consulta o banco de dados de inventário quanto à disponibilidade do produto por SKU".
Nenhum tratamento de erro	As ferramentas podem falhar (erros de rede, entrada inválida). Retorne mensagens de erro claras para que o modelo possa raciocinar sobre o que deu errado e tentar novamente ou informar o usuário.
Ferramentas excessivamente permissivas	Uma ferramenta que pode "executar qualquer consulta SQL" é um risco à segurança. Definir ferramentas para operações específicas e bem definidas.
Aprovação pendente em ações sensíveis	Se uma ferramenta puder fazer alterações irreversíveis, adicione a aprovação da ferramenta para manter um humano no loop.

Menção especial: Ferramenta de Interpretador de Código

Conforme discutido nos conceitos básicos do LLM, as LLMs podem cometer erros em cálculos precisos e lógica formal. Isso ocorre porque as LLMs geram as respostas token por token com base na correspondência de padrões – elas não realmente calculam. Um LLM solicitado a multiplicar dois números grandes não está realizando aritmética; ele está antecipando como seria a resposta com base nos dados de treinamento. Isso funciona surpreendentemente com frequência, mas falha imprevisivelmente em casos extremos.

O Interpretador de Código resolve isso permitindo que o agente escreva e execute código em um ambiente em área restrita. Em vez de adivinhar a resposta, o modelo grava um script Python que o calcula exatamente, o executa e usa o resultado verificado em sua resposta.

Observação

O modelo pode escrever um script ligeiramente diferente sempre que for solicitado a resolver o mesmo problema, mas os resultados devem ser consistentes principalmente .

Aviso

O Interpretador de Código não substitui o raciocínio cuidadoso por parte do humano. Sempre verifique o trabalho do agente e verifique os resultados de forma independente quando necessário.

Dê ao seu agente o Interpretador de Código quando ele precisar:

• Execute cálculos precisos – modelagem financeira, análise estatística, conversões de unidade – em que um "melhor palpite" aproximado não é aceitável.
• Transformar ou analisar dados — analisar CSVs, agregar linhas, gerar gráficos ou remodelar dados estruturados.
• Processar arquivos — ler documentos carregados, extrair conteúdo, converter formatos ou gerar novos arquivos.
• Valide seu próprio raciocínio – escreva o código de teste para verificar uma declaração lógica antes de apresentá-la ao usuário.

Dica

O Interpretador de Código pode ser uma ferramenta hospedada pelo provedor – o código é executado na infraestrutura do provedor em uma área restrita, não em seu ambiente. Isso torna seguro usar sem se preocupar com a execução arbitrária de código em seus servidores. Consulte a referência do Interpretador de Código para obter detalhes de instalação.

Próximas Etapas 

Depois que o agente tiver ferramentas, a próxima etapa é aprender sobre habilidades : pacotes portáteis de instruções, material de referência e scripts que fornecem aos agentes conhecimentos de domínio que eles podem carregar sob demanda.

Adicionando habilidades

Vá mais fundo:

• Visão geral das ferramentas – todos os tipos de ferramentas e matriz de suporte do provedor
• Ferramentas de Função – referência detalhada da ferramenta de função
• Hosted MCP Tools — servidores MCP do Microsoft Foundry ou de outros provedores
• Ferramentas MCP locais – servidores MCP personalizados
• Aprovação da ferramenta – human-in-the-loop para ferramentas
• Etapa 2: Adicionar Ferramentas — tutorial prático