Errors and troubleshooting

Agent failures normally come from the model request, a local tool, schema validation, cancellation, or an incomplete human decision. Keep these paths visible in logs and return safe errors to callers.

Recover from tool errors

Set OnError: "return-to-model" on a tool when the model can reasonably recover from the failure. The SDK converts the error into a tool result and allows the next turn to choose another action. Leave the default fail-run behavior for unsafe or unrecoverable failures.

Respect cancellation

Pass the request context to Run, Continue, or Stream. Cancelling it stops model streaming and prevents new tool work from starting.

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := agent.Run(ctx, options)
if errors.Is(err, context.DeadlineExceeded) {
  // Persist enough application state to retry or report the timeout.
}

Diagnose continuation errors

When a run is waiting for a person, every pending call needs an approval, rejection, or externally supplied result keyed by its tool-call ID. Persist the entire returned run record; a human message alone is not a substitute for those decisions.

Capture useful context

Record the run ID, step index, request ID, provider, model, finish reason, tool-call ID, and stop reason. Lifecycle hooks and DevTools expose these fields without requiring transport-level logging.

Start Here

Build

Observe

Reference

Errors and troubleshooting

Recover from tool errors

Respect cancellation

Diagnose continuation errors

Capture useful context

​Recover from tool errors

​Respect cancellation

​Diagnose continuation errors

​Capture useful context

Recover from tool errors

Respect cancellation

Diagnose continuation errors

Capture useful context