---

name: beam-debug-issue-tasks description: Debug failed/issue tasks from Beam.ai using Langfuse traces. Load when user says "debug issue tasks", "check failed tasks", "why did task fail", "task errors", "debug agent", or needs to investigate task failures.

Beam Debug Issue Tasks

Debug failed Beam.ai tasks using Langfuse traces.

When to Use

• Diagnose why a task failed, stopped, or needs input
• Find root cause from Langfuse trace reasoning
• Generate debug reports for documentation or handoff

---

Prerequisites

.env file at project root:

Copy# Beam.ai - BID instance
BEAM_API_KEY=your_bid_api_key
BEAM_WORKSPACE_ID=your_bid_workspace_id

# Beam.ai - Prod instance
BEAM_API_KEY_PROD=your_prod_api_key
BEAM_WORKSPACE_ID_PROD=your_prod_workspace_id

# Langfuse (self-hosted)
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://tracing.beamstudio.ai

Dependencies: pip install requests python-dotenv

---

Quick Start

Copy# List issue tasks (default: last 1 day, BID workspace)
python 03-skills/beam-debug-issue-tasks/scripts/debug_issue_tasks.py <agent_id>

# Debug specific task with full trace analysis
python 03-skills/beam-debug-issue-tasks/scripts/debug_issue_tasks.py <agent_id> --task-id <task_id>

# Use prod workspace
python 03-skills/beam-debug-issue-tasks/scripts/debug_issue_tasks.py <agent_id> --workspace prod

---

Workspaces

---

Issue Statuses

Tasks are flagged as "issue" if status is:

• FAILED - Execution failed
• ERROR - Processing error
• STOPPED - Condition failed
• CANCELLED - User cancelled
• TIMEOUT - Execution timeout
• USER_INPUT_REQUIRED - Missing input data

---

Debug Reports

Reports saved to: 04-workspace/agents/{agent_name}/debug/

Format: Smart Brevity (headline, takeaway, why it matters, details, fix)

Key spans analyzed:

• ParameterSelection/v2 - How parameters were matched
• ExecuteGPT_Tool/v1 - Tool execution reasoning
• NodeSelection:EdgeEvaluation/v1 - Routing decisions
• TaskSuccessCriteriaCheck/v1 - Why task stopped

---

CLI Reference

---

Example Output

Debug Report (Smart Brevity)

Copy# Task stopped: condition failed

Checklist evaluation: subfolder must equal 'Schreiben Schuldner' but was null.

**Why it matters**: This task did not complete successfully and may need attention.

**The details**:
- **Status**: `STOPPED`
- **Task**: `ab3cbbb8-28da-41aa-b726-25931d14d7d4`
- **Latency**: 159.6s
- **Cost**: $0.1043

**Key spans**:
- NodeSelection:EdgeEvaluation/v1 (23.4s)
- TaskSuccessCriteriaCheck/v1 (7.2s)

**Root cause**:
> The criterion is not met because subfolder is not set to required value.

**Fix**: Review the condition that stopped execution. Check if input data meets requirements.

---

Langfuse Links

Each report includes direct links:

• Session URL: All traces for the task
• Trace URL: Specific execution with full details

---

Error Handling

---

Related Skills

• beam-get-agent-analytics - Performance metrics
• beam-create-agent-task - Create test tasks
• beam-list-agents - List available agents