Cuga Debug Trajectory

Debugging a cuga agent run

Trajectory viewer

Every run is logged to a trajectory data directory (<cuga log dir>/trajectory_data). Inspect it visually:

cuga viz

Launches a web dashboard for browsing execution trajectories: what the reasoning engine decided at each step, which tools it called with what arguments, and what came back. Start here before reading raw logs — it's usually faster to spot the wrong branch/tool call visually than to grep JSON.

Environment sanity check

cuga doctor

Run this first if the agent won't even start, or behaves inconsistently across environments — it validates the environment/dependency setup.

cuga status

cuga status <service|all>

Confirms whether the service you expect to be running actually is, before chasing a bug that's really just "nothing is listening on that port."

Common failure patterns

• Tool "not found" or never called — check the tool actually got passed to CugaAgent(tools=[...]), or (for OpenAPI/MCP tools) that the registry service (cuga start registry, or the registry bundled in a demo_*/manager service) picked up your mcp_servers.yaml change — those are build-time, not hot-reloaded.
• Request silently redirected/blocked with no obvious reason — an intent_guard policy may be matching. Check .cuga/guards/ (or policies added via agent.policies.add_intent_guard) for a guard whose triggers/intent_examples overlap the query, and check priority — guards default to high priority (90-100) and are checked before other policies. See cuga-author-policy.
• Response in the wrong shape — an output_formatter policy may be firing (or not firing when expected) based on its triggers.natural_language keywords and threshold. Lower/raise the threshold or adjust keywords.
• Tool paused waiting on nothing — a tool_approval policy is likely gating that tool; check .cuga/approvals/ for required_tools/required_apps matches and auto_approve_after.
• thread_id confusion — state (conversation history, session-scoped knowledge) is isolated per thread_id. If a run seems to have "forgotten" something from a previous call, confirm the same thread_id was passed both times.
• Multi-agent: wrong sub-agent picked — the CugaSupervisor routes based on each sub-agent's .description. Vague or overlapping descriptions between sub-agents cause misrouting — make them distinct and specific.

Policy-level test coverage

If you're debugging policy interaction bugs specifically, the policy engine's own integration tests are a good reference for expected behavior: src/cuga/backend/cuga_graph/policy/tests/ in a cuga-agent checkout (covers intent guard blocking/priority resolution, playbook guidance injection, and more).