CH 29 · Observabilidade e Gestão de Contexto
Objetivo do Capítulo
Depois que o Agent está de pé e rodando, você eventualmente vai se deparar com estas perguntas: por que ele tomou aquela decisão agora? Quantos tokens essa rodada custou? Sessões longas ficam mais lentas e mais caras, o que fazer?
A abordagem do dsh é expor cada passo do Agent para você — o que ele viu, o que pensou, o que fez, quanto custou, tudo rastreável. O CH 04 cobriu o básico da interface Trajectory, o CH 16 mencionou taxa de acerto de cache; este capítulo deixa observabilidade e desempenho totalmente claros: como ler a Trajectory, onde os logs de sessão são armazenados, como ler métricas de Token e cache, como gerenciar contexto. Depois de dominar isso, você pode avançar de "usável" para "usar de forma eficiente e estável".
Trajectory: O Relatório Completo de Execução do Agent
O Que É a Trajectory
Ferramentas comuns de Agent mostram o "histórico de chat" — o que você disse, o que ele respondeu. Mas o que aconteceu entre eles? Qual arquivo ele leu, que ferramenta ele chamou, o que a ferramenta retornou, por que decidiu chamar essa ferramenta e não aquela — tudo isso é invisível na visão de chat.
A Trajectory resolve esse problema: ela registra o processo de execução completo do Agent em uma linha do tempo, é "a visão do modelo do relatório de execução", não "a visão do usuário do histórico de chat".
O que é registrado:
| Categoria | O que registra |
|---|---|
| System prompt | O system prompt completo enviado ao modelo em cada requisição |
| Entrada do usuário | Sua mensagem, contexto injetado |
| Requisição ao modelo | Conteúdo completo enviado ao modelo, conteúdo completo retornado pelo modelo |
| Chamada de ferramenta | Qual ferramenta, quais parâmetros, qual foi o resultado do retorno |
| Escalonamento de subagent | Quantos subagents foram iniciados, o que cada um fez, como os resultados foram agregados |
| Interação de aprovação | Quais operações pediram aprovação, se você permitiu ou negou |
Tudo isso é escrito em um único log de sessão append-only — apenas adicionado, nunca modificado, garantindo completude de registro e auditabilidade.
Onde Visualizar a Trajectory
Na interface de sessão da Web UI, há uma aba Trajectory no topo, clique nela.
A interface se parece com o painel network das ferramentas de desenvolvedor do navegador:
- Linha do tempo no topo: desenhada da esquerda para a direita pelos horários reais de início e fim, cada rodada de requisições ocupa um segmento
- Lista de eventos à esquerda: uma linha por registro, agrupada por turn, cada uma marcada com o tipo (LLM / TOOL / SUBAGENT / APPROVAL)
- Painel de detalhes à direita: clique em um registro para expandir e ver o conteúdo completo — Schema / Payload / Result da chamada de ferramenta, o prompt e resposta completos da requisição do modelo
Para Que a Trajectory Pode Ser Usada
- Solução de problemas: o Agent fez algo inesperado? Volte na Trajectory e veja o que ele recebeu na hora, por que tomou aquela decisão. 90% dos "AI agindo estranho" podem ser encontrados na Trajectory — geralmente ele leu um arquivo que você não percebeu, ou a ferramenta retornou um valor anormal.
- Revisão: a tarefa foi bem ou mal, volte na Trajectory e veja qual passo foi o ponto de virada chave, qual passo desperdiçou tokens. Da próxima vez você pode otimizar o prompt ou fluxo.
- Reproduzir experimentos: ao fazer pesquisa com Agent, a Trajectory é o registro experimental completo — mesma entrada, mesma ferramenta, mesma versão do modelo, pode reproduzir o mesmo resultado.
- Auditoria: quando a equipe compartilha, a Trajectory pode responder "quando ele mudou esse arquivo, por quê" — mais granular que git log, porque registra até "por que mudou".
Log de Sessão: Onde Mora, Como Usar
Os dados da Trajectory no final das contas vão para arquivos locais, não só na memória.
Local de Armazenamento
Todas as sessões são armazenadas no diretório ~/.dsh/sessions/ (no Windows: C:\Users\<seu-usuário>\.dsh\sessions\), organizado por diretório de workspace.
O nome do diretório de workspace é a forma escapada do caminho — envolto com --, separadores de caminho substituídos por -, caracteres especiais codificados em URL. Por exemplo, workspace E:\software-workspace\DeepSeek harness demo corresponde ao nome de diretório --E-software-workspace-DeepSeek~0020harness~0020demo--.
Cada sessão é um subdiretório, nomeado no formato session-<uuid> (criado pela Web UI) ou <uuid> puro (rodado por headless), contendo um arquivo session.jsonl.zstd (JSONL comprimido com zstd, um evento por linha).
~/.dsh/sessions/
├── --E-software-workspace-DeepSeek~0020harness~0020demo--/
│ ├── session-05da13b1-c7bf-4f42-843b-.../
│ │ └── session.jsonl.zstd
│ ├── session-06451c43-35fb-4338-bc87-.../
│ │ └── session.jsonl.zstd
│ └── 37e884fa-7c73-40fa-81fc-.../ ← sessão rodada por headless
│ └── session.jsonl.zstd
└── --E-software-workspace-doubaowork-DeepSeekHarnessGuide--/
└── session-f417b4dd-3c8f-4098-85.../
└── session.jsonl.zstdTrês Capacidades de uma Sessão
Com base nesse log, o dsh suporta três operações:
- Resume: feche o dsh e reabra, a sessão anterior ainda está lá, você pode continuar conversando — porque o log é persistente, não in-memory.
- Fork: clique no ícone de fork abaixo de uma mensagem histórica, comece um novo caminho a partir dessa mensagem, sem tocar na sessão original. Por exemplo, se o Agent foi até o passo 5 e você acha que a direção está errada, pode fazer fork para o passo 4 e tentar um prompt diferente, a sessão original é preservada. A nova sessão vinda do fork terá um sufixo
(1),(2)no nome, distinguindo da original. - Replay: reproduza o stream de eventos de uma sessão, veja a entrada e saída de cada passo. Adequado para depurar plugins ou reproduzir problemas.
Métricas de Desempenho: Token, Cache, Contexto
O dsh exibe várias métricas chave de desempenho em tempo real na interface; aprenda a ler essas e você pode controlar custo e velocidade.
Uso de Tokens
Depois de cada rodada de requisições, a parte de baixo da interface exibe as estatísticas de Token desta rodada:
- Input Token: total de tokens enviados ao modelo (incluindo system prompt, histórico de conversa, resultados de ferramentas)
- Output Token: tokens gerados pelo modelo
- Cache hit Token: porção do input que acertou o cache de contexto do DeepSeek
O uso cumulativo está nas estatísticas da sessão — quantos tokens a sessão toda usou, quanto custou.
Taxa de Ocupação de Contexto
Há um anel à direita da caixa de entrada, mostrando o percentual atual de ocupação de contexto. Esse é um design único do dsh — deixando você ver em tempo real "quanto espaço de contexto resta".
Contexto é finito (diferentes tamanhos de janela do modelo, geralmente 128K para cima). Quando a ocupação se aproxima de 100%, o dsh auto-comprime o contexto — resumindo o histórico antigo em um digest, substituindo a conversa multi-turno original, garantindo que a conversa possa continuar sem dar erro por exceder a janela.
A auto-compressão é um mecanismo de fallback. Então uma abordagem mais recomendada é: no momento certo, acione manualmente a compressão você mesmo — digite o comando /compact na caixa de entrada, e o dsh vai comprimir imediatamente a conversa atual em um resumo, substituindo o histórico multi-turno original. Comprimindo no seu ritmo, informação chave não se perde.
Quando a ocupação estiver quase cheia, duas escolhas: digite /compact para comprimir manualmente, ou simplesmente abra uma nova sessão.
Gestão de Contexto: Como Evitar que Sessões Longas Quebrem
Sessões de Agent têm um problema natural: quanto mais você conversa, mais tokens gasta, e o modelo "lembra" menos do início. O dsh dá várias ferramentas para gerenciar isso.
Quando Abrir uma Nova Sessão
Nem todas as tarefas devem ser feitas em uma sessão. As seguintes situações sugerem abrir uma nova sessão:
- Tipo de tarefa mudou: agora há pouco estava escrevendo código, agora precisa fazer um PPT — abra uma nova sessão, não deixe o contexto do código poluir a tarefa do PPT
- Workspace mudou: trocou o diretório do projeto — abra uma nova sessão, as sessões do dsh estão vinculadas ao workspace
- Ocupação de contexto acima de 70%: continuando a conversa o modelo vai soltar conteúdo do início, e as reações ficam lentas — às vezes você sente de repente que o modelo ficou mais burro, é por isso. Abra uma nova sessão, ou primeiro
/compactpara comprimir
Alguns Hábitos de Controle de Custo
- Não faça tudo em uma sessão — divida sessões por tarefa, cada sessão tem contexto curto, alta taxa de acerto de cache, baixo custo
- Não leia repetidamente arquivos grandes — o Agent lendo um arquivo de 1000 linhas custa tokens cada vez. Depois de ler uma vez, faça ele escrever a informação chave em um arquivo de resumo, depois é só ler o resumo depois
- Use o modelo certo — tarefas simples com flash, raciocínio complexo com pro, tarefas visuais com vision — não use o mais caro para tudo
- Verifique o uso cumulativo regularmente — as estatísticas da sessão mostram total de tokens e custo estimado, não espere até o fim do mês para ter um susto
O Que Você Aprendeu Neste Capítulo
Você passa se conseguir completar os itens abaixo:
- [ ] Saber o que é a Trajectory, onde visualizá-la, qual conteúdo é registrado na Trajectory
- [ ] Saber que os logs de sessão são armazenados em
~/.dsh/sessions/, suportando resume, fork, replay - [ ] Conseguir entender o que são input / output / cache hit nas estatísticas de Token
- [ ] Saber onde a taxa de ocupação de contexto é mostrada, o que fazer quando está quase cheia
- [ ] Saber como usar o comando
/compact, e quando comprimir manualmente - [ ] Conseguir citar pelo menos 3 hábitos de controle de custo