Catálogo de ferramentas para agentes de IA: guia

O agente só deveria enxergar ferramentas que pode usar

Um agente comercial recebe acesso ao CRM, ao e-mail, à agenda e a um sistema de propostas. A equipe diz que ele deve apenas preparar reuniões. Mesmo assim, uma integração genérica permite editar negócios, enviar mensagens e excluir compromissos.

A instrução limita o comportamento esperado. A capacidade técnica continua ampla.

Um catálogo de ferramentas registra as operações que agentes podem chamar, em quais processos, sob qual identidade, com que parâmetros, limites e evidências. Ele transforma integrações dispersas em capacidades governáveis.

A menor unidade útil não é "acesso ao CRM". É uma operação como "consultar oportunidade ativa por identificador" ou "criar tarefa pendente sem alterar estágio e valor". Essa precisão permite conceder somente o necessário e localizar quem depende de cada ferramenta.

Catálogo de ferramentas, inventário, skill e MCP

Quatro camadas próximas resolvem perguntas diferentes.

O inventário de agentes de IA mostra quais funções existem, quem responde por elas, quais dados usam e qual risco carregam.

Uma skill de agente descreve como executar um trabalho: entradas, fontes, sequência, critérios, limites e saída.

O MCP para empresas padroniza a conexão entre aplicações de IA, recursos e ferramentas.

O catálogo governa cada capacidade executável. Ele responde:

o que a ferramenta faz;
quem pode chamá-la;
em nome de qual processo;
que entrada aceita;
qual efeito pode produzir;
que controles aplica;
onde funciona;
quem mantém;
como será alterada ou retirada.

Uma skill pode chamar várias ferramentas. Um servidor MCP pode publicar várias capacidades. Um agente pode receber apenas um subconjunto do catálogo. As fronteiras precisam continuar legíveis mesmo quando a tecnologia muda.

Registre operações, não sistemas inteiros

Nomes genéricos escondem autoridade.

Considere estas duas descrições:

crm_tool: gerencia clientes e oportunidades;
criar_proxima_acao: cria uma tarefa pendente em oportunidade ativa, atribuída ao responsável atual, sem alterar estágio, valor ou contato.

A segunda permite revisar escopo, parâmetros e consequência. A primeira exige confiar que o agente interpretará corretamente uma superfície enorme.

Separe operações por verbo e efeito:

Consulta

Lê informação sem alterar o sistema. Exemplos: buscar negócio, consultar agenda, recuperar política vigente e localizar documento.

Preparação

Cria um artefato ainda sem consequência externa. Pode gerar minuta, briefing, classificação proposta ou payload para revisão.

Registro reversível

Cria tarefa, nota ou rascunho que pode ser removido com baixo impacto e mantém atribuição.

Alteração operacional

Muda estado, responsável, prioridade, cadastro ou outro campo usado pelo processo.

Comunicação externa

Envia mensagem, proposta, notificação ou publicação para cliente, parceiro ou público.

Transação sensível

Movimenta dinheiro, aprova condição, exclui registro, altera contrato ou produz consequência regulada.

Essa classificação ajuda a distribuir permissões, aprovação e testes. Duas ferramentas do mesmo sistema podem receber níveis de controle muito diferentes.

Campos essenciais do catálogo

Uma ficha útil precisa ser curta o suficiente para permanecer atualizada e precisa o suficiente para orientar execução.

Identidade da capacidade

Registre nome funcional, identificador técnico, descrição, versão, status e ambiente. O nome deve revelar o efeito.

Status possíveis:

proposta;
em desenvolvimento;
homologação;
produção limitada;
produção;
suspensa;
em retirada;
desativada.

Processo e finalidade

Informe qual rotina usa a ferramenta e para qual unidade de trabalho. Uma capacidade sem processo associado tende a ser reutilizada por conveniência até alcançar dados e consequências que ninguém avaliou.

Dono e mantenedor

O dono operacional valida a necessidade, os critérios e o efeito no trabalho. O mantenedor técnico responde por contrato, integração, disponibilidade, teste e correção.

Uma ferramenta compartilhada pode ter mantenedor central e vários processos consumidores. Cada consumidor ainda precisa de dono.

Entradas

Defina campos obrigatórios, tipos, limites, enumerações, formatos e validações. Marque quais valores vêm do agente e quais o sistema deriva de fontes confiáveis.

Evite deixar o modelo escolher livremente:

identificador de cliente;
conta de origem;
ambiente;
identidade executora;
limite financeiro;
destino de comunicação;
política aplicável.

Sempre que possível, o dispatcher resolve esses valores pelo contexto autenticado e por registros oficiais.

Saída e confirmação

Descreva o retorno em sucesso, rejeição, falha temporária e estado incerto. Uma resposta ok não prova que o negócio terminou.

A saída deve informar:

identificador da operação;
objeto afetado;
estado anterior e novo quando aplicável;
horário;
versão da ferramenta;
confirmação do sistema de destino;
avisos ou pendências;
código de erro tratável;
orientação segura para nova tentativa.

Efeito e reversibilidade

