Shared resource library for Beam AI integration skills. DO NOT load directly - provides common references (setup, API docs, error handling, authentication) and scripts used by beam-connect and individual Beam skills.
Beam Master
This is NOT a user-facing skill. It's a shared resource library referenced by Beam integration skills.
Purpose
Provides shared resources to eliminate duplication across:
beam-connect- Meta-skill for Beam AI workspace operationsbeam-list-agents- List workspace agentsbeam-get-agent-graph- Fetch agent graph configurationbeam-get-agent-analytics- Get agent performance metricsbeam-create-agent-task- Create and execute agent tasksbeam-update-graph-node- Update node configurationbeam-test-graph-node- Test individual nodesbeam-get-nodes-by-tool- Get nodes using specific toolsbeam-debug-issue-tasks- Debug failed tasks via Langfuse
Instead of loading this skill, users directly invoke the specific skill they need above.
Architecture: DRY Principle
Problem solved: Beam skills would have duplicated content (setup instructions, API docs, auth flow, error handling).
Solution: Extract shared content into beam-master/references/ and beam-master/scripts/, then reference from each skill.
Result: Single source of truth, reduced context per skill.
Shared Resources
All Beam skills reference these resources (progressive disclosure).
references/
setup-guide.md - Complete setup wizard
- Getting Beam API key
- Finding workspace ID
- Configuring .env file
- Token exchange flow
api-reference.md - Beam API patterns
- Base URL and authentication
- All 22 API endpoints documented
- Request/response examples
- Common curl examples
error-handling.md - Troubleshooting
- Common errors and solutions
- HTTP error codes
- Authentication issues
- Rate limiting
authentication.md - Token management
- API key to access token exchange
- Token refresh flow
- Header requirements
scripts/
Authentication & Configuration
check_beam_config.py - Pre-flight validation
python check_beam_config.py [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--json |
No | False | Output structured JSON for AI consumption |
Exit codes: 0=configured, 1=partial, 2=not configured
When to Use: Run this FIRST before any Beam operation. Use to validate API key and workspace ID are configured, diagnose authentication issues, or check if setup is needed.
setup_beam.py - Interactive setup wizard
python setup_beam.py
No arguments - runs interactively. Guides through API key setup, tests connection, saves to .env.
When to Use: Use when Beam integration needs initial setup, when check_beam_config.py returns exit code 2, or when user needs to reconfigure credentials.
get_access_token.py - Token exchange (POST /auth/access-token)
python get_access_token.py [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--json |
No | False | Output as JSON |
When to Use: Use to exchange API key for access token. Called automatically by beam_client.py, but use directly when debugging authentication issues or testing token exchange.
refresh_token.py - Token refresh (POST /auth/refresh-token)
python refresh_token.py --refresh-token TOKEN [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--refresh-token |
Yes | - | Refresh token to use |
--json |
No | False | Output as JSON |
When to Use: Use when access token has expired and you have a refresh token. Typically handled automatically, but use directly for debugging token lifecycle issues.
get_current_user.py - User profile (GET /v2/user/me)
python get_current_user.py [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--json |
No | False | Output as JSON |
When to Use: Use to verify authentication is working, get user profile info, or confirm workspace access after setup.
Agent Management
list_agents.py - List workspace agents (GET /agent)
python list_agents.py [--filter NAME] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--filter |
No | - | Filter agents by name/description |
--json |
No | False | Output as JSON |
When to Use: Use when user says "list agents", "show my agents", "what agents do I have", or when you need to find an agent ID for use with other scripts (tasks, graphs, analytics).
get_agent_graph.py - Get agent workflow graph (GET /agent-graphs/{agentId})
python get_agent_graph.py --agent-id AGENT [--graph-id GRAPH] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--agent-id |
Yes | - | Agent ID |
--graph-id |
No | - | Specific graph version ID |
--json |
No | False | Output as JSON |
When to Use: Use when user wants to see agent workflow structure, understand node configuration, get node IDs for testing/updating, or analyze agent architecture.
Graph & Node Operations
test_graph_node.py - Test a specific node (POST /agent-graphs/test-node)
python test_graph_node.py --agent-id AGENT --node-id NODE --graph-id GRAPH [--input JSON] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--agent-id |
Yes | - | Agent ID |
--node-id |
Yes | - | Node ID to test |
--graph-id |
Yes | - | Graph ID |
--input |
No | {} |
JSON input params |
--json |
No | False | Output as JSON |
When to Use: Use when debugging a specific node, testing node behavior with custom input, validating node configuration changes, or isolating issues in a workflow.
update_graph_node.py - Update node configuration (PATCH /agent-graphs/update-node)
python update_graph_node.py --node-id NODE [--objective TEXT] [--on-error STOP|CONTINUE] [--auto-retry BOOL] [--config JSON] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--node-id |
Yes | - | Node ID to update |
--objective |
No | - | New objective text |
--on-error |
No | - | Error behavior: STOP or CONTINUE |
--auto-retry |
No | - | Enable auto retry (true/false) |
--config |
No | - | JSON config object to merge |
--json |
No | False | Output as JSON |
When to Use: Use when modifying node objectives/prompts, changing error handling behavior, enabling/disabling auto-retry, or updating node configuration programmatically.
get_nodes_by_tool.py - Find nodes by tool (GET /agent-graphs/agent-task-nodes/{toolFunctionName})
python get_nodes_by_tool.py --tool TOOL_NAME [--agent-id AGENT] [--rated] [--page N] [--page-size N] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--tool |
Yes | - | Tool function name |
--agent-id |
No | - | Filter by agent ID |
--rated |
No | False | Only return rated nodes |
--page |
No | 1 | Page number |
--page-size |
No | 50 | Items per page |
--json |
No | False | Output as JSON |
When to Use: Use when finding all nodes that use a specific tool, analyzing tool usage patterns across agents, or gathering rated nodes for optimization training.
get_tool_output_schema.py - Get node output schema (GET /agent-tasks/tool-output-schema/{graphNodeId})
python get_tool_output_schema.py --node-id NODE [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--node-id |
Yes | - | Graph node ID |
--json |
No | False | Output as JSON |
When to Use: Use when understanding what output format a node produces, debugging output parsing issues, or documenting node interfaces.
Task Operations
create_task.py - Create new agent task (POST /agent-tasks)
python create_task.py --agent-id AGENT --query "Task instructions" [--urls URL1,URL2] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--agent-id |
Yes | - | Agent ID |
--query |
Yes | - | Task query/instructions |
--urls |
No | - | Comma-separated URLs to parse |
--json |
No | False | Output as JSON |
When to Use: Use when user wants to run an agent, execute a task, start a job, or invoke an agent with specific instructions. This is the primary way to trigger agent execution.
get_task.py - Get task details (GET /agent-tasks/{taskId})
python get_task.py --task-id TASK [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--task-id |
Yes | - | Task ID |
--json |
No | False | Output as JSON |
When to Use: Use when checking task status after creation, getting detailed results of a completed task, reviewing task execution history, or debugging why a task failed.
list_tasks.py - List tasks with filtering (GET /agent-tasks)
python list_tasks.py [--agent-id AGENT] [--status STATUS1,STATUS2] [--search TEXT] [--start-date DATE] [--end-date DATE] [--page N] [--page-size N] [--order FIELD:DIR] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--agent-id |
No | - | Filter by agent ID |
--status |
No | - | Comma-separated: COMPLETED,FAILED,RUNNING,etc |
--search |
No | - | Search query text |
--start-date |
No | - | Start date (ISO 8601) |
--end-date |
No | - | End date (ISO 8601) |
--page |
No | 1 | Page number |
--page-size |
No | 20 | Items per page |
--order |
No | createdAt:desc | Sort order (field:asc/desc) |
--json |
No | False | Output as JSON |
When to Use: Use when user asks "show my tasks", "list failed tasks", "what tasks ran today", or when finding tasks by status, date range, or search criteria. Best for filtered views.
iterate_tasks.py - Paginated task iteration (GET /agent-tasks/iterate)
python iterate_tasks.py [--agent-id AGENT] [--cursor CURSOR] [--limit N] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--agent-id |
No | - | Filter by agent ID |
--cursor |
No | - | Pagination cursor |
--limit |
No | 50 | Items per page |
--json |
No | False | Output as JSON |
When to Use: Use when iterating through large numbers of tasks efficiently, exporting task data, or building reports. Better than list_tasks for bulk operations due to cursor-based pagination.
retry_task.py - Retry failed task (POST /agent-tasks/retry)
python retry_task.py --task-id TASK [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--task-id |
Yes | - | Task ID to retry |
--json |
No | False | Output as JSON |
When to Use: Use when a task has failed and user wants to re-run it, after fixing underlying issues that caused failure, or when retrying transient errors.
get_task_updates.py - Stream real-time updates (GET /agent-tasks/{taskId}/updates - SSE)
python get_task_updates.py --task-id TASK [--timeout SECONDS] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--task-id |
Yes | - | Task ID |
--timeout |
No | 300 | Timeout in seconds |
--json |
No | False | Output as JSON lines |
When to Use: Use when monitoring a running task in real-time, watching for HITL (human-in-the-loop) requests, or streaming task progress updates to the user.
Task Feedback & HITL
approve_task.py - Approve HITL task (POST /agent-tasks/execution/{taskId}/user-consent)
python approve_task.py --task-id TASK [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--task-id |
Yes | - | Task ID to approve |
--json |
No | False | Output as JSON |
When to Use: Use when a task is waiting for human approval (HITL), agent requests user consent to proceed, or task status shows "WAITING_FOR_CONSENT".
reject_task.py - Reject task execution (POST /agent-tasks/execution/{taskId}/rejection)
python reject_task.py --task-id TASK [--reason TEXT] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--task-id |
Yes | - | Task ID to reject |
--reason |
No | - | Rejection reason |
--json |
No | False | Output as JSON |
When to Use: Use when user wants to cancel/reject a running task, stop task execution, or provide negative feedback that halts the task.
provide_user_input.py - Provide HITL input (PATCH /agent-tasks/execution/{taskId}/user-input)
python provide_user_input.py --task-id TASK --input "User response" [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--task-id |
Yes | - | Task ID |
--input |
Yes | - | User input/response text |
--json |
No | False | Output as JSON |
When to Use: Use when a task is waiting for human input (HITL), agent asks a question and needs user's answer, or task status shows "WAITING_FOR_USER_INPUT".
rate_task_output.py - Rate task output (PATCH /agent-tasks/execution/{taskId}/output-rating)
python rate_task_output.py --task-id TASK --node-id NODE --rating RATING [--feedback TEXT] [--expected-output TEXT] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--task-id |
Yes | - | Task ID |
--node-id |
Yes | - | Task node ID |
--rating |
Yes | - | positive, negative, or excellent |
--feedback |
No | - | Feedback text |
--expected-output |
No | - | Expected output for comparison |
--json |
No | False | Output as JSON |
When to Use: Use when providing feedback on task/node output quality, training the system with positive/negative examples, or improving agent performance through ratings.
Analytics & Optimization
get_analytics.py - Agent performance analytics (GET /agent-tasks/analytics)
python get_analytics.py --agent-id AGENT [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--agent-id |
Yes | - | Agent ID |
--start-date |
No | 30 days ago | Start date (YYYY-MM-DD) |
--end-date |
No | today | End date (YYYY-MM-DD) |
--json |
No | False | Output as JSON |
When to Use: Use when user asks "how is my agent performing", "show analytics", "success rate", or when analyzing agent performance metrics over a time period.
get_latest_executions.py - Recent executions (GET /agent-tasks/latest-executions)
python get_latest_executions.py [--agent-id AGENT] [--limit N] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--agent-id |
No | - | Filter by agent ID |
--limit |
No | 10 | Number of results |
--json |
No | False | Output as JSON |
When to Use: Use when user asks "what ran recently", "show recent tasks", "latest executions", or when quickly checking what tasks completed recently without complex filtering.
optimize_tool.py - Start tool optimization (POST /tool/optimize/{toolFunctionName})
python optimize_tool.py --tool TOOL_NAME [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--tool |
Yes | - | Tool function name |
--json |
No | False | Output as JSON |
When to Use: Use when user wants to improve a tool's performance, has collected rated node examples, or wants to trigger AI-driven optimization of tool prompts/behavior.
get_optimization_status.py - Check optimization status (POST /tool/optimization-status/thread/{threadId})
python get_optimization_status.py --thread-id THREAD [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--thread-id |
Yes | - | Optimization thread ID |
--json |
No | False | Output as JSON |
When to Use: Use after starting an optimization with optimize_tool.py to check progress, see if optimization is complete, or get optimization results.
File Operations
download_context_file.py - Download agent context file (GET /agent/{agentId}/context/file/{fileId}/download)
python download_context_file.py --agent-id AGENT --file-id FILE [--output PATH] [--json]
| Argument | Required | Default | Description |
|---|---|---|---|
--agent-id |
Yes | - | Agent ID |
--file-id |
Yes | - | File ID to download |
--output |
No | from headers | Output file path |
--json |
No | False | Output metadata as JSON |
When to Use: Use when user needs to download a file attached to an agent's context, retrieve agent documentation/assets, or access files stored in agent configuration.
Intelligent Error Detection Flow
When a Beam skill fails due to missing configuration, the AI should:
Step 1: Run Config Check with JSON Output
python 00-system/skills/beam/beam-master/scripts/check_beam_config.py --json
Step 2: Parse the ai_action Field
The JSON output includes an ai_action field that tells the AI what to do:
| ai_action | What to Do |
|---|---|
proceed_with_operation |
Config OK, continue with the original operation |
prompt_for_api_key |
Ask user: "I need your Beam API key. Get one from your Beam workspace settings" |
prompt_for_workspace_id |
Ask user: "I need your Beam workspace ID" |
create_env_file |
Create .env file and ask user for credentials |
run_setup_wizard |
Run: python 00-system/skills/beam/beam-master/scripts/setup_beam.py |
Step 3: Help User Fix Issues
If ai_action is prompt_for_api_key:
- Tell user: "Beam integration needs setup. I need your API key."
- Show them: "Get one from: Beam workspace → Settings → API Keys"
- Ask: "Paste your Beam API key here (starts with 'bm_key_'):"
- Once they provide it, write directly to
.env:# Edit .env file to add: BEAM_API_KEY=bm_key_their_key_here BEAM_WORKSPACE_ID=their-workspace-id - Re-run config check to verify
JSON Output Structure
{
"status": "not_configured",
"exit_code": 2,
"ai_action": "prompt_for_api_key",
"missing": [
{"item": "BEAM_API_KEY", "required": true, "location": ".env"}
],
"fix_instructions": [...],
"env_template": "BEAM_API_KEY=bm_key_YOUR_API_KEY_HERE\nBEAM_WORKSPACE_ID=your-workspace-id",
"setup_wizard": "python 00-system/skills/beam/beam-master/scripts/setup_beam.py"
}
How Skills Reference This
Each skill loads shared resources only when needed (progressive disclosure):
beam-connect uses:
check_beam_config.py(validate before any operation)- All API scripts based on user request
- All references as needed
beam-list-agents uses:
check_beam_config.py(validate before query)list_agents.py(core functionality)error-handling.md(troubleshooting)
beam-create-agent-task uses:
check_beam_config.py(validate before task creation)create_task.py(core functionality)get_task_updates.py(monitor execution)api-reference.md(request format)
Usage Example
User says: "list my beam agents"
What happens:
- AI loads
beam-connectskill (NOT beam-master) beam-connectSKILL.md says: "Run check_beam_config.py first"- AI executes:
python beam-master/scripts/check_beam_config.py --json - AI executes:
python beam-master/scripts/list_agents.py - If errors occur, AI loads:
beam-master/references/error-handling.md
beam-master is NEVER loaded directly - it's just a resource library.
Environment Variables
Required in .env:
BEAM_API_KEY=bm_key_xxxxxxxxxxxxx
BEAM_WORKSPACE_ID=your-workspace-id
API Base URL
All API requests go to: https://api.beamstudio.ai
Version: 1.2
Created: 2025-12-11
Updated: 2025-12-11
Status: Production Ready
Changelog:
- v1.2: Added "When to Use" sections to all 27 scripts for AI routing guidance
- v1.1: Added comprehensive script argument documentation with usage examples and argument tables
You Might Also Like
Related Skills
gog
Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs.
openclaw
orpc-contract-first
Guide for implementing oRPC contract-first API patterns in Dify frontend. Triggers when creating new API contracts, adding service endpoints, integrating TanStack Query with typed contracts, or migrating legacy service calls to oRPC. Use for all API layer work in web/contract and web/service directories.
langgenius
