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