Registre qual consequência a chamada pode produzir, até onde se propaga e como corrigir.

Criar uma tarefa é diferente de enviar um e-mail, mesmo quando ambos começam com texto gerado. O catálogo deve dizer se a ação pode ser desfeita, se exige reconciliação e qual evento confirma a reversão.

Identidade e permissão

Informe se a ferramenta age com identidade do usuário, do agente ou do processo. Registre escopos, ambientes, dados permitidos, restrições por cliente e método de revogação.

Credenciais ficam no cofre. O catálogo guarda referência, responsável, rotação e escopo, sem copiar segredo.

O guia sobre identidade e credenciais de agentes detalha contas de serviço, atribuição, rotação e privilégio mínimo.

Aprovação e bloqueios

Liste as condições em que a ferramenta:

executa;
transforma ou reduz o pedido;
pede aprovação;
encaminha para outra pessoa;
bloqueia.

Bloqueios objetivos devem existir na camada técnica. Uma ferramenta de desconto pode recusar valor acima da alçada, mesmo que o agente tente justificar a exceção no texto.

Limites operacionais

Inclua taxa, concorrência, custo, tamanho de entrada, prazo, horário, validade e volume por cliente ou processo. Esses limites reduzem erro em lote e protegem dependências compartilhadas.

Evidência

Defina o que será registrado em cada chamada:

identidade solicitante;
agente e versão;
processo e unidade de trabalho;
parâmetros relevantes com dados sensíveis protegidos;
decisão de política;
aprovação associada;
ferramenta e versão;
duração e custo;
resultado ou erro;
confirmação externa;
identificador de trace.

Logs técnicos mostram que uma função respondeu. Evidência operacional mostra que o trabalho correto aconteceu no objeto correto.

Um modelo de ficha

| Campo | Exemplo | |---|---| | Nome | criar próxima ação comercial | | Identificador | crm.proxima_acao.create.v2 | | Processo | continuidade de oportunidades ativas | | Unidade | oportunidade com compromisso confirmado | | Efeito | cria tarefa pendente | | Exclusões | não altera estágio, valor ou contato | | Identidade | conta de serviço do processo comercial | | Aprovação | exigida para conta estratégica | | Limites | uma tarefa aberta por oportunidade e compromisso | | Confirmação | ID da tarefa no CRM | | Reversão | encerrar tarefa criada por engano com motivo | | Dono | operação comercial | | Mantenedor | tecnologia ou fornecedor responsável | | Status | produção limitada |

A ficha aponta para o schema completo, testes, política e painel. O catálogo não precisa duplicar toda a documentação técnica.

Desenhe o contrato de entrada com desconfiança saudável

Ferramentas recebem argumentos produzidos por modelos e dados vindos de fontes variadas. Validação começa antes da lógica de negócio.

Use schema fechado

Declare tipos, campos obrigatórios, faixas, formatos e enumerações. Rejeite campos desconhecidos em operações sensíveis. Saídas estruturadas reduzem ambiguidade, mas ainda precisam de validação semântica.

Resolva referências no sistema

Em vez de aceitar nome livre de cliente, exija um identificador localizado por uma etapa autorizada. Depois, confirme que o objeto pertence ao escopo da identidade solicitante.

Revalide o estado

O agente pode ter lido a oportunidade minutos antes. Antes de alterar, a ferramenta precisa confirmar que ela continua ativa, com o mesmo responsável e dentro da alçada.

Separe proposta de execução

Uma ferramenta pode preparar uma alteração e outra aplicar a mudança depois da aprovação. Essa divisão preserva o payload examinado e reduz a chance de o contexto mudar entre revisão e ação.

Torne repetição segura

Chamadas podem ser repetidas depois de timeout, retentativa ou retomada. Use identificador estável e verifique o efeito já existente. O artigo sobre idempotência em agentes de IA cobre reserva, confirmação e estado incerto.

O catálogo deve variar por agente e ambiente

Publicar todas as ferramentas para todos os agentes facilita integração e destrói o princípio de menor privilégio.

Crie conjuntos por responsabilidade. Um preparador de reunião pode consultar agenda, CRM e documentos autorizados. Ele não precisa enxergar envio de e-mail, alteração de preço ou exclusão de compromisso.

Separe também os ambientes:

desenvolvimento usa mocks e dados sintéticos;
homologação usa identidades próprias e destinos controlados;
produção limitada recebe volume e classes restritas;
produção amplia somente capacidades aprovadas.

O agente não deve escolher o ambiente por argumento textual. A configuração e a identidade determinam o destino.

Quando uma ferramenta sensível não participa da tarefa atual, remova-a do contexto. Isso reduz seleção acidental, superfície de ataque e custo de interpretação.

Permissão para chamar não significa autoridade para decidir

Uma ferramenta tecnicamente disponível ainda pode exigir política antes da execução.

Considere um agente de atendimento com capacidade de preparar reembolso. A política pode avaliar:

identidade do cliente confirmada;
pedido elegível;
valor dentro da faixa;
ausência de reembolso anterior;
motivo documentado;
aprovador exigido;
canal permitido;
prazo contratual.

