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:

# 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

# 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)

# 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