Sistemas empresariais foram desenhados para pessoas navegarem ou para aplicações chamarem APIs com parâmetros exatos. Agentes ocupam uma fronteira nova: interpretam linguagem, escolhem ferramentas e aprendem com respostas, mas podem confundir nomes, omitir campos e gastar contexto lendo dados irrelevantes.
Agent Experience, ou AX, é uma forma útil de nomear o trabalho de tornar capacidades compreensíveis e seguras para agentes. Não é um padrão formal nem substitui UX e experiência de desenvolvimento. É o desenho conjunto de contratos, descrições, resultados, erros, limites e evidências para um consumidor probabilístico.
Em uma frase
Uma boa Agent Experience reduz ambiguidade para o modelo e preserva limites para o negócio: poucas ferramentas claras, respostas úteis e erros que orientam sem liberar autoridade.
A dor de entregar uma API humana demais ao agente
Uma API pode ser tecnicamente correta e ainda ser ruim para agentes. Operações com nomes parecidos, parâmetros genéricos, UUIDs sem contexto e respostas gigantes aumentam seleção incorreta. Um erro “500” força nova tentativa sem ensinar se faltou permissão, dado, formato ou disponibilidade.
Publicar todos os endpoints como ferramentas cria uma superfície enorme. O agente precisa decidir entre centenas de ações de baixo nível e compor sequências que a aplicação poderia executar deterministicamente. A flexibilidade aumenta tokens, latência e risco; o sistema transfere sua complexidade interna para o modelo.
Ferramentas para agentes exigem um contrato diferente
A engenharia da Anthropic recomenda ferramentas com propósito distinto, namespace claro, respostas relevantes, paginação e erros acionáveis. O texto relata que excesso e sobreposição podem confundir agentes e que respostas volumosas desperdiçam contexto. É experiência de um fornecedor e deve ser testada em modelos reais.
A especificação MCP 2026-07-28 permite esquemas estruturados de entrada e saída e mecanismos de extensibilidade. Protocolo ajuda na portabilidade, mas não transforma automaticamente um endpoint mal modelado em ferramenta compreensível, nem aplica a regra de negócio da empresa.
Exemplo composto: de sete endpoints a uma capacidade
Em um exemplo composto, para agendar manutenção o agente precisava buscar usuário, equipamento, agenda, técnicos e peças em cinco endpoints, criar evento num sexto e atualizar ordem num sétimo. Pequenas diferenças de identificador produziam chamadas redundantes e falhas difíceis de explicar.
A empresa publica uma ferramenta “programar manutenção” com equipamento, janela e prioridade. Por baixo, um serviço determinístico resolve relações, valida disponibilidade e devolve opções ou um erro específico. A ferramenta não esconde consequência: informa mudanças previstas, exige aprovação quando necessário e retorna os identificadores oficiais da execução.
Os princípios de uma boa Agent Experience
Comece por tarefas, não por endpoints. Dê a cada ferramenta um nome inequívoco, descrição de quando usar e de quando não usar, parâmetros específicos, defaults seguros e esquema de saída. Retorne informação semântica suficiente para a próxima decisão, com fonte, versão e estado; ofereça paginação e filtros antes de listas completas.
Erros devem separar entrada inválida, falta de autorização, conflito de negócio, indisponibilidade e resultado desconhecido. Marque ações destrutivas e abertas, exija confirmação proporcional e forneça chave idempotente. Avalie ferramenta escolhida, parâmetros, chamadas redundantes, tokens, latência e efeito real no sistema.
Teste rápido de Agent Experience
- O nome e a descrição distinguem a ferramenta de todas as alternativas?
- Entradas e saídas têm esquemas, exemplos e identificadores compreensíveis?
- A resposta contém somente o contexto útil para o próximo passo?
- Erros orientam correção, recusa ou espera sem incentivar retry cego?
- Testes medem seleção, parâmetros, estado final, custo e segurança?
Como a Uiless ajuda
A Uiless organiza integrações como capacidades de negócio delimitadas, em vez de expor livremente cada endpoint. Contratos REST, OpenAPI, adaptadores privados e fontes MCP entram em um catálogo com identidade, permissão, política, aprovação e evidência ao redor da chamada.
Para a pessoa, a experiência continua natural por voz ou texto. Para o agente, ferramentas recebem contexto suficiente e retornos previsíveis. Para a empresa, sistemas oficiais permanecem responsáveis pelo dado e pela consequência. AX, UX e governança passam a descrever o mesmo fluxo sob perspectivas diferentes.
Aplique os critérios de boa automação e veja como mensagens de erro orientam recuperação.
