Visão geral
Um rastreamento de execução é um registro de tudo o que acontece enquanto seu agente processa uma solicitação. Ele mostra quais etapas são executadas, quanto tempo cada uma leva e quantos tokens cada chamada de modelo usa. Cada vez que seu agente é executado, o Atlas Agent Engine registra um rastreamento automaticamente.
Use rastreamentos para responder a dois tipos de perguntas:
O que aconteceu? Os rastreamentos mostram a sequência de chamadas de ferramentas, chamadas de modelo e outras etapas que um agente realiza para produzir uma resposta. Verifique isto quando uma execução produzir um resultado inesperado ou errado.
Por que foi lento? Os rastreamentos mostram quanto tempo leva cada etapa, para que você possa encontrar a etapa específica responsável por uma execução lenta em vez de tentar fazer suposições.
Um rastreamento é composto por três níveis: uma sessão, suas execuções e as etapas de cada execução. Uma sessão é um thread de conversa com um ID de sessão exclusivo, criado sempre que seu agente é invocado. Uma sessão pode conter várias execuções, uma para cada vez de execução.Uma execução, por sua vez, pode conter várias etapas: as operações individuais que um agente executa, como uma chamada de modelo ou uma chamada de ferramenta. Para saber o que significa cada tipo de etapa, consulte Tipos de etapas mais tarde nesta página.
Você pode visualizar rastreamentos em dois locais:
O Playground, onde uma bandeja Traces no lado direito da página mostra o rastreamento de suas próprias sessões de teste interativo à medida que são executadas.
A página Traces, em Monitor, que mostra todas as sessões no projeto em todos os espaços de trabalho. Uma sessão aparece aqui independentemente de seu agente ter sido invocado por meio do Playground, da UI, da API REST ou da CLI, portanto, é aqui que você encontra a atividade real do usuário final. O Playground só mostra suas próprias sessões.
Step Kinds
Cada etapa de um rastreamento tem um tipo, exibido como um ícone e um rótulo. A tabela a seguir descreve cada tipo:
Kind | Descrição |
|---|---|
chamada LLM (grandes modelos de linguagem) | Uma chamada para um grandes modelos de linguagem, como gerar uma resposta ou decidir qual ferramenta usar em seguida. |
Chamada da ferramenta | Uma chamada para uma ferramenta à qual o agente tem acesso, como uma query de banco de dados ou uma solicitação de API externa. |
Memória | Uma leitura de ou escrita no armazenamento de memória do agente. Para saber mais, consulte Adicionar memória ao seu agente. |
guardrail | Uma verificação de conteúdo aplicada à entrada ou saída do agente. Para saber mais, consulte Usar grades de proteção de conteúdo. |
Verificação da política | Uma verificação para verificar se o agente tem permissão para realizar uma ação, como chamar uma ferramenta ou um modelo específico. Para saber mais, consulte Mecanismo de Política. |
Chamada de agente para agente | Uma chamada de um agente para outro agente no mesmo projeto, mostrada como Subagents no filtro de Playground. Para saber mais, consulte Usar comunicação agente-a-agente. |
Nó de Gráfico | Um nó no gráfico de execução do agente que não é um dos outros tipos de etapa, como uma etapa de roteamento ou de fluxo de controle. |
Revisão humana | Uma pausa na execução enquanto a execução aguarda que uma pessoa aprove ou rejeite uma ação. Para saber mais,consulte Execução do agente humano-in-the-loop. |
Observação
Uma etapa Human review de longa duração não é um problema de desempenho. O agente não está fazendo nenhum trabalho enquanto espera por uma decisão.
Pré-requisitos e acesso
Você pode visualizar os rastreamentos de um projeto com qualquer role de leitura no nível da organização ou do projeto. Essas funções incluem Administrador da organização, membro da organização, proprietário do projeto, membro do projeto e agente desenvolvedor.
Com a permissão da sua organização, os engenheiros de suporte do MongoDB também podem visualizar seus rastreamentos por meio de um Visualizador de Dados somente leitura. Um administrador de organização concede esse acesso por um tempo limitado. Enquanto a concessão estiver ativa, o Visualizador de Dados mostra as mesmas sessões, execuções e etapas que a página Traços. Um banner no Visualizador de Dados informa que a visualização é somente leitura e identifica a expiração da concessão. As cargas úteis da etapa, como entradas e saídas de chamadas de ferramentas, são eliminadas nesta visualização. Para saber como conceder esse acesso, consulte Conceder acesso de suporte.
Ver rastreamentos no playground
O Atlas Agent Engine mostra uma bandeja Traces ao lado do painel de bate-papo do Playground. A bandeja é atualizada ao vivo à medida que a execução atual é executada. Ative o botão Timeline para mostrar as barras de duração das etapas ao lado do bate-papo.
O resumo da execução na parte superior da bandeja mostra o prompt da execução e, se a execução foi interrompida ou bloqueada, um selo de status.
Abaixo do prompt, uma linha de resumo relata a duração total da execução, o tempo até o primeiro evento e uma contagem de etapas por tipo, como "2 ferramentas". O tempo para o primeiro evento é o atraso antes da primeira etapa visível do agente. Isso é separado da duração total da execução, de modo que uma execução pode ser lenta para começar sem ser lenta para concluir, ou o inverso.
Cada etapa da execução aparece na linha do tempo com um ícone, um rótulo e uma contagem de tokens, uma duração ou ambos, dependendo do tipo. Selecione uma etapa para ver seus detalhes: uma chamada de modelo mostra suas contagens de solicitação, conclusão e total de tokens, enquanto uma chamada de ferramenta mostra sua entrada e saída. Filtre a lista por categoria, como LLM ou Tools, para isolar um tipo de etapa quando uma execução tiver muitas etapas.
Para interromper uma execução em andamento, use o controle de parada na barra de entrada do chat. Para saber mais, consulte Interromper uma corrida no Playground.
Exibir rastreamentos na página de rastreamento
A página Traços abrange todas as sessões do projeto em todos os espaços de trabalho. Use-o para encontrar a sessão de um usuário final específico ou uma invocação direta.
Encontrar uma sessão
A lista de sessões mostra as seguintes colunas:
coluna | Descrição |
|---|---|
Sessão | O título da sessão, retirado da primeira mensagem, e sua contagem de execuções. |
ID da sessão | O identificador exclusivo da sessão. Copie isso para fazer a referência cruzada de uma sessão com o filtro |
duração | Tempo ativo total em todas as execuções da sessão, excluindo o tempo ocioso entre as execuções. |
Tokens | Total de tokens consumidos em todas as execuções da sessão. Este é um limite inferior: ele não conta algum uso de token, como a extração de memória. |
Espaço de trabalho | O agente implementado que produziu a sessão. |
Última atividade | Quando a sessão foi atualizada pela última vez. |
Última execução | O status da execução mais recente da sessão. |
Leia a Linha do tempo de execuções
Abrir uma sessão mostra suas execuções como uma linha do tempo compartilhada. Três cartões de resumo na parte superior total da duração, dos tokens e da atividade de memória da sessão (recalls e salvamentos) em cada execução mostrada. Os tokens e os totais de memória são limites inferiores: eles refletem apenas as execuções e etapas que foram concluídas, portanto podem ser subcontados enquanto uma execução ainda está ativa.
Um menu suspenso de classificação e um botão Elapsed time/Tokens alteram a leitura da linha do tempo. O menu suspenso controla qual execução você vê primeiro. A alternância controla o que o comprimento de uma barra mede: duração na visualização Elapsed time e contagem de tokens na visualização Tokens.
Na visualização Elapsed time, o eixo horizontal representa o tempo decorrido desde o início da execução. A barra de uma etapa é posicionada e dimensionada por quando começa e por quanto tempo funciona. Isso permite que você determine quais etapas são executadas sequencialmente e quais se sobrepõem. Como todas as execuções da sessão compartilham o mesmo eixo, você também pode comparar execuções separadas entre si rapidamente. Na visualização Tokens, não há eixo de tempo: as barras são alinhadas à esquerda e dimensionadas proporcionalmente à contagem de token de cada etapa.
A imagem a seguir mostra a linha do tempo de execuções de uma sessão enquanto uma execução está em andamento:
O cabeçalho de cada execução informa o tempo de início relativo, a duração total, o tempo até o primeiro evento, o total de tokens e a etapa mais lenta que ele contém, no formato slowest: <step> (<duration>).
Uma execução em andamento mostra um controle de parada. A interrupção de uma execução altera seu status para Interrompendo... e, em seguida, para Interrompido quando for interrompida. O cancelamento nem sempre é instantâneo porque uma etapa pode precisar terminar sua operação atual primeiro. A etapa interrompida mostra um selo Stopped correspondente, identificando exatamente qual etapa a parada interrompeu.
Cada linha de etapa mostra um ícone e um nome. Dependendo do estado da etapa, ela mostra uma duração ou um rótulo de estado. Uma etapa concluída mostra sua duração, e uma chamada LLM também mostra sua contagem de token. Uma etapa ainda em andamento mostra Em execução...
Selecione uma etapa para abrir seus detalhes em um painel lateral, incluindo tipo, status, duração e quem invocou a execução. O painel também mostra as entradas e saídas da etapa, como as mensagens enviadas e retornadas de uma chamada de modelo.
Encontre a causa de uma execução lenta
Quando uma execução demorar mais do que o esperado, use os seguintes sinais para encontrar a etapa específica responsável:
Comece com a chamada de etapa mais lenta do cabeçalho da execução, no formato
slowest: <step> (<duration>). Selecione essa etapa para inspecionar seus detalhes diretamente.Se a execução foi lenta para começar e não lenta para terminar, verifique o tempo para o primeiro evento em vez da etapa mais lenta. Um valor consistentemente alto em todas as execuções significa que o atraso ocorre antes mesmo do início de qualquer etapa que você possa inspecionar.
Se a contagem total de tokens de uma execução for alta, mas nenhuma etapa se destacar na visualização Elapsed time, alterne para a visualização Tokens. Uma etapa pode ser um gargalo simbólico sem ser a etapa mais lenta em termos de tempo de relógio de parede.
Se a duração total de uma execução for alta, mas todas as suas etapas parecerem rápidas, verifique se a execução esperou por uma revisão humana. Em caso afirmativo, o cabeçalho de execução substitui os campos de duração e tempo para o primeiro evento por uma divisão
active/review, como "2min 3s ativo - 1h 30minutos de revisão". O alto tempo de revisão significa que a execução foi pausada na fila de revisão do ser humano no loop, e não está realmente executando lentamente. Para saber mais, consulte Execução do agente humano-in-the-loop.
Próximos passos
Para saber mais sobre como monitorar e invocar seu agente, consulte os seguintes guias: