Debugging Tools

Techniques for debugging LeafMesh agent systems using Studio, event tracing, and component status queries.

Inspection

Every agent execution is automatically captured. Debug through:

Studio — Sessions tab for per-session traces, Activity tab for the live event feed, Agents tab for status
REST API — GET /session/{session_id} returns the full session record (yields, conversation, mesh calls) for programmatic inspection

Component Status

Query system health via the health endpoint:

GET http://localhost:18820/health

{
  "status": "healthy",
  "components": {
    "backend": {"status": "connected", "latency_ms": 2},
    "scheduler": {"status": "running"}
  }
}

Agent-level statistics are available via the SDK:

agent_stats = leafmesh.get_agent_stats()
for agent, stats in agent_stats.items():
    print(f"{agent}: calls={stats.get('execution_count')}, errors={stats.get('error_count')}")

Event Tracing

Events are automatically captured and surfaced as a live feed. Watch them in Studio's Activity tab — filter by event type (agent.call.failed, etc.) or by session_id. All agent errors, mesh calls, and lifecycle events are captured automatically.

For programmatic access, use Studio's Dashboard for aggregated statistics.

Common Debugging Scenarios

Agent Returns Unexpected Output

Check yields schema matches what the LLM is producing
Inspect the session's conversation history in Studio's Sessions tab
Verify pre-compose processors are returning expected data

Chain Not Routing Correctly

Check yields values against can_call conditions
Verify condition syntax is correct
Watch the session's events in Studio's Activity tab — filter by session_id to see yields and routing decisions in real time

Agent Timing Out

Check LLM provider status
Check model configuration (some models are slower)
Check tool execution time if tools are involved

Mesh Call Failing

Check that the target agent exists in the configuration
Verify the target agent's model/provider is available
Check call depth limits
Browse the registered agents in Studio's Agents tab to confirm what's running

Health Check Endpoint

The API services expose a health endpoint:

{
  "status": "healthy",
  "components": {
    "backend": {"status": "connected", "latency_ms": 2},
    "scheduler": {"status": "running", "scheduled_agents": 4}
  }
}

Next Steps

Testing Framework — Automated testing
Best Practices — Development guidelines
State Management — Session state patterns

LeafMesh — Debugging multi-agent systems