Glossary
78 terms from “Observability and Debugging: Seeing Every Step Your Agent Takes.” Hover the first occurrence in the lesson for its definition.
| Term | Definition | Source |
|---|---|---|
| non-deterministic | A system property where identical inputs can produce different responses; agents are this kind of system, breaking the traditional 'reproduce and set a breakpoint' debugging intuition. | Writing effective tools for agents — with agents — Anthropic Engineering |
| trajectory divergence | When one step fails and causes the agent to explore an entirely different trajectory, with all subsequent turns growing on the wrong branch, leading to unpredictable outcomes. | How we built our multi-agent research system — Anthropic Engineering |
| cross-turn compounding | Agents are stateful and errors compound; agents can run for long periods maintaining state across many tool calls, so errors accumulate turn by turn. | How we built our multi-agent research system — Anthropic Engineering |
| emergent behavior | Behaviors in multi-agent systems that arise without specific programming—for instance, small changes to the lead agent unpredictably changing subagent behavior. | How we built our multi-agent research system — Anthropic Engineering |
| evaluation track | The terminal-state scoring, validators, and evaluation sets built in the previous course—answers only 'did it break,' not 'why.' | How we built our multi-agent research system — Anthropic Engineering |
| think like your agents | Building simulations using the exact same prompts and tools from your system, then watching agents work step-by-step. | How we built our multi-agent research system — Anthropic Engineering |
| abstraction layers | The middle layers frameworks add to simplify calling LLMs, defining tools, and chaining calls—they obscure underlying prompts and responses. | Building Effective AI Agents — Anthropic Engineering |
| sandbox | An isolated environment where agents that can take action undergo extensive testing, used with appropriate guardrails. | Building Effective AI Agents — Anthropic Engineering |
| tool boundary | The contract surface between deterministic systems and non-deterministic agents; the only position that leaves traces in records. | Building Effective AI Agents — Anthropic Engineering |
| ground truth | The real feedback the agent gains from the environment at each step during execution, such as tool call results and code execution results. | Building Effective AI Agents — Anthropic Engineering |
| raw transcript | The complete tool name and parameters for each tool call in a run, plus the complete return value or error for each tool response—first-hand evidence. | Writing effective tools for agents — with agents — Anthropic Engineering |
| self-report | What the agent writes about itself: wrap-up summaries, reasoning segments, self-assessments after tool execution—secondary material. | Writing effective tools for agents — with agents — Anthropic Engineering |
| chain of thought | The reasoning process the model writes before giving an answer, abbreviated CoT. | Writing effective tools for agents — with agents — Anthropic Engineering |
| four questions | A reading checklist for transcripts: called wrong tool, called right tool but wrong parameters, called too few tools, processed tool response incorrectly. | Writing effective tools for agents — with agents — Anthropic Engineering |
| tool_use | A content block where the model names which tool to call, containing the tool name and a complete parameter object the model generated. | Writing effective tools for agents — with agents — Anthropic Engineering |
| tool_result | The block the harness sends back after actually running the tool—on success the complete return value, on failure the error content plus an error flag. | Writing effective tools for agents — with agents — Anthropic Engineering |
| is_error | An error flag on tool results, used to distinguish 'tool returned content' from 'tool threw an error.' | Writing effective tools for agents — with agents — Anthropic Engineering |
| content farms | SEO-optimized, high-ranking sources with poor authority; manual testing found early agents consistently preferred them over academic PDFs and personal blogs. | How we built our multi-agent research system — Anthropic Engineering |
| transcript | Conversation messages persisted to disk, like Claude Code's JSONL session records written to disk. | Monitoring — Claude Code Official Documentation |
| structured logs | Turning each step into JSON records with fields, so evidence can be not only read by humans but also filtered, aggregated, and analyzed for distributions. | Writing effective tools for agents — with agents — Anthropic Engineering |
| prose logs | Log writing that encodes structure into natural language; reads smoothly but can only be decoded by humans. | Writing effective tools for agents — with agents — Anthropic Engineering |
| JSON Lines | One file where each line is a complete JSON object, no commas between lines and no outer array wrapper—commonly written JSONL. | Writing effective tools for agents — with agents — Anthropic Engineering |
| session_id | An identifier for one conversation session, constant across multiple turns, used to answer 'how much did this session cost total, did it switch permission modes.' | Monitoring — Claude Code Official Documentation |
| prompt_id | An identifier for one user prompt; all model requests and tool calls it triggers share this value. | Monitoring — Claude Code Official Documentation |
| correlation ID | An ID number given to 'one trigger event,' and every event that trigger spawned copies it—no infrastructure needed, just a field. | Monitoring — Claude Code Official Documentation |
| duration_ms | Milliseconds a step took, used to find performance bottlenecks and also to check 'is it stuck.' | Writing effective tools for agents — with agents — Anthropic Engineering |
| tool_input | Parameters sent to the tool, directly provided in PostToolUse payloads as half of the complete call record. | Hooks reference — Claude Code Official Documentation |
| tool_response | The result returned by the tool, part of the complete round-trip record that tool_input and tool_response together form in one trigger. | Hooks reference — Claude Code Official Documentation |
| error | The error field on records, only present when it fails; the first field to filter when locating. | Writing effective tools for agents — with agents — Anthropic Engineering |
| metrics | A set of numbers: runtime for individual tool calls and whole tasks, total tool call count, total token consumption, tool errors. | Writing effective tools for agents — with agents — Anthropic Engineering |
| redundant calls | Lots of repeated tool calls, often suggesting pagination size or token limit parameters need tuning. | Writing effective tools for agents — with agents — Anthropic Engineering |
| invalid-parameter errors | Lots of errors for invalid parameters, pointing to tool descriptions needing clearer writing or better examples. | Writing effective tools for agents — with agents — Anthropic Engineering |
| error rate | A proportion metric of error count divided by call count, used instead of absolute numbers to see health. | Writing effective tools for agents — with agents — Anthropic Engineering |
| terminal signal | The error event emitted only after internal retries completely give up, representing 'this request ultimately failed.' | Monitoring — Claude Code Official Documentation |
| suspected stall | A state where the last record for a prompt has an error and no subsequent records follow—versus 'recovered from error.' | Monitoring — Claude Code Official Documentation |
| threshold | The line that judges 'how much counts as abnormal'; no numbers in first-hand materials—wrong error budget and SLO alike. | Monitoring — Claude Code Official Documentation |
| SIEM | Security Information and Event Management system; anomaly detection, baselining, cross-session correlation, and alerting are all responsibilities on its side. | Monitoring — Claude Code Official Documentation |
| audit trail | After attaching end-user identity attributes, tool decisions, tool results, MCP connections, and permission mode changes form a per-user record. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| span | A record of a piece of work with a beginning and end: has a name, start time, end time, several attributes, and can identify its parent span. | Monitoring — Claude Code Official Documentation |
| trace | An entire tree of spans connected by parent-child relationships; everything that happened in one complete request from start to finish, read as a tree. | Monitoring — Claude Code Official Documentation |
| claude_code.interaction | The root span name corresponding to each user prompt in first-party traces. | Monitoring — Claude Code Official Documentation |
| subagent | A lower-level agent dispatched through the Agent tool; its model requests and tool spans nest under the parent agent's tool span. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| exporter | The code in the process responsible for packaging spans and sending them out. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| collector | The relay station or backend service that receives spans; the exporter sends data to it, you see the tree on its dashboard. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| fail silently | The default behavior where when the endpoint is unreachable or the backend rejects data, the agent runs normally, telemetry is dropped, and no error surfaces in your application. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| batch export | The mechanism of accumulating telemetry into batches and sending them out on intervals—by default metrics every 60 seconds, traces and logs every 5 seconds. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| service.name | A resource attribute identifying which service data came from; the CLI defaults to reporting it as claude-code. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| claude_code.session.count | A counting metric emitted as soon as a session starts; the cheapest probe for verifying export config worked. | Monitoring — Claude Code Official Documentation |
| TRACEPARENT | A standard-format environment variable carrying trace id and current span id; Bash and PowerShell subprocesses automatically inherit it. | Monitoring — Claude Code Official Documentation |
| W3C trace context | A standard-format string containing trace id and current span id; whoever receives it knows where to attach themselves. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| CLAUDE_CODE_ENHANCED_TELEMETRY_BETA | The switch that when turned on makes each step of the agent loop become an inspectable span in the tracing backend. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| hooks | User-defined shell commands, HTTP endpoints, or LLM prompts that execute automatically at specific points in Claude Code's lifecycle. | Hooks reference — Claude Code Official Documentation |
| matcher | The matching rule that determines when a hook fires; omitted or set to wildcard means one-hook-records-all. | Hooks reference — Claude Code Official Documentation |
| PreToolUse | An event that runs after the model creates tool parameters and before processing the tool call. | Hooks reference — Claude Code Official Documentation |
| PostToolUse | An event that fires after successful tool execution; the input carries both tool_input and tool_response. | Hooks reference — Claude Code Official Documentation |
| SessionStart | A once-per-session event; fires when a new session opens and also when an existing session resumes. | Hooks reference — Claude Code Official Documentation |
| Stop | An end-of-turn event in the once-per-turn cadence; paired with UserPromptSubmit can calculate one turn's duration. | Hooks reference — Claude Code Official Documentation |
| payload | The JSON context handed to your handler when an event fires and the matcher matches. | Hooks reference — Claude Code Official Documentation |
| OTEL_* | A set of environment variables related to telemetry export; Claude Code removes them from every subprocess it spawns, including hooks. | Hooks reference — Claude Code Official Documentation |
| debug log | A log file that records which hooks matched, their exit codes, and full stdout and stderr. | Hooks reference — Claude Code Official Documentation |
| five-step workflow | This course's arranged debugging approach: narrow by prompt id, find first divergence, replay observation, repeatedly stress the same component, recover from failure point after fixing. | How we built our multi-agent research system — Anthropic Engineering |
| narrow | Step one: filter by prompt id to shrink the range from 'agent broke' to 'these ten-plus events under this id.' | Monitoring — Claude Code Official Documentation |
| first divergence | The step where behavior starts deviating from expectations; the absurdities at the end are mostly downstream noise. | How we built our multi-agent research system — Anthropic Engineering |
| contagion | Steps after the divergence point that look equally absurd but are just continuing forward on the wrong premise. | How we built our multi-agent research system — Anthropic Engineering |
| replay | Building simulations using identical prompts and tools, watching step-by-step to immediately force failure modes out. | How we built our multi-agent research system — Anthropic Engineering |
| stub client | A stand-in that doesn't send network requests, returning preset response objects from a fixed array in sequence, making the model side reproducible. | How we built our multi-agent research system — Anthropic Engineering |
| response queue | The array the stub client draws from in sequence, each element carrying complete stop_reason, content blocks, and usage. | How we built our multi-agent research system — Anthropic Engineering |
| tool-testing agent | An agent that, given a flawed tool, repeatedly tries using it then rewrites the tool description to avoid failures; testing dozens of times finds key nuances and bugs. | How we built our multi-agent research system — Anthropic Engineering |
| trace_id | One id per run, threading scattered records in the same stream back to the same run. | Monitoring — Claude Code Official Documentation |
| span_id | This record's own id; other records point to it to declare 'I'm under you.' | Monitoring — Claude Code Official Documentation |
| parent_id | A field pointing to the parent record's id; trees are reconstructed from on-disk JSONL using this. | Monitoring — Claude Code Official Documentation |
| MAX_ROUNDS | A hard gate on loop iteration count; exceeding it throws an error, records an interrupt, and exits non-zero. | Building Effective AI Agents — Anthropic Engineering |
| stop_reason | The field in model responses that drives the harness loop to continue or finish. | Building Effective AI Agents — Anthropic Engineering |
| HEAD_CHARS | The line defining how many characters maximum each content snippet in logs keeps; set to 0 and not a single word hits disk. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| shape | A field in records describing a value's type and scale: is it string or object, how long, what keys. | Observability with OpenTelemetry — Claude Agent SDK Official Documentation |
| metrics summary | One line outputting total rounds, tool call count, tokens, error count, and total duration—one piece of the observability three-part kit. | Writing effective tools for agents — with agents — Anthropic Engineering |
| compare-runs.mjs | A comparison script that reads two run logs, compares side-by-side by record type and tool name, and exits non-zero if errors exist. | Writing effective tools for agents — with agents — Anthropic Engineering |
| gate | A judgment wired to exit codes; non-zero can be caught by CI, cron, or any 'non-zero means alert' place. | Writing effective tools for agents — with agents — Anthropic Engineering |