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