Glossário
78 termos de “Observabilidade e depuração: enxergando cada passo do seu agente”. Passe o cursor sobre a primeira ocorrência na lição para ver a definição.
| Termo | Definição | Fonte |
|---|---|---|
| não determinístico | Propriedade de um sistema em que entradas idênticas podem produzir respostas diferentes; agentes são desse tipo de sistema, o que quebra a intuição tradicional de depuração do tipo 'reproduza e coloque um breakpoint'. | Writing effective tools for agents — with agents — Anthropic Engineering |
| divergência de trajetória | Quando uma etapa falha e faz o agente explorar uma trajetória inteiramente diferente, com todos os turnos seguintes crescendo sobre o galho errado, levando a resultados imprevisíveis. | How we built our multi-agent research system — Anthropic Engineering |
| acúmulo entre turnos | Agentes têm estado e os erros se acumulam; agentes podem rodar por longos períodos mantendo estado ao longo de muitas chamadas de ferramenta, então os erros se acumulam turno a turno. | How we built our multi-agent research system — Anthropic Engineering |
| comportamento emergente | Comportamentos em sistemas multiagentes que surgem sem programação específica — por exemplo, pequenas mudanças no agente líder alterando de forma imprevisível o comportamento dos subagentes. | How we built our multi-agent research system — Anthropic Engineering |
| trilha de avaliação | A pontuação de estado final, os validadores e os conjuntos de avaliação construídos no curso anterior — respondem apenas 'quebrou?', não 'por quê'. | How we built our multi-agent research system — Anthropic Engineering |
| think like your agents | Construir simulações usando exatamente os mesmos prompts e ferramentas do seu sistema e então observar os agentes trabalhando etapa por etapa. | How we built our multi-agent research system — Anthropic Engineering |
| camadas de abstração | As camadas intermediárias que os frameworks acrescentam para simplificar chamar LLMs, definir ferramentas e encadear chamadas — elas obscurecem os prompts e as respostas subjacentes. | Building Effective AI Agents — Anthropic Engineering |
| sandbox (ambiente isolado) | Um ambiente isolado onde agentes capazes de tomar ações passam por testes extensivos, usado com as devidas proteções. | Building Effective AI Agents — Anthropic Engineering |
| fronteira de ferramenta | A superfície de contrato entre sistemas determinísticos e agentes não determinísticos; a única posição que deixa rastro nos registros. | Building Effective AI Agents — Anthropic Engineering |
| ground truth | O feedback real que o agente obtém do ambiente a cada etapa durante a execução, como resultados de chamadas de ferramenta e de execução de código. | Building Effective AI Agents — Anthropic Engineering |
| transcrição bruta | O nome da ferramenta e os parâmetros completos de cada chamada de ferramenta de uma execução, mais o valor de retorno completo ou o erro de cada resposta de ferramenta — evidência de primeira mão. | Writing effective tools for agents — with agents — Anthropic Engineering |
| autorrelato | O que o agente escreve sobre si mesmo: resumos de fechamento, trechos de raciocínio, autoavaliações depois da execução de uma ferramenta — material secundário. | Writing effective tools for agents — with agents — Anthropic Engineering |
| cadeia de raciocínio (CoT) | O processo de raciocínio que o modelo escreve antes de dar uma resposta, abreviado como CoT. | Writing effective tools for agents — with agents — Anthropic Engineering |
| quatro perguntas | Um checklist de leitura de transcrições: chamou a ferramenta errada, chamou a ferramenta certa com parâmetros errados, chamou ferramentas de menos, processou a resposta da ferramenta incorretamente. | Writing effective tools for agents — with agents — Anthropic Engineering |
| bloco tool_use | Um bloco de conteúdo em que o modelo nomeia qual ferramenta chamar, contendo o nome da ferramenta e um objeto completo de parâmetros que o modelo gerou. | Writing effective tools for agents — with agents — Anthropic Engineering |
| bloco tool_result | O bloco que o harness devolve depois de efetivamente rodar a ferramenta — em caso de sucesso, o valor de retorno completo; em caso de falha, o conteúdo do erro mais uma flag de erro. | Writing effective tools for agents — with agents — Anthropic Engineering |
| is_error | Uma flag de erro nos resultados de ferramenta, usada para distinguir 'a ferramenta retornou conteúdo' de 'a ferramenta lançou um erro'. | Writing effective tools for agents — with agents — Anthropic Engineering |
| fazendas de conteúdo | Fontes otimizadas para SEO, bem ranqueadas, mas de baixa autoridade; testes manuais mostraram que os primeiros agentes as preferiam de forma consistente a PDFs acadêmicos e blogs pessoais. | How we built our multi-agent research system — Anthropic Engineering |
| transcrição | Mensagens de conversa persistidas em disco, como os registros de sessão em JSONL que o Claude Code grava no disco. | Monitoring — Claude Code Official Documentation |
| logs estruturados | Transformar cada etapa em registros JSON com campos, para que a evidência possa não só ser lida por humanos como também ser filtrada, agregada e analisada por distribuição. | Writing effective tools for agents — with agents — Anthropic Engineering |
| logs em prosa | Escrita de log que codifica a estrutura dentro da linguagem natural; lê-se bem, mas só pode ser decodificada por humanos. | Writing effective tools for agents — with agents — Anthropic Engineering |
| JSON Lines | Um arquivo em que cada linha é um objeto JSON completo, sem vírgulas entre linhas e sem um array externo envolvendo tudo — comumente escrito JSONL. | Writing effective tools for agents — with agents — Anthropic Engineering |
| session_id | Um identificador de uma sessão de conversa, constante ao longo de vários turnos, usado para responder 'quanto esta sessão custou no total, ela trocou de modo de permissão'. | Monitoring — Claude Code Official Documentation |
| prompt_id | Um identificador de um prompt do usuário; todas as requisições ao modelo e chamadas de ferramenta que ele dispara compartilham este valor. | Monitoring — Claude Code Official Documentation |
| ID de correlação | Um número de ID dado a 'um evento disparador', e todo evento que esse disparador gerou o copia — não precisa de infraestrutura nenhuma, é só um campo. | Monitoring — Claude Code Official Documentation |
| duration_ms | Os milissegundos que uma etapa levou, usados para achar gargalos de desempenho e também para checar 'está travado?'. | Writing effective tools for agents — with agents — Anthropic Engineering |
| tool_input | Os parâmetros enviados à ferramenta, fornecidos diretamente nos payloads de PostToolUse como metade do registro completo da chamada. | Hooks reference — Claude Code Official Documentation |
| tool_response | O resultado devolvido pela ferramenta, parte do registro completo de ida e volta que tool_input e tool_response formam juntos em um único disparo. | Hooks reference — Claude Code Official Documentation |
| error | O campo error dos registros, presente apenas quando falha; o primeiro campo a filtrar na hora de localizar. | Writing effective tools for agents — with agents — Anthropic Engineering |
| métricas | Um conjunto de números: tempo de execução de chamadas de ferramenta individuais e de tarefas inteiras, contagem total de chamadas de ferramenta, consumo total de tokens, erros de ferramenta. | Writing effective tools for agents — with agents — Anthropic Engineering |
| chamadas redundantes | Muitas chamadas de ferramenta repetidas, que muitas vezes sugerem que os parâmetros de tamanho de página ou de limite de tokens precisam de ajuste. | Writing effective tools for agents — with agents — Anthropic Engineering |
| erros de parâmetro inválido | Muitos erros por parâmetros inválidos, que apontam para descrições de ferramenta que precisam de escrita mais clara ou de exemplos melhores. | Writing effective tools for agents — with agents — Anthropic Engineering |
| taxa de erro | Uma métrica de proporção, contagem de erros dividida pela contagem de chamadas, usada no lugar de números absolutos para enxergar a saúde. | Writing effective tools for agents — with agents — Anthropic Engineering |
| sinal terminal | O evento de erro emitido apenas depois que as retentativas internas desistem por completo, representando 'esta requisição falhou em definitivo'. | Monitoring — Claude Code Official Documentation |
| suspeita de travamento | Um estado em que o último registro de um prompt tem um erro e nenhum registro posterior o segue — em contraste com 'recuperou-se do erro'. | Monitoring — Claude Code Official Documentation |
| limiar | A linha que julga 'quanto conta como anormal'; os materiais de primeira mão não trazem números — nem para orçamento de erro nem para SLO. | Monitoring — Claude Code Official Documentation |
| SIEM | Sistema de Security Information and Event Management; detecção de anomalias, definição de linha de base, correlação entre sessões e alertas são todas responsabilidades do lado dele. | Monitoring — Claude Code Official Documentation |
| trilha de auditoria | Depois de anexar atributos de identidade do usuário final, as decisões de ferramenta, os resultados de ferramenta, as conexões MCP e as mudanças de modo de permissão formam um registro por usuário. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| span | O registro de um pedaço de trabalho com começo e fim: tem um nome, um horário de início, um horário de fim, alguns atributos, e consegue identificar o span pai dele. | Monitoring — Claude Code Official Documentation |
| trace | Uma árvore inteira de spans conectados por relações pai-filho; tudo o que aconteceu em uma requisição completa, do começo ao fim, lido como uma árvore. | Monitoring — Claude Code Official Documentation |
| claude_code.interaction | O nome do span raiz correspondente a cada prompt do usuário nos traces de primeira parte. | Monitoring — Claude Code Official Documentation |
| subagente | Um agente de nível mais baixo despachado pela ferramenta Agent; suas requisições ao modelo e spans de ferramenta se aninham sob o span de ferramenta do agente pai. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| exportador (exporter) | O código dentro do processo responsável por empacotar spans e mandá-los para fora. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| coletor (collector) | A estação de retransmissão ou serviço de backend que recebe os spans; o exportador manda os dados para ele, e você vê a árvore no painel dele. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| falha silenciosa | O comportamento padrão em que, quando o endpoint está inacessível ou o backend rejeita os dados, o agente continua rodando normalmente, a telemetria é descartada e nenhum erro aparece na sua aplicação. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| exportação em lote | O mecanismo de acumular telemetria em lotes e enviá-la em intervalos — por padrão, métricas a cada 60 segundos, traces e logs a cada 5 segundos. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| service.name | Um atributo de recurso que identifica de qual serviço os dados vieram; por padrão, a CLI o reporta como claude-code. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| claude_code.session.count | Uma métrica de contagem emitida assim que uma sessão começa; a sonda mais barata para verificar se a configuração de exportação funcionou. | Monitoring — Claude Code Official Documentation |
| TRACEPARENT | Uma variável de ambiente em formato padronizado que carrega o id do trace e o id do span atual; subprocessos Bash e PowerShell a herdam automaticamente. | Monitoring — Claude Code Official Documentation |
| contexto de trace W3C | Uma string em formato padronizado contendo o id do trace e o id do span atual; quem a recebe sabe onde se pendurar. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| CLAUDE_CODE_ENHANCED_TELEMETRY_BETA | A chave que, quando ligada, faz cada etapa do loop do agente virar um span inspecionável no backend de tracing. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| hooks | Comandos de shell, endpoints HTTP ou prompts de LLM definidos por você que executam automaticamente em pontos específicos do ciclo de vida do Claude Code. | Hooks reference — Claude Code Official Documentation |
| matcher | A regra de casamento que determina quando um hook dispara; omitido ou definido como curinga significa um-hook-registra-tudo. | Hooks reference — Claude Code Official Documentation |
| PreToolUse | Um evento que roda depois que o modelo cria os parâmetros da ferramenta e antes de processar a chamada da ferramenta. | Hooks reference — Claude Code Official Documentation |
| PostToolUse | Um evento que dispara após a execução bem-sucedida da ferramenta; a entrada carrega tanto tool_input quanto tool_response. | Hooks reference — Claude Code Official Documentation |
| SessionStart | Um evento uma-vez-por-sessão; dispara quando uma nova sessão abre e também quando uma sessão existente é retomada. | Hooks reference — Claude Code Official Documentation |
| Stop | Um evento de fim de turno na cadência uma-vez-por-turno; emparelhado com UserPromptSubmit permite calcular a duração de um turno. | Hooks reference — Claude Code Official Documentation |
| payload | O contexto JSON entregue ao seu handler quando um evento dispara e o matcher casa. | Hooks reference — Claude Code Official Documentation |
| OTEL_* | Um conjunto de variáveis de ambiente relacionadas à exportação de telemetria; o Claude Code as remove de todo subprocesso que ele gera, inclusive hooks. | Hooks reference — Claude Code Official Documentation |
| log de depuração | Um arquivo de log que registra quais hooks casaram, seus códigos de saída e a stdout e a stderr completas. | Hooks reference — Claude Code Official Documentation |
| fluxo de cinco etapas | A abordagem de depuração arranjada por este curso: estreitar pelo id do prompt, achar a primeira divergência, reexecutar e observar, martelar repetidamente o mesmo componente, retomar do ponto de falha depois de corrigir. | How we built our multi-agent research system — Anthropic Engineering |
| estreitar | Etapa um: filtrar pelo id do prompt para encolher a faixa de 'o agente quebrou' para 'estes dez e tantos eventos sob este id'. | Monitoring — Claude Code Official Documentation |
| primeira divergência | A etapa em que o comportamento começa a se desviar das expectativas; os absurdos no fim são, em sua maioria, ruído a jusante. | How we built our multi-agent research system — Anthropic Engineering |
| contágio | Etapas depois do ponto de divergência que parecem igualmente absurdas, mas estão só continuando em frente sobre a premissa errada. | How we built our multi-agent research system — Anthropic Engineering |
| reexecutar e observar | Construir simulações usando prompts e ferramentas idênticos, observando etapa por etapa para forçar imediatamente os modos de falha para fora. | How we built our multi-agent research system — Anthropic Engineering |
| cliente stub | Um substituto que não envia requisições de rede, devolvendo em sequência objetos de resposta pré-definidos de um array fixo, tornando o lado do modelo reproduzível. | How we built our multi-agent research system — Anthropic Engineering |
| fila de respostas | O array de que o cliente stub puxa em sequência, cada elemento carregando stop_reason, blocos de conteúdo e usage completos. | How we built our multi-agent research system — Anthropic Engineering |
| agente de teste de ferramentas | Um agente que, recebendo uma ferramenta defeituosa, tenta usá-la repetidamente e então reescreve a descrição da ferramenta para evitar as falhas; testar dezenas de vezes encontra nuances e bugs importantes. | How we built our multi-agent research system — Anthropic Engineering |
| trace_id | Um id por execução, costurando registros espalhados no mesmo fluxo de volta à mesma execução. | Monitoring — Claude Code Official Documentation |
| span_id | O id do próprio registro; outros registros apontam para ele para declarar 'estou sob você'. | Monitoring — Claude Code Official Documentation |
| parent_id | Um campo que aponta para o id do registro pai; as árvores são reconstruídas a partir do JSONL em disco usando isto. | Monitoring — Claude Code Official Documentation |
| MAX_ROUNDS | Uma comporta dura sobre a contagem de iterações do loop; ultrapassá-la lança um erro, grava uma interrupção e sai com código não-zero. | Building Effective AI Agents — Anthropic Engineering |
| stop_reason | O campo nas respostas do modelo que faz o loop do harness continuar ou terminar. | Building Effective AI Agents — Anthropic Engineering |
| HEAD_CHARS | A linha que define quantos caracteres, no máximo, cada trecho de conteúdo nos logs mantém; defina 0 e nenhuma palavra toca o disco. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| shape | Um campo nos registros que descreve o tipo e a escala de um valor: é string ou objeto, qual o comprimento, quais as chaves. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| resumo de métricas | Uma linha que imprime o total de rodadas, a contagem de chamadas de ferramenta, os tokens, a contagem de erros e a duração total — uma das três peças do kit de observabilidade. | Writing effective tools for agents — with agents — Anthropic Engineering |
| compare-runs.mjs | Um script de comparação que lê dois logs de execução, compara lado a lado por tipo de registro e nome de ferramenta, e sai com código não-zero se houver erros. | Writing effective tools for agents — with agents — Anthropic Engineering |
| comporta | Um julgamento ligado a códigos de saída; um valor não-zero pode ser capturado por CI, cron ou qualquer lugar do tipo 'não-zero significa alerta'. | Writing effective tools for agents — with agents — Anthropic Engineering |