A evolução de AI Agents está deslocando um dos problemas mais importantes de AI Engineering para uma camada frequentemente tratada como simples detalhe de integração: o Tool Layer. Em sistemas agentic, ferramentas não são APIs consumidas exclusivamente por software determinístico. Elas são interfaces interpretadas, selecionadas e parametrizadas por modelos probabilísticos que podem compreender parcialmente a intenção, escolher uma capacidade inadequada, produzir argumentos semanticamente incorretos ou interpretar equivocadamente o resultado obtido.
Essa diferença muda profundamente o problema de engenharia. Uma API tradicional precisa ser correta para chamadas válidas. Uma tool destinada a LLMs precisa também ser compreensível, discriminável, verificável e resistente a chamadas imperfeitas. JSON Schema, function calling e structured outputs ajudam a restringir a sintaxe, mas não eliminam ambiguidades semânticas. Mesmo quando o modelo produz argumentos estruturalmente válidos, ele ainda pode executar a operação correta sobre a entidade errada, no momento errado ou com consequências não pretendidas. Structured tool calling reduz uma classe de falhas; não transforma reasoning probabilístico em execução semanticamente correta.
Tool Engineering surge, portanto, como disciplina de arquitetura. Ela envolve contract design, failure semantics, idempotência, observabilidade, evaluation, segurança, custo, capability discovery e governança. Para Staff e Principal AI Engineers, a questão deixa de ser “como fazer um agente chamar uma função?” e passa a ser “como construir uma plataforma de capacidades na qual agentes probabilísticos possam agir com segurança, eficiência e confiabilidade operacional?”. É nessa fronteira entre intenção probabilística e execução determinística que grande parte da próxima geração de sistemas de AI Engineering será projetada.
Fale comigo no LinkedIn: https://www.linkedin.com/in/celso-sousa/
1. Tool Engineering como disciplina: projetando interfaces para consumidores probabilísticos
Tool Engineering precisa ser tratada como uma disciplina própria porque o consumidor de uma ferramenta agentic possui características diferentes das de um cliente de API convencional. Em software tradicional, o caller foi implementado por desenvolvedores, validado por testes e geralmente executa caminhos previamente conhecidos. Em AI Agents, o caller é um modelo que decide dinamicamente qual ferramenta utilizar, quais argumentos construir, quando interromper uma sequência e como interpretar o estado retornado.
Isso cria uma nova superfície arquitetural. O design da ferramenta passa a influenciar diretamente o reasoning behavior do sistema. Nome, descrição, quantidade de parâmetros, cardinalidade dos enums, semântica dos campos, estrutura da resposta e existência de ferramentas semanticamente próximas alteram a probabilidade de seleção correta. A API deixa de ser apenas um integration contract e passa a funcionar parcialmente como uma representação do espaço de ações disponíveis ao modelo.
Por isso, Tool Engineering está intimamente ligada a Context Engineering, Agent Architecture e Evaluation Engineering. A qualidade de um agente não depende somente do modelo ou do system prompt. Ela depende de quanto o ambiente de execução torna ações corretas fáceis de identificar e ações perigosas difíceis de executar.
Um princípio útil para sistemas de produção é separar três propriedades. O reasoning pode permanecer probabilístico. O contrato precisa ser estruturalmente restrito. A execução deve ser deterministicamente verificável. Quanto maior o impacto de uma operação, menor deve ser a quantidade de semântica implícita deixada para o modelo. Essa separação transforma tools de simples wrappers sobre APIs em componentes arquiteturais capazes de controlar a liberdade operacional de sistemas autônomos.
1.1. O contrato agente–ferramenta: quando a interface é interpretada, não apenas executada
Uma interface para agentes possui dois contratos simultâneos. Existe o contrato executável, compreendido pelo runtime, e existe o contrato cognitivo, interpretado pelo modelo. O primeiro descreve tipos, campos obrigatórios, enums e restrições estruturais. O segundo comunica intenção, limites, pré-condições, consequências e diferenças entre capacidades semanticamente próximas. Confundir esses contratos é uma das causas mais comuns de fragilidade em sistemas agentic.
Considere duas ferramentas: get_customer e search_customers. Para um desenvolvedor, a diferença parece evidente. Para um modelo, entretanto, a escolha depende do contexto linguístico, das descrições disponíveis e das entidades presentes na conversation state. Se get_customer aceitar identificadores vagos ou search_customers retornar resultados excessivamente semelhantes, o espaço de decisão torna-se ambíguo. O problema não está necessariamente no modelo; pode estar na topologia semântica da interface.
Schemas rígidos ajudam a reduzir erros sintáticos. Documentações atuais de function calling, por exemplo, permitem restringir chamadas por meio de JSON Schema e modos estruturados, garantindo aderência maior ao formato declarado. Isso aumenta type safety, mas não prova que o modelo selecionou semanticamente a operação correta.
Em Tool Engineering, o contrato precisa responder não apenas “quais argumentos são válidos?”, mas também “quando essa operação deve ser utilizada?”, “quando não deve?”, “qual estado ela modifica?” e “como verificar seu efeito?”. Esse design exige pensar em affordances para modelos. Uma boa tool API reduz interpretação desnecessária. Ela transforma intenção ambígua em decisões explícitas e reduz o branching factor do agente antes que qualquer código de negócio seja executado.
1.2. Tool schemas como mecanismos de controle comportamental e redução do espaço de erro
JSON Schema costuma ser tratado como mecanismo de serialization. Em sistemas agentic, ele deve ser entendido como mecanismo de controle comportamental. Cada parâmetro livre aumenta o espaço de estados que o modelo pode produzir. Strings genéricas, objetos arbitrários e campos opcionais em excesso oferecem flexibilidade para desenvolvedores humanos, mas transferem complexidade cognitiva para o agente. O resultado é uma interface sintaticamente elegante e semanticamente instável.
O objetivo não é tornar todos os schemas pequenos. É minimizar graus de liberdade que não agregam capacidade real. Se uma operação aceita apenas três estratégias de processamento, um enum é superior a uma string livre. Se um identificador possui semântica própria, ele não deveria ser representado apenas como “string”. Se campos possuem dependências, elas precisam ser validadas antes da execução. Quando o provider oferece structured tool calling ou strict schemas, essas restrições devem fazer parte do contrato, não depender exclusivamente de prompting.
Existe, entretanto, um trade-off importante. Schemas excessivamente complexos também podem piorar tool selection e argument generation. O modelo precisa compreender a interface inteira dentro do contexto disponível. Ferramentas com dezenas de parâmetros opcionais frequentemente representam múltiplos comandos escondidos sob um único endpoint.
A estratégia Staff-level é tratar schema design como state-space engineering. Cada campo deve justificar a complexidade que adiciona. Operações irreversíveis devem possuir contratos mais restritivos que consultas read-only. Dados críticos devem usar identifiers canônicos, não nomes inferidos. Defaults silenciosos devem ser evitados quando modificam comportamento relevante. O schema ideal não apenas valida a saída do LLM. Ele estrutura o espaço de ação para que decisões corretas sejam significativamente mais prováveis que decisões perigosas.
1.3. Granularidade de capacidades: atomicidade, composição e autonomia do agente
Granularidade é uma das decisões mais difíceis em Tool Engineering. Ferramentas extremamente pequenas aumentam composabilidade, mas obrigam o agente a executar longas trajectories. Ferramentas muito amplas reduzem o número de chamadas, porém escondem decisões importantes dentro de operações monolíticas. O problema, portanto, não pode ser resolvido pela regra simplista de que tools devem sempre ser pequenas.
Imagine um fluxo de cancelamento de pedido. Uma arquitetura pode expor get_order, verify_cancellation_policy, calculate_refund, cancel_order e create_refund. Outra pode oferecer cancel_order_with_refund. A primeira maximiza observabilidade e controle do reasoning, mas aumenta latência, tokens, oportunidades de erro e necessidade de state management. A segunda reduz o trajectory length, porém concentra políticas, efeitos colaterais e compensações em uma única ação.
O critério correto é a localização da decisão. Decisões determinísticas, baseadas em regras estáveis, devem preferencialmente ficar dentro da ferramenta ou de serviços downstream. Decisões que dependem de linguagem natural, objetivos do usuário ou interpretação contextual podem permanecer no reasoning loop. Forçar o LLM a reproduzir regras de negócio já codificáveis aumenta variância sem gerar valor.
Isso conduz a um princípio importante de AI Engineering: tool granularity deve minimizar probabilistic decision surface, e não simplesmente minimizar linhas de código. Uma operação composta pode ser arquiteturalmente superior quando preserva atomicidade e encapsula invariantes. Já uma operação ampla demais torna impossível compreender por que determinado efeito ocorreu. Staff Engineers precisam encontrar a fronteira na qual o agente decide o “quê”, enquanto infraestrutura determinística controla o “como”, especialmente em processos financeiros, administrativos ou operacionalmente sensíveis.
1.4. Determinismo na execução, incerteza na decisão: redesenhando a fronteira entre agent e tool
AI Agents são valiosos justamente porque conseguem trabalhar com objetivos incompletos, linguagem natural e ambientes parcialmente observáveis. Tentar remover toda incerteza do reasoning loop eliminaria boa parte dessa capacidade. O erro arquitetural ocorre quando a incerteza necessária para interpretar intenção invade componentes que poderiam operar de forma determinística.
A tool boundary deve funcionar como uma transformação. Antes dela existe intenção probabilística: “encontre o cliente correto”, “identifique a melhor política”, “prepare o reembolso”. Depois dela precisam existir contratos explícitos, identifiers resolvidos, invariantes verificáveis e efeitos controlados. O Tool Layer é, portanto, uma espécie de determinization boundary dentro da arquitetura agentic.
Isso não significa que tools sejam simples funções puras. Elas podem executar retrieval, chamar serviços distribuídos, iniciar jobs assíncronos ou consultar sistemas externos. A diferença é que suas failure semantics precisam ser definidas de forma compreensível para o runtime. Success, retryable failure, validation failure, conflict e authorization failure não deveriam ser reduzidos a uma única mensagem textual.
A fronteira também define responsabilidades. O agente pode decidir que precisa alterar uma reserva; a tool deve validar se aquela reserva existe, pertence ao escopo autorizado e continua modificável. O agente pode escolher uma operação; a infrastructure layer precisa garantir concurrency control, authorization e auditability.
Essa arquitetura reduz o acoplamento entre inteligência probabilística e integridade transacional. O LLM continua responsável pela interpretação onde ele oferece vantagem. Sistemas determinísticos permanecem responsáveis pelas invariantes que não podem depender de probabilidade. Essa separação é central para transformar demos impressionantes em AI Agents confiáveis, auditáveis e operáveis em produção.
2. Tool Design Systems: construindo uma linguagem operacional consistente para agentes
Quando um sistema possui cinco ferramentas, inconsistências de naming ou contratos ainda podem ser corrigidas manualmente. Quando uma organização possui centenas de capabilities distribuídas entre equipes, MCP servers, internal APIs e aplicações, Tool Engineering torna-se um problema de design system. Sem padrões, cada equipe cria sua própria linguagem operacional, e o agente precisa reaprender convenções a cada integração.
Um Tool Design System define como capacidades são nomeadas, descritas, versionadas, autenticadas, observadas e avaliadas. Mais importante, define como o espaço de ações é apresentado ao consumidor probabilístico. Isso inclui conventions para verbs, resource identifiers, paginação, errors, provenance, dry-run, approvals e side-effect classification. O objetivo não é estética arquitetural; é diminuir entropia semântica.
Esse problema torna-se mais relevante com protocolos de interoperabilidade. O Model Context Protocol, por exemplo, padroniza a exposição de tools, resources e prompts, permitindo que aplicações conectem capacidades por uma interface comum. Padronização de transporte, entretanto, não elimina a necessidade de padronização semântica. Dois MCP servers podem ser perfeitamente compatíveis com o protocolo e ainda oferecer ferramentas cognitivamente inconsistentes.
Para Staff e Principal Engineers, o design system precisa ser tratado como parte da platform architecture. Tools devem possuir ownership, lifecycle, compatibility policy e quality gates. A organização precisa evitar que cada novo agente crie wrappers diferentes sobre a mesma capability. O objetivo final é construir uma linguagem operacional relativamente estável sobre sistemas corporativos heterogêneos, permitindo que modelos diferentes consumam capacidades de maneira previsível sem conhecer toda a complexidade da infraestrutura subjacente.
2.1. Taxonomia, namespaces e semantic affordances para descoberta e seleção de ferramentas
Tool selection começa antes do inference. Ela começa na maneira como o catálogo de capabilities foi organizado. Se nomes são vagos, descrições se sobrepõem ou diferentes equipes utilizam verbos distintos para a mesma intenção, o modelo enfrenta um classification problem artificialmente difícil. Taxonomia é, portanto, parte do comportamento do agente.
Namespaces devem refletir bounded contexts ou domínios operacionais, não organogramas internos. customer.lookup, billing.get_invoice e order.cancel comunicam relações mais úteis ao reasoning do que nomes baseados em squads ou microsserviços. Porém, namespaces não devem crescer indefinidamente dentro do prompt. Em sistemas grandes, eles funcionam principalmente como metadata para registry, discovery e filtering.
Semantic affordance significa tornar a finalidade da ferramenta inferível pela representação disponível ao modelo. Nome, descrição, parâmetros e exemplos precisam produzir uma fronteira relativamente clara com ferramentas vizinhas. get_invoice e search_invoices não deveriam aceitar exatamente os mesmos argumentos nem retornar estruturas indistinguíveis. A diferença conceitual precisa existir no contrato.
À medida que o catálogo cresce, enviar todos os schemas a cada inference torna-se economicamente e cognitivamente insustentável. Arquiteturas modernas já suportam mecanismos de descoberta ou carregamento tardio de tools, permitindo selecionar capabilities relevantes antes de inseri-las no contexto. A própria documentação atual da OpenAI descreve tool search como mecanismo para deferir ferramentas raramente utilizadas em catálogos grandes.
A consequência arquitetural é importante: capability discovery torna-se um retrieval problem. Precision importa mais que recall indiscriminado. Recuperar vinte ferramentas semanticamente semelhantes pode ser pior do que recuperar cinco cuidadosamente discriminadas. Tool Registry, metadata, embeddings, regras determinísticas e contextual filtering passam a compor uma nova camada de routing dentro de AI Engineering.
2.2. Contratos de entrada: schemas estritos, tipos semânticos, invariantes e prevenção de estados inválidos
Um contrato de entrada robusto deve impedir que estados semanticamente inválidos alcancem sistemas downstream. Type validation é apenas o primeiro nível. Saber que customer_id é string não prova que o identificador existe, pertence ao tenant correto ou pode ser utilizado naquela operação. Tool Engineering precisa trabalhar com semantic validation, não apenas structural validation.
Uma técnica importante é representar conceitos de domínio diretamente no contrato. Currency, AccountId, DateRange, Region e OperationMode possuem semânticas diferentes apesar de frequentemente serem serializados como strings. Quanto mais relevante a operação, menos dependência deve existir de convenções implícitas. Enums, formatos, ranges, mutually exclusive fields e required identifiers reduzem ambiguity budget.
Também é importante diferenciar invalid input de unresolved intent. Se o usuário diz “cancele meu último pedido”, o agente talvez ainda precise resolver qual pedido é o alvo. Permitir que cancel_order aceite “last order” como identifier mistura entity resolution com mutation. Uma arquitetura mais segura exige primeiro resolver uma entidade canônica e apenas depois executar a ação.
Schemas estritos podem reduzir substancialmente erros de forma. Em function calling moderno, mecanismos de structured outputs conseguem restringir argumentos ao JSON Schema declarado, eliminando várias categorias de parsing failure. Entretanto, aderência estrutural não valida business invariants, que continuam responsabilidade da aplicação.
O princípio fundamental é make invalid states unrepresentable sempre que economicamente possível. Cada ambiguidade removida do schema reduz trabalho posterior de guardrails, retries e evaluation. Isso também melhora portabilidade entre modelos, porque a segurança deixa de depender tanto da capacidade específica de um LLM interpretar instruções textuais complexas.
2.3. Contratos de saída: signal density, provenance, evidence e resultados machine-actionable
Grande parte das discussões sobre tool calling concentra-se na entrada. Entretanto, o output contract frequentemente determina se o agente conseguirá concluir a tarefa corretamente. Uma tool pode executar perfeitamente e ainda prejudicar o sistema se devolver texto verboso, dados irrelevantes ou resultados sem provenance.
Outputs de tools devem ser projetados para consumo por máquinas probabilísticas. Isso significa maximizar signal density. Se uma consulta retorna cem campos e apenas quatro são relevantes para decisões subsequentes, toda chamada consome contexto desnecessário e aumenta a superfície para interpretação incorreta. O ideal não é retornar “tudo porque talvez seja útil”, mas fornecer informações suficientes para a próxima decisão, com mecanismos explícitos para aprofundamento.
Structured outputs também deveriam separar conteúdo destinado ao modelo de metadata utilizada pelo runtime. Status codes semânticos, identifiers, pagination cursors, confidence metadata e provenance podem ser processados deterministicamente, enquanto o LLM recebe apenas o conteúdo necessário para reasoning. Em protocolos modernos, essa distinção já aparece em mecanismos que permitem retornar conteúdo estruturado além de conteúdo textual. O SDK atual do MCP, por exemplo, diferencia content consumível e structuredContent quando a ferramenta declara output schema.
Provenance torna-se particularmente importante em retrieval tools. O agente precisa saber não apenas uma resposta, mas sua origem, freshness e escopo. Sem essa informação, avaliações posteriores não conseguem distinguir hallucination do modelo de dados incorretos retornados pela ferramenta.
Um bom output contract, portanto, não é apenas serialização. Ele funciona como context compression controlada. Reduz tokens, preserva evidence, facilita evaluation e permite que decisões futuras sejam reconstruídas durante tracing e incident analysis.
2.4. Tool APIs como produtos versionados: compatibilidade, evolução de contratos e depreciação segura
Tools em produção não permanecem estáticas. Campos mudam, políticas evoluem, backends são substituídos e novas capacidades surgem. Em clientes determinísticos, breaking changes já são difíceis. Em consumidores probabilísticos, o problema é maior porque comportamento pode mudar mesmo quando o contrato permanece tecnicamente compatível.
Adicionar um novo enum, por exemplo, pode alterar a distribuição de escolhas do modelo. Modificar a descrição de uma tool pode afetar selection rate. Criar uma capability semanticamente semelhante pode reduzir accuracy de uma ferramenta existente. Tool versioning precisa, portanto, considerar behavioral compatibility, não somente API compatibility.
Isso exige release engineering específico. Mudanças relevantes deveriam passar por offline evals, shadow traffic ou canary exposure antes de alcançar toda a população de agentes. Golden trajectories ajudam a verificar se tasks críticas continuam sendo resolvidas. Contract tests validam schema; agent evals validam interação.
Versionamento explícito também é necessário quando o significado da operação muda. Porém, adicionar versões ao nome de todas as tools pode aumentar cognitive noise. Em muitos casos, o registry deve gerenciar versões enquanto o agente enxerga uma capability semanticamente estável. O runtime resolve qual implementação utilizar conforme tenant, deployment ring ou compatibility policy.
Depreciação exige telemetria. Antes de remover uma ferramenta, a organização precisa saber quais agents ainda a utilizam, em quais trajectories e com qual taxa de sucesso. Essa informação conecta platform governance a observability.
Em uma organização madura, uma tool passa a ser tratada como produto interno. Ela possui owner, SLO, documentação, eval suite, changelog e política de lifecycle. Essa disciplina evita que a camada agentic se transforme gradualmente em um conjunto de integrações frágeis e impossíveis de evoluir.
3. Failure Engineering: projetando tools para chamadas erradas, ambíguas e repetidas
Sistemas agentic falham de maneiras diferentes de aplicações tradicionais porque uma mesma tarefa pode produzir trajectories distintas entre execuções. O agente pode repetir chamadas, escolher uma sequência alternativa, reinterpretar uma resposta ou decidir tentar novamente após uma falha. Failure Engineering precisa assumir essa variabilidade como característica estrutural, não como exceção.
A primeira consequência é abandonar a equivalência simplista entre “tool retornou sucesso” e “task foi concluída”. Uma operação pode retornar HTTP 200 e ter produzido o efeito incorreto. Da mesma maneira, uma chamada pode falhar tecnicamente enquanto o side effect foi efetivamente persistido. Em sistemas distribuídos, exatamente esse tipo de ambiguidade gera duplicação, inconsistência e decisões erradas.
O Tool Layer precisa expressar failure semantics que o runtime possa compreender. Validation failures não deveriam ser tratadas como transient failures. Rate limits não possuem a mesma política de retry de permission errors. Conflicts podem exigir re-read de estado. Timeouts podem significar resultado desconhecido, não simplesmente falha.
Protocolos de tools modernos já diferenciam erros de execução de falhas de protocolo. No MCP, por exemplo, uma chamada pode retornar um resultado marcado como erro, enquanto determinadas falhas de protocolo são representadas separadamente. Essa distinção ilustra por que failure semantics precisam fazer parte do contrato da ferramenta.
Para AI Engineering, confiabilidade emerge da composição entre model behavior e runtime guarantees. Retries, deduplication, compensations, idempotency keys, state verification e approvals precisam ser projetados junto com o agente. A pergunta correta não é “a tool funciona?”, mas “o sistema permanece correto quando a tool é chamada duas vezes, na ordem errada ou sob informação parcialmente desatualizada?”.
3.1. Idempotência, deduplicação e replay safety em agentes com retries não determinísticos
Retries são inevitáveis em sistemas distribuídos. Em AI Agents, eles são ainda mais perigosos porque podem ocorrer em diferentes camadas. O HTTP client pode repetir uma requisição. O runtime agentic pode reconsiderar uma ação. Um workflow retomado após crash pode executar novamente um nó. O próprio modelo pode decidir repetir uma ferramenta porque não compreendeu a resposta anterior.
Por isso, mutations deveriam ser idempotentes sempre que possível. A estratégia mais comum é associar uma idempotency key à intenção lógica da operação. Duas chamadas equivalentes com a mesma chave devem produzir um único efeito observável. Esse identificador precisa sobreviver a retries do runtime e, quando necessário, a retomadas de execução.
A dificuldade está em definir equivalência. Se o agente envia novamente create_refund com valores ligeiramente diferentes, trata-se do mesmo comando ou de uma nova intenção? Idempotency não pode ser apenas hash dos argumentos. Em operações críticas, a chave deveria estar associada a uma business operation explicitamente identificada pelo workflow.
Deduplication também precisa de janela temporal e storage apropriado. Manter todas as keys indefinidamente é caro. Expirá-las cedo demais pode permitir duplicações tardias. O desenho depende do risco econômico do side effect.
Replay safety vai além de idempotência. Uma trajectory reproduzida para debugging não deveria acidentalmente executar mutations reais. Ferramentas precisam suportar execution modes, sandboxes ou ambientes controlados.
No nível Staff, retries nunca devem ser tratados como detalhe de biblioteca. Eles pertencem ao correctness model da arquitetura. Em agentic systems, assume-se que qualquer etapa pode ser repetida. Se repetir uma chamada pode causar dano operacional, o sistema ainda não está preparado para autonomia real.
3.2. Partial failures, timeouts e semantic errors: por que exceptions tradicionais não são suficientes
Uma exception informa que algo deu errado. Ela raramente informa ao agente o que deve acontecer em seguida. Para consumidores probabilísticos, failure responses precisam ser desenhadas como parte do action space. O runtime deve conseguir distinguir entre tentar novamente, reformular argumentos, selecionar outra ferramenta, solicitar informação ao usuário ou interromper a operação.
Timeout é um exemplo clássico. Quando create_payment excede o deadline, existem pelo menos dois estados possíveis: o pagamento não ocorreu ou ocorreu, mas a resposta foi perdida. Repetir cegamente a chamada pode duplicar uma transação. A resposta correta talvez seja executar get_payment_by_operation_id antes de qualquer retry.
Semantic errors são ainda mais importantes. Um argumento pode ser perfeitamente válido no schema e mesmo assim violar uma regra de negócio: invoice já paga, pedido não cancelável ou recurso atualizado por outra transação. Esses estados deveriam possuir error taxonomy consistente, com machine-readable codes e metadata suficientes para recovery.
Partial failures surgem quando uma operação composta conclui apenas parte do trabalho. Uma tool que atualiza CRM, billing e notification pode falhar depois de duas etapas. Retornar simplesmente success=false esconde informação crítica. O contrato precisa indicar quais efeitos já aconteceram e se existe compensação segura.
Isso sugere uma arquitetura em que errors possuem estrutura explícita: category, retryability, operation_id, current_state e recovery hints. O agente pode usar parte dessas informações, enquanto o runtime aplica políticas determinísticas.
A regra é simples: exceptions são adequadas para programadores; agentes precisam de failure semantics. Quanto mais autônomo o sistema, mais importante transformar falhas em estados operacionalmente interpretáveis, observáveis e recuperáveis.
3.3. Side effects, compensating actions e transactional boundaries em workflows agentic
Ferramentas read-only e ferramentas com side effects não deveriam receber o mesmo tratamento arquitetural. Uma consulta incorreta geralmente custa latência e tokens. Uma mutation incorreta pode gerar transferência financeira, exclusão de dados, comunicação externa ou alteração de estado irreversível. Tool Engineering precisa tornar essa diferença visível tanto ao runtime quanto ao agente.
Uma estratégia é classificar capabilities por effect level. Read operations podem ser executadas automaticamente. Reversible writes exigem verificações adicionais. Irreversible ou high-impact operations podem exigir approval, policy evaluation ou two-phase execution. Essa taxonomia deve existir como metadata de plataforma, não apenas na descrição textual da tool.
Transactional boundaries também precisam ser cuidadosamente escolhidas. Distribuir uma operação lógica por várias chamadas oferece flexibilidade, mas expõe estados intermediários. Quando possível, invariantes críticas devem ser preservadas dentro de um boundary determinístico. Quando transações distribuídas não são viáveis, sagas e compensating actions tornam-se relevantes.
Compensação, entretanto, não é rollback. Enviar um e-mail não pode ser desfeito; pode apenas ser seguido por uma correção. Um pagamento estornado não retorna o mundo exatamente ao estado anterior. Tools devem representar essas diferenças explicitamente para evitar a falsa percepção de atomicidade.
Human-in-the-loop também deve ser colocado em boundaries de decisão, não aleatoriamente no fluxo. Aprovar cada chamada destrói a vantagem da automação. Não aprovar nenhuma ação amplia blast radius. O desenho correto considera valor, reversibilidade e confiança na intenção.
Em arquitetura agentic madura, side effects são first-class citizens. O objetivo não é impedir agentes de agir, mas construir boundaries capazes de limitar consequências quando reasoning probabilístico produz uma decisão incorreta.
3.4. Postcondition verification: nunca confiar apenas no sucesso declarado pela ferramenta
Uma das técnicas mais poderosas para aumentar confiabilidade é verificar estado depois de operações críticas. Em software tradicional, frequentemente confiamos no retorno da função que executou a mutation. Em sistemas distribuídos e agentic, postcondition verification fornece uma camada adicional de evidência de que o objetivo realmente foi alcançado.
Se uma tool afirma que o pedido foi cancelado, o workflow pode consultar o estado do pedido e validar status=CANCELLED. Se uma transferência foi criada, uma segunda operação pode verificar transaction_id, valor e destinatário. Essa abordagem aumenta latência, porém reduz false success em etapas de alto impacto.
É importante diferenciar verification pelo LLM de verification determinística. Pedir ao mesmo modelo que revise se sua própria ação “parece correta” possui valor limitado quando existe uma invariável verificável por código. Sempre que uma postcondition pode ser expressa deterministicamente, ela deveria ser testada fora do reasoning probabilístico.
Também é útil separar execution result de business outcome. Uma API pode confirmar que aceitou um job, enquanto a tarefa real será concluída minutos depois. Nesse caso, success significa accepted, não completed. O contrato precisa representar estados assíncronos e fornecer mecanismos de polling, webhook ou event-driven continuation.
Postcondition checks têm custo. Aplicá-los a toda leitura simples seria desperdício. Eles devem ser proporcionais ao risk profile da operação.
Essa estratégia altera a filosofia de Tool Engineering. Em vez de perguntar se a chamada foi bem-sucedida, pergunta-se se o sistema alcançou o estado desejado. Essa diferença aproxima agent architecture de princípios de distributed systems e permite construir workflows onde autonomia não depende de confiança cega na última resposta recebida.
4. Arquitetura do Tool Layer: de dezenas a milhares de capacidades disponíveis
A arquitetura que funciona com dez tools dificilmente funciona com mil. O problema deixa de ser function calling e passa a envolver capability discovery, registry, policy enforcement, context management e routing. Simplesmente inserir todos os schemas no prompt aumenta custo, latência e confusão semântica, além de reduzir a capacidade de evoluir o ecossistema independentemente dos agentes.
Uma arquitetura escalável normalmente separa três elementos. O capability registry conhece as ferramentas existentes e sua metadata. O discovery layer determina quais capacidades são relevantes para determinada tarefa. O execution layer executa uma ferramenta escolhida sob políticas de autenticação, observabilidade e governança. O LLM não precisa conhecer toda a topologia da organização.
Esse desacoplamento permite tratar tools como infraestrutura compartilhada. MCP ajuda a padronizar a conexão entre aplicações de IA e sistemas que expõem tools, resources e outras capabilities. Contudo, o protocolo não substitui decisões de platform architecture: ownership, trust, routing, caching, authorization e semantic quality continuam sendo responsabilidade da organização.
Também surge uma questão fundamental: quanto controle deve permanecer no model loop? Nem todo workflow precisa executar uma chamada de LLM entre duas operações determinísticas. Programmatic orchestration pode reduzir tokens e latência, enquanto agentic reasoning é utilizado apenas nos pontos em que interpretação realmente agrega valor.
A arquitetura do Tool Layer, portanto, deve ser desenhada como control plane de capacidades. O objetivo é oferecer ao agente apenas o conjunto necessário de ações, no momento adequado, com context suficiente para decidir e boundaries suficientes para impedir consequências indevidas. Escala não significa mostrar mais ferramentas ao modelo; significa esconder complexidade sem perder capacidade.
4.1. Tool Registry, capability discovery e carregamento dinâmico sem explodir o contexto
Um Tool Registry é mais que um catálogo de endpoints. Ele precisa armazenar metadata necessária para discovery, policy enforcement e lifecycle management. Isso pode incluir domínio, descrição semântica, input e output schemas, owner, versão, side-effect level, required scopes, custo esperado, latência histórica, SLO e tags de compliance.
Capability discovery utiliza essa metadata para construir um subconjunto de tools relevante para cada tarefa. A seleção pode combinar regras determinísticas, retrieval semântico, task classification e policy filtering. Um agente financeiro, por exemplo, não deveria sequer receber ferramentas de administração de infraestrutura quando não existe relação com o objetivo atual.
Essa abordagem reduz context pressure. Schemas podem representar uma parcela relevante do prompt em plataformas grandes. Além do custo direto de tokens, existe interference: quanto maior o número de ações similares, maior a dificuldade de discriminação. Sistemas modernos já começam a incorporar mecanismos de tool search e carregamento tardio justamente para resolver esse problema.
Entretanto, retrieval de tools cria seu próprio evaluation problem. Se a ferramenta correta não for recuperada, o modelo nunca terá oportunidade de utilizá-la. Por isso, discovery quality precisa ser medida separadamente de selection quality. Recall@K pode ser útil no registry layer; precision torna-se importante para evitar catálogos excessivamente amplos.
Caching também entra nessa arquitetura. Capabilities relevantes para uma sessão podem permanecer carregadas enquanto contexto e permissions não mudarem. Mudanças do registry exigem invalidation.
Em escala, Tool Registry torna-se equivalente a um service catalog orientado a agentes. Ele permite governança central sem eliminar autonomia das equipes e transforma capability discovery em componente explícito da plataforma de AI Engineering.
4.2. Direct Tool Calling vs. Programmatic Tool Calling: onde deve viver o controle do workflow
Existe uma tendência de colocar toda decisão de execução dentro do LLM loop porque isso torna demos extremamente flexíveis. Em produção, essa estratégia pode ser economicamente ruim e operacionalmente frágil. Se duas ferramentas sempre precisam ser executadas em sequência sob regras determinísticas, não há razão para solicitar ao modelo que redescubra essa sequência a cada tarefa.
Direct Tool Calling é apropriado quando a escolha da ação depende de linguagem, contexto ou objetivos abertos. Programmatic Tool Calling é superior quando o workflow já conhece dependências, invariantes e branching rules. A arquitetura mais robusta normalmente é híbrida.
Considere um agente que analisa fraude. O modelo pode decidir quais fontes investigar. Porém, depois que uma fonte específica é escolhida, autenticação, paginação, parallel fetches e normalização podem ocorrer deterministicamente. Retornar cada operação intermediária ao reasoning loop aumenta round trips sem melhorar inteligência.
Essa distinção também influencia debugging. Fluxos explicitamente codificados possuem behavior mais previsível e podem ser testados por métodos tradicionais. Decisões realmente semânticas permanecem avaliadas por agent evals. Misturar tudo dentro de um loop agentic dificulta identificar se um erro veio de reasoning ou orchestration.
Plataformas atuais já oferecem diferentes níveis de abstração, desde APIs mais diretas até runtimes que gerenciam loops, tools e estado. A escolha arquitetural não deveria ser orientada por conveniência do framework, mas pela quantidade de controle necessária.
A regra prática é manter decisões determinísticas fora do LLM sempre que isso não reduz capacidade. Cada inference removida de uma trajectory diminui custo, latência e variância. Autonomia útil não significa delegar ao modelo decisões que software convencional resolve melhor.
4.3. MCP, gateways e adapters: desacoplando agentes da topologia real dos sistemas corporativos
Empresas raramente possuem sistemas desenhados para agentes. Elas possuem REST APIs, gRPC services, bancos legados, ERPs, filas, SaaS e aplicações internas construídas ao longo de décadas. Expor diretamente essa heterogeneidade aos LLMs cria forte acoplamento entre agent architecture e infraestrutura corporativa.
Gateways e adapters devem criar uma capability layer estável acima desses sistemas. O agente não precisa saber se customer.lookup utiliza PostgreSQL, Salesforce ou três microsserviços. Ele precisa de um contrato consistente que represente a capacidade de negócio. Essa abstração permite substituir sistemas downstream sem alterar o espaço cognitivo do agente.
MCP fornece uma camada útil de interoperabilidade ao padronizar como aplicações descobrem e chamam tools e acessam resources. A versão atual do SDK oficial enfatiza exatamente essa separação entre aplicações de IA e sistemas onde ferramentas e dados residem.
Porém, MCP não deveria ser confundido com arquitetura completa. É possível construir um MCP server ruim, com tools semanticamente ambíguas, permissões excessivas e outputs inutilizáveis. Protocol compliance não é equivalente a Tool Engineering maturity.
Um enterprise tool gateway pode adicionar capabilities adicionais: authentication federation, rate limits, policy enforcement, schema validation, tracing, quotas, caching e tenant isolation. Adapters traduzem contratos canônicos para APIs internas.
O ganho estratégico é desacoplamento. Modelos podem mudar. Agent frameworks podem mudar. Serviços backend também podem mudar. Se a capability boundary permanece estável, esses movimentos não exigem reescrever toda a aplicação. Para Principal Engineers, essa separação é central: protocols resolvem interoperabilidade; gateways controlam execução; design systems controlam semântica; evals validam comportamento.
4.4. Context plane vs. execution plane: mantendo dados intermediários fora do reasoning loop
Um erro comum em agent architecture é devolver ao LLM todo dado produzido por todas as tools. Isso transforma o context window em barramento de integração. Grandes payloads são serializados para tokens, processados pelo modelo e frequentemente devolvidos para outra ferramenta, mesmo quando nenhum reasoning sobre esses dados era necessário.
Separar context plane de execution plane reduz esse desperdício. O execution plane pode movimentar datasets, arquivos, artifacts e handles entre ferramentas deterministicamente. O context plane recebe apenas summaries, references e evidence necessários para decisões do agente.
Imagine uma ferramenta que consulta dez mil transações. Enviar todas ao modelo é caro e cognitivamente desnecessário. A tool pode armazenar o resultado em um artifact store, retornar um handle e fornecer estatísticas agregadas. Se o agente precisar examinar registros específicos, outra capability realiza slicing ou filtering server-side.
Essa arquitetura também melhora segurança. Dados sensíveis podem permanecer fora do prompt quando não são necessários ao reasoning. Policies podem controlar quais projections são disponibilizadas ao modelo.
O mesmo princípio vale para multimodal e code execution. O modelo frequentemente precisa saber que um artifact existe e quais propriedades possui, não receber sua representação completa a cada turno.
Context Engineering, portanto, não é apenas selecionar mensagens do histórico. É controlar a fronteira entre informação operacional e informação cognitiva. O Tool Layer desempenha papel central nessa decisão.
Para Staff Engineers, uma boa métrica é context amplification: quantos tokens são introduzidos por uma chamada em relação à informação realmente necessária para a próxima decisão? Reduzir essa razão diminui custo, melhora latency budget e pode aumentar reliability ao limitar distrações. O context window deve ser tratado como recurso computacional escasso, não como armazenamento de workflow.
5. Evaluation Engineering: medindo a qualidade real de um ecossistema de tools
Tool Engineering sem evaluation é otimização baseada em intuição. Um schema aparentemente melhor pode reduzir tool selection accuracy. Uma descrição mais detalhada pode aumentar tokens sem melhorar task success. Um novo router pode selecionar ferramentas corretas individualmente e ainda produzir trajectories piores. Por isso, evaluation precisa acontecer em múltiplos níveis.
O primeiro nível mede componentes: discovery, tool selection e argument generation. O segundo observa cada chamada: execution correctness e output interpretation. O terceiro avalia a trajectory completa. O último mede business outcome. Esses níveis não são substitutos. Eles formam uma cadeia causal.
Uma taxa de 98% de argument validity pode parecer excelente. Porém, se uma tarefa média exige dez chamadas independentes, pequenas probabilidades de erro podem se acumular. Além disso, argumentos estruturalmente válidos podem estar semanticamente incorretos. Task completion rate, portanto, continua sendo fundamental.
Trace-based evaluation tornou-se especialmente importante para agentes porque permite inspecionar model calls, tool calls, guardrails e handoffs dentro de uma execução. Plataformas atuais de agent evaluation já utilizam traces e graders justamente para analisar comportamento em nível de workflow.
Uma organização madura mantém eval datasets representando tarefas reais, edge cases e incidentes históricos. Mudanças em prompts, tools, schemas, models ou routing precisam passar por regression evaluation. Production telemetry posteriormente retroalimenta esse conjunto.
Evaluation Engineering transforma Tool Engineering em disciplina mensurável. A pergunta deixa de ser “essa ferramenta parece clara?” e passa a ser “qual mudança observamos em selection accuracy, trajectory length, recovery rate, cost per successful task e downstream correctness após alterar este contrato?”.
5.1. De tool-call accuracy a task success: métricas locais podem esconder falhas sistêmicas
Métricas locais são úteis porque permitem diagnosticar componentes. Entretanto, elas podem produzir falsa confiança. Um agente pode escolher a ferramenta correta em 99% das vezes e ainda falhar frequentemente em tarefas longas. Isso ocorre porque reliability compõe ao longo da trajectory.
Suponha que cada etapa possua probabilidade elevada de sucesso, mas o workflow exija múltiplas decisões: discovery, selection, argument generation, interpretation e final synthesis. Pequenos erros se acumulam. Além disso, falhas não são independentes; uma interpretação incorreta pode contaminar todas as etapas seguintes.
Por isso, task success deve permanecer uma métrica de topo. Ela pode ser complementada por intermediate metrics que expliquem a causa dos fracassos. Tool selection accuracy mostra se a capability correta foi escolhida. Argument correctness mede parâmetros. Execution success mede comportamento do backend. Interpretation accuracy verifica se o agente compreendeu o resultado.
Outro cuidado é definir “success”. Uma resposta linguisticamente convincente não significa que o objetivo operacional foi alcançado. Para agents que modificam sistemas, o evaluator deve considerar postconditions e estado real.
Cost per successful task também é superior a cost per call em muitos cenários. Um modelo barato que necessita mais retries pode ser economicamente pior do que um modelo mais caro com trajectories menores. Da mesma forma, uma tool que economiza tokens mas aumenta failure rate pode elevar custo total.
O princípio é avaliar a unidade de valor do sistema, não apenas a unidade de execução técnica. Para AI Engineering, isso significa ligar metrics de tool calling a outcomes de workflow. Optimization local sem visão end-to-end frequentemente desloca falhas para outra parte da arquitetura em vez de eliminá-las.
5.2. Avaliação de seleção, argumentos, sequência, interpretação do resultado e decisão final
Uma trajectory agentic pode falhar em pelo menos cinco pontos distintos. O primeiro é selecionar a ferramenta errada. O segundo é escolher a capability correta, mas construir argumentos incorretos. O terceiro é executar tools corretas em sequência inadequada. O quarto é interpretar incorretamente o output. O quinto é possuir todas as evidências necessárias e ainda tomar a decisão final errada.
Agrupar esses casos sob uma única métrica “agent failed” reduz a capacidade de melhorar o sistema. Cada classe exige uma intervenção diferente. Selection failures podem indicar nomes ambíguos, discovery ruim ou tools sobrepostas. Argument failures podem exigir schemas melhores. Sequence failures apontam para orchestration. Interpretation failures podem revelar outputs verbosos ou pouco estruturados.
A avaliação precisa, portanto, preservar trajectory structure. Traces são particularmente úteis porque permitem comparar ações observadas com expected behaviors sem exigir que exista uma única sequência perfeita. Em tarefas abertas, várias trajectories podem ser válidas.
Grading também pode combinar métodos. Regras determinísticas são adequadas para identifiers, schemas e postconditions. LLM-as-judge pode avaliar propriedades semânticas quando não existe função objetiva simples. Human review continua relevante para amostras críticas e calibração dos graders.
É essencial evitar que o evaluator recompense apenas conformidade com uma trajectory de referência. Um agente pode descobrir uma sequência mais eficiente e ainda estar correto. A métrica deve priorizar invariants e outcome.
Esse decomposition também facilita ownership. Platform teams podem responder por discovery e execution reliability. Agent teams respondem por reasoning e orchestration. Domain teams definem business correctness. Evaluation torna-se, assim, a linguagem comum que conecta diferentes responsabilidades da plataforma.
5.3. Trajectory evaluation, counterfactual testing e fault injection para workflows multi-tool
Offline datasets tradicionais normalmente fornecem input e expected output. Agentes exigem uma dimensão adicional: o caminho entre eles. Trajectory evaluation analisa decisões intermediárias e permite descobrir comportamentos que uma avaliação final não revelaria, como chamadas redundantes, loops, ferramentas perigosas ou consultas desnecessárias.
Counterfactual testing amplia essa ideia. Em vez de avaliar apenas o que ocorreu, pergunta-se o que aconteceria se uma tool retornasse resultado diferente, demorasse mais ou estivesse indisponível. Isso permite testar robustness sem esperar incidentes reais.
Fault injection é especialmente valioso. Ferramentas podem ser configuradas em ambiente de teste para produzir timeouts, stale data, partial results, rate limits e conflicts. O objetivo é verificar se o agente e o runtime possuem recovery behavior apropriado. Chaos Engineering encontra aqui uma extensão natural para sistemas agentic.
Esses testes devem incluir ambiguity injection. Se duas entidades possuem nomes semelhantes, o agente confirma identidade antes de uma mutation? Se uma ferramenta retorna múltiplos candidatos, ele escolhe silenciosamente o primeiro ou solicita desambiguação?
Também é possível avaliar tool removal. Quando a capability preferida desaparece, o agente utiliza alternativa segura ou inventa dados? Esse tipo de experimento revela dependências implícitas.
Trace graders já oferecem uma base operacional para avaliar decisões e tool calls ao longo de workflows, mas equipes maduras precisam construir critérios específicos ao domínio.
A principal mudança mental é tratar o agente como sistema que navega estados, não como função de texto. O objetivo da evaluation não é apenas verificar respostas finais. É medir se o sistema chegou ao resultado correto por uma trajectory operacionalmente aceitável sob condições normais e adversas.
5.4. Regression matrices: avaliando tools através de modelos, prompts, versões e distribuições de tarefas
Uma tool não possui qualidade absoluta. Seu comportamento depende do modelo que a consome, das instruções disponíveis, das demais tools presentes e da distribuição de tarefas. Alterar qualquer elemento pode mudar selection accuracy ou argument generation. Por isso, regression testing precisa considerar uma matriz, não um único benchmark.
Uma dimensão é model version. Um schema que funciona perfeitamente com determinado modelo pode apresentar comportamento diferente após upgrade. Outra dimensão é prompt version. Mudanças no system prompt podem modificar strategy e tool preference. Tool catalog também importa: adicionar uma capability semelhante pode degradar discriminação.
A quarta dimensão é task distribution. Evals compostos apenas por happy paths produzem métricas pouco representativas. O conjunto precisa incluir long-tail queries, dados incompletos, ambiguidades, permissões insuficientes e tarefas que não deveriam utilizar ferramentas.
Regression matrices permitem comparar combinações antes de releases. Nem todas precisam ser executadas a cada commit; diferentes suites podem existir para pull requests, nightly runs e pre-production gates.
Production traffic deve complementar offline evaluation. Shadow evaluation em traces reais consegue detectar distribuição que o dataset ainda não representa. Incidentes relevantes devem retornar ao corpus como novos test cases.
É importante também acompanhar variance. Um agente pode possuir boa média e comportamento instável entre execuções. Para workflows críticos, repeated-run evaluation revela probabilistic tail risk.
No nível Principal, eval infrastructure passa a ser plataforma compartilhada. Ela permite que equipes evoluam models, prompts e tools independentemente sem perder confiança sistêmica. O resultado é semelhante ao papel desempenhado por CI/CD em software tradicional: mudanças deixam de depender de percepção subjetiva e passam a ser promovidas com evidência quantitativa de compatibilidade comportamental.
6. Performance Economics: otimizando custo, latência e context consumption
O custo de um AI Agent não é equivalente ao preço da chamada do modelo. Ele é a soma de inference, tool execution, network latency, serialization, retrieval, storage, retries e trabalho downstream. Em sistemas multi-step, esses componentes se multiplicam ao longo da trajectory. Otimizar apenas tokens por inference frequentemente produz decisões arquiteturais incorretas.
Uma métrica mais útil é cost per successful task. Ela incorpora o fato de que uma execução barata que falha e precisa ser repetida pode custar mais do que uma execução inicialmente cara, porém confiável. Da mesma forma, latency precisa ser medida end-to-end. Reduzir cinquenta milissegundos de uma tool é irrelevante se o workflow executa três chamadas de modelo de dois segundos desnecessariamente.
Tool design influencia diretamente essa economia. Granularidade determina quantidade de round trips. Output contracts afetam token consumption. Server-side filtering reduz context growth. Batching diminui overhead. Caching evita chamadas repetitivas. Programmatic orchestration pode remover inference steps inteiros.
A arquitetura deve trabalhar com budgets. Cada classe de tarefa pode possuir limites de custo, latency e tool calls. O runtime pode interromper loops, trocar estratégia ou selecionar modelos diferentes quando o orçamento está próximo do limite.
Também existe custo de infraestrutura invisível. Uma tool aparentemente simples pode disparar queries caras, GPU jobs ou chamadas SaaS cobradas por uso. O agente não deveria otimizar somente seu próprio token budget enquanto consome recursos downstream sem controle.
Performance Economics conecta AI Engineering a FinOps. Staff Engineers precisam compreender que autonomia tem preço variável. A arquitetura vencedora não é aquela que maximiza número de tool calls, mas aquela que converte reasoning e execução em outcomes com a melhor relação entre qualidade, custo e latência.
6.1. O custo invisível das tools: tokens, round trips, serialization, inference e downstream compute
Uma tool call normalmente parece barata quando observada isoladamente. O modelo emite alguns argumentos, a aplicação executa uma função e devolve um resultado. Em uma trajectory real, entretanto, cada chamada pode adicionar schema tokens, reasoning tokens, network round trips, payload serialization, parsing, logging e uma nova inference para interpretar o resultado.
Payloads grandes amplificam o problema. Retornar cinquenta kilobytes de JSON não custa apenas transferência de rede; pode transformar dados estruturados em milhares de tokens que serão processados pelo modelo. Se o agente chama várias ferramentas, context growth pode dominar o custo da tarefa.
Downstream compute também precisa ser contabilizado. Search tools podem executar queries caras. Analytics tools podem acionar Spark jobs. Image tools podem consumir GPU. APIs externas podem cobrar por request. Cost governance precisa acompanhar esses recursos de forma unificada.
Um modelo econômico útil associa cada tool a estimated_cost e estimated_latency. O agent runtime pode utilizar essa metadata para escolher entre estratégias equivalentes. Nem sempre essa escolha deve ficar com o LLM; policies determinísticas podem impor limites.
Observability precisa registrar custo por trajectory e por capability. Sem attribution, otimizações tornam-se especulativas. Uma ferramenta pouco utilizada pode representar grande parte do spend se cada chamada for extremamente cara.
É comum equipes reduzirem prompt tokens enquanto ignoram duas consultas downstream redundantes. Isso otimiza a parte visível, não o sistema.
Staff-level performance work exige analisar a critical path inteira. O custo de Tool Engineering não está somente no token emitido pelo modelo. Está em toda infraestrutura ativada por uma decisão probabilística. A unidade correta de análise é a tarefa completa, incluindo retries, falhas e efeitos indiretos.
6.2. Tool granularity como problema econômico: mais chamadas versus maior complexidade por chamada
Granularidade também é uma decisão de custo. Tools pequenas favorecem reuse e combinatorial flexibility, mas cada composição adiciona orchestration overhead. Tools compostas reduzem round trips, porém podem executar trabalho desnecessário ou dificultar caching granular.
Considere um workflow que precisa recuperar cliente, pedidos e pagamentos. Três tools independentes permitem que o agente execute apenas o necessário. Uma get_customer_360 pode reduzir chamadas quando todas as informações são frequentemente utilizadas. A escolha correta depende da workload distribution, não de uma preferência estética por APIs pequenas.
A métrica relevante é expected task cost. Se 90% das tarefas exigem os três datasets, uma capability agregada pode ser superior. Se apenas 10% precisam de tudo, ela pode desperdiçar compute e context. Telemetry real deveria orientar esse desenho.
Existe também custo cognitivo. Cada tool adicional aumenta action space. Uma arquitetura altamente granular pode exigir mais reasoning para selecionar e ordenar capabilities. Esse custo não aparece diretamente na API, mas manifesta-se em maior latency e failure rate.
Composite tools são particularmente úteis quando encapsulam operações determinísticas frequentes. O agente expressa intenção de alto nível, enquanto a infraestrutura executa etapas internas sem novos LLM round trips. Porém, essas ferramentas não deveriam esconder decisões que precisam permanecer observáveis ou sujeitas a approval.
O design ótimo frequentemente utiliza múltiplas granularidades: primitives para workflows especializados e higher-level capabilities para caminhos comuns. O registry pode decidir quais versões expor conforme task context.
Tool Engineering madura evita dogmas como “one tool per endpoint”. APIs foram desenhadas para software; agent capabilities devem ser desenhadas para trajectories. A melhor granularidade é aquela que equilibra flexibility, reliability, observability e cost per successful task.
6.3. Filtering, pagination, caching, batching e server-side aggregation como mecanismos de controle de contexto
Context management não deve começar depois que os dados retornam da tool. O melhor token é aquele que nunca precisou entrar no context window. Filtering, pagination, caching e aggregation deveriam ser considerados parte do design de capabilities.
Server-side filtering permite que o modelo especifique critérios estruturados em vez de receber grandes datasets e filtrá-los por linguagem natural. Além de economizar tokens, isso melhora determinismo. Sort e aggregation também deveriam ser executados por sistemas adequados quando não exigem reasoning semântico.
Pagination precisa considerar comportamento agentic. APIs que retornam milhares de registros por default são perigosas. Porém, pages pequenas demais podem criar loops de chamadas. O contrato deve fornecer total_count, next_cursor e hints suficientes para o agente decidir se precisa continuar.
Caching reduz custo principalmente em dados relativamente estáveis ou consultas repetidas dentro da mesma trajectory. Entretanto, stale data pode ser perigoso para mutations. O cache policy deve considerar freshness requirements da capability.
Batching é valioso quando várias operações independentes podem ser processadas de uma vez. Um agente que consulta vinte identifiers individualmente cria vinte oportunidades de latency e failure. Uma batch tool pode reduzir overhead significativamente.
Aggregation também funciona como context compression. Em vez de retornar milhões de eventos, a infraestrutura fornece estatísticas, anomalies ou top-K candidates e preserva acesso aos dados detalhados por referência.
Essas técnicas parecem tradicionais porque realmente são. AI Engineering não substitui Distributed Systems Engineering; ela adiciona um consumidor probabilístico sobre os mesmos fundamentos.
A diferença está na importância do context budget. Dados excessivos não apenas custam memória. Eles afetam inference. Tool performance, portanto, deve considerar simultaneamente bytes, tokens, latency e semantic utility. Essa visão integrada é essencial para agents eficientes em produção.
6.4. Cost-aware execution: quando mover raciocínio do modelo para código determinístico
O LLM não deveria ser o executor universal de lógica. Muitas decisões que aparecem inicialmente em prompts podem ser transformadas em código depois que o domínio é compreendido. Esse movimento reduz custo e variance sem necessariamente reduzir flexibilidade.
Imagine que o prompt instrua: “se o valor for superior a 10.000, solicite aprovação; caso contrário, execute automaticamente”. Não existe razão para consumir reasoning probabilístico para aplicar essa regra. Ela deveria estar em policy code. O modelo pode determinar intenção; a infraestrutura aplica thresholds.
O mesmo ocorre com sorting, arithmetic, validation, access control, retry policy e state transitions. Delegar essas operações ao LLM aumenta token usage e cria possibilidades de erro que software determinístico já sabe resolver.
A arquitetura deve identificar probabilistic islands: pontos onde interpretação semântica realmente é necessária. Entre essas ilhas, execution flow pode ser programático. Isso reduz quantidade de inference hops e facilita testing.
Cost-aware routing também pode escolher modelos diferentes. Tasks simples de classification podem utilizar modelos menores, enquanto decisões complexas recebem modelos mais capazes. Porém, model routing precisa ser avaliado por cost per successful task, não apenas preço por token.
Ferramentas também podem fornecer precomputed features para diminuir reasoning load. Em vez de pedir ao modelo que analise centenas de eventos, uma capability calcula aggregates e anomalies.
Esse princípio possui implicação estratégica: AI Engineering madura tende a retirar trabalho do LLM conforme aprende sobre o problema. Protótipos concentram lógica em prompts porque isso maximiza velocidade. Sistemas maduros codificam invariantes e padrões recorrentes.
O objetivo não é usar menos IA por ideologia. É utilizar probabilistic compute somente onde ele oferece vantagem econômica ou funcional. Todo reasoning determinístico delegado ao LLM precisa justificar seu custo e sua variância.
7. Tool Platforms em produção: segurança, observabilidade e evolução operacional
Quando tools permitem que modelos atuem sobre sistemas reais, elas deixam de ser simples integrações e passam a formar uma execution platform. Segurança, observabilidade e governança precisam ser consideradas desde o início porque o blast radius cresce com o nível de autonomia.
O principal erro é conceder ao agente credentials amplas e confiar que o prompt impedirá ações inadequadas. Prompt instructions não são authorization boundaries. O Tool Layer precisa aplicar least privilege, tenant isolation, scopes e policy checks fora do modelo. O agente pode solicitar uma ação; apenas infraestrutura autorizada decide se ela é permitida.
Observabilidade também muda. Logs tradicionais de API mostram que uma chamada ocorreu, mas não explicam por que o agente escolheu aquela capability. Tracing precisa conectar user intent, model decisions, tool calls, outputs, retries, approvals e final outcome. Essa causal chain é necessária tanto para debugging quanto para auditoria.
As plataformas modernas de agents já tratam tracing e workflow evaluation como componentes centrais justamente porque tool interactions precisam ser analisadas no contexto da execução completa.
Operação em produção exige ainda SLOs e release discipline. Uma tool pode estar tecnicamente disponível e semanticamente degradada. Uma mudança de schema pode aumentar latency ou selection errors sem gerar HTTP failures. SLOs precisam incorporar qualidade comportamental.
Finalmente, governance deve permitir escala organizacional. Centralizar toda criação de tools impede velocidade; ausência completa de padrões produz caos. Platform teams precisam oferecer golden paths, SDKs, registries, policies e eval gates.
Tool Engineering atinge maturidade quando capabilities podem evoluir independentemente, agentes podem consumi-las com confiança e incidentes podem ser reconstruídos de ponta a ponta sem depender de adivinhação.
7.1. Least privilege, scoped credentials e approval boundaries para ações de alto impacto
Segurança em AI Agents precisa partir de uma premissa simples: o modelo não é um security principal confiável. Ele interpreta instruções e pode ser influenciado por contexto externo. Portanto, autorização nunca deveria depender exclusivamente de o LLM “decidir corretamente”.
Credentials devem ser scoped à capability e, quando possível, à execução específica. Uma tool de consulta não precisa de permissão para modificar registros. Um agente operando sobre determinado tenant não deveria conseguir acessar outro mesmo que produza um identifier válido. Enforcement precisa ocorrer no execution layer.
Delegated authorization é especialmente importante quando o agente atua em nome de usuários. O runtime precisa saber quem autorizou a operação, qual escopo foi concedido e por quanto tempo. Essa informação não deveria ser inferida do texto da conversa.
Approval boundaries entram quando impacto ultrapassa determinado threshold. O design mais sofisticado não classifica aprovação apenas por tool, mas pelo contexto da operação. Transferir dez reais pode ser tratado de maneira diferente de transferir um milhão. Excluir um draft difere de excluir um dataset de produção.
Também é recomendável separar propose de execute para operações críticas. O agente constrói uma proposta estruturada, a policy layer valida e somente então uma capability de execução recebe autorização.
Auditing precisa preservar identity chain: usuário, agente, model run, tool, credential e target resource. Isso permite investigar ações posteriormente.
Protocolos de interoperabilidade facilitam acesso a capacidades, mas não eliminam a necessidade de trust architecture. Quanto mais simples se torna conectar agentes a ferramentas, maior a importância de controlar o que essas conexões podem fazer. Autonomia sem least privilege transforma produtividade em blast radius.
7.2. Observabilidade de trajectories: traces, causalidade, auditoria e debugging de decisões agentic
Logs de microservices respondem “o que aconteceu neste serviço?”. Para AI Agents, precisamos também responder “por que esta sequência aconteceu?”. Isso exige trajectory observability. Cada execução deveria possuir correlation identifiers capazes de conectar model inference, tool selection, argumentos, backend calls, outputs e decisões subsequentes.
Tracing não precisa armazenar todo conteúdo indiscriminadamente. Dados sensíveis exigem redaction e retention policies. O objetivo é preservar causalidade suficiente para reconstruir comportamento sem transformar observabilidade em novo vetor de vazamento.
Spans deveriam representar chamadas relevantes: model, tool, retrieval, policy evaluation, approval e external API. Metadata pode incluir latency, token usage, model version, tool version, retry count e error class. Essa estrutura permite identificar onde uma regressão realmente ocorreu.
Agent eval platforms já utilizam traces para avaliar questões como escolha de tools, handoffs e violações de instruções. Isso demonstra como observability e evaluation convergem em sistemas agentic.
Causal debugging é particularmente importante. Se a resposta final contém erro, o modelo inventou informação ou a tool forneceu dados incorretos? Se uma mutation errada ocorreu, o problema estava na entity resolution, tool selection ou backend? Sem traces, essas classes tornam-se indistinguíveis.
Metrics agregadas complementam traces. Selection rate, error rate, p95 latency, retry rate, tokens por tool e cost per successful task ajudam a identificar padrões.
Em maturidade elevada, production traces alimentam evaluation datasets automaticamente. Incidentes deixam de ser apenas problemas operacionais e tornam-se novos testes de regressão. Essa retroalimentação cria uma ponte direta entre observabilidade, reliability engineering e evolução contínua da arquitetura de AI Agents.
7.3. SLOs, error budgets, canary releases e rollback para contratos consumidos por agentes
SLOs tradicionais medem availability e latency. Para Tool Engineering, essas métricas continuam necessárias, mas são insuficientes. Uma tool pode responder em 100 milissegundos com 99,99% de disponibilidade e ainda causar degradação sistêmica se suas descrições induzirem selection errors ou seus outputs deixarem de fornecer informações necessárias ao agente.
Por isso, SLOs podem incorporar dimensões comportamentais. Tool execution success, semantic correctness, valid argument rate e downstream task success fornecem uma visão mais completa. Nem toda métrica precisa ser contractual SLO, mas precisa existir observabilidade sobre elas.
Error budgets também podem orientar velocidade de evolução. Se uma capability está gerando regressões frequentes, mudanças adicionais podem ser limitadas até reliability retornar ao nível esperado.
Canary releases são particularmente importantes porque modificações aparentemente pequenas podem alterar comportamento probabilístico. Uma nova description ou novo optional field deve ser exposto inicialmente a parcela limitada de tráfego. Comparar trajectories entre versões permite detectar diferenças antes de rollout completo.
Rollback precisa considerar contrato e backend. Se agents começaram a gerar argumentos que só a nova versão entende, voltar apenas o serviço pode criar incompatibilidade. Version management deve existir no gateway ou registry.
Model upgrades também merecem canaries. Mesmo sem modificar uma tool, um novo modelo pode utilizá-la de forma diferente. Regression matrices precisam validar essa combinação.
Essa disciplina aproxima Tool Engineering de Site Reliability Engineering, mas adiciona uma camada comportamental. O serviço não é saudável apenas quando responde. Ele é saudável quando consumidores probabilísticos continuam conseguindo utilizá-lo de maneira correta. Availability mede infraestrutura; agentic reliability mede a capacidade efetiva de transformar intenção em outcome seguro.
7.4. Tool Engineering como plataforma: ownership, golden paths e governança para organizações multi-agent
À medida que diferentes equipes constroem agents, o risco é cada uma criar seu próprio ecossistema de tools, wrappers, prompts e políticas. O resultado é duplicação de capabilities, contratos divergentes e observabilidade fragmentada. Tool Engineering precisa evoluir de prática local para platform capability.
Um platform team não deveria implementar todas as ferramentas. Sua função é criar golden paths. Isso inclui SDKs, schema conventions, MCP templates, authentication adapters, tracing libraries, eval harnesses e deployment pipelines. Domain teams continuam responsáveis pela semântica de suas capacidades, enquanto a plataforma fornece infraestrutura consistente.
Ownership precisa ser explícito. Cada tool deve possuir equipe responsável, documentação, escalation path e lifecycle. Orphaned tools são particularmente perigosas porque agents podem continuar descobrindo e utilizando capabilities que ninguém mantém.
Quality gates ajudam a escalar governança sem review manual centralizado. Um pipeline pode verificar naming conventions, schemas, security metadata, test coverage, eval results e backward compatibility antes de registrar uma nova capability.
O registry funciona como source of truth. Agents consultam capabilities aprovadas, não endpoints arbitrários. Policies podem determinar quais ferramentas cada runtime enxerga.
Também é importante medir reuse. Se cinco equipes criaram maneiras diferentes de consultar o mesmo domínio, talvez exista uma abstração ausente. Porém, consolidar cedo demais pode gerar um contrato genérico e ruim. Platform architecture precisa equilibrar standardization e domain autonomy.
No longo prazo, o Tool Layer pode se tornar um dos ativos mais valiosos da infraestrutura de AI Engineering. Modelos serão substituídos e frameworks mudarão. Uma camada bem projetada de capacidades corporativas, segura e observável, preserva conhecimento operacional e permite que diferentes gerações de AI Agents atuem sobre a organização sem reconstruir todas as integrações.
Tool Engineering é, portanto, muito mais que function calling. É a disciplina responsável por transformar capacidades determinísticas em interfaces que sistemas probabilísticos conseguem descobrir, compreender, executar e verificar. Quanto maior a autonomia dos agents, maior a importância dessa camada.
O erro arquitetural mais comum é tentar resolver confiabilidade exclusivamente no modelo. Prompts melhores, modelos maiores e reasoning mais longo podem melhorar decisões, mas não substituem idempotência, authorization, semantic contracts, postcondition verification ou failure semantics. Reliability precisa emergir do sistema completo.
Para Staff e Principal AI Engineers, a consequência é profunda. Projetar agentes passa a exigir domínio simultâneo de AI Engineering, Distributed Systems, API Design, SRE, Security Engineering, Evaluation e Context Engineering. O modelo é apenas um componente dentro de uma arquitetura muito maior.
A tese final pode ser resumida em uma fronteira: reasoning pode ser probabilístico; efeitos não podem ser ambíguos. O agente deve possuir liberdade para interpretar objetivos, explorar alternativas e selecionar estratégias. O Tool Layer deve converter essas decisões em operações restritas, auditáveis e verificáveis.
As organizações que compreenderem essa diferença deixarão de construir coleções de demos conectadas a APIs e começarão a construir verdadeiras Agent Platforms. Nesse estágio, a vantagem competitiva não estará apenas no modelo utilizado. Estará na qualidade da infraestrutura que permite aos modelos agir sobre o mundo com custo controlado, segurança e confiabilidade operacional.
A2A em produção: arquitetura, contratos e confiabilidade para interoperabilidade entre agentes…
MCP como infraestrutura de AI Engineering: design, operação e confiabilidade em ambientes…
Memory Engineering para AI Agents: arquitetura, persistência e controle semântico da memória
