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

| Workspace | API Endpoint | Langfuse Project | |-----------|--------------|------------------| | bid (default) | api.bid.beamstudio.ai | cmauxbgww000582ry4644c2qr | | prod | api.beamstudio.ai | clw5gbhuy0003u3rv4jzzoesh |

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

| Flag | Description | Default | |------|-------------|---------| | agent_id | Beam agent ID (required) | - | | --workspace, -w | Workspace: bid or prod | bid | | --days, -d | Look back period (1, 3, 7, 14, 30) | 1 | | --task-id, -t | Debug specific task ID | - | | --summary, -s | Show grouped summary | false | | --limit, -l | Max tasks to show | 10 | | --output, -o | Save to JSON file | - | | --no-trace | Skip Langfuse lookup | false |

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

| Error | Solution | |-------|----------| | BEAM_API_KEY not found | Add to .env | | Invalid workspace | Check workspace parameter (bid/prod) | | No traces found | Verify agent has Langfuse integration | | 401 Unauthorized | Verify API keys |

Related Skills

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