beam-connect

Beam Connect 是一个面向用户的元技能（meta-skill），用于连接 Beam AI 工作区进行智能体管理。它是所有 Beam AI 操作的单一入口，遵循 master/connect 模式，共享脚本和参考位于 beam-master 中。

用途

该技能在用户提及以下内容时加载：

"beam" / "beam ai"
"list agents" / "show beam agents"
"create beam task" / "run agent task"
"beam analytics" / "agent performance"
"beam task status"
缓存上下文中的任何智能体名称

主要能力

发现工作区智能体
创建和管理任务
监控分析与性能
调试失败的执行
优化工具配置

使用方式

预检查（必须先运行）

在执行任何 Beam 操作之前，先验证配置：

python 00-system/skills/beam/beam-master/scripts/check_beam_config.py --json

根据配置状态处理：

ai_action	操作
proceed_with_operation	配置正常，继续
prompt_for_api_key	向用户索取 API Key，保存至 .env
prompt_for_workspace_id	向用户索取工作区 ID，保存至 .env
run_setup_wizard	运行交互式设置向导

如需设置，向用户说明获取凭据的方式：登录 Beam AI（app.beam.ai），进入 Settings → API Keys 创建新 API Key，并从 Settings → Workspace 获取 Workspace ID。用户提供后写入 .env：

BEAM_API_KEY=xxx
BEAM_WORKSPACE_ID=workspace-id

随后重新运行配置检查脚本验证。

各工作流

Workflow 0：配置检查（自动）

触发：任何操作之前
脚本：check_beam_config.py --json
输出：配置状态、所需操作

Workflow 1：列出智能体

触发："list agents"、"show beam agents"、"my agents"
命令：

python 00-system/skills/beam/beam-master/scripts/list_agents.py --json

显示格式示例：

Found 5 agents in your workspace:

1. Customer Support Agent
   ID: abc-123-def
   Type: beam-os
   Created: 2024-01-15

2. Email Processor
   ID: ghi-456-jkl
   ...

缓存智能体列表至上下文，用户可按名称引用，例如 "run task for Customer Support"。

Workflow 2：获取智能体图谱

触发："get agent graph"、"show agent workflow"、"agent config for X"
命令：

python 00-system/skills/beam/beam-master/scripts/get_agent_graph.py --agent-id AGENT_ID --json

显示：节点、连接、入口/出口点

Workflow 3：创建任务

触发："create task"、"run agent"、"execute agent X"
必需：Agent ID、任务查询
可选：要解析的 URL、上下文文件
命令：

python 00-system/skills/beam/beam-master/scripts/create_task.py \
  --agent-id AGENT_ID \
  --query "Task description" \
  --json

后续可提供监控任务进度：

python 00-system/skills/beam/beam-master/scripts/get_task_updates.py --task-id TASK_ID

Workflow 4：获取分析

触发："analytics"、"agent performance"、"how is X performing"
命令：

python 00-system/skills/beam/beam-master/scripts/get_analytics.py \
  --agent-id AGENT_ID \
  --json

显示示例（含任务总数、完成/失败、平均评估分、平均运行时间、正向反馈等指标）。

Workflow 5：任务管理

触发："task status"、"retry task"、"approve task"
获取任务详情：

python 00-system/skills/beam/beam-master/scripts/get_task.py --task-id TASK_ID --json

重试失败任务：

python 00-system/skills/beam/beam-master/scripts/retry_task.py --task-id TASK_ID

批准 HITL 任务：

python 00-system/skills/beam/beam-master/scripts/approve_task.py --task-id TASK_ID

提供用户输入：

python 00-system/skills/beam/beam-master/scripts/provide_user_input.py \
  --task-id TASK_ID \
  --input "User response"

评价任务输出：

python 00-system/skills/beam/beam-master/scripts/rate_task_output.py \
  --task-id TASK_ID \
  --node-id NODE_ID \
  --rating positive \
  --feedback "Worked well"

Workflow 6：测试与更新节点

触发："test node"、"update node config"
测试节点：

python 00-system/skills/beam/beam-master/scripts/test_graph_node.py \
  --agent-id AGENT \
  --node-id NODE \
  --graph-id GRAPH \
  --input '{"key": "value"}'

更新节点：

python 00-system/skills/beam/beam-master/scripts/update_graph_node.py \
  --node-id NODE \
  --objective "New objective"

Workflow 7：工具优化

触发："optimize tool"、"improve tool performance"
开始优化：

python 00-system/skills/beam/beam-master/scripts/optimize_tool.py --tool TOOL_NAME

检查状态：

python 00-system/skills/beam/beam-master/scripts/get_optimization_status.py --thread-id THREAD

智能路由

根据用户短语路由到对应工作流：

短语	路由到
"list agents"、"show agents"	Workflow 1
"agent graph"、"agent workflow"	Workflow 2
"create task"、"run task"、"execute"	Workflow 3
"analytics"、"performance"、"metrics"	Workflow 4
"task status"、"retry"、"approve"	Workflow 5
"test node"、"update node"	Workflow 6
"optimize tool"	Workflow 7
智能体名称（来自缓存）	显示智能体详情并提供操作

错误处理

常见错误与解决方案：

错误	解决方案
401 Unauthorized	Token 过期，重新认证
403 Forbidden	检查工作区权限
404 Not Found	验证 agent/task ID
Rate Limited	等待后重试

出错时加载 beam-master/references/error-handling.md，显示用户友好消息，并在可能时提供修复。

上下文缓存

列出智能体后为会话缓存：

agents_cache = [
    {"name": "Customer Support", "id": "abc-123"},
    {"name": "Email Processor", "id": "def-456"}
]

当用户说 "run Customer Support" 时，匹配到缓存的智能体 ID。

与其他 Beam 技能的集成

该技能可交接给专门技能：

技能	使用时机
beam-list-agents	详细智能体列表
beam-get-agent-graph	深度图谱分析
beam-get-agent-analytics	扩展分析
beam-create-agent-task	带监控的任务创建
beam-debug-issue-tasks	通过 Langfuse 调试

版本信息

版本：1.0
创建：2025-12-11
状态：Production Ready

限制

资料未提供关于该技能的具体收费、价格、平台依赖要求或可支持智能体数量上限等信息。实际使用前需拥有 Beam AI 账户及有效的 API Key 与 Workspace ID。

技能介绍