O AgentsView pode reunir logs de sessões de agentes de programação de várias ferramentas em um arquivo local pesquisável. Este guia é para uma liderança de engenharia que precisa encontrar uma tarefa conhecida, examinar os campos de uso que o agente realmente registrou e identificar a fonte de qualquer valor de custo.

Este passo a passo se baseia na documentação da versão v0.45.0 do AgentsView, de 9 de outubro de 2026, e nos guias atuais de início rápido e uso de tokens, consultados em 17 de outubro. O BIG CHANGE não instalou o AgentsView, não importou uma transcrição nem testou estes passos. Confira a versão instalada, pois a documentação e as listas de versões podem mudar.

Antes de começar

Você precisa de uma sessão concluída de um agente de programação que tenha autorização para ler, uma frase característica ou o ID de sessão dessa tarefa e permissão para ler o diretório local dos logs. O Quick Start lista downloads para desktop de macOS, Windows e Linux, com pacotes wheel da CLI para Linux x86_64 e aarch64, macOS x86_64 e arm64 e Windows x86_64 e arm64. O aplicativo de desktop já vem empacotado; compilar a partir do código-fonte exige separadamente Go, Node e CGO. Segundo o guia de início rápido, o arquivamento local básico não exige uma conta em serviço hospedado nem uma chave de API.

Os logs das sessões podem conter prompts, código-fonte, entradas de ferramentas e segredos. Escolha apenas diretórios que sua equipe permita examinar. Decida quais provedores e diretórios raiz o arquivo pode incorporar antes da primeira inicialização: executar apenas agentsview serve descobre e sincroniza imediatamente as fontes compatíveis padrão. Mantenha a interface web no endereço de loopback documentado para este exercício. Não ative sincronização hospedada de dados brutos, envios para PostgreSQL ou ClickHouse, publicação em Gist, insights gerados ou um endpoint hospedado de embeddings só para responder a esta pergunta. A busca semântica é opcional; a busca comum de texto completo funciona com o índice local.

1. Instale e identifique o executável

Escolha um método no guia de instalação. Para uma CLI independente, a instalação permanente com Python documentada é:

Terminal
pip install agentsview
agentsview --version

O guia também oferece uvx agentsview para executar sem uma instalação permanente, instaladores por plataforma e pacotes de desktop. No macOS, o cask do Homebrew cria o vínculo com a CLI incluída no aplicativo; um aplicativo instalado a partir de um DMG pode exigir que o diretório da CLI seja adicionado ao PATH. Confirme qual executável seu shell encontra antes de confiar na versão informada. O GitHub identifica v0.45.0 como a versão de 9 de outubro, mas use seu próprio resultado de --version ao interpretar as telas e o esquema do relatório.

2. Restrinja as fontes antes da primeira sincronização

Para uma instalação de CLI ou desktop no host, prepare um diretório de dados novo e seu config.toml antes de iniciar o AgentsView. O guia de configuração documenta disabled_agents para excluir provedores do sistema de arquivos local e [agents.<id>].dirs para substituir os diretórios raiz padrão de um provedor. Liste todos os IDs dos outros provedores da tabela Session Discovery desse guia em disabled_agents e defina o dirs do único provedor autorizado como o diretório raiz aprovado. Por exemplo, [agents.codex] com dirs = ["/approved/codex/sessions"] substitui os diretórios padrão do Codex; ajuste o caminho ao seu sistema. Se a lista de exclusão não estiver completa, ainda não inicie o daemon do host. Uma única substituição de CODEX_SESSIONS_DIR ou CLAUDE_PROJECTS_DIR altera a raiz desse provedor, mas deixa os outros habilitados para sua própria descoberta padrão.

Use um AGENTSVIEW_DATA_DIR novo para esta auditoria se um arquivo existente já puder conter sessões não relacionadas. O guia de configuração diz que as sessões já arquivadas de provedores desativados continuam disponíveis, portanto mudar a configuração não limpa um arquivo antigo. Também diz que disabled_agents abrange descoberta e monitoramento locais, não importações ou exportações remotas; deixe hosts remotos e destinos de exportação sem configuração nesta tarefa local.

