beam-debug-issue-tasks_skill

Overview

This skill debugs failed or problematic Beam.ai tasks by analyzing Langfuse traces and generating concise debug reports. It helps pinpoint root causes, surfacing critical spans, status, latency, and actionable fixes for each issue. Load it when you need to investigate task failures, timeouts, or missing inputs.

How this skill works

The skill fetches issue tasks from a specified Beam workspace, optionally limited by days or a specific task ID. It retrieves Langfuse traces for each task, analyzes key spans (parameter selection, tool execution, routing, success checks), and produces a Smart Brevity debug report with root cause and remediation steps. Reports are saved per agent for review and sharing.

When to use it

• Investigating why a Beam task failed, stopped, or timed out
• Finding the root cause using Langfuse trace reasoning
• Producing a concise debug report for handoff or documentation
• Verifying whether missing inputs or condition checks blocked progress
• Checking tool execution failures or routing decisions

Best practices

• Provide agent_id and use --task-id to focus analysis on a single problematic run
• Start with a short lookback (1–3 days) then widen if needed
• Include Langfuse keys and correct workspace in .env before running
• Use the --summary flag to scan multiple issues quickly, then drill into full traces
• Save reports to the agent debug folder for consistent handoffs

Example use cases

• List issue tasks for the last day to identify recent failures in a development agent
• Run a full trace analysis on a specific task to extract the exact span and error message
• Generate a Smart Brevity report to share with engineering or product teams
• Compare issue patterns across bid and prod workspaces to spot environment-specific bugs
• Quickly confirm whether a task stopped due to missing input or an execution error