Find the cause
Read the current definition, related tools, relevant instructions, and the exact conversation or eval case. Agent Platform records every turn’s model request, tool results, decisions, and timings. Open them at Project → Operate → Sessions → session → Traces, or read them withdebug_traces. A transcript tells you what was said; a trace shows why.
Trace the result through its layers: routing, agent instructions, execution flow, tool contract, workflow, data, channel configuration, or deployment. Check the earlier steps that shaped the turn before you edit the most visible agent.
For example, a call offers a standard cancellation fee after the airline caused the delay. Check whether the disruption route was selected, whether the status tool returned the delay, and whether the refund workflow received and enforced that status. A change to the greeting can’t fix a missing eligibility check.
Read what the model received
Open Project → Operate → Sessions → session → Traces → LLM step → Request. It shows the system prompt, the history, and the tool list the model received. To follow a value that went missing, see Debug a missing value.Find the layer where the fix lives
Write the expected path from the ABL anddebug_get_flow_graph before you open the trace. Then pick the earliest layer whose evidence is already wrong.
For voice calls, see Diagnose a failed call.
Plan a small change
The plan names the behavior to change, the files or definitions involved, possible side effects, and the checks to run. Prefer the smallest layer that owns the rule. A policy enforced in a write workflow must not depend only on wording in a prompt.
For a single agent change, use the guarded edit action instead of a whole-project import or an unguarded save. If the edit is refused because the source changed, read the current definition, reconcile the change, and reapply it. See How guarded edits work.
Validate and test
Validation tells you whether the definition is structurally acceptable. A conversation or evaluation tells you whether behavior meets the scenario. Neither one alone proves a release is safe.- Run syntax, schema, and package checks.
- Test the scenario that motivated the change.
- Run nearby regression cases, including neighboring routes and negative cases.
- Review complete evaluation runs with the same cases and evaluators. See Evaluate agents.
- Review the diff and the evidence before you merge or release.
Write a change note
The note gives the next reviewer enough context to understand why the change exists and how to detect a regression.Change note template
Review a change
Read the diff from the outside in. Start with the behavior and the affected boundary, then inspect individual edits. This stops a technically neat change with the wrong product outcome from getting through.
Ask for an assistant’s reasoning only where it explains a consequential choice. Ground the review in the source and the test evidence. Keep the run ID and source version with each result, and say when the test set, evaluator, or environment changed.
Match review depth to the risk
Use a stronger review when a mistake can change customer data, disclose private information, create a financial effect, or affect many journeys. Match the review depth to the consequence, whatever the size of the diff.
Ask a domain owner to decide policy questions. A coding assistant can show where a decision is needed and present the evidence. It must never invent a business rule to complete a change.