…
Módulo 1 · Parte C de 3

Ferramentas em Escala

No Módulo 1b, você conectou uma única ferramenta ao ciclo do agente: o modelo solicitou uma função nomeada, seu harness de execução a executou e o resultado voltou para a chamada seguinte do modelo. Esse percurso de ida e volta não muda aqui. O que muda é a superfície de ferramentas: o modelo deve escolher entre mais descrições, e cada ferramenta pode ocultar uma capacidade maior.

A página segue esse contrato desde funções locais até um backend de pesquisa e um subagente. Um subagente como ferramenta coloca um agente especializado atrás de um único esquema para que o workflow externo possa encaminhar o trabalho sem expor cada capacidade interna. O Model Context Protocol (MCP) oferece ao cliente uma forma padrão de descobrir e chamar ferramentas servidas por outro processo. Use-o em um limite de capacidades, depois de validar o servidor, a identidade e o escopo. Os dois padrões mantêm pequena a lista de ferramentas do loop principal e motivam os workflows delimitados do Módulo 2.

O contrato de chamada de ferramenta permanece fixo

A figura traça o ciclo a partir de 1b. Seções posteriores mudam de onde vem o esquema e o que o executor faz, enquanto o modelo ainda solicita uma ferramenta nomeada e lê seu resultado.

O modelo solicita uma ferramenta. O harness de execução a executa e retorna o resultado para a próxima decisão do modelo.
Valide a solicitação da ferramenta antes de executá-la. O esquema de entrada descreve os nomes, tipos e campos obrigatórios dos argumentos oferecidos ao modelo. Ele não executa a ferramenta nem garante que os argumentos propostos pelo modelo sejam seguros. Confira o nome recebido, analise os argumentos e valide os valores antes de encaminhar a chamada. Os exemplos abaixo mostram as chamadas solicitadas e param diante de uma entrada inválida.

Como o modelo escolhe entre várias ferramentas

Quando há várias ferramentas disponíveis, o modelo usa os nomes, descrições, esquemas de argumentos, a conversa e qualquer restrição tool_choice para propor uma chamada. A description de cada definição explica quando a ferramenta é útil. Examine o nó Especificação da ferramenta abaixo para ver a definição completa ou consulte o guia de chamadas de função para conhecer o formato da solicitação.

A célula abaixo fornece ao modelo duas ferramentas e uma pergunta que exige escolha, e a visualização mostra por qual caminho o modelo foi e por quê.

Editar qualquer descrição altera o roteamento do modelo, pois o campo de descrição é uma das superfícies de engenharia de prompt com maior impacto em um agente que usa ferramentas.

Conectando glossary_search a uma ferramenta real

A célula conecta glossary_search a um catálogo de termos da NVIDIA na página. A busca classificada é executada no navegador sem uma chave e retorna definições curtas com links de fonte. A web_search compartilhada do curso aplica a mesma classificação ao catálogo completo. Abra o explorador de glossário para inspecionar cada termo, ler a fonte de webSearch e instantAnswer ao vivo ou executar a consulta você mesmo.

A próxima seção troca o executor pela recuperação de artigos completos, mantendo o mesmo contrato de ferramenta. Assim você observa o contrato permanecer estável enquanto o backend muda.

O nome de uma ferramenta deve descrever uma capacidade. Uma ferramenta chamada nvidia_glossary_api é frágil: alterar o backend força você a atualizar cada prompt que referencia o nome. Uma ferramenta chamada glossary_search descreve o que o chamador precisa. Pesquisa classificada, busca exata, ou um índice mais rico pode estar por trás desse contrato sem alterar o prompt do agente.
Trocar o executor sem alterar a ferramenta?

Substituindo o backend enquanto o contrato da ferramenta é mantido

O mesmo ciclo é executado aqui como um script mountRunCell plano, com uma alteração: o executor. A busca anterior retornou um breve resumo para cada um dos vários resultados. Este backend retorna o artigo completo para a melhor correspondência, recuperado da página de glossário em cache do termo. O esquema e o ciclo não mudam; apenas a fonte por trás de glossary_search se tornou mais rica.

O modelo só vê o contrato. Ele solicita glossary_search com uma consulta natural e lê o que é retornado, sem saber qual backend respondeu. Você pode começar com um índice de resumos e mais tarde substituir por artigos completos ou uma busca ao vivo sem tocar no ciclo. A precisão pode mudar quando um backend resolve uma correspondência de maneira diferente, mas o contrato é mantido.
Ocultar um agente especializado atrás de uma ferramenta?

Ocultando um agente inteiro atrás de uma única ferramenta

