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.aiDependencies: 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 prodWorkspaces
| 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 failedERROR- Processing errorSTOPPED- Condition failedCANCELLED- User cancelledTIMEOUT- Execution timeoutUSER_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 matchedExecuteGPT_Tool/v1- Tool execution reasoningNodeSelection:EdgeEvaluation/v1- Routing decisionsTaskSuccessCriteriaCheck/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 metricsbeam-create-agent-task- Create test tasksbeam-list-agents- List available agents