Skip to main content
Separate diagnosis from editing. Make one focused change, then prove both the behavior you intended and the behavior that must stay the same. Keep the loop small enough that a reviewer can connect the change to the evidence.

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 with debug_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.
Write down the cause before the fix. State the observed event, the expected event, and the evidence that separates them. If the trace can’t tell two causes apart, ask for the missing data instead of choosing one.
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 and debug_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.
  1. Run syntax, schema, and package checks.
  2. Test the scenario that motivated the change.
  3. Run nearby regression cases, including neighboring routes and negative cases.
  4. Review complete evaluation runs with the same cases and evaluators. See Evaluate agents.
  5. Review the diff and the evidence before you merge or release.
If a write times out, read back first. When a tool call times out or returns an ambiguous result, inspect the resulting record or operation before a retry. A blind retry can duplicate a booking change, refund, or claim.
Studio test chats, debug messages, workflow runs, and eval runs write real rows; there is no isolated copy. Keep read-only and write scenarios in separate eval sets. Name the test rows before you start, and reset them after each stage.

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
Keep the evidence linked to the exact version or eval run. “Looks better” isn’t a useful result without the scenario, the expected behavior, and the observed outcome.

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.