Uma ferramenta não precisa ser uma pequena função. Um sub-agente inteiro pode estar por trás de uma única chamada de ferramenta. O modelo chamador ainda vê um contrato. O agente por trás pode consultar um banco de dados, executar código ou buscar um repositório sem expor essas ferramentas internas ao ciclo principal.

A célula abaixo expõe um subagente que lê uma pequena tabela de clientes por meio de uma ferramenta em linguagem natural. As linhas são omitidas do contexto inicial do agente principal, mas a resposta do subagente pode incluir dados dessas linhas. Isso separa os contextos; não impõe controle de acesso aos dados.

O modelo principal recebe a resposta do subagente, de modo que os erros ou omissões dessa resposta passam a compor sua evidência. Examine ambas as respostas antes de decidir se a tabela sustenta o resultado.
Revisar o fluxo de descoberta e invocação do MCP?

Recuperando ferramentas de um servidor separado com MCP

O Model Context Protocol (MCP) fornece uma forma padrão para servir ferramentas. O agente recupera a lista de ferramentas que um servidor oferece com uma chamada tools/list, então invoca qualquer uma delas com tools/call. Essas ferramentas vivem em um processo separado que o agente conecta e consulta quando é iniciado. Como o protocolo é o mesmo em todos os lugares, o agente pode se conectar a servidores adicionais sem aprender uma nova interface para cada um. Use MCP quando a descoberta de ferramentas e o transporte precisam de um protocolo compartilhado. Use uma função local, uma habilidade de repositório ou uma chamada de API direta quando o harness de execução já sabe onde a capacidade vive e como invocá-la.

A descoberta é uma fronteira de confiança. Trate uma resposta tools/list como entrada não confiável. Antes de se conectar ao servidor:
  • verifique sua identidade,
  • mostre as capacidades solicitadas ao usuário,
  • conceda o menor escopo útil,
  • e vincule cada credencial à audiência desse servidor.
Para conexão remota e descoberta OAuth, rejeite destinos privados e link-local e valide todos os redirecionamentos. A orientação de segurança do MCP atribui consentimento, manipulação de token e controles de falsificação de solicitação de servidor (SSRF) ao cliente.

A célula abaixo simula um pequeno servidor MCP em JavaScript puro com o mesmo formato JSON-RPC definido pelo MCP (sem transporte). O agente obtém a lista de ferramentas, passa os esquemas ao modelo e encaminha tool_calls de volta pelo manipulador tools/call do servidor. O ciclo continua solicitando uma ferramenta, executando-a e acrescentando seu resultado. A descoberta de ferramentas e o encaminhamento das chamadas agora passam pela interface do servidor.

O Módulo 2 mantém esse contrato de ferramenta e altera a estrutura externa. Um workflow pode encaminhar chamadas através de um pipeline fixo, distribuir trabalho em ramificações ou delegar uma tarefa focada a outro ciclo sem expor todas as ferramentas internas ao chamador.

Antes de continuar

Use as chamadas e os resultados exibidos como evidência. Para as perguntas sobre delegação e MCP, abra primeiro as seções opcionais Agentes como ferramentas e MCP; você pode voltar a essas extensões depois do ciclo básico.

  1. O que acontece quando o modelo chama uma ferramenta com argumentos que não passam pela validação? O ciclo atual falha; como você trataria o erro de modo controlado sem fazer o modelo acreditar que a chamada foi bem-sucedida?
  2. O subagente usado como ferramenta é opaco para o agente principal. Além da resposta, quais informações ele deveria retornar para que o agente principal decida se confia nele no próximo turno?
  3. O parâmetro tool_choice pode ser definido como "required" ou como um nome de ferramenta específico. Quando forçar uma chamada de ferramenta seria a escolha certa, e qual risco isso cria?
  4. Antes de adicionar um servidor MCP remoto a este agente, quais identidade, escopo de capacidade, audiência do token e destinos de rede você verificaria? Qual deles se torna um caminho SSRF quando aceito sem validação?
Revisar as fontes sobre uso de ferramentas e MCP?

Referências

Lista abrangente em Ir Além · Referências.

Tente · um agente com duas ferramentas reais

Este artefato executa um agente LangChain createReactAgent conectado às duas funções cujos contratos você acabou de ler: calculate para aritmética e glossary_search contra o glossário NVIDIA na página que roda no navegador sem uma chave. Peça um número que ele não possa calcular na cabeça ou um termo para definir, e observe o chip de ferramenta acender antes da resposta ser transmitida.

← Módulo 1b: O Ciclo do Agente