Um contêiner isolado é a alternativa quando não for viável manter uma lista de exclusão de todos os outros provedores. O exemplo de Docker no Quick Start publica a interface somente em 127.0.0.1, monta uma fonte de agente como somente leitura e usa um volume de dados separado. Monte apenas a raiz da fonte autorizada e defina a variável de diretório correspondente dentro de um contêiner novo; omita as outras montagens do exemplo de Compose do projeto. Um contêiner só vê os diretórios de sessões do host explicitamente montados. As imagens Docker publicadas abrangem Linux amd64 e arm64; esse caminho exige uma instalação funcional do Docker.

3. Crie o arquivo local

Para a CLI do host com escopo restrito, inicie o servidor em primeiro plano documentado:

Terminal
agentsview serve

Depois de aplicar e conferir o escopo das fontes na etapa 2, isso inicializa ~/.agentsview/sessions.db ou o diretório de dados escolhido, descobre logs dos agentes habilitados, sincroniza, monitora alterações e abre http://127.0.0.1:8080. Deixe esse terminal aberto. Se preferir um processo em segundo plano, use agentsview daemon start e agentsview daemon status; o aplicativo de desktop gerencia seu próprio backend. Um servidor compatível que já esteja em execução pode apenas informar sua URL; por isso, confira se há um daemon em execução antes de supor que a nova configuração controlou a ingestão.

Se você escolheu o contêiner isolado, inicie-o com o comando Docker documentado depois de conferir sua única montagem de fonte somente leitura e seu volume de dados novo. Use a interface de loopback e execute os relatórios posteriores da CLI do agentsview dentro desse contêiner, para que leiam o mesmo arquivo. Não execute um serve no host sem restrição de escopo ao mesmo tempo.

Confira se a fonte da tarefa conhecida aparece e os provedores indesejados não aparecem. Se a sessão estiver ausente, examine o caminho aprovado, a configuração do provedor e o estado da sincronização antes de concluir que não existe sessão. Execute agentsview sync quando precisar incorporar arquivos recém-alterados antes de um relatório; o servidor também monitora mudanças. Confira novamente o escopo configurado antes de qualquer nova sincronização completa.

4. Encontre a tarefa e verifique a transcrição

Na interface web, use Ctrl/Cmd+K para buscar uma frase literal característica da tarefa conhecida. Restrinja a lista por projeto, agente ou data, abra um candidato e confira suas mensagens e chamadas de ferramentas. Se já tiver o ID completo da sessão ou UUID, Ctrl/Cmd+G a abre diretamente. Esses controles estão documentados no Quick Start. Registre o agente, o ID de sessão e a data para relacionar o resultado de uso à conversa correta.

Se a busca literal não encontrar a tarefa, tente uma frase mais curta e confirme se o agente de origem gravou uma transcrição local em um diretório que o AgentsView consiga ler. Uma tarefa presente apenas em um serviço remoto, formato incompatível ou diretório fora das raízes configuradas não pode ser recuperada com mais buscas. Não ative indexação semântica ou upload de transcrições como solução rotineira para uma fonte local ausente.

5. Examine os campos de uso da sessão

Abra a visualização de uso da sessão encontrada e identifique os campos registrados de modelo, entrada, saída, criação de cache e leitura de cache que estiverem presentes. O guia de uso de tokens classifica o relatório de custos como experimental e ainda em amadurecimento. O AgentsView incorpora metadados de modelo e tokens dos logs de origem e mantém o uso bruto de tokens nas linhas das mensagens. Usa custos explícitos informados pela fonte quando disponíveis; caso contrário, calcula um custo a partir dos tokens utilizáveis e das tarifas do modelo. Sua indicação de origem em JSON os chama de reported, computed ou mixed.

Se quiser guardar um registro legível por máquina daquela única sessão, o exemplo de CLI do projeto usa agentsview session usage SESSION_ID --format json. Substitua SESSION_ID pelo ID que você verificou na transcrição e guarde o JSON junto à anotação da tarefa. Confira o modelo informado, as categorias de tokens e a fonte do custo nessa saída antes de citar qualquer total.

