Debug a project

Give Agent a failing preview, test, deployment or runtime path to investigate and fix.

Give Agent the failure

Include the error, failing command, URL, or deployment state.

text
The preview route /settings returns a server error.
Find the cause, fix it, and run the relevant check.

Ask for cause before edits

For unclear failures, ask Agent to explain the cause before changing files.

text
Inspect the logs and related code first.
Tell me the likely cause before editing.

Inspect an agent run

Start with the run's recorded status and error. Then read its events with veryfront__list_run_events, one page at a time.

  • Failure: Filter by is_error to find the failing event. Then query again with only its span_id to see the call arguments next to the result.
  • Overview: Filter event_class to fact to skip streaming deltas.
  • More events: Pass page_info.next as cursor and keep the same filters.

Use the run ID the API returns. Don't build a conversation ID from it. A filtered page doesn't prove the rest of the run succeeded.

Improve context and cost

Compare runs with the same input, model, and configuration. Check usage, discovery calls, retrieved knowledge, loaded skills, retries, and the outcome. If usage data is missing, say so.

Fix the part that caused the failure: project code, agent instructions, skill guidance, docs, or the platform. Rerun the same request and check both the outcome and any usage claim.

Keep the fix scoped

Name the behavior that must stay unchanged.

text
Fix the failing settings route.
Do not change the account routes.
Keep the existing form components.

Verify the fix

Ask Agent to rerun the failing path and any related checks.

text
After the fix, rerun the failing test or preview path.
Report the command output and any remaining risk.

Next

Review the branch after the fix. For a planned behavior change, use Change a project.

Put recurring debug commands and constraints in project instructions. Child forks explains how Agent can isolate an investigation.