beam-debug-issue-tasks

用途

Beam Debug Issue Tasks 用于调试 Beam.ai 中失败或出现异常的任务，通过 Langfuse traces（追踪数据）帮助定位任务为什么失败、停止或需要输入。

何时使用

诊断任务失败、停止或需要输入的原因
从 Langfuse trace 的推理过程中查找根因
为文档或交接生成调试报告

前置条件

需要在项目根目录准备 .env 文件，包含以下配置：

Beam.ai - BID 实例：

BEAM_API_KEY=your_bid_api_key
BEAM_WORKSPACE_ID=your_bid_workspace_id

Beam.ai - Prod 实例：

BEAM_API_KEY_PROD=your_prod_api_key
BEAM_WORKSPACE_ID_PROD=your_prod_workspace_id

Langfuse（自托管）：

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://tracing.beamstudio.ai

依赖安装：

pip install requests python-dotenv

使用方式

快速开始命令示例：

列出问题任务（默认最近 1 天，BID 工作区）：

python 03-skills/beam-debug-issue-tasks/scripts/debug_issue_tasks.py <agent_id>

调试指定任务并做完整追踪分析：

python 03-skills/beam-debug-issue-tasks/scripts/debug_issue_tasks.py <agent_id> --task-id <task_id>

使用 prod 工作区：

python 03-skills/beam-debug-issue-tasks/scripts/debug_issue_tasks.py <agent_id> --workspace prod

工作区

工作区	API 端点	Langfuse 项目
bid（默认）	api.bid.beamstudio.ai	cmauxbgww000582ry4644c2qr
prod	api.beamstudio.ai	clw5gbhuy0003u3rv4jzzoesh

问题状态

当任务状态为以下之一时，会被标记为 issue：

FAILED - 执行失败
ERROR - 处理错误
STOPPED - 条件未满足
CANCELLED - 用户取消
TIMEOUT - 执行超时
USER_INPUT_REQUIRED - 缺少输入数据

调试报告

报告保存到：04-workspace/agents/{agent_name}/debug/

格式：Smart Brevity（标题、要点、重要性、细节、修复建议）

分析的关键 span：

ParameterSelection/v2 - 参数如何被匹配
ExecuteGPT_Tool/v1 - 工具执行推理
NodeSelection:EdgeEvaluation/v1 - 路由决策
TaskSuccessCriteriaCheck/v1 - 任务为何停止

CLI 参考

参数	说明	默认值
agent_id	Beam agent ID（必填）	-
--workspace, -w	工作区：bid 或 prod	bid
--days, -d	回溯周期（1, 3, 7, 14, 30）	1
--task-id, -t	调试特定任务 ID	-
--summary, -s	显示分组摘要	false
--limit, -l	最大显示任务数	10
--output, -o	保存为 JSON 文件	-
--no-trace	跳过 Langfuse 查询	false

输出示例

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 链接

每份报告包含直接链接：

Session URL：该任务的所有 traces
Trace URL：具体执行的完整详情

错误处理

错误	解决办法
BEAM_API_KEY not found	添加到 .env
Invalid workspace	检查 workspace 参数（bid/prod）
No traces found	确认 agent 已集成 Langfuse
401 Unauthorized	核对 API 密钥

限制

以上内容均来自已有资料，未提供的功能、收费、价格、平台或效果信息暂未提供。

技能介绍

用途