beam-ai-team/beam-debug-issue-tasks

Beam Debug Issue Tasks

Debug failed Beam.ai tasks using Langfuse traces.

Safety Contract

This skill is read-only for Beam and Langfuse state. Before saving or sharing debug reports, show the workspace, agent ID, task IDs, destination path, and any customer-sensitive fields that will be included. Require explicit user approval in the current turn before exporting reports outside the local workspace. Do not retry tasks, approve HITL work, update prompts, or modify graphs from this skill.

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=<bid-api-key>
BEAM_WORKSPACE_ID=<bid-workspace-id>

# Beam.ai - Prod instance
BEAM_API_KEY_PROD=<prod-api-key>
BEAM_WORKSPACE_ID_PROD=<prod-workspace-id>

# Langfuse (self-hosted)
LANGFUSE_PUBLIC_KEY=<langfuse-public-key>
LANGFUSE_SECRET_KEY=<langfuse-secret-key>
LANGFUSE_HOST=https://tracing.beamstudio.ai

Dependencies: pip install requests python-dotenv

---

Quick Start

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

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

# Use prod workspace
python skills/beam/beam/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