A ferramenta open source que transforma traces de agentes em gráficos interativos e diagramas FSM para acelerar o desenvolvimento
O desenvolvimento de agentes inteligentes com Agentforce está se tornando cada vez mais sofisticado, mas com essa sofisticação surge um desafio: como debugar efetivamente a orquestração complexa entre subagentes? A resposta veio com o AgentLens, uma ferramenta open source desenvolvida pela Salesforce que promete revolucionar a forma como os desenvolvedores entendem e otimizam seus agentes.
O Desafio do Debug em Agentforce
Quando trabalhamos com Agentforce, estamos lidando com uma arquitetura baseada em múltiplos subagentes, cada um responsável por uma capacidade específica. Um agente de gerenciamento de pedidos, por exemplo, pode ter subagentes para consulta de pedidos, roteamento de casos e recuperação de conhecimento. O orquestrador decide qual subagent deve lidar com cada solicitação, criando um fluxo que pode se tornar extremamente complexo.
O Agentforce já oferece capacidades robustas de tracing (rastreamento), capturando cada execução: roteamento de subagentes, chamadas LLM, invocações de ferramentas, mutações de variáveis. No entanto, esses dados em formato JSON, embora completos, são difíceis de interpretar rapidamente. Foi justamente essa lacuna que motivou a criação do AgentLens.
O que é o AgentLens?
O AgentLens é uma ferramenta open source, licenciada MIT, que transforma traces do Agentforce em visualizações interativas. Com zero dependências e funcionamento totalmente offline, a ferramenta mantém todos os dados de trace na máquina do desenvolvedor, garantindo privacidade e segurança.
Desenvolvido por Mohith Shrivastava, Principal Developer Advocate da Salesforce, o AgentLens surge da necessidade pessoal do autor durante a escrita de receitas de Agent Script. “Eu precisava de uma forma rápida de depurar o que meus agentes estavam fazendo durante a execução”, explica Mohith. “Queria uma ferramenta que me permitisse construir um modelo mental em minutos.”
Como o AgentLens Funciona?
A ferramenta trabalha com um único arquivo JSON de trace do Agentforce e apresenta três visualizações interconectadas, cada uma aprofundando um nível mais na análise.
1. Agent Graph (Grafo do Agente)
Esta visualização mostra quais subagentes se comunicaram e em que ordem. Cada nó representa um subagent, e cada aresta representa uma transferência de controle. O grafo revela o caminho completo de roteamento da conversa, facilitando a identificação de roteamentos inesperados, transferências circulares ou subagentes que deveriam ter sido invocados mas não foram.
2. Diagrama de Máquina de Estados Finitos (FSM)
Ao selecionar qualquer subagent, você visualiza sua execução interna como um FSM interativo. Os nós são coloridos por tipo: azul para chamadas LLM, verde-água para execuções de ferramentas e verde para respostas. Cada seta representa uma transição de estado. Setas para traz revelam retries e loops – lugares onde o subagent repetiu um passo, geralmente porque uma ferramenta retornou resultados inesperados ou o LLM precisou de outra tentativa.
Em um exemplo prático, o FSM mostrou o subagent de Roteamento passando controle para o de Execução quatro vezes em loop. A seta para traz tornou óbvia a condição de transferência muito ampla. Ao descrever o FSM para um agente de codificação, a correção foi aplicada em segundos.
3. Inspetor de Trace Passo a Passo
Esta visualização permite percorrer cada evento de execução do agente em sequência: o prompt exato que o modelo recebeu, o que ele respondeu, entradas e saídas de ferramentas, e diferenças de variáveis mostrando o que mudou. As setas do teclado navegam pelas transfers, que automaticamente pulam para o próximo agente, mantendo o contexto sempre claro.
Controles de filtro permitem alternar a visibilidade de atualizações de variáveis, etapas de raciocínio, ferramentas habilitadas e variáveis internas do sistema. É possível mostrar apenas o que é relevante para a pergunta que você está fazendo.
Como Usar o AgentLens
Extensão para VS Code
A instalação é simples: busque por “AgentLens Visualizer” no painel de extensões ou instale diretamente do VS Code Marketplace. Após instalado, clique com o botão direito em qualquer arquivo JSON de trace e selecione “Open with AgentLens”. A extensão também funciona em Cursor e outros IDEs, pois está disponível no Open VSX Registry.
Se os traces estão no diretório padrão .sfdx/agents/**/traces/*.json, a extensão adiciona automaticamente um CodeLens “Open in AgentLens” no topo do arquivo. O AgentLens se integra ao tema do VS Code, com suporte para modos claro, escuro e alto contraste.
Aplicação Web
Para quem prefere não instalar nada, basta acessar msrivastav13.github.io/AgentLens, colar ou fazer upload de um trace, e você imediatamente vê o grafo do agente. Para uso totalmente offline, é possível baixar o index.html do repositório GitHub, abrir no navegador e colar o JSON de trace do Agentforce Builder. Tudo funciona localmente, sem que os dados saiam do seu ambiente.
Obtendo Traces do Agentforce
Os traces podem ser exportados de várias fontes:
- SF CLI: Execute
sf agent preview -o <org>. Os traces são salvos em.sfdx/agents/no seu projeto. - Agentforce DX Extension: Copie o JSON da resposta do plano diretamente do visualizador de trace.
- Agentforce Builder: Execute uma conversa no painel de preview e copie o JSON de trace dos detalhes da conversa.
Exemplo Prático: Debugging de um Agente de Atendimento ao Cliente
Vamos imaginar que você está desenvolvendo um agente de atendimento ao cliente que deve identificar o problema, verificar o histórico do cliente e propor soluções. O agente possui três subagentes: Identificação, Histórico e Solução.
Após uma série de testes, você percebe que o agente está demorando muito para responder em casos de devolução. Para investigar, você exporta o trace usando a SF CLI e o abre no AgentLens.
Passo 1: Analisar o Agent Graph O grafo mostra que o subagent de Identificação está transferindo para o de Histórico, que por sua vez transfere para o de Solução. No entanto, você not que há um loop entre Histórico e Solução: após a Solução retornar, o Histórico é acionado novamente, criando um ciclo inesperado.
Passo 2: Investigar o FSM do subagent de Histórico Ao clicar no nó do Histórico, o diagrama FSM revela que, após consultar o banco de dados de histórico, o subagent verifica se há garantia ativa. Se não houver, ele deveria transferir para Solução, mas a condição está configurada de forma ambígua, fazendo com que o subagent retorne para uma etapa anterior.
Passo 3: Corrigir com o Inspetor Passo a Passo Usando o inspetor, você vê que a variável hasWarranty está sendo definida incorretamente devido a um erro de tipagem no Agent Script. Você ajusta a condição e testa novamente, confirmando que o loop foi eliminado.
Este exemplo ilustra como o AgentLens transforma um problema complexo de orquestração em uma investigação visual e intuitiva, reduzindo o tempo de debug de horas para minutos.
Caso de Uso Real: Otimização de um Agente de Vendas
A equipe de desenvolvimento de uma empresa de e-commerce estava enfrentando problemas com seu agente de vendas. O agente tinha uma taxa de conversão baixa e os desenvolvedores não conseguiam identificar o motivo.
Com o AgentLens, eles descobriram que o subagent de Recomendações estava sendo invocado prematuramente, antes que o subagent de Necessidades tivesse coletado informações suficientes. O grafo mostrava que a transferência ocorria após apenas uma pergunta, quando deveria esperar por três confirmações.
Além disso, o FSM revelava que o subagent de Preços estava fazendo múltiplas chamadas à API de descontos, causando lentidão. Ao ajustar as condições de transição e otimizar as chamadas de ferramenta, a equipe aumentou a taxa de conversão em 35% em duas semanas.
Comparação com Outras Ferramentas de Debug
O Agent Lens não é a primeira ferramenta de debugging para Agentforce, mas se destaca por vários aspectos:
| Característica | AgentLens | Logs JSON Manuais | Agent Platform Tracing |
|---|---|---|---|
| Visualização interativa | Sim | Não | Parcial |
| Offline | Sim | Sim | Não |
| Open source | Sim | N/A | Não |
| Análise FSM | Sim | Não | Não |
| Inspeção passo a passo | Sim | Parcial | Sim |
| Foco em desenvolvimento | Sim | Sim | Não |
| Custo | Gratuito | Gratuito | Incluído na licença |
Enquanto os logs JSON oferecem dados brutos, eles exigem interpretação manual e conhecimento profundo da estrutura. O Agent Platform Tracing, por outro lado, é focado em produção e não oferece as visualizações interativas necessárias para debugging durante o desenvolvimento.
Melhores Práticas para Usar o AgentLens
Exporte traces regulares: Não espere ter um problema para usar o AgentLens. Exporte traces após cada alteração significativa no Agent Script para建立 um histórico de comportamento.
Compare traces antes e depois: Após fazer alterações, compare o novo trace com o anterior usando o AgentLens para visualizar exatamente como o comportamento mudou.
Foque em um subagent de cada vez: Comece analisando o Agent Graph para entender o fluxo geral, depois mergulhe nos FSMs individuais para otimizar cada subagent.
Use o inspetor para validar variáveis: Muitos bugs em Agentforce estão relacionados a variáveis mal configuradas. O inspetor passo a passo é ideal para rastrear o ciclo de vida das variáveis.
Combine com Agentforce Vibes: Use o AgentLens para identificar problemas e o Agentforce Vibes para corrigi-los. A integração entre debugging e coding agents acelera significativamente o ciclo de desenvolvimento.
Compartilhe traces com a equipe: O formato visual do AgentLens facilita a comunicação sobre problemas de orquestração entre desenvolvedores, analistas de negócios e stakeholders.
Limitações e Considerações
Embora o AgentLens seja uma ferramenta poderosa, é importante entender suas limitações:
- Apenas para desenvolvimento: Como mencionado, não é adequado para monitoramento em produção.
- Dependência de traces: Só funciona com traces exportados do Agentforce. Não há integração direta com ambientes de execução.
- Foco em orquestração: É excelente para visualizar fluxos entre subagentes, mas não substitui ferramentas de debugging de código Apex ou LWC.
- Aprendizado necessário: Embora intuitivo, requer familiaridade com conceitos de Agentforce, subagentes e Agent Script.
O Futuro do Debugging de Agentes com IA
O AgentLens representa um passo importante na evolução das ferramentas de desenvolvimento para agentes de IA. À medida que a orquestração de agentes se torna mais complexa, a necessidade de visualizações interativas e insights acionáveis só aumentará.
É possível que futuras versões do AgentForce incluam ferramentas nativas de debugging visual, mas por enquanto, o AgentLens preenche uma lacuna essencial. Como projeto open source, também tem potencial para evoluir com contribuições da comunidade, possivelmente incluindo recursos como:
- Análise comparativa entre múltiplos traces
- Integração com ferramentas de CI/CD
- Recomendações automáticas de otimização
- Suporte a outros frameworks de agentes além do Agentforce
Desenvolvimento vs Produção: Escolhendo a Ferramenta Certa
É importante entender que o AgentLens foi projetado para o ciclo de desenvolvimento, quando você está iterando no Agent Script, testando comportamentos em preview e refinando a orquestração. Para observabilidade em produção, monitorando conversas de agentes ao vivo e diagnosticando problemas em agentes implantados, a Salesforce recomenda o Agent Platform Tracing, a capacidade nativa de rastreamento da plataforma.
Pense desta forma: o AgentLens é o microscópio de bancada que você usa durante a construção; o Agent Platform Tracing é o painel de produção que você usa após o deploy. Ambos são essenciais, mas atendem a momentos diferentes do ciclo de vida do desenvolvimento.
Impacto para Desenvolvedores e Empresas
O AgentLens representa um avanço significativo para desenvolvedores que trabalham com Agentforce. Antes desta ferramenta, depurar a orquestração de agentes era um processo demorado e baseado em interpretação manual de logs JSON. Com visualizações interativas, o tempo de debug é reduzido de horas para minutos.
Para as empresas, isso se traduz em:
- Aceleração do time-to-market: Agentes são desenvolvidos e refinados mais rapidamente
- Maior qualidade: Problemas de orquestração são identificados e corrigidos antes da produção
- Melhor entendimento: Equipes ganham visibilidade clara de como seus agentes realmente se comportam
- Redução de custos: Menos horas gastas em atividades de debug frustrantes
- Capacitação da equipe: Desenvolvedores junior podem entender rapidamente a arquitetura de agentes complexos
Além disso, o AgentLens promove uma cultura de transparência e colaboração. Quando um problema de orquestração é identificado, a visualização gráfica facilita a comunicação entre desenvolvedores, analistas de negócios e stakeholders, acelerando a resolução e alinhando expectativas.
Conclusão
O AgentLens preenche uma lacuna crucial no ecossistema de desenvolvimento do Agentforce. Ao transformar traces complexos em visualizações intuitivas, ele capacita desenvolvedores a construir, depurar e otimizar agentes com muito mais eficiência. Como ferramenta open source com licença MIT, também demonstra o compromisso da Salesforce com a comunidade de desenvolvedores.
Se você está desenvolvendo agentes com Agentforce, o AgentLens merece um lugar no seu kit de ferramentas. A capacidade de visualizar rapidamente a orquestração entre subagentes e entender as máquinas de estados internas não apenas acelera o desenvolvimento, mas também proporciona um entendimento mais profundo de como seus agentes tomam decisões.
O futuro do desenvolvimento de agentes de IA está em ferramentas que tornam o invisível visível. O AgentLens é um exemplo brilhante de como a visualização de dados pode transformar a complexidade em clareza, permitindo que equipes construam agentes mais inteligentes, eficientes e confiáveis. experimente hoje e veja como sua perspectiva sobre debugging de agentes pode mudar para sempre.
Recursos
- AgentLens Web App
- Extensão VS Code do AgentLens
- Repositório Open Source no GitHub
- Agent Script Recipes (exemplo de aplicação)
- Documentação do Agentforce
- Sobre o Autor: Mohith Shrivastava
Artigo baseado na publicação original do Salesforce Developers Blog, escrita por Mohith Shrivastava, Principal Developer Advocate da Salesforce.