Trate um campo vazio ou modelo ausente como desconhecido. O AgentsView não consegue reconstruir uso que o agente nunca registrou. Suas notas de versão dizem que a ingestão de Junie CLI exclui conversas e chamadas de ferramentas que só existem na IDE, enquanto a alternativa de texto simples do Antigravity contém a transcrição sem uso de tokens nem custo. São exemplos concretos de por que uma sessão pesquisável não precisa ter um valor completo de gasto. Um valor informado pela fonte também pode descrever o total da sessão, enquanto as alocações por modelo continuam sendo estimativas.

6. Delimite o relatório diário

Use os filtros de data, projeto e agente da página Usage para examinar o dia da sessão. A página também oferece a tabela Top Sessions by Cost, com links para transcrições individuais. Para um relatório auditável no terminal, substitua a data local e o nome do agente da sessão em:

Terminal
agentsview usage daily --since YYYY-MM-DD --until YYYY-MM-DD --agent codex --breakdown

A tabela diária separa entrada sem cache, saída, criação de cache e leituras de cache, com linhas por modelo quando --breakdown está definido. A data é agrupada pelo fuso horário do sistema, a menos que --timezone seja informado. O total de um dia pode incluir outras sessões daquele agente; ele serve para conferir escopo e ordem de grandeza, não é o custo daquela única tarefa. Mantenha o ID de sessão junto ao relatório diário e confira quais linhas realmente pertencem a ela.

Para um relatório sem buscar o catálogo de preços, adicione --offline. Segundo o AgentsView, isso lê o arquivo existente sem sincronizar fontes ou iniciar o daemon e usa seus preços de reserva incorporados. Atualize o arquivo antes se as mudanças recentes da sessão forem importantes; um relatório offline não consegue descobrir logs novos. Os comandos normais de uso podem buscar preços do LiteLLM e do OpenRouter, enquanto o catálogo incorporado envelhece com a versão instalada.

7. Interprete o número e pare o serviço

Rotule cada número conforme sua origem. Computed significa que o AgentsView multiplicou os tokens registrados pelas tarifas selecionadas. Reported significa que a fonte forneceu um custo explícito. Mixed significa que o relatório combina tipos. Mesmo um valor informado pela fonte não prova que uma fatura do provedor para a conta inteira tenha sido conciliada. Compare de forma independente os registros de cobrança ou do plano do provedor relevante, sobretudo quando houver níveis de serviço, descontos ou franquias de assinatura. A documentação do AgentsView diz que não consegue inferir preços Batch, Flex, Priority, regionais ou de cache de uma hora quando o uso armazenado omite esse nível. Alguns tokens do lado das ferramentas não aparecem nas transcrições locais.

A verificação de sucesso é uma transcrição encontrada cujo agente, ID e data correspondam à visualização de uso selecionada, com os campos de modelo e tokens disponíveis registrados e os indisponíveis marcados como desconhecidos. O resultado é um arquivo local pesquisável e uma nota de uso da tarefa ou do dia com escopo definido, não uma fatura. Pare um agentsview serve em primeiro plano com Ctrl+C, ou pare um servidor em segundo plano com agentsview daemon stop. O Quick Start diz que parar o daemon interrompe tanto a interface web quanto o monitoramento das sessões.

A grande mudança

Uma transcrição local oferece um ponto de partida rastreável para a discussão de custos. A liderança de engenharia pode seguir um número até uma tarefa específica registrada e ver se ele veio do agente ou de um catálogo de preços. Quando o log estiver incompleto, o relatório deve preservar essa lacuna.

Fontes e leitura adicional

  • Notas da versão v0.45.0 do AgentsView: mudanças datadas no suporte a agentes, nos cartões Usage, na sincronização e no comportamento dos preços. Uma nota de versão é um registro do fornecedor, não um teste do BIG CHANGE.
  • AgentsView Quick Start: caminhos de instalação compatíveis, comandos de servidor e daemon, configuração de fontes e controles de busca local.
  • Configuração do AgentsView: descoberta de fontes, exclusão de provedores, localização do arquivo e limites desses controles.
  • Uso de tokens e custos do AgentsView: suporte de fontes, relatórios de uso, origem dos preços, modo offline e limitações conhecidas dos relatórios.
  • Repositório do AgentsView: código-fonte e licença MIT; o repositório descreve o arquivo padrão como local.