skills.rest
bbvch-ai
bbvch-aiOFFICIAL
Explore all skills by this author →
GitHub

debug-agent

Diagnose dispatchable workflow agent failures using MCP tools and NATS JetStream streams.

9|2|Updated Nov 29, 2024
Search Tags:#race conditions#Langfuse#agent debugging#distributed agents#workflow diagnostics#NATS JetStream
One-click install
npx skills add https://github.com/bbvch-ai/aihub-core --skill debug-agent-bbvch-ai
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debug-agent
Source: https://github.com/bbvch-ai/aihub-core/tree/main/.claude/skills/debug-agent
Command: npx skills add https://github.com/bbvch-ai/aihub-core --skill debug-agent-bbvch-ai

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

AI agents built with dispatchable workflows often fail in non-obvious ways due to distributed execution, race conditions, and opaque event flows, making manual debugging time-consuming and error-prone.

Core Features & Use Cases

  • Symptom-Driven Diagnostic Cookbook: Step-by-step guides for common agent issues like steps executing multiple times, never running, or emitting events after stop.
  • Runtime Inspection Tools: MCP-powered access to NATS JetStream streams, MongoDB persisted events, and Langfuse traces to inspect live agent behavior.
  • Execution Semantics Deep Dive: Clear explanations of agent dispatch rules, parameter behavior, and common constraint violations to prevent bugs at the design stage. Use case: For example, if your agent step runs twice unexpectedly, this skill helps you identify optional parameter traps or duplicate event arrivals via NATS stream views.

Quick Start

Use the debug-agent skill to diagnose why my agent step is executing twice and producing duplicate outputs.

Frequently Asked Questions about debug-agent

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my AI agent step execute twice and produce duplicate outputs?▼

Duplicate agent step executions often stem from optional parameter traps or duplicate event arrivals. You can inspect NATS JetStream stream views to identify whether multiple events are triggering the same step unexpectedly.

How do I debug a distributed AI agent workflow that is stalled or emitting events after stop?▼

Debugging stalled distributed agents requires inspecting live runtime behavior. Use MCP tools to query NATS JetStream streams, MongoDB persisted events, and Langfuse traces to trace event flows and identify execution rule violations.

What causes race conditions in dispatchable workflow AI agents?▼

Race conditions in dispatchable agents arise from asynchronous event handling and distributed execution. Examining MongoDB persisted events and Langfuse traces helps pinpoint timing conflicts where steps trigger concurrently or out of order.

How do I diagnose configuration errors in a distributed agent system?▼

Diagnosing configuration errors involves checking execution semantics and engineering constraints. Inspect Langfuse traces and NATS JetStream streams to verify parameter behavior and identify violations of dispatch rules.

Do I need Langfuse traces to troubleshoot an agent that never runs a specific step?▼

Langfuse traces are essential for troubleshooting steps that never run, providing visibility into execution paths. Combined with MongoDB event inspection, they reveal whether events fail to reach the step or are filtered incorrectly.

Related Skills

Explore More Software Engineering Skills→
bbvch-aibbvch-ai
9

nats-events

Document NATS messaging, JetStream persistence, and SAAP event implementation.

Official
Advanced
JaimeJunrJaimeJunr
2

run-tests

Execute unit and integration tests, analyze failures, and re-run to verify corrections.

Community
Advanced
filipexyzfilipexyz
6

events

Monitor NATS event streams and replay JetStream messages via the Ravi CLI.

Community
Advanced
rahulgupta2018rahulgupta2018

adk-debug

Inspect ADK agent sessions, event flows, and LLM interactions.

Community
Advanced