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