Claude-skill-registry beam-debug-issue-tasks

Debug failed/issue tasks from Beam.ai using Langfuse traces. Load when user says "debug issue tasks", "check failed tasks", "why did task fail", "task errors", "debug agent", or needs to investigate task failures.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/beam-debug-issue-tasks" ~/.claude/skills/majiayu000-claude-skill-registry-beam-debug-issue-tasks && rm -rf "$T"

manifest: skills/data/beam-debug-issue-tasks/SKILL.md

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