O agente reúne fatos e propõe. A camada de política decide se o pedido pode seguir, precisa de revisão ou deve ser bloqueado. A ferramenta executora recebe somente solicitações já autorizadas e continua validando invariantes.

Os guardrails para agentes de IA organizam barreiras entre entrada, contexto, planejamento, chamada, confirmação e saída.

Teste a ferramenta isolada e dentro do fluxo

O teste isolado confirma contrato e controles. O teste do agente mostra se a capacidade é escolhida e usada no momento correto.

Testes do contrato

Inclua:

entrada válida;
campo obrigatório ausente;
tipo ou enumeração inválida;
identificador inexistente;
objeto fora do escopo;
estado alterado desde a leitura;
permissão insuficiente;
aprovação ausente ou vencida;
chamada repetida;
timeout antes e depois do efeito;
indisponibilidade do destino;
tentativa de ultrapassar limite.

Testes de uso pelo agente

Verifique:

escolha da ferramenta correta;
ausência de chamada quando a resposta pode vir de fonte de leitura;
argumentos apoiados em dados disponíveis;
respeito à sequência;
interpretação de erro;
escalonamento em estado incerto;
confirmação antes de declarar conclusão;
nenhuma ferramenta fora da responsabilidade.

Testes de abuso

Tente induzir o agente com documento, e-mail ou mensagem que peça outra ação, outro cliente, destino externo ou dado protegido. O dispatcher deve bloquear a consequência mesmo quando o modelo segue a instrução indevida.

O red team para agentes de IA amplia esse teste para identidade, rede, dados, filas e outras camadas do sistema.

Versione contrato e comportamento

Alterar nome de campo, enumeração, efeito, política ou formato de erro pode quebrar agentes que dependem da ferramenta.

Use versão identificável e registre:

mudança realizada;
consumidores afetados;
compatibilidade;
data de publicação;
período de transição;
testes executados;
plano de rollback;
versão anterior ainda disponível;
responsável pela migração.

Adicionar campo opcional costuma ser menos arriscado do que mudar o significado de um campo existente. Quando houver quebra, publique nova versão e migre consumidores de forma controlada.

O controle de mudanças em agentes de IA deve tratar ferramentas junto com instruções, modelos, fontes, permissões e estado.

Retire ferramentas sem deixar dependências órfãs

Capacidades antigas acumulam acesso e confundem seleção. A retirada precisa ser planejada.

Antes de desativar:

localize agentes, skills e workflows consumidores;
verifique volume e última utilização;
anuncie prazo de migração;
ofereça substituição quando necessário;
bloqueie novos consumidores;
monitore chamadas restantes;
desative gatilhos e credenciais;
preserve evidências pelo prazo aplicável;
confirme que nenhuma fila ainda chama a versão;
atualize catálogo e inventário.

Uma ferramenta sem uso pode continuar perigosa se a credencial permanece ativa. Encerramento termina com revogação confirmada.

Métricas do catálogo e das ferramentas

Acompanhe o portfólio:

ferramentas sem dono;
capacidades em produção sem testes;
operações genéricas com escopo amplo;
versões antigas ainda chamadas;
credenciais próximas da expiração;
ferramentas expostas a agentes sem uso recente;
capacidades sem plano de retirada.

Acompanhe cada operação:

chamadas por processo e agente;
sucesso confirmado no destino;
rejeições por política;
erros por classe;
estado incerto;
duplicidade evitada;
aprovações solicitadas e vencidas;
tempo e custo;
uso fora do horário ou volume esperado;
incidentes e quase incidentes;
correções humanas após execução.

Volume alto não prova valor. Ligue a chamada à unidade de trabalho concluída e ao indicador do processo.

Checklist para criar um catálogo de ferramentas

Cada item representa uma operação delimitada?
O nome revela verbo e efeito?
Processo, unidade de trabalho e dono estão registrados?
Entradas possuem schema e validação semântica?
Identidade, ambiente e escopo são definidos fora do texto do agente?
Leitura, preparação, escrita e transação estão separadas?
A ferramenta revalida o estado antes da consequência?
Aprovações e bloqueios existem na camada técnica?
Repetições evitam efeitos duplicados?
O retorno confirma o resultado no sistema de destino?
Logs ligam agente, processo, ferramenta, objeto e resultado?
O conjunto disponível varia por agente e ambiente?
Contrato e política possuem versão?
Mudanças identificam consumidores afetados?
Retirada inclui migração, revogação e confirmação?

Ferramenta governada transforma conexão em capacidade

Conectar um agente a um sistema ficou simples. Manter a conexão útil, limitada e explicável exige mais trabalho.

O catálogo cria uma fronteira entre a inteligência do agente e a autoridade da empresa. Cada capacidade ganha escopo, contrato, identidade, dono, controles, evidência e ciclo de vida. Com isso, integrações deixam de ser acessos genéricos escondidos em configurações e passam a funcionar como peças operacionais que a empresa consegue conceder, testar, revisar e retirar.