# Core Concepts
Source: https://docs.beam.ai/01-getting-started/core-concepts/core-concepts
Understand the current Beam workspace, agents, Flows, tools, variables, memory, and task surfaces.
Beam brings together a workspace, agents, and Flows. Use the workspace home to start a task or brainstorm, then configure agents and review their work from the workspace navigation.
![The current Beam workspace home with the Ask Beam composer, Build agents control, and recommended task prompts.]()
## Workspace
The workspace home is the starting point for asking Beam to perform a task or brainstorm. The workspace navigation provides access to **Skills**, **Projects**, **Inbox**, **Tasks**, **Agent templates**, **Integrations**, and **Views**.
## Agents
An agent is the unit you configure to perform work. You can start from **Agent templates** or select **New agent** in the template gallery. An agent includes its own **Chat**, **Tasks**, **Flow**, **Learning**, **Configuration**, and **Analytics** areas.
## Flows
A Flow is the configured graph that an agent uses to carry out work. The current Flow canvas starts with a **Trigger** and can contain tool and LLM-based **Condition** nodes. Its header shows the Flow state, **Test mode**, and **Publish** controls.
When you select a tool node, the sidebar includes **Parameters**, **Settings**, and **Evaluation**. Parameters includes input variables, model, output variables, and integrations.
## Tools and integrations
Tools give a Flow the capabilities it needs to complete work. Use the workspace **Integrations** page to browse available integrations, add a connection, review existing connections, or start a custom integration.
Configure the integration used by a Flow node from the node sidebar's **Parameters → Integrations** section. See [Selecting Tools](/02-building-agents/agent-fundamentals/tools-integrations/tools-integrations) and [Integrations](/02-building-agents/agent-configuration/integrations/integrations).
## Variables
Variables supply values to node inputs while a Flow runs. Beam currently provides seven fill methods:
* **Auto fill**
* **Prompt fill**
* **Linked fill**
* **Static fill**
* **User fill**
* **Memory fill**
* **Attachment fill**
See [Variable Fill](/02-building-agents/agent-configuration/variables-state/variables-state) for when to use each method.
## Memory
Each agent has a **Memory** module. Add documents from **Configuration → Memory → Add data**, then use **Memory fill** when a node needs knowledge from those files as an input.
Google Drive and SharePoint connections for keeping an agent's memory in sync with repository folders are planned but are not yet available.
## Tasks
A task is one execution of an agent. Use the workspace **Tasks** page to review task records, switch between **Tasks** and **Tests**, filter the list, search by task name, and create a task manually.
See [Task Executions](/03-running-operations/task-management/task-executions/task-executions) for the verified task-list and task-detail controls.
## Triggers
The Flow canvas begins with a **Trigger** node. Select it to review existing trigger cards or add a trigger. The detailed trigger configuration depends on the trigger type; see [Triggers and Webhooks](/03-running-operations/task-management/triggers-webhooks/triggers-webhooks) for the current verified Gmail trigger editor.
## Next steps
Start from an available agent template.
Learn the current agent entry points.
Configure a Flow with triggers, tools, and conditions.
# Quick start: create your first agent
Source: https://docs.beam.ai/01-getting-started/quickstart/quickstart
Create an agent from a template, review its Flow and integrations, test it, and publish when it is ready.
Start with an agent template when you want a prebuilt starting point. The template gallery lets you filter, search, and create an agent from the templates available in your workspace.
![Agent templates gallery with category filters, template cards, Create agent buttons, and pagination]()
## Before you begin
You need access to a Beam workspace. Decide what the agent should do and which integrations it needs before you choose a template.
## Create an agent from a template
1. Open **Agent templates** from the workspace navigation.
2. Use **Categories** or **Search agents by name** to find a suitable template.
3. Read the template card's category, name, and description.
4. Select **Create agent**.
The available template catalogue can change. Use the live template card as the source of truth for the template's current purpose.
## Review the Flow
Open the created agent's **Flow**. The Flow page contains the agent graph and provides **Test mode** and **Publish** controls in its header.
Select a node to review its sidebar configuration. For a tool node, the current sidebar includes **Parameters**, **Settings**, and **Evaluation**. Parameters include input variables, the selected model, output variables, and integrations.
Learn how to work with the Flow canvas and node configuration.
## Configure inputs and integrations
Review each node's input variables and choose the fill method that matches the value source. Configure the integrations the agent needs before testing the Flow.
Choose how node inputs receive values at runtime.
Connect and manage the services an agent uses.
## Test before publishing
Enable **Test mode** from the Flow header to test the Flow with data from past executions. Test runs are separate from live Tasks, and integrations are sandboxed so tests do not create, update, or delete live records.
Learn how Test mode works and where to review test Tasks.
## Publish the agent
When the Flow is ready, select **Publish** from the Flow header. Review the Flow and its integrations before publishing.
Review the current publishing options.
## Next steps
Review the agent's Task executions.
Review available agent analytics.
# Agent Templates
Source: https://docs.beam.ai/01-getting-started/template-gallery/template-gallery
Browse, filter, and create agents from the templates available in your Beam workspace.
Agent templates provide a starting point for common agent workflows. Open **Agent templates** from the workspace navigation, then browse the templates available in your workspace.
![Agent templates gallery with categories, template cards, Create agent buttons, and pagination]()
## Browse templates
The Agent templates page includes:
| Control | Use it to |
| ------------------------- | --------------------------------------------------------------- |
| **New agent** | Start creating an agent without selecting a gallery template. |
| **Categories** | Filter the gallery by template category. |
| **Search agents by name** | Find a template by name. |
| Template cards | Read each template's category, name, and description. |
| **Create agent** | Start creating an agent from that template. |
| Pagination | Move through the available templates and adjust items per page. |
## Create an agent from a template
1. Open **Agent templates** from the workspace navigation.
2. Use **Categories** or **Search agents by name** to find a template.
3. Review the template card's category, name, and description.
4. Select **Create agent** on the template you want to use.
5. Review the created agent's **Flow**, integrations, and configuration before publishing it.
The templates shown in the gallery and their configuration requirements can change. Use the live template card as the source of truth for a template's current purpose and setup.
## Continue configuring the agent
After starting from a template, use the agent navigation to review **Flow**, **Configuration**, and **Tasks**. These pages let you inspect the agent's graph, connections, and executions.
Learn the current agent-creation paths.
Configure the agent's Flow.
Connect the services an agent needs.
# Welcome to Beam
Source: https://docs.beam.ai/01-getting-started/welcome/welcome
Start in your Beam workspace, ask Beam AI for help, and navigate to the surfaces used to build and run agents.
Beam gives you a workspace for asking Beam AI to perform a task or brainstorm an idea, then building and managing the agents that do that work.
![Beam AI Demo workspace home with the workspace picker closed and the left navigation sidebar visible]()
## Start in your workspace
Use the workspace picker in the top-left corner to switch workspaces; the active workspace has a check mark. The workspace home then shows **What do you want to work on?** and a composer for asking Beam to perform tasks or brainstorm ideas. Enter a task or idea there, then select the send arrow.
For a guided start, use the paths below.
Create an agent from a template and configure its Flow.
Browse the available agent templates.
Understand agents, Flows, tools, variables, tasks, and memory.
Orient yourself to workspace navigation, members, and integrations.
## Workspace navigation
The workspace navigation includes these surfaces:
| Surface | Use it to |
| ------------------- | ------------------------------------------------------------- |
| **Skills** | Open workspace skills. |
| **Projects** | Open workspace projects. |
| **Inbox** | Review workspace notifications. |
| **Tasks** | Review Tasks and test Tasks in the workspace. |
| **Agent templates** | Browse agent templates. |
| **Integrations** | Manage workspace integrations and create custom integrations. |
| **Views** | Open workspace Views. |
## Agent navigation
When you open an agent, its navigation includes **Chat**, **Tasks**, **Flow**, **Learning**, **Configuration**, and **Analytics**. Use **Flow** to build the agent's graph; the Flow page states that Flows run from chat or triggers. You can also enable **Test mode** from the Flow header before publishing changes.
Create an agent and choose how to start building it.
Configure a Flow with tools, conditions, and triggers.
Review an agent's Task executions.
## Next steps
Choose how each node input receives a value.
Connect the services your agent needs.
# Workspace Setup
Source: https://docs.beam.ai/01-getting-started/workspace-setup/workspace-setup
Create or join a workspace to start collaborating with your team on AI agent automation
Your Beam workspace is where your team collaborates on AI agent automation. Whether you're creating a new workspace or joining an existing one, setup takes just minutes.
## Navigate your workspace
The workspace home shows your agents and a chat composer for asking Beam to perform tasks or brainstorm. Use the workspace navigation to open **Skills**, **Projects**, **Inbox**, **Tasks**, **Agent templates**, **Integrations**, and **Views**.
## Understanding Workspaces
A workspace is your team's dedicated environment for building and managing AI agents. Each workspace keeps your team's agents, tasks, and integrations completely separate from other organizations using Beam.
**What's Included**:
* Team member access and permissions
* Shared agents and workflows
* Integration connections
* Task execution history
* Workspace-level settings
Beam offers SaaS (cloud-hosted), Managed Service (dedicated infrastructure), and Self-hosted deployment options. All provide the same workspace management experience.
## Creating Your Workspace
### Access Workspace Creation
1. Click the workspace dropdown in the top-left corner
2. Select **"Create or Join Workspace"**
3. Click the **"Create workspace"** tab
### Configure Workspace Details
**Workspace Name** (Required):
* Choose a descriptive name like "Engineering Team" or "Customer Success"
* Appears in workspace dropdown for all members
* Can be changed later in settings
**Domain** (Optional):
* Enter your company domain (e.g., yourcompany.com)
* Beam automatically fetches your company logo
* You can upload a custom logo instead
**Icon**:
* Automatically generated from workspace name
* Displays in the workspace selector
![]()
### Create and Invite Members
1. Click **"Create workspace"** button
2. Workspace created in 2-3 seconds
3. Optionally add team member emails to invite them now, or skip to invite later from workspace settings
![]()
You can add member emails at this step or click Continue to invite them later:
![]()
## Joining an Existing Workspace
If you've been invited by a team member, follow these steps.
### Check Your Invitation
You'll receive an email with:
* Workspace name and organization
* Your assigned role
* Access link or password login instructions
* Invitation expiry (typically 7 days)
**Authentication Methods**:
* **Magic Link**: Click link in email (most common)
* **Password Login**: Use email + password if magic links are blocked
If your magic link is invalidated immediately, your organization's email scanner is pre-clicking links. Use password login instead.
### Access Join Workspace
1. Navigate to Beam platform
2. Click workspace dropdown in top-left
3. Select **"Create or Join Workspace"**
4. Click **"Join workspace"** tab
![]()
### Accept Invitation
1. Review workspace name and inviting user
2. Confirm role and permissions
3. Click **"Join \[Workspace Name]"**
4. Access provisioned in 2-5 seconds
![]()
**Verify Success**:
* Workspace appears in top-left dropdown
* Can see workspace agents
* User role displays in profile settings
### Troubleshooting
**Problem**: Corporate email scanner interference
**Solution**:
1. Use password login fallback option
2. Request password reset if needed
3. Login with email + password
**Check**:
* Spam/junk folder
* Email address typo
* Corporate email filters
**Solutions**:
* Request admin resend invitation
* Try alternative email
* Contact IT about email filtering
**Causes**:
* Browser not refreshed
* Permissions not propagated (5-10 seconds)
* Different browser used
**Steps**:
1. Refresh page (Ctrl+R or Cmd+R)
2. Log out and back in
3. Clear browser cache
4. Verify workspace in dropdown
## Inviting Team Members
To invite people once the workspace exists:
1. Open the workspace dropdown and select **Settings**
2. Open the **Access** tab and stay on **People**
3. Select **Invite members**
4. Enter the email addresses, choose the **Role** those people should hold, and select **Send invite**
![The People list under the Access tab of Workspace settings, showing each member and the role they hold]()
Everyone you invite receives an email and appears in the People list with a **Pending
invitation** badge until they accept. They join by following the steps in "Joining an
Existing Workspace" above.
The role you pick decides which agents that person can reach and what they can do with them.
**Member** is filled in for you unless you change it. To build roles of your own, see
[Roles and Permissions](/05-resources/roles-and-permissions/roles-and-permissions).
## Next Steps
![]()
Start with pre-built agent templates
Deploy your first agent in minutes
Master agent development
Understand the platform fundamentals
# Custom Integrations
Source: https://docs.beam.ai/02-building-agents/advanced-patterns/custom-integrations/custom-integrations
Build an integration for an internal or proprietary platform from the workspace Integrations page
When you need connections to proprietary systems, internal tools, or services not in Beam's integration catalog, custom integrations let you build direct API connections.
![Custom integration builder with name, category, authentication, custom headers, and tool options]()
## When to Build Custom Integrations
Connect proprietary business systems and internal platforms
Integrate industry-specific platforms not in the catalog
Work with custom-built APIs and microservices
Implement specialized authentication requirements
**Before Building:**
* Check if the service exists in Beam's 1500+ integration catalog
* Have API documentation ready (OpenAPI spec preferred)
* Confirm authentication credentials and permissions
## Building a Custom Integration
In the workspace sidebar, open **Integrations**, then select **Create custom integration**.
**Name**: Clear, descriptive (e.g., "Acme CRM API")
**Upload an icon**: Optional, for visual identification
**Category**: Select appropriate category for filtering
Select **None**, **API Key**, **Basic**, or **OAuth (2.0)**. Add any required custom header keys and values in the header table.
Choose **Add tool** for manual tool setup or **Import from URL** to start from a specification URL. The builder also provides a **Bypass SSL verification** option.
**API Endpoint:**
* HTTP Method: GET, POST, PUT, PATCH, DELETE
* Endpoint URL with parameter placeholders
* Example: `https://api.vendor.com/orders/{order_id}`
![Tool configuration with endpoint and parameters]()
**Parameters:**
* **URL**: Path variables (`{order_id}`)
* **Query**: URL parameters (`?status=completed`)
* **Body**: JSON for POST/PUT/PATCH
![Query parameters configuration]()
Each parameter needs:
* Key (name)
* Type (String, Number, Boolean, Object, Array)
* Parameter hint (AI context)
* Required toggle
**Test Tool**: Validate with sample values before saving
Select **Save** to create the integration. Select **Discard** to leave the builder without saving.
## Using in Workflows
### Adding Custom Integration to Nodes
1. **Select Tool**: Browse to your custom integration in node configuration
2. **Choose Action**: Pick specific API operation
3. **Map Inputs**: Use variable fill methods to pass data
4. **Select Connection**: Choose which credentials to use
### Accessing Outputs
Custom integration outputs are accessible to downstream nodes:
```text theme={null}
${node_name.field_name}
```
**Example:**
```text theme={null}
Order ID: ${get_order.order_id}
Status: ${get_order.status}
Total: ${get_order.total}
```
## Authentication Methods
### API Key
Most common method. Configure where the key is sent:
* **Bearer**: `Authorization: Bearer {api_key}`
* **Header**: Custom header name
* **Query**: URL parameter
**Best Practice**: Use connection-level storage, rotate regularly, separate keys for environments
### OAuth 2.0
Secure, user-authorized access:
**Authorization Code**: User explicitly authorizes, supports token refresh
**Client Credentials**: Machine-to-machine, no user authorization
**Required**: Authorization URL, Access Token URL, Scopes, Client ID/Secret
### Basic
Username/password for legacy systems. Less secure than modern methods.
## Schema Definition
### OpenAPI Import
Fastest setup for documented APIs:
1. Provide OpenAPI spec URL
2. System generates tools automatically
3. Review and activate endpoints
Supports OpenAPI 3.0.x, 2.0 (Swagger), JSON or YAML
### Manual Schema
For APIs without OpenAPI specs:
```json theme={null}
{
"tool_name": "Get Order Details",
"description": "Retrieve order information",
"required_extracted_args": [
"order_id: string // Order identifier"
],
"integration_provider_details": {
"request": {
"method": "GET",
"endpoint": "https://api.vendor.com/orders/{order_id}"
},
"response": {
"order_id": "{{result.data.id}}",
"status": "{{result.data.status}}"
}
}
}
```
## Testing
**Test Tool Feature:**
1. Open tool configuration
2. Click "Test tool" tab
3. Provide sample values
4. Verify response structure
**Test in Workflow:**
* Build minimal flow with static data
* Run task manually
* Review execution results
* Verify data flows to next nodes
## Common Errors
**401 Unauthorized**: Check credentials, token expiration, OAuth scopes
**400 Bad Request**: Verify required parameters, types, formats
**429 Too Many Requests**: Add delays, use caching, batch operations
**Request Timeout**: Check endpoint accessibility, optimize queries
## Advanced Patterns
**Dynamic Endpoints**: Use variable substitution
```text theme={null}
https://api.vendor.com/tenants/{tenant_id}/orders/{order_id}
```
**Pagination**: Loop through pages, extract next token, aggregate results
**Response Transformation**: Use Custom GPT tools to process raw API data into structured outputs
## Best Practices
**Security:**
* Never expose API keys in logs
* Separate credentials for dev/staging/prod
* Rotate credentials regularly
**Performance:**
* Minimize unnecessary requests
* Cache frequently accessed data
* Respect rate limits
**Maintenance:**
* Document API version in integration name
* Test after API updates
* Monitor provider changelogs
## Examples
### Internal CRM
* **Auth**: API Key (Header)
* **Tools**: Get Customer, Create Customer, Update Status
* **Use**: Workflow creates CRM record on signup
### Legacy ERP
* **Auth**: Basic Authentication
* **Tools**: Query Inventory, Create PO, Update Status
* **Use**: Check inventory before order, create PO if low
### Microservices
* **Auth**: OAuth 2.0 (Client Credentials)
* **Tools**: Process Order, Calculate Shipping, Validate Payment
* **Use**: E-commerce workflow orchestrates multiple services
## Next Steps
Enable agents to call other agents for complex workflows
Learn about pre-built integration catalog
Design predictable output schemas for integrations
Enable agents to share data and coordinate workflows
# Loop Nodes
Source: https://docs.beam.ai/02-building-agents/advanced-patterns/loop-node/loop-node
Iterate over an array or run a fixed number of passes inside a flow to process multi-item payloads sequentially
A Loop Node runs a section of your flow once per element in an array, or a fixed number of times. It is the right primitive when a single task carries multiple items that each need the same processing, for example a batch of documents, a list of order line items, or a set of records returned by an upstream API call.
## When to Use a Loop Node
Run the same set of steps against each element of an array produced by an earlier node
Repeat a section of the flow a known number of times, for example for retry passes
Spawn one child task per item against another agent for parallel-style orchestration
Collect per-iteration outputs into a single array for a downstream node to summarise
## Loop Modes
A Loop Node operates in one of two modes, either (fixed) Iteration count or Linked.
**Count Mode (fixed iterations):**
* The loop runs its body a fixed number of times, set as a static value.
* No per-iteration data is passed to the body automatically.
* Best for retry loops or any flow where the body does not depend on per-iteration data.
**Linked Mode (array-driven):**
* The loop reads an array variable from an upstream node and runs its body once per element.
* Iteration count is derived from the array length at runtime.
* Each iteration exposes a single element of the array to the body via Linked variable fill.
* Best for "do the same thing to every item" workflows.
## Building a Loop
Insert a Loop Node at the point in the flow where iteration should begin. The body nodes you add afterwards will run inside the loop.
Pick **Count** for fixed-iteration mode, or **Items to loop through** for Linked mode.
For Count mode, enter the number of iterations as a static value.
For Linked mode, use the picker to select an array variable emitted by an earlier node. The loop will iterate once per element in that array.
Add the nodes that should run on each iteration directly inside the loop container. The body can be a single node or a chain of nodes.
When the body has more than one node, wire them together with edges in the canvas the same way you would outside a loop. Studio adds the required edges automatically when you connect nodes via the UI.
Inside the loop body, configure the first node's input to use **Linked** fill against the loop's array source. At runtime Beam injects one element per iteration into that input.
The body sees one element at a time, not the full array. The shape of the element matches whatever shape the upstream node produced for each entry in the array.
After the loop, add the nodes that should consume the loop's collected output. Downstream nodes link to the loop node itself, not to any single body node.
## How the Loop Body Reads Data
In Linked mode, the body sees one element of the source array per iteration via the Linked variable it was configured with. That element is the only per-iteration value injected automatically.
The iteration index is not exposed to the body as a directly readable variable. If your body logic needs to know which item it is processing, include that information inside each element of the source array (for example a `position` field) rather than expecting a free iteration-counter variable.
The iteration index does appear in runtime telemetry on each body-node execution record as `loopingNodeIterationCount`, useful for inspecting individual iterations in task views, but it is not a value your body code can read at runtime.
## Loop Output Shape
After the loop completes, post-loop nodes can read the loop's collected output as an array. Each entry in the array represents one iteration and contains the output of the body's inner nodes for that iteration.
When the body has a single inner node, each entry contains that node's output. When the body has multiple inner nodes, each entry contains the outputs of all body nodes for that iteration, keyed by their position in the body.
Downstream nodes typically pass the loop output to a summariser node or write each entry to an external system in a follow-on step.
## Troubleshooting
**Cause:** The Linked source is not actually wired, or the array variable id has not been saved on the loop node.
**Things to check:**
* The loop node's Linked picker shows the source variable, not an empty field.
* The upstream node that produces the array is published and emitting that variable in recent task runs.
* The variable id stored on the loop matches a real output id on the source node.
When Linked mode is configured but the array source is missing, the loop falls back to a single-iteration pass and the body receives the source as-is (often as the whole array rather than one element).
**Cause:** The inner nodes are not edged together. Studio's canvas enforces edges between sibling body nodes when you wire them via the UI, but body nodes added through other paths can end up unconnected.
**Things to check:**
* In the canvas, confirm there is an explicit edge from body node 1 to body node 2 (and so on).
* The first body node has an edge from the loop, the last body node has an edge to the loop's exit.
Without sibling edges, only the first body node runs each iteration and subsequent body nodes are silently skipped.
**Cause:** When a parent flow passes a structured object as the `query` field of a Create Agent Task request, the child task's `task_query.query` arrives JSON-stringified.
**Solution:** In the child agent's first node, `JSON.parse(input.task_query)` (or the equivalent in your tool's prompt) before reading nested fields. This is a normal artefact of the request body schema, not a Loop Node behaviour, but it shows up frequently in loop-driven fan-out and is worth knowing.
**Cause:** Studio's link picker on a body-node input filters by static type compatibility. When the body input is typed `object` and the loop's source is typed `object[]`, the picker may not surface the array as a selectable source, even though Beam auto-unwraps one element per iteration at runtime.
**Things to check:**
* The body input's declared type matches the per-element shape of the source array, not the array shape itself.
* If the picker still does not show the source, configure the Linked variable via the Agent Graph API by setting `fillType: linked` and `linkParamOutputId` to the source array's output id. Beam injects one element per iteration regardless of how the link was configured.
## Next Steps
Build the Custom Integration used in the fan-out pattern
Understand single-task agent-to-agent triggering
Configure Linked variable fill for per-iteration inputs
Reference for the endpoint called by the fan-out integration
# Multi-Agent Collaboration
Source: https://docs.beam.ai/02-building-agents/advanced-patterns/multi-agent-collaboration/multi-agent-collaboration
Enable agents to call other agents for complex workflow orchestration and specialized task delegation
Multi-agent collaboration allows one agent to trigger another agent within a workflow, enabling orchestration where specialized agents handle specific tasks while a coordinator manages the overall process.
## Understanding Multi-Agent Systems
Rather than building monolithic agents that handle everything, create specialized agents that excel at specific tasks and coordinate them through agent-to-agent communication.
Build focused agents optimized for specific domains or tasks
Use the same specialized agents across multiple workflows
Update individual agents without affecting the entire system
Coordinate complex processes with clear separation of concerns
## How Agent Triggering Works
Agents trigger other agents using the **"Trigger Agent Task"** tool within workflow nodes.
![The current Beam Flow canvas with triggers, conditions, integration steps, and connected branches.]()
**The Process:**
1. Parent agent reaches a node with "Trigger Agent Task"
2. Payload data is passed to the target agent
3. Target agent executes its workflow
4. Result is returned to parent agent
5. Parent agent continues execution
## Triggering Agents from Workflows
Add a new node where you want to trigger another agent
Choose **"Trigger Agent Task"** from the tool selector
![Trigger Agent Task tool configuration]()
Specify which agent to trigger:
**Static Configuration:**
* Hardcode agent name: "Demo: Email Triage Agent"
* Best for fixed orchestration
**Dynamic Configuration:**
* Agent name from previous node output
* Enables conditional routing to different agents
Define what data to send to the target agent:
![Payload configuration with linked variables]()
**Payload Variable:**
* Use "Linked" to pass data from previous nodes
* Example: `${query_filter.CleanedConversation}`
* The payload becomes the `task_query` input for the target agent
The triggered agent returns its result
**Access results:**
```
${trigger_node.output_variable}
```
Output structure depends on the target agent's configuration
## Tool Execution Modes
**Fully Automated:**
* Agent triggers automatically
* Best for trusted collaborations
* Fastest execution
**Consent Required:**
* Pauses for user approval before triggering
* Best for critical operations or testing
* Shows what data will be sent
## Troubleshooting
**Error:** "Agent '' not found"
**Solutions:**
* Verify exact agent name (case-sensitive)
* Check agent exists and is published
* Update configuration if agent renamed
**Issue:** Target agent doesn't receive expected data
**Solutions:**
* Verify previous node outputs contain data
* Check variable names match exactly
* Review target agent's expected input format
**Issue:** Agent A triggers Agent B which triggers Agent A
**Solutions:**
* Add recursion depth tracking in payload
* Implement max iteration limits
* Redesign to avoid circular dependencies
## Next Steps
Deploy multi-agent systems to production
Learn advanced flow patterns for orchestration
Understand data passing between agents
Design output schemas for agent responses
# Publishing & Deployment
Source: https://docs.beam.ai/02-building-agents/advanced-patterns/publishing-deployment/publishing-deployment
Run a Flow draft, publish it, review its version history, and find the current API reference.
Each Flow has a current draft, publishing controls, and version history. Use the Flow canvas to run the draft before publishing, then use the API Reference for the current programmatic build and publishing endpoints.
## Publish your agent
Open the agent's **Flow**. The header shows the current draft state and the **Publish** control.
Select **Execute flow** to run the draft version of the Flow before you publish it.
Select **Publish** when the Flow is ready to make the current draft the active version.
Open the **Draft** control to view the current draft and previous Flow versions. The current active version is identified in the history.
![The Flow header's Version history menu showing the current unpublished draft and a previous active version.]()
## Use the API
Beam's API supports programmatic agent-building and publishing workflows. Endpoint names and request formats can change, so use the generated [API Reference](/08-reference/api/overview/overview) for the current API details rather than copying endpoint examples from this guide.
## Drafts and version history
Use **Execute flow** to test the draft. The **Draft** control opens version history, where Beam distinguishes the current draft from previous active Flow versions.
## API documentation
For complete API reference, authentication details, and current endpoint documentation, see the [API Reference](/08-reference/api/overview/overview).
## Next steps
Complete API documentation and endpoints
Coordinate multiple agents in production
Automate agent execution with triggers and webhooks
Monitor and track production tasks
# Integrations
Source: https://docs.beam.ai/02-building-agents/agent-configuration/integrations/integrations
Browse workspace integrations, add a connection, and use an integration when configuring an agent Flow.
Integrations are available at the workspace level. Use this page to find a service, add a connection, and review connections that already exist in the workspace.
![The Integrations page with the Available integrations tab, category and listing filters, integration cards, Add a connection buttons, and pagination.]()
## Browse available integrations
Open **Integrations** from the workspace navigation, then select **Available integrations**. The page includes:
* **Categories** to filter the integration gallery.
* **Listing** to change which integrations appear.
* **Search integrations by name...** to find a service.
* Integration cards with a category, name, description, and **Add a connection** action.
* Pagination controls for browsing the gallery.
## Add a connection
1. Open **Integrations** in the workspace navigation.
2. Select **Available integrations**.
3. Use **Categories**, **Listing**, or search to find the service you need.
4. Select **Add a connection** on its card.
## Review workspace connections
Select the **Connections** tab to review integrations that are already connected in the workspace.
## Create a custom integration
If the gallery does not contain the service you need, select **Create custom integration**. See [Custom Integrations](/02-building-agents/advanced-patterns/custom-integrations/custom-integrations) for the builder workflow.
## Use an integration in a Flow
Add an integration as a step from the Flow canvas:
1. Open the agent's **Flow**.
2. Add a new step where you need the integration.
3. In the **Add step** picker, select **Integration**.
4. Choose the integration and configure the step's input variables.
To replace an existing step, open that step's actions menu, select **Replace**, then choose the replacement from the same **Add step** picker.
For fill-method guidance, see [Variable Fill](/02-building-agents/agent-configuration/variables-state/variables-state). For choosing and configuring tools, see [Selecting Tools](/02-building-agents/agent-fundamentals/tools-integrations/tools-integrations).
## Next steps
Choose tools for an agent Flow.
Supply the right value to each tool input.
Build an integration that is not in the gallery.
# Structured Outputs
Source: https://docs.beam.ai/02-building-agents/agent-configuration/structured-outputs/structured-outputs
Configure named outputs for an AI step and link them to later Flow steps.
Structured outputs are named values produced by an AI step. Configure them in the step's **Parameters** sidebar, then use them as linked inputs in later steps.
## Understanding structured outputs
Each output variable has a name, a **Data type** selector, a **Make array** control, and a required description. Add as many outputs as the AI step needs.
**Why use structured outputs:**
* Keep related results as separate, named values.
* Describe the value and data type the AI step should return.
* Link a selected output directly to a downstream input.
* Use **Make array** when an output needs multiple values of the same type.
## Configure output variables
Output variables are defined in an AI step's **Parameters** tab.
Open the agent's **Flow**, select the AI step that produces the result, and keep **Parameters** selected in the sidebar.
In **Output variables**, select **Add new**.
Enter the output name, select a **Data type**, optionally enable **Make array**, and provide the required description.
Select **Add new** again to define another value for the same node.
### Multiple output variables
Use one output variable for each value a later step needs. For example, an AI step can return a summary, search terms, and a title as separate outputs.
![An AI step's Output variables section with separate bug_summary, search_keywords, and title outputs, each with a data type and description.]()
## Data types
**String:** Text data of any length. Use for names, descriptions, categories.
**Number:** Numeric values including integers and decimals. Use for IDs, quantities, amounts, scores.
**Boolean:** True or false values. Use for flags, status indicators, yes/no determinations.
**Object:** Nested data for complex, grouped values. Select **Object** in **Data type**, then select **Define structure** to add the properties the object should contain.
![The output variable Data type menu with Object available as a type.]()
**Enum:** Constrained to specific allowed values. Use for fixed categories, status values.
**Example:**
```text theme={null}
Variable: priority_level
Type: Enum
Allowed values: HIGH, MEDIUM, LOW
```
## Key principles
### Order related values clearly
For a complex extraction, group related outputs together and use names that make their relationship clear.
**Example:**
```json theme={null}
{
"request_summary": "",
"urgency_analysis": "",
"is_urgent": "",
"category_reasoning": "",
"category": "",
"priority": ""
}
```
### Keep rationale when it is useful
If a later step or reviewer needs the rationale behind a classification, add a separate reasoning output alongside the final value.
**Poor Design:**
```json theme={null}
{
"category": ""
}
```
**Better Design:**
```json theme={null}
{
"category_reasoning": "",
"category": ""
}
```
This keeps the classification and its explanation as distinct values that later steps can use independently.
### Descriptions are directives
The description is a direct instruction to the AI. Be explicit.
**Examples:**
**Simple extraction:**
```text theme={null}
"Extract the 7-digit customer ID, numbers only"
```
**Conditional logic:**
```text theme={null}
"Extract language as ISO-639-1 code. If unknown, return 'N/A'"
```
**Constrained values:**
```text theme={null}
"Classify as one of: EXACT_MATCH, SIMILAR_MATCH, MISMATCH, or N/A"
```
### Unique naming
Give each output a clear, unique name so it is easy to choose in a later step.
**Good naming:**
* `email_classifier_category`
* `invoice_extractor_total`
* `customer_analysis_id`
**Avoid:**
* `result`, `output`, `data` (too generic, likely duplicated)
## Linking outputs to downstream nodes
To use an output in a later step, select that input's fill-method menu, choose **Linked fill**, then select the output variable.
![A downstream integration step's input variable with the Linked fill menu open and an output variable selected.]()
The variable picker lists output variables from earlier steps in the Flow.
See [Variables & State](/02-building-agents/agent-configuration/variables-state/variables-state) for detailed linking patterns.
## Common patterns
**Classification + Data Extraction:**
```json theme={null}
{
"classification": "",
"customer_id": "",
"urgency_level": ""
}
```
Use: Branch workflow based on `classification`, pass `customer_id` to CRM lookup, use `urgency_level` for prioritization.
**Validation with Confidence:**
```json theme={null}
{
"extracted_value": "",
"confidence_score": "",
"needs_review": ""
}
```
Use: Branch on `needs_review` - high confidence → automate, low confidence → human review.
**Handling Arrays:**
For multiple values of the same type, enable **Make array** for the output variable:
```text theme={null}
Variable: products
Data type: String
Make array: enabled
Description: Product names found in the order
```
Use **Object** and **Define structure** when each array item needs its own nested properties.
## Best practices
**Naming Conventions:**
* Prefix with tool purpose: `email_classifier_category`, `invoice_extractor_total`
* Use descriptive names: `customer_priority_score` not `score`
* Avoid generic names: Don't use `result`, `output`, `data`
**Separation of Concerns:**
Don't combine everything into one field. Split outputs logically:
```json theme={null}
{
"customer_name": "",
"customer_email": "",
"order_id": "",
"priority": ""
}
```
**Error Handling:**
Design outputs to capture extraction confidence:
```json theme={null}
{
"extracted_date": "",
"date_confidence": "",
"extraction_notes": ""
}
```
**Performance Optimization:**
Minimize unnecessary reasoning fields in high-volume workflows. Use reasoning for critical extractions, skip for simple operations.
## Troubleshooting
**Issue:** AI returns string when you expected number
**Solutions:**
* Make description more explicit: "Extract as a number, digits only, no text"
* Check if source data actually contains the expected type
* Add validation in description: "If not a number, return 0"
**Issue:** AI returns dates in different formats
**Solutions:**
* Be prescriptive: "Return date in YYYY-MM-DD format exactly"
* Provide examples in description: "Format: 2024-01-15"
* Use constrained values (Enum) when possible
**Issue:** Some outputs are empty or null
**Solutions:**
* Add fallback instructions: "If not found, return 'N/A'"
* Check if AI has access to required input data
* Verify previous nodes are passing data correctly
**Issue:** Downstream node can't access structured output
**Solutions:**
* Confirm the source step runs before the step that consumes it
* Open the destination input's fill-method menu and select **Linked fill**
* Select the expected output variable from the variable picker
## Next steps
Learn how to link structured outputs between nodes
Choose AI steps and integrations for an agent Flow.
Pass linked outputs to integration steps.
Use structured outputs for branching and routing
# Variable Fill
Source: https://docs.beam.ai/02-building-agents/agent-configuration/variables-state/variables-state
Configure how each tool input receives a value while an agent flow runs.
Variables control how data moves through an agent flow. For every input variable on a node, choose the fill method that supplies its value at runtime.
## Fill methods
Beam provides seven fill methods:
AI fills the value automatically.
AI fills the value from the description you provide.
Uses an output from another tool in the flow.
Uses a fixed value that you enter manually.
Prompts the user to provide the value at runtime.
Looks up the value from the agent's memory.
Extracts the value from a task attachment.
## Configure a variable
1. Open the agent's **Flow**.
2. Select the node that needs the input.
3. In the node sidebar, open **Parameters**.
4. Under **Input variables**, select the variable's current fill method.
5. Choose the fill method that matches the source of the value.
![A Flow node's Parameters sidebar with the Input variables fill-method menu open.]()
## Choose the right fill method
| If the value... | Use |
| ------------------------------------------------- | --------------- |
| Should be produced automatically by AI | Auto fill |
| Needs instructions that tell AI how to produce it | Prompt fill |
| Comes from an earlier tool output | Linked fill |
| Is fixed for every execution | Static fill |
| Must be supplied by a user during execution | User fill |
| Should be looked up in the agent's memory | Memory fill |
| Comes from a task attachment | Attachment fill |
## How each fill method works
### Auto fill
Use Auto fill when Beam can determine the value without an explicit instruction. The node fills the value automatically from the available execution context.
### Prompt fill
Use Prompt fill when the node needs your instructions for how to produce the value. Write a clear description of the required value and format in the variable's value field.
### Linked fill
Use Linked fill to pass an earlier node's output to a later node. The source node must run before the node that consumes the linked value.
### Static fill
Use Static fill for a value you enter once and want to keep the same for every execution, such as a fixed identifier or configuration value.
### User fill
Use User fill when the person running the task must provide the value at runtime.
### Memory fill
Use Memory fill when a node needs knowledge from the agent's Memory module. Add documents in **Configuration → Memory**, then use Memory fill to look up a value from that knowledge base. See [Core Concepts](/01-getting-started/core-concepts/core-concepts#memory) for how agent memory works.
### Attachment fill
Use Attachment fill when the node needs to extract a value from a file attached to the task.
## Next steps
Choose and configure tools for your agent.
Build a flow with tools, conditions, and triggers.
Configure integration-specific variable patterns and connectors.
Build custom API connections for advanced integration patterns.
# Creating Agents
Source: https://docs.beam.ai/02-building-agents/agent-fundamentals/creating-agents/creating-agents
Start an agent from a workspace template or the New agent entry point, then configure its Flow and connections.
Create agents from **Agent templates** in the workspace navigation. You can start from a template card or use **New agent** to begin without selecting a gallery template.
![Agent templates gallery with New agent, category filters, template cards, and Create agent buttons]()
## Start from a template
1. Open **Agent templates** from the workspace navigation.
2. Filter with **Categories** or search with **Search agents by name**.
3. Review the category, name, and description on the template card.
4. Select **Create agent** on the template you want to use.
The current gallery is the source of truth for the templates available in your workspace.
## Start a new agent
Select **New agent** on the Agent templates page when you want to begin without choosing a gallery template. Review the resulting agent's Flow and configuration before publishing it.
## Configure the agent
An agent's navigation includes **Chat**, **Tasks**, **Flow**, **Learning**, **Configuration**, and **Analytics**.
Use these surfaces to continue setup:
| Surface | Use it to |
| ----------------- | --------------------------------------------------------------------------------------------- |
| **Flow** | Review and configure the agent graph. The Flow header includes **Test mode** and **Publish**. |
| **Configuration** | Open agent-level configuration, including its Memory module. |
| **Tasks** | Review the agent's Task executions. |
| **Analytics** | Review the agent's available analytics. |
For a selected tool node, the Flow sidebar has **Parameters**, **Settings**, and **Evaluation**. Parameters include input variables, the selected model, output variables, and integrations.
## Add memory and integrations
Add documents in **Configuration → Memory** when an agent needs files as knowledge. Configure workspace integrations and node inputs before testing the Flow.
Add memory files and choose how node inputs receive values.
Connect the services an agent uses.
## Add a trigger
The Flow canvas starts with a **Trigger** node. Select it to review existing trigger cards or use **Add trigger**. In the audited Gmail Flow, an existing trigger opens controls for its connection, context, filters, conditions, groups, and **Configure & test**.
Configure the verified trigger editor controls.
## Next steps
Configure the agent's graph.
Test the Flow before publishing it.
Review the current publishing controls.
# Creating Flows
Source: https://docs.beam.ai/02-building-agents/agent-fundamentals/flow-configuration/flow-configuration
Build and review an agent Flow from its canvas and node sidebar, then test it before publishing.
A Flow is the graph that an agent runs from chat or triggers. Open an agent's **Flow** page to work on its canvas and node configuration.
![Current Flow canvas with Trigger, Linear Create Issue, and Slack Send Message to Channel nodes, with the Trigger sidebar open]()
## Flow page controls
The Flow header includes:
| Control | Use it to |
| ------------- | ---------------------------------------- |
| **Draft** | See the Flow's current draft state. |
| **Test mode** | Turn on Test mode before testing a Flow. |
| **Publish** | Publish the Flow when it is ready. |
The canvas begins with a **Trigger**. Add later steps from the blue **+** control at the end of the Flow.
## Build on the canvas
1. Open the agent's **Flow** page.
2. Use the blue **+** control to add a step.
3. Select a node to open its sidebar.
4. Configure the node, then review the Flow before testing it.
## Add a step
Select the blue **+** control at the end of a path to open **Add step**. In the modal, choose **AI**, **Integration**, **Controls**, or **Utilities**.
You can describe what the step should do and select **Create with AI**, or select **Add blank step** to configure it yourself.
![Current Add step modal with AI, Integration, Controls, and Utilities categories, a task description field, Create with AI, and Add blank step]()
## Configure a tool node
Select a tool node to open its sidebar. The sidebar has **Parameters**, **Settings**, and **Evaluation** tabs.
| Parameters section | What you configure |
| ------------------- | ------------------------------------ |
| **Connection** | The connected account the tool uses. |
| **Input variables** | How the tool receives its inputs. |
| **Model** | The model assigned to the tool node. |
![Current Flow tool-node sidebar showing a Linear connection, input variables with Static fill and Auto fill, and the Configure and test button]()
Choose how each input variable gets a value.
Configure output variables for a node.
## Configure the trigger
Select the **Trigger** node, then select its configured trigger card. For a Gmail **New Email Received** trigger, the sidebar lets you set the trigger name, connection, optional trigger context, and filters such as **Has attachment**, **Should Trigger On Reply**, and **Contains body**. Select **Configure & test** when ready to test that trigger setup.
![Current Gmail New Email Received trigger configuration with trigger name, Gmail connection, trigger context, filters, and Configure and test]()
Configure the verified current trigger editor.
## Test and publish
Turn on **Test mode** in the Flow header before testing the Flow. Use the current testing controls to review the Flow before publishing.
When the Flow is ready, select **Publish** from the header.
Learn how Test mode works.
Review current publishing controls.
# Selecting Tools
Source: https://docs.beam.ai/02-building-agents/agent-fundamentals/tools-integrations/tools-integrations
Choose AI, Integration, Controls, or Utilities steps for an agent Flow.
Tools determine what a node does in a Flow. The current Flow canvas begins with a Trigger and can contain tool and LLM-based Condition nodes.
![The current Flow canvas showing a Trigger, a tool node, and an LLM-based Condition node.]()
## Choose a step type
Use the **Add step** modal to choose one of four categories: **AI**, **Integration**, **Controls**, or **Utilities**. The modal is the current entry point for adding Flow steps.
| If the Flow needs to... | Choose |
| ------------------------------------------- | --------------- |
| Perform model-driven work from instructions | **AI** |
| Interact with a connected external service | **Integration** |
| Control Flow logic or timing | **Controls** |
| Run a built-in helper | **Utilities** |
### AI
Use **AI** to describe the work a prompt step should perform. Prompt steps can also use tools when they need to call supported capabilities as part of that work.
### Integration
Use **Integration** to browse connected-service actions or create a custom integration. **Trigger Agent Task** is available in **Integration → Beam Tools**.
### Controls
Use **Controls** to direct execution without selecting an AI or service action:
* **Loop** repeats steps for a collection or condition.
* **Condition** routes execution based on a condition.
* **Wait** pauses the Flow before it continues.
* **Exit** ends the current Flow path.
### Utilities
Use **Utilities** for built-in helper steps, such as file and document processing. Available utilities can change with the workspace, so use the modal as the source of truth.
## Configure a tool node
1. Open the agent's **Flow**.
2. Select the tool node you want to configure.
3. Use the node sidebar to review **Parameters**, **Settings**, and **Evaluation**.
4. In **Parameters**, configure the node's input variables, model, output variables, and integrations as needed.
5. Choose a fill method for every input variable.
The exact available inputs depend on the selected tool. See [Variable Fill](/02-building-agents/agent-configuration/variables-state/variables-state) for the current fill methods.
## Use an integration
Use an **Integration** step when a node needs an external service. First, add or review the workspace connection from **Integrations**, then configure the integration section of the node's **Parameters**.
See [Integrations](/02-building-agents/agent-configuration/integrations/integrations) for the current gallery, connection entry point, and workspace Connections tab.
## Use a custom integration
Select **Create custom integration** from the workspace **Integrations** page when the gallery does not contain the service you need. See [Custom Integrations](/02-building-agents/advanced-patterns/custom-integrations/custom-integrations) for the current builder entry point and verified controls.
## Evaluate and require consent
The node sidebar includes an **Evaluation** tab and a **Settings** tab. Use **Settings → Consent required** when a task must pause for approval before the selected node proceeds.
For the verified evaluation controls, see [Evaluation Framework](/04-observability-analytics/evaluation-framework/evaluation-framework). For consent behavior, see [Automation Modes](/03-running-operations/task-management/automation-modes/automation-modes).
## Next steps
Build and inspect the current Flow canvas.
Browse integrations and add workspace connections.
Supply values to each node input.
# Debug Tools
Source: https://docs.beam.ai/03-running-operations/debugging-testing/debug-tools/debug-tools
Inspect agent task execution and configure a Flow node with sample input before testing its output
Debug tools help identify and resolve issues in agent workflows through systematic error analysis, node-level testing, and execution tracing.
## Understanding Debug Tools
Beam provides multiple debugging approaches for different scenarios:
**Test Tool** - Isolate and test individual nodes with mock input data to debug specific workflow steps
**Error Handling** - Configure how agents respond to failures, including continue-on-error and retry logic
**Execution Logs** - Detailed step-by-step traces showing inputs, outputs, and errors for each node
## Test a Flow node
Use **Configure & test** from a Flow node to inspect its connected input variables, provide sample input, and review the node's test output.
Open your agent's [Flow](/02-building-agents/agent-fundamentals/flow-configuration/flow-configuration) and select the node you want to inspect.
In the node sidebar, select **Configure & test**.
Review the node's input variables from connected nodes. Use **Input method** and **Run sample input** to provide data for the test.
After sample input is available, use **Test output** to run the tool and review the result.
**Node Producing Unexpected Output:**
* Data extraction returning wrong values
* Classification categorizing incorrectly
* Integration call failing
* Field mapping errors
**Validating Prompt Changes:**
* Test new prompts before full workflow run
* Compare outputs with different prompt versions
* Verify edge case handling
**Debugging Integration Nodes:**
* Test API authentication
* Validate request/response format
* Check integration configuration
* Verify data transformation logic
**Use Real Production Data:**
* Test with actual failed task inputs
* Include edge cases from production
* Cover variety of input formats
**Iterative Testing:**
* Test → Adjust → Test cycle
* Small changes between iterations
* Document what works
**Compare Before/After:**
* Test with old configuration
* Make single change
* Test with new configuration
* Measure improvement
**Build Test Case Library:**
* Save successful test inputs
* Reuse for regression testing
* Share with team for consistency
## Error Handling Configuration
Configure how agents respond to errors at workflow and node levels.
### Continue on Error
Allow workflow to proceed even when specific nodes fail.
**Node-Level Setting:**
* Enable "Continue on error" in node configuration
* Workflow proceeds to next step even if this node fails
* Failed node output marked as error, available to downstream nodes
* Useful for non-critical steps where failure shouldn't block entire workflow
**Use Cases:**
* Optional data enrichment that shouldn't block processing
* Logging or notification steps
* Non-essential validation checks
* Backup or fallback operations
**When to Enable:**
* Step is optional for workflow completion
* Downstream nodes handle missing data gracefully
* Failure rate is acceptable (e.g., external API occasionally unavailable)
* Manual review will catch issues later
**When NOT to Enable:**
* Critical data extraction or validation
* Security or compliance checks
* Payment or transaction processing
* Data accuracy is paramount
**Implementation:**
1. Open node configuration in Flow builder
2. Locate "Error Handling" section
3. Toggle "Continue on error" option
4. Test with failing scenarios to verify behavior
5. Publish workflow changes
When upstream node fails with "Continue on error" enabled:
**Downstream Node Strategy:**
* Check if required input exists before processing
* Use conditional branches to route around missing data
* Provide default values for missing fields
* Flag task for human review when critical data missing
**Example Workflow:**
* Node 1: Extract invoice data (Continue on error: enabled)
* Node 2: Check if invoice\_amount exists
* Branch A: Amount exists → Process payment
* Branch B: Amount missing → Route to inbox for manual review
### Auto-Retry on Error
Automatically retry failed steps to handle transient errors.
**Retry Configuration:**
* Set maximum retry attempts (typically 1-3)
* Configure retry delay between attempts
* Specify error types that trigger retry vs immediate failure
**Common Retry Scenarios:**
* API timeout errors (network issues)
* Rate limiting (429 errors)
* Temporary service unavailability (503 errors)
* Database connection failures
**Appropriate for Retries:**
* Network timeouts
* Temporary service outages
* Rate limiting
* Resource temporarily unavailable
**NOT Appropriate for Retries:**
* Authentication errors (won't resolve with retry)
* Invalid request format (will fail again)
* Missing required data
* Business logic errors
**Retry Strategy:**
* Start with 2 retries maximum
* Use exponential backoff for delays
* Monitor retry frequency
* High retry rates indicate underlying issue needing fix
## Execution Logs and Tracing
Analyze detailed execution logs to identify root causes of failures.
### Accessing Execution Logs
View step-by-step execution details for any task. See [Task Executions](/03-running-operations/task-management/task-executions/task-executions) for comprehensive monitoring guidance.
Go to Tasks page and select failed or problematic task execution.
See complete workflow execution with each node's status, duration, and output.
Click failed node to view error message, input data received, and attempted output.
Examine error type, stack trace (for integration errors), and contextual information.
**Data Format Errors:**
* Symptom: Node expecting JSON receives text
* Solution: Check upstream node output format, update extraction prompt
**Missing Required Fields:**
* Symptom: Node fails with "field X is required"
* Solution: Verify upstream extraction captured all fields, check input data completeness
**Integration Authentication Errors:**
* Symptom: 401 Unauthorized from API calls
* Solution: Verify integration credentials in Integrations page, re-authenticate if expired
**Timeout Errors:**
* Symptom: Node exceeds execution time limit
* Solution: Optimize prompt complexity, reduce input size, or enable auto-retry
**Context Window Exceeded:**
* Symptom: Silent failure or truncation errors
* Solution: Reduce input size, summarize before processing, or split into smaller chunks
**Systematic Debugging Approach:**
1. **Reproduce Error:**
* Identify exact input causing failure
* Rerun task to confirm error persists
* Note if error is consistent or intermittent
2. **Isolate Failed Step:**
* Identify which node failed
* Review input that node received
* Check if input matches expected format
3. **Test in Isolation:**
* Use Test Tool with same input
* Verify error reproduces
* Try variations to find working input
4. **Identify Root Cause:**
* Prompt issue (unclear instructions)
* Integration issue (API error, auth failure)
* Data issue (malformed input, missing fields)
* Configuration issue (wrong tool selected, invalid parameters)
5. **Apply Fix:**
* Update prompt, configuration, or integration
* Test fix with same input
* Verify resolution
6. **Validate:**
* Rerun original failed task (see [Rerunning Tasks](/03-running-operations/debugging-testing/rerunning-tasks/rerunning-tasks))
* Run test dataset with similar cases (see [Test Datasets](/03-running-operations/debugging-testing/test-datasets/test-datasets))
* Monitor for recurrence in [Task Executions](/03-running-operations/task-management/task-executions/task-executions)
## Test mode
Use **Test mode** in an agent's Flow to configure a bounded test run with the connections used by its trigger and integration nodes.
![The Set up test mode dialog in Flow, showing the max test runs field and connections for Gmail, Linear, and Slack.]()
Open the agent's **Flow** and turn on **Test mode** beside the Flow status.
In **Set up test mode**, enter the maximum number of runs. Beam shows a supported range of 2–200 runs and stops after that limit to control costs.
Choose the connection for the trigger, then choose a connection for each integration used by the Flow. Use **All nodes** when that connection should be available to every relevant node.
Select **Start testing**, then inspect the resulting task executions and node output for errors or unexpected results.
Use Test mode after changing a prompt, connection, or Flow logic. For larger sets of repeatable inputs, see [Test Datasets](/03-running-operations/debugging-testing/test-datasets/test-datasets).
## Best Practices
**Start Simple:**
* Test individual nodes before full workflow
* Use Test Tool to isolate issues
* Verify one change at a time
**Document Findings:**
* Record what worked and what didn't
* Note error messages and resolutions
* Build knowledge base for team
**Test Thoroughly:**
* Use diverse test cases
* Include edge cases
* Validate with production-like data
**Continue on Error:**
* Only for truly optional steps
* Ensure downstream handles missing data
* Monitor failure rates
**Auto-Retry:**
* For transient errors only
* Limit retry attempts to 2-3
* Track retry frequency to spot systematic issues
**Regular Reviews:**
* Check execution logs weekly
* Identify recurring error types
**Proactive Optimization:**
* Fix high-frequency errors
* Optimize slow nodes
* Update prompts based on failures
* Improve error handling coverage
**Build Resilience:**
* Add error handling to critical paths
* Create fallback workflows
* Implement human review for edge cases
* Test disaster recovery scenarios
## Next Steps
Rerun failed tasks after applying debugging fixes
Create test datasets to validate debugging improvements
Use AI-powered optimization to improve failing prompts
Monitor task execution results to identify issues
# Rerunning Tasks
Source: https://docs.beam.ai/03-running-operations/debugging-testing/rerunning-tasks/rerunning-tasks
Re-execute tasks for debugging, testing workflow changes, backtesting prompt improvements, and validating agent performance
Rerunning tasks allows you to re-execute completed or failed workflows with the same inputs and test modifications. This is essential for debugging, validating changes, and demonstrating improvements.
## Understanding Task Reruns
Every completed task can be re-executed to verify behavior, test changes, or debug issues. Beam provides multiple rerun strategies:
**Full Task Rerun** - Re-execute entire workflow from start with original trigger data
**Auto-run** - Automatically retry nodes that fail evaluation criteria
**Batch Rerun** - Re-process multiple tasks to backtest prompt or workflow improvements
## Manual Task Rerun
Re-execute any completed or failed task to test changes or debug issues.
![A completed task in Beam with Create Issue and Send Message to Channel completed, and the Re-run task button below the execution.]()
**Accessing Rerun:**
1. Navigate to task execution details in Tasks page
2. Scroll to bottom of execution timeline
3. Click **"Re-run task"** button below workflow steps
**What Happens:**
* Workflow re-executes with identical trigger input (`task_query`)
* All file attachments from original task preserved
* New execution creates separate task record
* Original task remains unchanged for comparison
**Testing Workflow Changes:**
* Modified node configurations or prompts
* Updated evaluation criteria
* Changed tool selections
* Added or removed nodes
**Debugging Failures:**
* Task failed due to transient error (API timeout, network issue)
* Integration temporarily unavailable
* Want to verify fix worked
**Demonstrating Improvements:**
* Show before/after results to stakeholders
* Validate optimization impact
* Compare agent performance over time
**Preserved Elements:**
* Original trigger input data (task\_query)
* File attachments uploaded with task
* Variable configurations
**Fresh Execution:**
* New timestamps and task ID
* Current workflow configuration (reflects any edits made)
* Latest tool versions and integrations
* Updated evaluation criteria
**Important:** Rerun uses current published workflow, not the version from original execution.
## Auto-run configuration
Use Auto-run to retry a node when its evaluation result does not meet the configured accuracy score.
![A selected Create Issue node in Flow with the Evaluation tab open, showing Evaluation metrics, a criterion, Auto-run, and the accuracy score field.]()
**Configure Auto-run:**
1. Open the agent's **Flow**.
2. Select the node to configure.
3. In the node sidebar, open **Evaluation**.
4. Enable **Evaluation metrics** and add or generate the criteria the node should meet.
5. Turn on **Auto-run**, then set the **Accuracy score (%)** and **Number of re-runs**.
**Configuration Options:**
**Evaluation metrics:** Enable criteria that assess the node's output against your expected standard.
**Auto-run:** Enable automatic retries for the node.
**Accuracy score (%):** Set the score the node must meet.
**Number of Re-runs:** Set maximum retry attempts (max 3)
**Evaluation-Based Triggering:**
1. Node executes and generates output
2. Evaluation criteria assess accuracy
3. If score is below the configured threshold → Auto-run triggers
4. Step re-executes with same input
5. Repeat until passing score or max retries reached
**Example:**
* Evaluation threshold: 90%
* First execution: 75% (fails)
* Auto-run 1: 85% (fails)
* Auto-run 2: 92% (passes)
* Workflow continues with passing output
**When to Enable:**
* Steps with non-deterministic outputs (GPT-based extraction)
* Classification tasks requiring high confidence
* Data extraction from inconsistent formats
* Steps where retry often improves results
**When NOT to Enable:**
* Deterministic operations (API calls with fixed responses)
* Steps failing due to missing data (retries won't help)
* Integration errors requiring manual fix
* Final output steps (may need human review instead)
**Optimal Configuration:**
* Max 2-3 retries (more rarely helps)
* Clear evaluation criteria (specific, measurable)
* Monitor retry frequency (high retries indicate prompt issues)
**Auto-run:**
* Happens during task execution automatically
* Triggered by evaluation scores
* No human intervention required
* Limited to configured max retries
**Manual Rerun:**
* Initiated by user after task completes
* Re-runs the complete task
* Unlimited reruns available
* Useful for testing changes made after execution
* Demonstrates improvements to stakeholders
## Flow context for reruns
Auto-run is configured on the selected node in the Flow sidebar's **Evaluation** tab. Keep the criteria, accuracy score, and rerun limit aligned with the outcome that node is expected to produce.
## Backtesting Prompt Changes
Re-execute multiple tasks to validate prompt improvements across representative data set.
**Backtesting Workflow:**
Identify 10-20 tasks representing common scenarios, edge cases, and failure patterns. Mark or note task IDs for batch rerun.
Update node prompts, evaluation criteria, or tool configurations based on identified improvements.
Execute rerun on each saved task individually. Beam creates new execution records for comparison.
Review evaluation scores before/after changes. Calculate improvement rate: tasks that now pass vs previously failed.
If improvement meets targets (e.g., 90%+ success rate), publish workflow changes to production.
**Criteria for Good Backtest Set:**
* **Variety**: Cover all workflow branches and scenarios
* **Failures**: Include tasks that previously failed
* **Edge Cases**: Unusual data formats or inputs
* **Success Cases**: Verify changes don't break working scenarios
* **Recent Data**: Reflects current data patterns
**Recommended Size:**
* Minimum: 10 tasks for basic validation
* Optimal: 20-30 tasks for comprehensive testing
* Large Changes: 50+ tasks for major overhauls
**Key Metrics:**
**Accuracy Improvement:**
* Before: Average evaluation score across backtest set
* After: Average evaluation score after prompt changes
* Target: 10-20% improvement in scores
**Failure Reduction:**
* Before: Number of tasks failing evaluation
* After: Number of tasks failing after changes
* Target: 50%+ reduction in failures
**Consistency:**
* Standard deviation of evaluation scores
* Lower = more consistent performance
* Target: Reduced variance in results
**Regression Check:**
* Previously passing tasks still pass
* No new failures introduced
* Target: Zero regression on working cases
**Prompt Optimization:**
* Tested new extraction prompts on 15 invoices
* Accuracy improved from 78% to 93%
* Reduced "amount" field extraction errors by 60%
**Evaluation Criteria Tuning:**
* Adjusted confidence thresholds
* Retested on 25 classification tasks
* Improved precision without sacrificing recall
**Tool Configuration Changes:**
* Modified API parameters for data lookup
* Reran 20 validation workflows
* Reduced timeout errors from 15% to 2%
## Best Practices
**Create Task Libraries:**
* Save 10-20 representative tasks per agent
* Cover all workflow branches
* Include both successes and failures
* Update quarterly with new patterns
**Organization:**
* Label tasks by scenario type
* Note which branch/node they test
* Document expected outcomes
* Track when last used for backtesting
**Systematic Comparison:**
* Keep original execution visible
* Note evaluation score changes
* Review output quality differences
* Document unexpected behavior
**Metrics to Track:**
* Execution time (faster/slower?)
* Evaluation scores (improved/degraded?)
* Branch selections (changed logic?)
* Tool errors (more/fewer issues?)
**Warning Signs:**
* Step frequently uses all 3 retries
* Auto-run happens on >30% of tasks
* Retries rarely improve scores
* Execution time significantly increased
**Action Items:**
* Review and improve evaluation criteria
* Optimize prompts causing frequent retries
* Consider if data quality is issue
* Disable Auto-run if not helping
**What to Track:**
* Which tasks were rerun and why
* Changes made before rerun
* Before/after evaluation scores
* Whether change solved the issue
**Benefits:**
* Proves ROI of optimization work
* Identifies patterns in failures
* Guides future improvements
* Demonstrates value to stakeholders
## Next Steps
Monitor task execution results before rerunning
Configure evaluation criteria that can trigger Auto-run
Use AI-powered prompt optimization before rerunning
Leverage debugging features alongside reruns
# Test Mode
Source: https://docs.beam.ai/03-running-operations/debugging-testing/test-datasets/test-datasets
Run an agent Flow with data from past tasks in a safe environment before you publish.
Test mode lets you validate an agent Flow with data from past tasks before you publish it. Beam runs tests in a safe environment: integrations are sandboxed, so test runs do not create, update, or delete live records.
![Flow header with the Test mode toggle]()
## When to use test mode
Use Test mode when you want to:
* Check Flow changes before publishing them.
* Run a Flow against data from a previous task.
* Review multiple test executions without affecting connected systems.
## Run a test
Open the agent's **Flow**.
Turn on **Test mode** in the Flow header.
Run the Flow with data from a previous task to validate the current Flow configuration without sending changes to live systems.
Open workspace **Tasks**, then select **Tests** to review test-mode task runs.
## What test mode protects
* Connected Integrations run in a sandbox while you test, so no live records are created, updated, or deleted.
* You can run as many test executions as you need and review them separately from regular tasks.
* Beam warns you before publishing when live connections are still active.
## Review test runs
The workspace **Tasks** page has separate **Tasks** and **Tests** tabs. The **Tests** tab includes the current task-list controls, including status and agent filters, a date picker, task-name search, and a View selector.
## Next steps
Test an individual node with sample input.
Review task and test execution details.
Publish a validated Flow.
# Automation Modes
Source: https://docs.beam.ai/03-running-operations/task-management/automation-modes/automation-modes
Configure human-in-the-loop workflows with consent approvals, input requests, and failure handling for controlled agent autonomy
Configure human approval on the individual Flow nodes that need it. Tasks can also pause with an **Input required** status when a node needs a value to continue.
## Understanding Automation Modes
For a tool node, open **Settings** in the node sidebar and use **Consent required**. When enabled, Beam states that the task pauses at that step and waits for user approval before proceeding.
## Human-in-the-Loop (HITL)
### Inbox Overview
Inbox is Beam's workspace notification view. Select a task notification to open its task details and respond to the requested action.
![The current Inbox with a consent-required notification selected, showing the task details and paused Slack action.]()
**When you open a notification:**
* **Task status**: shows why the task needs attention, such as **Consent required**.
* **Task activity**: shows the task creation event and the Flow's execution steps.
* **Requested action**: expands the paused step so you can review it and make the required decision.
**Task states to review in Tasks:**
Agent needs approval before executing sensitive action
Agent missing variable or data needed to continue workflow
Workflow stopped due to error requiring human intervention
### Consent Approvals
Agents pause before executing actions requiring explicit human permission.
![The current Flow node sidebar with Settings selected and Consent required enabled.]()
**Consent Workflow:**
1. Open the agent's **Flow**.
2. Select the tool node that needs approval.
3. Open **Settings** in the node sidebar.
4. Enable **Consent required**.
**Example Use Case:**
Agent drafts customer email response after extracting invoice data and checking payment records. Before sending, requires human approval to ensure tone and accuracy.
**Recommended for:**
* Sending emails or messages to external parties
* Updating critical database records
* Financial transactions or payments
* Deleting data or making irreversible changes
* Publishing content to public channels
* Compliance-sensitive operations
**Configuration:**
In the tool node's **Settings** tab, enable **Consent required** before publishing the Flow.
**Clear Context:**
* Show what agent has done so far
* Display exact action requiring approval
* Provide reasoning for proposed action
**Actionable Decisions:**
* Make approval/rejection consequences clear
* Allow feedback to improve future decisions
* Log all consent decisions for audit trail
**Response Time:**
* Set SLA for consent review (e.g., 2 hours)
* Configure escalation if no response
* Send notifications to relevant team members
### Input Requests
Agents pause when missing required data or variables to complete workflow.
![The current task detail page showing an Input required task and the fields needed to continue.]()
**Input Request Workflow:**
1. A node needs a value to continue.
2. The task shows an **Input required** status.
3. The task's execution panel shows the question, a text field, and **Continue**.
**Example:**
Agent classifying debt reminder tier needs "days past due" variable. After fetching debt details from database, cannot determine this value and requests human input.
**Input Form Elements:**
* **Question**: The value requested by the node
* **Input field**: A field for the value
* **Continue**: The control for continuing the task after providing the value
**Common Scenarios:**
* Variable not available in trigger data or memory
* Conditional logic requires human judgment
* External system unavailable, manual lookup needed
* Ambiguous data requiring clarification
* Custom business rules not encoded in workflow
**Configuration:**
Configure the input variable on the relevant Flow node and give it a clear description. The current node sidebar shows each input variable's fill method and description.
**Minimize Input Requests:**
* Automate data fetching where possible
* Use integrations to pull missing data
* Configure memory files with reference data
* Set default values for optional fields
**Clear Communication:**
* Explain why input is needed
* Show what agent has done so far
* Indicate how response will be used
* Provide examples of valid inputs
**Validation:**
* Define expected data type and format
* Validate input before resuming workflow
* Provide error messages for invalid data
## Managing Inbox Tasks
### Task Details View
Select an Inbox notification or open a task from **Tasks** to see its execution context and take action.
![The current task detail page for a Consent required task, showing the completed and paused Flow nodes.]()
**Detail Panel Sections:**
**Task Header** - Shows task ID, type (Consent/Input/Failed), agent name
**Task Activity** - Timeline of creation and updates
**Task Execution** - Visual workflow showing completed steps and where agent paused
**Context Documents** - Files, emails, or data agent processed
**Action Required** - Form, approval buttons, or re-run option
### Workflow Continuation
When a node has **Consent required** enabled, the task detail page shows a **Consent required** status and the Flow nodes completed before the pause. Use the task's decision controls to accept or reject the proposed action.
![The current Consent required task detail page, showing completed and paused nodes in the Flow execution.]()
The screenshot shows a completed **Create Issue** node and the **Send Message to Channel** node where the consent checkpoint is waiting.
Handle multiple inbox items efficiently:
**Filtering:**
* Filter by task type (Consent, Input, Failed)
* Filter by agent
* Filter by age or priority
**Bulk Actions:**
* Approve multiple similar consent requests
* Mark multiple failures for batch re-run
* Delegate tasks to team members
**Prioritization:**
* Sort by creation date (oldest first)
* Sort by agent criticality
* Custom priority tags
Stay informed of tasks requiring attention:
**Email Notifications:**
* New consent request created
* Input needed for critical workflow
* Failed execution requiring review
**Slack Integration:**
* Post to dedicated channel for urgent items
* @mention specific team members
* Include direct link to inbox task
**In-App Badges:**
* Inbox count indicator in navigation
* Real-time updates as tasks arrive
* Desktop notifications for high-priority items
Handle execution failures in inbox:
**Review Failure:**
* See which step failed and why
* Check error messages from tools/integrations
* Examine input data that caused failure
**Recovery Options:**
* **Re-run**: Retry from beginning with same inputs
* **Modify & Re-run**: Edit trigger data before retry
* **Fix Workflow**: Update agent flow to prevent future failures
* **Mark Resolved**: Document failure and close task
**Failure Prevention:**
* Add error handling nodes
* Improve validation criteria
* Enhance tool configurations
* Update prompts for edge cases
## Configuring Automation Modes
### Configure consent at a tool node
Add human checkpoints to your workflow for controlled execution.
**Consent configuration:**
In **Flow**, select the tool node for the action that requires approval.
Open **Settings** and enable **Consent required**. Beam pauses the task at that step and waits for user approval before proceeding.
**Input-required tasks:**
When a node needs a value, the task panel can show **Input required** with a question, input field, and **Continue** control. See [Task Executions](/03-running-operations/task-management/task-executions/task-executions) for the current task-detail flow.
### Automation Strategy
Choose the right balance of autonomy vs oversight for each workflow.
**Fully Autonomous:**
* **Use When**: High confidence in agent accuracy, low-risk actions, well-tested workflows
* **Examples**: Data extraction, classification, reporting, simple notifications
* **Benefits**: Maximum efficiency, 24/7 operation, instant processing
* **Risks**: Errors propagate without review, missed edge cases
**Human-in-the-Loop:**
* **Use When**: Sensitive actions, compliance requirements, learning phase, complex decisions
* **Examples**: Customer communications, financial transactions, legal documents, hiring decisions
* **Benefits**: Quality control, compliance adherence, human judgment
* **Tradeoffs**: Slower processing, requires human availability, potential bottlenecks
**Hybrid Approach:**
* **Use When**: Most production scenarios balancing efficiency and control
* **Examples**: Agent extracts/analyzes autonomously, human approves final action
* **Benefits**: 80% automation with 20% oversight on critical steps
* **Configuration**: Enable consent on the specific tool nodes that require approval, and review input-required exceptions in task detail.
Start with oversight, remove as confidence grows:
**Phase 1: Full HITL (Weeks 1-2)**
* Consent required for all actions
* Review every agent decision
* Identify patterns in approvals/rejections
**Phase 2: Selective HITL (Weeks 3-4)**
* Remove consent for consistently approved actions
* Keep oversight on edge cases
* Monitor evaluation scores
**Phase 3: Autonomous with Exceptions (Weeks 5+)**
* Fully autonomous for standard cases
* HITL only for low-confidence predictions
* Periodic spot-checks for quality
**Metrics to Track:**
* Approval rate by action type
* Time to resolve inbox items
* Error rate in autonomous vs HITL modes
Distribute inbox management across team:
**Role-Based Routing:**
* Finance team handles payment approvals
* Customer success reviews client communications
* Legal approves compliance-sensitive actions
**Assignment Rules:**
* Auto-assign based on agent or task type
* Round-robin distribution
* Skill-based routing
**Handoff Workflows:**
* First approver reviews, second approver finalizes
* Escalation path for complex decisions
* Delegation when team member unavailable
## Best Practices
Make agent reasoning clear for human reviewers:
**Show Work:**
* Display data extraction results
* Explain classification logic
* Highlight confidence scores
* Surface validation checks performed
**Provide Context:**
* Link to source documents
* Show related historical tasks
* Display relevant memory/knowledge base references
Reduce inbox bottlenecks:
**SLA Targets:**
* Set response time goals (e.g., 2 hours for consent)
* Monitor actual vs target
* Alert when approaching deadline
**Reduce Friction:**
* Pre-fill forms with best guesses
* Provide one-click approvals for simple cases
* Batch similar requests for efficient review
**Fallback Handling:**
* Auto-approve after timeout for low-risk items
* Escalate to manager for high-stakes decisions
* Queue for next business hours if after-hours
Use inbox data to improve automation:
**Approval Analytics:**
* Track approval/rejection rates by task type
* Identify consistently approved categories
* Find patterns in rejections
**Automation Opportunities:**
* High approval rate (95%+) → Remove consent requirement
* Repeated input requests → Add data source integration
* Common failures → Improve error handling
**Continuous Improvement:**
* Review inbox monthly for optimization
* Gradually increase autonomy for proven patterns
* Add checkpoints when quality degrades
Maintain records for regulated workflows:
**Decision Logging:**
* Record all consent approvals/rejections
* Capture human input provided
* Store failure resolution actions
**Audit Trail:**
* Who made decision and when
* Reasoning/feedback provided
* Original vs modified data
* Outcome of continued workflow
**Retention:**
* Archive completed inbox tasks
* Export for compliance reporting
* Link to final workflow execution records
## Next Steps
Monitor full workflow execution including HITL pause points
Set confidence thresholds triggering HITL requests
Add consent and input nodes to workflows
Configure triggers feeding HITL workflows
# Task Executions
Source: https://docs.beam.ai/03-running-operations/task-management/task-executions/task-executions
Review an agent's task list, filter task records, and open individual tasks for execution details.
Task executions show the current state and activity of work handled by your agents. Open a task from **Tasks** to review the executed Flow path, respond when input is required, or re-run the task when that control is available.
## Understanding task executions
Every task execution represents a single workflow run from trigger to completion. Beam captures the complete execution trace including:
**Execution Metadata** - Task ID, trigger source, start/end timestamps, overall status
**Workflow Steps** - Every node executed with inputs, outputs, and tool usage
**Branch Decisions** - Which paths were selected and why based on conditions
**Evaluation Metrics** - Accuracy scores and validation results per step
**Performance Data** - Execution duration, token usage, API calls made
## Viewing task executions
### Tasks overview
The workspace **Tasks** page lists tasks across your workspace. An individual agent's **Tasks** page shows only tasks for that agent.
![The current workspace Tasks page, with task rows, statuses, agent names, filters, and view controls.]()
**Task list features:**
* **Tasks and Tests** tabs: switch between task records and tests in the current scope.
* **Create task**: start a task manually.
* **Task ID and description**: identify a task and its request.
* **Status, agent, and date filters**: narrow the task list.
* **View control**: change the task-list view.
**Observed status types:**
Workflow finished successfully through all nodes to exit point
The task is waiting for user input.
### Task execution details
Click any task to open its execution details in the right panel.
![The current task detail panel showing an Input required task, its Flow execution, an input field, and Continue.]()
**Execution Panel Sections:**
**Task header** - Shows the task ID, current status, assigned agent, and task title.
**Task activity** - Shows task activity with created and updated timestamps.
**Task execution** - Shows the executed Flow nodes, including tool and condition nodes.
**Input required** - When a node needs a value, the panel shows the input prompt and a **Continue** control. A **Re-run task** control can also be available for the task.
## Analyzing executions
### Workflow step breakdown
Select a node in **Task execution** to open its detail panel.
**Node detail controls:**
* **View full details** opens the selected node's detail view.
* **Step actions** provides actions for that node.
* **Parameters** shows the node's execution data.
* **Evaluation** is shown as a separate tab and can be unavailable when the task has no evaluation data.
The **Parameters** tab groups the selected node's **Output**, **Reasoning**, and **Input**. Input values display the fill method used for each value when it is available.
Use **View full details** to inspect the selected node. The exact information depends on the node and task data.
The node panel includes an **Evaluation** tab. It can be disabled when no evaluation data is available for the selected task.
### Branch logic and path selection
Select a Condition node in **Task execution** to view its detail panel.
For an LLM-based condition, the panel shows that the condition evaluates branches semantically with an AI model and lists the configured branch outcomes. Select **View full details** for the selected condition's complete detail view.
## Creating and managing tasks
### Manual task creation
Select **Create task** to open **Execute flow**. It has **Trigger** and **Manual** tabs.
![The current Execute flow dialog with Trigger and Manual tabs.]()
* In **Trigger**, select an agent, then fetch and select one of its past trigger records.
* In **Manual**, select an agent, provide instructions, and optionally add attachments. Attachments support **File upload** and **Fetch from URL**; the URL option accepts multiple URLs on separate lines.
* The Manual tab also includes **Re-run your most recent task** when an eligible task is available.
* Select **Create task** after completing the required inputs.
### Performance metrics
Track agent performance across all task executions:
**Completion Rate** - Percentage of tasks finishing successfully
**Average Runtime** - Mean execution duration from start to completion
**Evaluation Scores** - Average accuracy across all steps and tasks
**Success by Trigger** - Completion rates by trigger source (Email, Webhook, Manual, Timer)
Access detailed performance data through the Analytics tab.
**Completion Trends** - Visualize task completion rates over time with daily, weekly, monthly aggregation
**Runtime Analysis** - Identify slowest steps and bottlenecks in execution flow
**Evaluation Insights** - Track quality improvements and failure patterns
**Tool Performance** - See which integrations perform best with success rates and response times
## Debugging and best practices
### Debugging failed executions
Failed tasks appear with red status indicator in task list.
**Common Failure Causes:**
**Validation Failure** - Step didn't meet evaluation criteria (e.g., accuracy \< 90%)
**Tool Error** - Integration API returned error or timeout
**Missing Data** - Required field not present in trigger input or previous step output
**Timeout** - Execution exceeded maximum duration limit
Scroll through execution timeline to find red X status icon. Failed step shows error message and which criteria wasn't met.
Verify the node received expected data format. Common issues: incorrect variable mapping, null/empty previous step, data type mismatch.
Examine what the tool actually returned vs expected. Integration errors often include API error codes.
Look at which evaluation criteria failed. Adjust criteria thresholds or improve prompts based on failures.
Make changes to workflow, then re-run the same task to verify fix.
Check task executions daily during initial deployment:
* Monitor completion rates
* Review evaluation scores
* Identify recurring failures
* Validate output quality
Gradually reduce frequency as agent stabilizes (95%+ success rate).
Configure notifications for execution failures via email, Slack, or webhook to ticketing system. Respond quickly to prevent backlog buildup.
Establish expected performance benchmarks:
* Target completion rate (e.g., 95%)
* Maximum acceptable runtime (e.g., 2 minutes)
* Minimum evaluation scores (e.g., 90%)
Alert when metrics deviate beyond thresholds.
Use re-run feature to test changes:
* Keep 10-20 representative tasks saved
* Re-run after workflow modifications
* Compare results before/after changes
Maintain test case library for regression testing.
**Cause**: Human-in-the-loop approval required or queue backlog
**Solution**:
* Check Automation Modes settings (HITL enabled?)
* Review pending approvals in Inbox
* Verify agent has sufficient processing capacity
**Cause**: Evaluation criteria too broad or subjective
**Solution**:
* Make criteria more specific and measurable
* Use exact value matching instead of fuzzy matching
* Regenerate criteria based on successful tasks
**Cause**: Real-time connection lost or browser cached state
**Solution**:
* Refresh page to reconnect WebSocket
* Check network connection stability
* Clear browser cache if issue persists
## Next steps
Configure human-in-the-loop workflows and approval processes
Test workflow changes with previous task data
Set up quality criteria and accuracy scoring
Improve agent performance with AI-assisted optimization
# Triggers
Source: https://docs.beam.ai/03-running-operations/task-management/triggers-webhooks/triggers-webhooks
Configure the Trigger node that starts an agent Flow, then test it before publishing.
Triggers start an agent Flow. Configure them from the **Trigger** node in the Flow builder, not from a separate agent-configuration page.
![Current Flow canvas with the active Gmail trigger selected in the sidebar]()
## Open the Trigger node
1. Open the agent's **Flow**.
2. Select the **Trigger** node at the start of the Flow.
3. In the sidebar, select the trigger provider and then the configured trigger card.
The Trigger sidebar groups triggers by provider. Use **Add trigger** to set the Flow's trigger; a Flow has one Trigger node rather than separate parallel triggers.
## Configure a Gmail trigger
Selecting a Gmail **New Email Received** trigger opens its configuration in the Flow sidebar.
![Current Gmail New Email Received trigger configuration in the Flow sidebar showing trigger name, Gmail connection, trigger context, filters, and Configure and test]()
Configure these fields for the trigger:
| Field | Use it to |
| ------------------- | -------------------------------------------------------------------------------------------- |
| **Trigger name** | Give the trigger a recognizable name. |
| **Connection** | Choose the Gmail connection the trigger uses. |
| **Trigger context** | Add instructions that are sent with the trigger payload. |
| **Filters** | Narrow which messages start the Flow, including attachment, reply, and body-content filters. |
Use **Add condition** and **New Group** to refine the filters. Select **Configure & test** when the setup is ready to test.
## Configure a webhook trigger
Use a **Webhook** trigger when another system needs to start a Flow with an HTTP request.
1. Open the Flow's **Trigger** node and add or select the **Webhook** trigger.
2. Copy the webhook URL shown in the trigger configuration. Do not construct the URL by hand.
3. Send a JSON `POST` request to that URL.
The webhook endpoint uses this form:
```text theme={null}
https://api.beamstudio.ai/agent-tasks/{agentId}/webhook/{triggerId}
```
The request body follows the current task-session payload. Include the target `agentId` and a `taskQuery` object with its required `query` string. You can also provide URLs or Base64-encoded context files when the Flow needs them.
```json theme={null}
{
"agentId": "agent_123456",
"taskQuery": {
"query": "Process this customer inquiry"
},
"parsingUrls": ["https://example.com/customer-data"],
"encodedContextFiles": [
{
"data": "BASE64_ENCODED_CONTENT",
"mimeType": "application/pdf",
"fileName": "inquiry.pdf",
"fileSize": "2 MB"
}
]
}
```
Use the exact URL and trigger-specific requirements shown in the Flow UI. Webhook authentication controls are not documented here because their current configuration surface has not been verified.
## Test before publishing
Use **Execute trigger** to fetch trigger records and inspect their data before publishing the Flow. Use **Execute flow** when you want to test the complete Flow with a selected trigger record.
After reviewing the trigger and Flow results, publish from the Flow header.
## Next steps
Add and configure the other nodes in an agent Flow.
Connect the services used by Flow nodes and triggers.
Review runs that start from a trigger.
Review publishing and Flow version history.
# Evaluation Framework
Source: https://docs.beam.ai/04-observability-analytics/evaluation-framework/evaluation-framework
Validate agent accuracy with evaluation criteria, Auto-run retries, and Analytics monitoring.
The evaluation framework ensures agent quality by validating outputs against defined criteria, scoring accuracy, and enabling Auto-run retries when configured.
## Understanding Evaluation Framework
Every Flow node can have evaluation criteria that automatically validate outputs and score accuracy.
**Evaluation Criteria** - Plain-language validation rules checking if node outputs meet quality standards
**Accuracy Score** - Percentage (0-100%) measuring how well node output matches evaluation criteria
**Auto-run** - Automatic retry when a node's evaluation result falls below its configured accuracy score
**Analytics Dashboard** - Track completion rates, average evaluation scores, and performance trends over time
## Setting Evaluation Criteria
Define validation rules for Flow nodes to automatically measure output quality.
Open the agent's **Flow** and select the node requiring validation. Focus on critical extraction, classification, or decision points.
In the node sidebar, open **Evaluation**. Turn on **Evaluation metrics** to add criteria and Auto-run controls.
![A selected Create Issue node in Flow with the Evaluation tab open and Evaluation metrics turned off.]()
With **Evaluation metrics** enabled, select **Add criteria** to create a rule. Define what the node output must meet.
**Manual Entry:** Write criteria in plain language describing validation requirement
**AI Generation:** Select **Generate criteria** to create suggested validation rules from the node configuration.
Specify validation rule checking specific output field. Examples:
* "The 'invoice\_date' field must contain a date string in format YYYY-MM-DD"
* "The 'amount\_due' field must contain a numeric value greater than zero"
* "The 'currency' field must contain a three-letter ISO 4217 currency code"
* "The 'priority' field must be High, Medium, or Low"
![A selected Flow node with Evaluation metrics enabled, showing a criterion, Auto-run, and the accuracy score field.]()
Turn on **Auto-run**, set the **Accuracy score (%)**, and choose the **Number of re-runs** (up to three).
Click **Publish** to activate the Flow changes. They take effect on the next agent run.
**Be Specific:**
* Check individual fields, not entire output
* Define exact format requirements
* Specify acceptable values or ranges
**Good Examples:**
* "The 'email' field must contain a valid email address with @ symbol"
* "The 'invoice\_number' must be alphanumeric and 10-15 characters long"
* "The 'status' field must be one of: pending, approved, rejected"
**Poor Examples:**
* "Output should be good" (too vague)
* "Extract all information correctly" (not measurable)
* "Make sure data is accurate" (unclear definition)
**Test Criteria:**
* Run node with test input after adding criteria
* Verify criteria correctly identifies valid/invalid outputs
* Adjust wording if too strict or too lenient
**Manual Entry:**
* Full control over validation logic
* Tailored to specific business rules
* Best for unique or complex requirements
* Requires domain expertise
**AI-Generated ("Generate criteria"):**
* Analyzes node prompt and configuration
* Automatically suggests validation rules
* Fast setup for standard extraction tasks
* Can refine suggestions manually
**Recommended Approach:**
1. Use AI generation as starting point
2. Review suggested criteria for accuracy
3. Add business-specific rules manually
4. Test with sample inputs
5. Refine based on results
Each criterion should validate one specific field:
**Data Type Checks:**
* Number fields contain numeric values
* Date fields match expected format
* Boolean fields are true/false
**Format Validation:**
* Email addresses have @ symbol
* Phone numbers match pattern
* URLs start with http\:// or https\://
**Business Rules:**
* Amount greater than zero
* Date not in future
* Status matches allowed values
* Currency from approved list
**Relationship Checks:**
* Due date after invoice date
* Discount less than total amount
* End time after start time
## Auto-run configuration
Enable Auto-run when a node should retry after its evaluation result falls below the configured accuracy score.
**How Auto-run Works:**
1. Node executes and generates output
2. Evaluation criteria assess output quality
3. System calculates accuracy score (0-100%)
4. If the score is below the configured accuracy score → Auto-run retries the node
5. Repeat until passing score or max retries reached
6. Workflow continues with best output
**Enable in Evaluation:**
1. Select the node in the agent's **Flow**.
2. Open the **Evaluation** tab in the node sidebar.
3. Enable **Evaluation metrics**, then add or generate criteria.
4. Turn on **Auto-run**, set **Accuracy score (%)**, and choose **Number of re-runs** (up to three).
**Trigger Condition:**
Auto-run triggers when the node's evaluation result is below its configured accuracy score.
**Best For:**
* GPT-based extraction with variable outputs
* Classification tasks needing high confidence
* Data parsing from inconsistent formats
* Steps where retry often improves results
**Not Recommended:**
* Deterministic operations (always same output)
* Integration API calls (retry won't change response)
* Steps failing due to missing data
* Final output nodes (may need human review)
**Retry Limits:**
* Start with 2-3 max retries
* More retries increase execution time
* High retry rates indicate prompt issues
**Monitor Frequency:**
* Track how often auto-run triggers
* Review tasks using all retry attempts
* Optimize prompts if >30% tasks need retries
**Combine with Evaluation:**
* Clear, measurable criteria essential
* Vague criteria cause unnecessary retries
* Test criteria before enabling auto-run
**Performance Impact:**
* Each retry adds execution time
* Cost increases with retry attempts
* Balance quality vs speed/cost
**Auto-run (Automatic):**
* Happens during task execution
* Triggered by low evaluation scores
* No human intervention
* Limited to configured max retries
* Single node only
**Manual Rerun (User-Initiated):**
* After task completes (see [Rerunning Tasks](/03-running-operations/debugging-testing/rerunning-tasks/rerunning-tasks))
* User decides when to rerun
* Unlimited reruns available
* Re-runs the complete task
* Useful for testing changes
## Monitoring Evaluation Performance
Track agent accuracy and evaluation metrics over time through Analytics dashboard.
![The current Analytics dashboard with date-range controls, summary cards, completion rate, average evaluation score, and feedback score.]()
**Key Metrics:**
**Completion Rate** - Percentage of tasks completing successfully (98.95% in example)
**Average Evaluation Score** - Mean accuracy across all evaluated nodes (98.41% in example)
**Feedback Score** - Human feedback on agent outputs (100% positive in example)
**Tasks Completed vs Failed** - Track success/failure counts and trends
**Accessing Analytics:**
1. Navigate to agent in Beam AI
2. Click "Analytics" in left sidebar
3. Use the date picker or select **Last 7 days**, **Last 30 days**, or **Last 3 months**
4. Review metrics and trends
**95-100% Score:**
* Agent performing excellently
* Criteria well-calibrated
* Minimal failures
* Ready for production scaling
**85-94% Score:**
* Good performance with room for improvement
* Review failed cases for patterns
* Consider prompt optimization
* May need criteria adjustment
**70-84% Score:**
* Acceptable but needs optimization
* Identify common failure types
* Use [Optimize Outputs](/04-observability-analytics/optimize-outputs/optimize-outputs) for prompt improvement
* Review criteria strictness
**Below 70%:**
* Significant issues requiring attention
* Check if criteria too strict
* Review prompt quality
* Verify training data relevance
* Consider workflow redesign
**Improving Scores:**
* Prompt optimizations working
* Agents learning from feedback
* Criteria calibrated correctly
**Declining Scores:**
* Data drift (new input patterns)
* Criteria becoming outdated
* Integration changes
* Need prompt refresh
**Stable Scores:**
* Agent performing consistently
* Monitor for sudden changes
* Periodic optimization still valuable
**Action Items:**
* Review analytics weekly
* Investigate score drops immediately
* Celebrate improvements with stakeholders
* Document optimization changes
**Identify Weak Points:**
* Which nodes have lowest scores?
* Are failures clustered in specific steps?
* Do certain branches perform worse?
**Optimization Priority:**
1. Nodes with \<85% scores
2. High-volume nodes with 85-94% scores
3. Critical workflow steps regardless of score
4. Recently changed nodes
**Compare Across Agents:**
* Similar nodes in different agents
* Same task type performance
* Identify best practices to replicate
## Creating Expected Outputs
Define ground truth outputs from successful task executions to use in [Test Datasets](/03-running-operations/debugging-testing/test-datasets/test-datasets).
**Process:**
1. Run agent with sample input
2. Review task execution output
3. Verify output correctness
4. Export as expected output for test dataset
5. Use in batch testing for validation
**Expected Output Structure:**
Match exact output schema your workflow produces, including all evaluated fields.
```json theme={null}
{
"invoice_number": "INV-2025-001234",
"invoice_date": "2025-01-15",
"due_date": "2025-02-15",
"amount_due": 1500.00,
"currency": "USD",
"vendor_name": "Acme Corp",
"email_recipient": "billing@example.com"
}
```
**Successful Production Tasks:**
1. Find task with perfect evaluation scores
2. Review output for accuracy
3. Export complete node outputs
4. Verify all fields present and correct
**Manual Specification:**
* Domain expert defines correct output
* Based on input data analysis
* Follows business rules exactly
* Validated by stakeholders
**Corrected Agent Outputs:**
* Run agent on test input
* Human reviews and corrects errors
* Corrected version becomes expected
* Faster than manual from scratch
**Precision:**
* Exact field names matching node output
* Correct data types (string, number, boolean)
* Proper date/time formats (YYYY-MM-DD)
* Accurate currency/number precision
**Completeness:**
* All fields that will be evaluated
* Optional fields with null if not present
* Nested objects fully specified
**Documentation:**
* Note why this is correct answer
* Document business rules applied
* Mark edge case handling
* Keep updated as requirements change
**Validation:**
* Test expected outputs against criteria
* Ensure they would score 100%
* Use in dataset runs to verify
* Update when criteria change
## Integration with Test Datasets
Use evaluation framework with test datasets for systematic quality assurance. See [Test Datasets](/03-running-operations/debugging-testing/test-datasets/test-datasets) for comprehensive testing guidance.
**Workflow:**
1. Define evaluation criteria for nodes
2. Create test inputs with expected outputs
3. Run test dataset via webhook
4. Evaluation criteria score each output
5. Compare actual vs expected
6. Calculate overall dataset accuracy
7. Optimize prompts based on failures
**Benefits:**
* Automated quality validation
* Quantitative performance measurement
* Regression testing for changes
* Continuous improvement tracking
## Best Practices
**Priority Order:**
1. Data extraction nodes (invoice details, form fields)
2. Classification/routing nodes (priority, category)
3. Decision nodes (approval logic, validation)
4. Integration nodes (API calls, database lookups)
5. Final output formatting
**Rationale:**
* Focus effort where accuracy matters most
* Build expertise before tackling all nodes
* Demonstrate value quickly
* Iterate based on learnings
**Initial Setup:**
* Start with basic validation rules
* Use AI generation for suggestions
* Test with 5-10 sample inputs
**Refinement:**
* Too strict? Relax constraints
* Too lenient? Add specific checks
* Missing edge cases? Add coverage
* Review failed evaluations for patterns
**Continuous Improvement:**
* Update criteria quarterly
* Add rules for new failure types
* Remove outdated requirements
* Document changes and rationale
**Evaluation Criteria:**
* Automated validation of format/structure
* Check required fields present
* Verify data type correctness
**Human Review:**
* Semantic accuracy (correct meaning)
* Business logic appropriateness
* Edge case handling quality
* Overall output quality
**Use Both:**
* Criteria catch 80% of issues automatically
* Human review for remaining 20%
* Incorporate human feedback into criteria
* Reduce manual review over time
**Warning Signs:**
* Node using all retries frequently (>30% of tasks)
* Auto-run rarely improves scores
* Execution time significantly increased
* Cost impact from retries
**Actions:**
* Review and optimize prompts (see [Optimize Outputs](/04-observability-analytics/optimize-outputs/optimize-outputs))
* Adjust evaluation criteria if too strict
* Consider if auto-run appropriate for node
* Disable if not providing value
**Ideal State:**
* Auto-run triggers on \<10% of tasks
* Retries improve scores 80%+ of time
* Average 1-2 retries when triggered
* Clear ROI from quality improvement
## Next Steps
Create test datasets using evaluation criteria for validation
Use AI-powered optimization to improve failing evaluations
Rerun tasks after updating evaluation criteria
Monitor evaluation scores in task execution results
# Monitoring
Source: https://docs.beam.ai/04-observability-analytics/monitoring/monitoring
Configure task-status notifications for an agent by choosing a schedule, channel, task statuses, and whether to include test tasks.
Monitoring lets you configure notifications for an agent's tasks. You choose when Beam sends a notification, which task statuses trigger it, and whether tasks run in test mode are included.
![New monitoring configuration form with schedule, channels, task statuses, and test-task controls]()
## Create a monitoring configuration
1. Open the agent's **Configuration**.
2. Select **Monitoring**.
3. Select **Create configuration**.
4. Choose a monitoring type.
5. Enable **Email** or connect **Slack**.
6. Select the task statuses that should trigger the notification.
7. Choose whether to include tasks run in test mode, then select **Create**.
## Monitoring types
| Type | Use it to |
| ---------------- | ---------------------------------------------------------- |
| Real-time alerts | Send a notification when a task reaches a selected status. |
| Daily report | Receive a daily report. |
| Weekly report | Receive a weekly report. |
| Monthly report | Receive a monthly report. |
## Notification channels
The configuration form includes an **Email** toggle and a **Connect Slack** option. Connect Slack before using Slack as the notification channel.
## Task statuses
Choose one or more task statuses for the configuration:
* Completed
* Failed
* Input required
* Consent required
* Authentication required
* Insufficient credits
* Aborted
## Include test tasks
Enable **Include test tasks** to also notify for tasks run in test mode.
## See also
* [Task Executions](/03-running-operations/task-management/task-executions/task-executions)
* [Analytics](/04-observability-analytics/overview-analytics/overview-analytics)
# Optimize Outputs
Source: https://docs.beam.ai/04-observability-analytics/optimize-outputs/optimize-outputs
Use Pro Learning tools to test, tune, and optimize an agent's tool outputs
With a Pro plan, Optimize Outputs provides Learning tools for testing, tuning, and optimizing an agent's tool outputs.
Learning requires a Pro plan. Without Pro, the Learning page shows an **Unlock the Learning Hub** prompt and an **Upgrade to Pro** action.
## Understanding Optimize Outputs
Watch AI agents learn from failures and fix themselves automatically—no code required.
**Learning Hub** - Tracks tool performance across all workflow nodes, identifying underperforming tools below accuracy thresholds
**Feedback-Driven Optimization** - Mark what went wrong in failed outputs, and AI uses examples to rewrite prompts with better context
**Automatic Prompt Rewriting** - AI analyzes failures, identifies patterns, rewrites prompts with clearer instructions and structured logic
**Validation Testing** - Automatically retests new prompts against same failed cases to verify improvement before deployment
**Key Benefit**: Transform 5% accuracy tools to 100% accuracy in \~30 seconds by providing AI with feedback on what went wrong.
## Accessing Learning Hub
Monitor tool performance and identify optimization opportunities across your agent workflows.
On a Pro plan, open your agent and select **Learning** in the left sidebar.
View accuracy scores for all tools in your workflow. Tools below 90% threshold highlighted as needing optimization.
Locate tools with low accuracy scores (e.g., "Debt Reminder Tier Classifier: 5%"). Compare with high-performing tools (e.g., "Email Content Classifier: 100%") to understand potential.
Click "Optimize" button next to underperforming tool to begin improvement process.
**Accuracy Score:**
* Percentage of tool outputs meeting evaluation criteria
* Based on [Evaluation Framework](/04-observability-analytics/evaluation-framework/evaluation-framework) validation
* Updated with each task execution
**Accuracy Thresholds:**
* 90-100%: Excellent performance
* 70-89%: Good, minor optimization beneficial
* 50-69%: Moderate issues, optimization recommended
* Below 50%: Significant problems, optimization critical
**Execution Count:**
* Number of times tool has run
* Larger sample size = more reliable accuracy metric
* Minimum 5-10 executions for meaningful optimization
**High vs Low Performers:**
* 100% accuracy tools show optimization works when configured correctly
* Low accuracy tools (5-20%) indicate prompt issues, not capability limits
* Similar tasks performing differently = prompt quality difference
**Optimization Priority:**
1. Critical workflow tools with \<50% accuracy
2. High-volume tools with 50-89% accuracy
3. Recently added tools needing calibration
4. Tools with declining accuracy trends
## Reviewing Failed Outputs
Examine failed task executions to understand what went wrong before optimization.
![Optimize tool modal showing list of failed outputs all at 0% accuracy for Debt Reminder Tier Classifier]()
**Failed Outputs List:**
* Each row represents single task execution
* Shows task ID, description, thumbs up/down rating, accuracy score (0%), timestamp
* All failures displayed for pattern identification
* Checkbox for selecting outputs to provide feedback
Click "Optimize" button in Learning Hub for underperforming tool to open feedback interface.
Examine list of failed outputs showing 0% accuracy. Identify common patterns across failures.
**Example Pattern:**
Seven classification attempts, all failed (0% accuracy), all attempting same task: "Classify tier of debt reminder based on days-past-due, balance, and reminders"
Choose 3-5 representative failures covering different scenarios. Mix of good and bad outputs provides better learning signal.
**Pro Tip:** Select diverse failures rather than identical ones for AI to learn broader patterns
**What to Look For:**
* Consistent error patterns (same mistake repeated)
* Missing information in outputs
* Incorrect classifications or extractions
* Hallucinations (AI making up data not in input)
* Format issues (wrong structure, missing fields)
**Select Representative Failures:**
* Different input scenarios
* Various error types
* Edge cases and common cases
* Recent and older failures
**"Select all good outputs":**
* Check outputs that were correct
* Helps AI learn what success looks like
* Provides positive examples alongside failures
**"Select all bad outputs":**
* Quickly select all failed cases
* Useful when all outputs have same issue
* Uncheck outliers that failed for different reasons
**Individual Selection:**
* Choose specific mix of good and bad
* Recommended: 60-70% bad, 30-40% good
* Provides balanced learning signal
## Providing Feedback
Mark what went wrong in failed outputs so AI can learn and improve prompts.
![Feedback interface showing selected outputs with hallucination feedback and improved prompt on right side]()
Click checkbox next to failed output to review details. Left panel shows output details, right panel shows improved prompt being generated.
Examine actual output produced (e.g., "DebtTier: Active"). Compare against expected correct output.
Select between "Feedback" (explain what's wrong) or "Ideal output" (provide correct answer):
**Feedback (Recommended):** Explain the error - "Hallucinations with output not being accurate"
**Ideal Output:** Provide exact correct output for this input
Select error category from tags:
* **Data loss in execution**: Information from input missing in output
* **Missing task inputs**: Required data not provided to tool
* **Missing context**: Tool lacks background information needed
* **Incorrect memory lookup**: Wrong reference data retrieved
* **Hallucinations**: AI inventing data not in input (common for low-accuracy tools)
Provide feedback on 3-5 selected outputs. More diverse examples = better optimization.
**Status:** "3 selected" shows AI has enough examples to identify patterns
**Be Specific:**
* "Output classified as 'Active' but should be 'Tier 2' based on days past due"
* Not just "Wrong classification"
**Explain Why It's Wrong:**
* "Missing consideration of balance amount in tier determination"
* "Hallucinating 'Active' status not present in input data"
**Provide Context:**
* "Tool should use days\_past\_due, balance, and reminders count"
* "Classification requires comparing against tier thresholds"
**Use Error Tags Correctly:**
* Hallucinations: AI making up data
* Data loss: Correct data ignored
* Missing context: Need domain knowledge added to prompt
* Missing inputs: Input schema incomplete
**Ideal Output (Best for):**
* Extraction tasks (exact values to extract)
* Classification (correct category)
* Structured data output (fill in JSON)
* Clear right/wrong answers
**Feedback (Best for):**
* Explaining reasoning errors
* Complex decision logic
* Nuanced improvements
* Process problems vs output problems
**Combination Approach:**
* Provide ideal output for 1-2 examples
* Explain what's wrong via feedback for others
* Gives AI both target and reasoning
**Hallucinations (Most Common):**
* AI inventing classifications not in input
* Making up field values
* Creating data from assumptions
**Data Loss:**
* Ignoring key input fields
* Missing important context
* Overlooking edge case data
**Logic Errors:**
* Wrong decision criteria
* Misunderstanding task requirements
* Incorrect priority/weighting
**Format Issues:**
* Wrong output structure
* Missing required fields
* Incorrect data types
## AI Optimization Process
Watch AI analyze failures, rewrite prompts, and validate improvements automatically.
**Optimization Steps:**
1. **Analysis (\~10 seconds):** AI reviews all selected outputs and feedback to identify failure patterns
2. **Prompt Rewriting (\~15 seconds):** Generates improved prompt with better role context, structured logic, and clear output requirements
3. **Validation Testing (\~5 seconds):** Automatically retests new prompt against same failed cases
4. **Results Display:** Shows before/after comparison with accuracy improvements
**Role Context Added:**
* "You are a skilled debt classification specialist..."
* Provides domain expertise framing
* Sets expectations for task complexity
**Structured Classification Logic:**
* Breaks down decision process into steps
* Defines exact criteria for each tier
* Specifies how to weigh different factors
**Output Requirements:**
* Exact format specifications
* Required fields clearly listed
* Data type expectations (string, number, boolean)
* Validation rules embedded
**Edge Case Handling:**
* What to do when data missing
* How to handle boundary conditions
* Fallback logic defined
**Before (Vague):**
"Classify debt tier based on account information"
**After (Precise):**
"You are a skilled debt classification specialist. Analyze overdue accounts to determine appropriate tier. Extract days\_past\_due (numeric), balance (amount), reminders (count). Classify into: Tier 1 (0-30 days), Tier 2 (31-60 days), Tier 3 (61+ days). Output JSON with debt\_tier field."
**Automatic Retest:**
* Runs new prompt on same inputs that previously failed
* Compares outputs against evaluation criteria
* Calculates new accuracy scores
* Shows improvement percentage
**Example Results:**
* Original: 0% accuracy on 3 test cases
* Optimized: 100% accuracy on same 3 cases
* Improvement: +100 percentage points
**What Gets Tested:**
* All outputs you provided feedback on
* Additional recent failures if available
* Diverse input scenarios
* Edge cases from feedback
**Strong Improvement:**
* Accuracy jumps 50+ percentage points
* All test cases now passing
* Clear pattern recognition visible
* Prompt significantly more detailed
**Moderate Improvement:**
* Accuracy increases 20-49 points
* Most test cases passing
* Some edge cases still failing
* May need additional feedback iteration
**Minimal Improvement:**
* Accuracy increases \<20 points
* Many test cases still failing
* Pattern unclear or complex
* Need more diverse feedback examples
**Action on Minimal Improvement:**
* Add more feedback examples (aim for 5-10)
* Include diverse error types
* Provide ideal outputs
* Consider if tool has right input data
## Applying Optimizations
Deploy improved prompts to production after validating accuracy improvements.
![Flow builder showing Optimisation applied success message with Publish button to deploy changes]()
Examine improved prompt and validation test results. Verify accuracy improvement meets expectations (target: 90%+).
Click "Apply optimizations" button to update workflow with new prompt. Changes saved but not yet live.
Return to Flow builder. Green "Optimisation applied" message confirms changes saved successfully.
Click "Publish" button to deploy improved prompt to production. New prompt takes effect on next agent run.
**Important:** Changes not live until published. Test in E2E environment first if available.
Track tool accuracy in Learning Hub after deployment. Verify improvement persists with new production data.
**Verify Improvements:**
* ✅ Accuracy increased significantly (ideally 90%+)
* ✅ All test cases passing
* ✅ Prompt changes logical and clear
* ✅ No unintended side effects visible
**Test Safely:**
* Run manual test task with new prompt
* Verify output format unchanged
* Check integration compatibility
* Test with edge case inputs
**Rollback Plan:**
* Document original prompt before publishing
* Monitor first 10-20 production tasks closely
* Revert if accuracy drops unexpectedly
* Iterate with more feedback if needed
**First 24 Hours:**
* Check Learning Hub for updated accuracy
* Review first 10 task outputs manually
* Monitor for new error patterns
* Compare pre/post optimization metrics
**First Week:**
* Track daily accuracy trends
* Analyze any failures with new prompt
* Gather feedback from users/reviewers
* Iterate if accuracy below target
**Ongoing:**
* Weekly accuracy reviews
* Monthly optimization opportunities check
* Quarterly full prompt review
* Continuous feedback collection
**When to Re-Optimize:**
* Initial optimization improved but still \<90% accuracy
* New failure patterns emerge over time
* Input data characteristics changed
* Business rules updated
**Iterative Process:**
1. Deploy first optimization
2. Monitor for 1-2 weeks
3. Collect new failure examples
4. Run optimization again with fresh feedback
5. Repeat until target accuracy achieved
**Diminishing Returns:**
* First optimization: Often 40-60% improvement
* Second optimization: 10-20% improvement
* Third+ optimization: \<10% improvement
* Consider if prompting limits reached
## Optimization Best Practices
**Diversity Matters:**
* Include different error types
* Cover various input scenarios
* Mix recent and older failures
* Representative of production data
**Quantity Guidelines:**
* Minimum: 3 examples (basic optimization)
* Recommended: 5-7 examples (good optimization)
* Maximum useful: 10-15 examples (comprehensive)
* Beyond 15: Diminishing returns
**Balance Good and Bad:**
* 60-70% bad outputs (what to fix)
* 30-40% good outputs (what to preserve)
* Helps AI maintain good behavior while fixing issues
**Good Feedback Examples:**
* "Output classified as 'Active' but input shows 45 days past due, should be Tier 2"
* "Missing consideration of balance amount - only used days\_past\_due"
* "Hallucinating 'paid' status not present in input data"
**Poor Feedback Examples:**
* "Wrong" (too vague)
* "Bad output" (not actionable)
* "Doesn't work" (no specific guidance)
**Feedback Template:**
* What's wrong: "Output shows X"
* Why it's wrong: "But input indicates Y"
* What's needed: "Should classify as Z based on \[criteria]"
**Test in E2E Environment:**
1. Apply optimizations (don't publish)
2. Copy prompt to E2E agent version
3. Run test dataset (see [Test Datasets](/03-running-operations/debugging-testing/test-datasets/test-datasets))
4. Verify 90%+ accuracy maintained
5. Publish to production if validated
**Manual Spot Checks:**
* Run 5-10 manual test tasks
* Review outputs for correctness
* Check for format consistency
* Verify edge case handling
**Rollback Readiness:**
* Save original prompt version
* Document changes made
* Have revert process ready
* Monitor closely post-deployment
**Strong Improvement (90%+ accuracy):**
* Publish and monitor
* Document what worked
* Apply learnings to other tools
**Moderate Improvement (70-89% accuracy):**
* Run second optimization with more examples
* Add ideal outputs for clarity
* Test again before publishing
**Minimal Improvement (\<70% accuracy):**
* Review if tool has right inputs
* Check if task too complex for single prompt
* Consider workflow redesign
* Consult [Debug Tools](/03-running-operations/debugging-testing/debug-tools/debug-tools)
**No Improvement:**
* Verify feedback quality and diversity
* Check if evaluation criteria correct
* Review if fundamental data missing
* May need human-in-the-loop (see [Automation Modes](/03-running-operations/task-management/automation-modes/automation-modes))
## Integration with Evaluation Framework
Optimize Outputs works seamlessly with [Evaluation Framework](/04-observability-analytics/evaluation-framework/evaluation-framework) for continuous quality improvement.
**Connected Workflow:**
1. **Evaluation Framework** defines validation criteria for outputs
2. **Task executions** generate accuracy scores against criteria
3. **Learning Hub** aggregates scores to identify low-performing tools
4. **Optimize Outputs** uses failed evaluations as feedback for improvement
5. **Improved prompts** increase future evaluation scores
6. **Analytics** track improvement trends over time
**Benefits:**
* Automated quality measurement
* Data-driven optimization
* Quantifiable improvements
* Continuous learning loop
## Next Steps
Set evaluation criteria to measure optimization success
Validate optimized prompts with test datasets
Rerun failed tasks after optimization to demonstrate improvement
Monitor improved accuracy in production task executions
# Overview Analytics
Source: https://docs.beam.ai/04-observability-analytics/overview-analytics/overview-analytics
Monitor agent performance, task completion rates, evaluation scores, and user feedback through the centralized Analytics dashboard
The Analytics dashboard provides real-time visibility into agent performance across key metrics—completion rates, evaluation scores, runtime, and user feedback—enabling data-driven optimization decisions.
![The Analytics dashboard showing a date range, summary cards, completion rate, average evaluation score, and feedback score.]()
## Understanding the Analytics Dashboard
Access comprehensive performance insights for any agent by navigating to **Analytics** in the agent sidebar.
**Date range** - Use the date picker or choose **Last 7 days**, **Last 30 days**, or **Last 3 months** to filter metrics and trends
**Task summary cards** - Five indicators displayed at the top of the dashboard:
* Tasks completed
* Tasks failed
* Tasks approval rate (for HITL workflows)
* Avg. runtime duration
* Total runtime duration
**Performance summaries** - Separate panels below the task summary cards show:
* Completion rate (percentage of tasks finishing successfully)
* Average evaluation score (mean accuracy across all evaluated nodes)
* Feedback score (positive vs negative user ratings)
**Trend charts** - The lower dashboard shows:
* **Evaluation scores history**, showing average evaluation scores across the selected period
* **Tasks**, showing completed and failed task counts across the selected period
* **Credit consumption**, showing credit usage across the selected period
When no tasks fall within the selected date range, the summary values display `0` and the history charts show **No data available for this period**.
## Key Metrics Explained
### Tasks Completed
**What it measures:** Total number of tasks that executed successfully and reached completion without errors.
**Dashboard display:** Numeric count with percentage change from prior period (e.g., "+118.60% from prior period")
**What to monitor:**
* Steady growth indicates healthy agent adoption
* Sudden drops may signal workflow issues or reduced triggering
* Compare against tasks failed to calculate success rate
**Related pages:**
* [Task Executions](/03-running-operations/task-management/task-executions/task-executions) - View individual task details and execution logs
### Tasks Failed
**What it measures:** Total number of tasks that encountered errors and did not complete successfully.
**Dashboard display:** Numeric count with percentage change from prior period (e.g., "-100.00% from prior period" when zero failures)
**What to monitor:**
* Target: 0 failures or \<5% failure rate
* Investigate any non-zero values immediately
* Use [Debug Tools](/03-running-operations/debugging-testing/debug-tools/debug-tools) to diagnose failures
**Common failure causes:**
* Integration authentication errors
* Missing required input data
* Timeout errors on complex workflows
* API rate limiting
**Related pages:**
* [Debug Tools](/03-running-operations/debugging-testing/debug-tools/debug-tools) - Diagnose and resolve execution errors
* [Rerunning Tasks](/03-running-operations/debugging-testing/rerunning-tasks/rerunning-tasks) - Retry failed tasks after fixes
### Tasks Approval Rate
**What it measures:** Percentage of tasks requiring human approval that were approved vs rejected in HITL workflows.
**Dashboard display:** Percentage with change from prior period (e.g., "0% from prior period")
**What to monitor:**
* High rejection rates (>20%) indicate agent output quality issues
* Use rejected task feedback to improve prompts
* Consider adding [Evaluation Criteria](/04-observability-analytics/evaluation-framework/evaluation-framework) to catch issues before human review
**When this appears:**
* Only visible for agents with [Automation Modes](/03-running-operations/task-management/automation-modes/automation-modes) configured for human-in-the-loop (HITL)
* Shows 0% if no approval checkpoints configured
**Related pages:**
* [Automation Modes](/03-running-operations/task-management/automation-modes/automation-modes) - Configure HITL approval checkpoints
### Average Runtime
**What it measures:** Mean execution time per task from trigger to completion.
**Dashboard display:** Duration in minutes and seconds (e.g., "4m") with percentage change from prior period
**What to monitor:**
* Baseline your typical runtime for the agent's workflow complexity
* Sudden increases may indicate:
* Integration slowdowns
* Increased prompt complexity
* Model performance degradation
* Network latency issues
**Optimization strategies:**
* Review slow nodes using execution logs
* Simplify prompts where possible
* Use faster LLM models for non-critical steps
* Implement parallel execution for independent tasks
### Total Runtime
**What it measures:** Cumulative execution time across all completed tasks in the selected date range.
**Dashboard display:** Duration in hours and minutes (e.g., "21h 17m") with percentage change
**What this indicates:**
* Overall agent workload and resource consumption
* High values with high task counts = good adoption
* High values with low task counts = workflow inefficiency
### Completion Rate
**What it measures:** Percentage of tasks that finished successfully out of total tasks attempted.
**Dashboard display:** Large circular gauge showing percentage (e.g., "98.95%")
**Target benchmarks:**
* **95-100%:** Excellent - Agent highly reliable
* **90-94%:** Good - Minor optimization opportunities
* **85-89%:** Acceptable - Investigate frequent failure patterns
* **\<85%:** Needs attention - Significant reliability issues
**Calculation:** `(Tasks Completed / (Tasks Completed + Tasks Failed)) × 100`
**How to improve:**
* Identify and fix common failure patterns using [Debug Tools](/03-running-operations/debugging-testing/debug-tools/debug-tools)
* Add error handling and retry logic to workflow nodes
* Validate integrations are properly authenticated
* Use [Test Datasets](/03-running-operations/debugging-testing/test-datasets/test-datasets) to catch issues before production
**Related pages:**
* [Debug Tools](/03-running-operations/debugging-testing/debug-tools/debug-tools) - Systematic error diagnosis
* [Rerunning Tasks](/03-running-operations/debugging-testing/rerunning-tasks/rerunning-tasks) - Retry and validate fixes
### Average Evaluation Score
**What it measures:** Mean accuracy percentage across all nodes with evaluation criteria configured.
**Dashboard display:** Large circular gauge showing percentage (e.g., "98.41%")
**Target benchmarks:**
* **95-100%:** Excellent - Evaluation criteria well-calibrated
* **90-94%:** Good - Minor prompt optimization opportunities
* **85-89%:** Acceptable - Review criteria strictness and prompt quality
* **\<85%:** Needs improvement - Systematic quality issues
**What this indicates:**
* How well agent outputs match defined quality standards
* Effectiveness of evaluation criteria configuration
* Need for prompt optimization
**How to improve:**
* Use [Optimize Outputs](/04-observability-analytics/optimize-outputs/optimize-outputs) to automatically improve underperforming nodes
* Review and refine evaluation criteria for balance between strictness and practicality
* Enable auto-run on low-scoring nodes for self-healing
* Analyze failed evaluations to identify patterns
**When this appears:**
* Only shows data for agents with [Evaluation Framework](/04-observability-analytics/evaluation-framework/evaluation-framework) criteria configured
* Empty if no evaluation criteria defined on any workflow nodes
**Related pages:**
* [Evaluation Framework](/04-observability-analytics/evaluation-framework/evaluation-framework) - Configure validation criteria and auto-run
* [Optimize Outputs](/04-observability-analytics/optimize-outputs/optimize-outputs) - AI-powered prompt optimization
### Feedback Score
**What it measures:** User satisfaction with agent outputs based on thumbs up/down ratings.
**Dashboard display:** Large circular gauge showing percentage positive (e.g., "100% Positive feedback") with breakdown of positive (👍) vs negative (👎) counts
**Target benchmarks:**
* **90-100%:** Excellent - Users highly satisfied with outputs
* **80-89%:** Good - Minor quality improvements needed
* **70-79%:** Acceptable - Address common user complaints
* **\<70%:** Needs attention - Systematic output quality issues
**How users provide feedback:**
* Thumbs up/down buttons on task execution results
* Feedback captured per task or per workflow step
* Comments can accompany ratings for qualitative insights
**How to improve:**
* Review negative feedback comments to identify common issues
* Use feedback to refine prompts and evaluation criteria
* Implement feedback-driven optimization via [Optimize Outputs](/04-observability-analytics/optimize-outputs/optimize-outputs)
* Consider if evaluation criteria align with user expectations
**Related pages:**
* [Optimize Outputs](/04-observability-analytics/optimize-outputs/optimize-outputs) - Learn from user feedback to improve prompts
## Using Analytics for Optimization
### Identifying Performance Issues
**Low Completion Rate + High Failures:**
* **Issue:** Workflow reliability problems
* **Action:** Use [Debug Tools](/03-running-operations/debugging-testing/debug-tools/debug-tools) to diagnose common failure patterns
* **Validation:** Create [Test Datasets](/03-running-operations/debugging-testing/test-datasets/test-datasets) covering failure scenarios
**Low Evaluation Score + High Completion Rate:**
* **Issue:** Agent completing tasks but with poor quality
* **Action:** Use [Optimize Outputs](/04-observability-analytics/optimize-outputs/optimize-outputs) to improve underperforming nodes
* **Validation:** Review [Evaluation Framework](/04-observability-analytics/evaluation-framework/evaluation-framework) criteria for balance
**Low Feedback Score + High Evaluation Score:**
* **Issue:** Evaluation criteria don't match user expectations
* **Action:** Review negative feedback comments and adjust evaluation criteria
* **Validation:** Incorporate user feedback patterns into evaluation rules
**High Average Runtime + Low Task Count:**
* **Issue:** Workflow inefficiency limiting adoption
* **Action:** Identify slow nodes in execution logs and optimize prompts or use faster models
* **Validation:** Monitor runtime trends after optimization
### Tracking Improvement Trends
**After Prompt Optimization:**
1. Note baseline evaluation score and completion rate
2. Apply optimization via [Optimize Outputs](/04-observability-analytics/optimize-outputs/optimize-outputs)
3. Monitor analytics for 7-14 days
4. Expect 10-40% improvement in evaluation scores
5. Document successful optimization patterns
**After Adding Evaluation Criteria:**
1. Baseline period shows no evaluation score
2. After criteria deployment, evaluation score appears
3. Initial scores typically 70-85% as criteria are calibrated
4. Use auto-run to self-heal low scores
5. Scores stabilize at 90-95% after 2-4 weeks
**After HITL Implementation:**
1. Approval rate metric appears
2. Initial rejection rates often 15-30% as agents learn
3. Use rejection feedback to refine prompts
4. Target 5-10% rejection rate for mature agents
5. High approval rates indicate agents ready for full automation
## Best Practices
**Daily (for new agents):**
* Check completion rate and failure count
* Review any failed tasks immediately
* Monitor evaluation scores for instability
**Weekly (for stable agents):**
* Review all key metrics for trends
* Compare current week vs prior week performance
* Investigate any metric degradation >10%
* Celebrate improvements with stakeholders
**Monthly (for mature agents):**
* Analyze trends across 30-day and 3-month views
* Identify seasonal patterns or usage changes
* Plan optimization initiatives based on data
* Review and update evaluation criteria if needed
**New Agent Baseline (First 30 Days):**
* Completion rate: 85-90% acceptable as agent stabilizes
* Evaluation score: 75-85% during calibration
* Feedback score: 80-90% as users learn agent capabilities
* Average runtime: Establish typical duration for workflow complexity
**Mature Agent Targets (After 30 Days):**
* Completion rate: 95%+
* Evaluation score: 90%+
* Feedback score: 90%+
* Average runtime: Within 10% of baseline
**Document Baselines:**
* Record initial metrics when agent goes live
* Note any major workflow changes affecting comparability
* Use baselines to calculate ROI and improvement percentages
**Sudden Drops (>20% decrease overnight):**
* **Likely causes:** Integration outage, authentication failure, upstream system change
* **Action:** Check recent workflow changes, verify integrations, review execution logs
* **Urgency:** High - investigate within 1 hour
**Gradual Decline (10-20% decrease over 1-2 weeks):**
* **Likely causes:** Data drift, prompt degradation, evaluation criteria misalignment
* **Action:** Analyze recent task executions, run test datasets, consider re-optimization
* **Urgency:** Medium - investigate within 1 day
**Unexpected Spike (task count increases >50%):**
* **Likely causes:** New trigger source, increased adoption, duplicate triggering
* **Action:** Verify expected behavior, check for duplicate task creation, validate trigger configuration
* **Urgency:** Medium - investigate within 1 day
**Metric Stagnation (no change for 2+ weeks):**
* **Likely causes:** Stable agent performance OR lack of usage
* **Action:** Verify task triggering is occurring, check if usage patterns changed
* **Urgency:** Low - review during weekly check-in
**Benchmarking Similar Agents:**
* Compare completion rates for agents handling similar complexity
* Identify highest-performing agents and analyze their prompts/configuration
* Use top performers as templates for new agents
**Workflow Complexity Tiers:**
* **Simple (1-3 nodes):** Target 98%+ completion, 95%+ evaluation
* **Medium (4-8 nodes):** Target 95%+ completion, 90%+ evaluation
* **Complex (9+ nodes):** Target 92%+ completion, 88%+ evaluation
**Industry Standards:**
* Invoice processing: 95%+ completion, 95%+ evaluation
* Email triage: 97%+ completion, 90%+ evaluation
* Data extraction: 90%+ completion, 93%+ evaluation
* Customer inquiry: 93%+ completion, 88%+ evaluation
## Next Steps
Set up evaluation criteria to measure and track output quality
Use AI to improve agent accuracy when evaluation scores are low
Drill into individual task details and execution logs
Diagnose and resolve failures affecting completion rate
# Changelog
Source: https://docs.beam.ai/05-resources/changelog/changelog
Stay up-to-date with the latest Beam AI platform features, improvements, and releases
The public Beam AI Changelog is the source of truth for released product updates, improvements, and fixes.
## View the changelog
The changelog is updated independently of Beam Academy. Use it to see the current release notes.
See current Beam AI release notes on beam.ai.
# Roles and Permissions
Source: https://docs.beam.ai/05-resources/roles-and-permissions/roles-and-permissions
Create workspace roles that decide which agents each teammate can use and what they can do with them.
A role answers two questions about a teammate: which agents they can use, and what they can do with those agents. Every workspace ships with three built-in roles, **Owner**, **Admin**, and **Member**, and owners and admins can add roles of their own on top of them.
![The Roles table under Workspace settings, listing Owner, Admin, Member and a custom role]()
Roles only ever restrict. A workspace keeps working exactly as it did until you change one, so there is nothing to set up before you need it.
## What roles are
### The two things a role controls
Every role is made of the same two parts, and the role editor shows them in this order.
| Part | The question it answers | Where it lives in the editor |
| ---------------- | ----------------------------------------------------------- | ------------------------------------ |
| **Agent access** | Which agents can people with this role see and open? | The **Agent access** card at the top |
| **Capabilities** | What can they do with those agents, and with the workspace? | The **Capabilities** card below it |
Agent access is either **All agents** or a hand-picked list under **Selected agents**. Capabilities are checkboxes in collapsible groups, and whatever you tick applies the same way to every agent the role can reach. There is no per-agent level.
Both parts belong to the role, not to a person. Two people who need different sets of agents need two different roles.
### The built-in roles
| Role | What it is |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner** | Full access to everything, plus the actions no other role can be given: deleting the workspace, changing the payment method, and transferring ownership. |
| **Admin** | Full access to agents and workspace settings, and can manage people and roles. |
| **Member** | The default for new teammates. This is the role you edit when you want to change what an ordinary teammate can do. |
**Owner** and **Admin** are locked. They carry a **Locked** badge in the Roles table, their capabilities open read-only, and they cannot be deleted. As new features are added to Beam, those two roles pick up the new capabilities on their own. **Member** is editable, but like the other built-in roles it cannot be deleted.
### Where roles live
Roles sit under **Workspace settings**, on the **Access** tab. The tab has two sub-tabs:
* **People** lists everyone in the workspace and the role each person holds.
* **Roles** lists the roles themselves and what each one grants.
Only owners and admins see the **Roles** sub-tab and can change anyone's role. Everyone else sees **People** as a read-only list. If you cannot find **Roles**, that is why.
### When to create your own
Reach for a custom role when more than a couple of people share a workspace and not all of them should be able to change everything in it.
* A live agent runs a business-critical process and you want most of the team to run it, not edit it.
* A new teammate should start with a narrow set of agents rather than all of them.
* Finance owns billing, IT owns SSO, and neither needs to touch agents.
* An outside collaborator needs one agent and nothing else.
If everyone in your workspace is meant to do everything, the built-in roles are already enough and you do not need to create any.
## How to use roles
### Create a role
Go to **Workspace settings**, open the **Access** tab, then select **Roles**.
The **Create role** button sits in the page header, to the right of the heading. The role editor opens.
Fill in **Role name**, which is required. Add a **Description** as well.
![The Create role dialog showing the Role details section with a name and description filled in]()
The description is shown to admins when they assign the role. A line like "runs the invoicing agents, cannot edit them" saves someone guessing later.
In the **Agent access** card, open the dropdown on the right and pick one:
* **All agents**: every agent in the workspace is available to the role.
* **Selected agents**: only the agents you pick.
Choosing **Selected agents** enables the **Allowed agents** list below it. Search it, tick the agents this role should reach, and leave the rest unticked.
![The Agent access section set to Selected agents with four agents ticked in the Allowed agents list]()
An agent created after you save the role is kept out of it. New agents stay private until someone adds them to a role's **Allowed agents** list, so widening a role is always a deliberate edit rather than something that happens on its own.
In the **Capabilities** card, expand a group and tick the boxes the role should have. Use **Select all** at the top of a group to tick the whole group at once.
![The Capabilities section of the role editor with the Agents group expanded showing Create & edit, Delete and Run]()
The groups are:
| Group | What it covers |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| **Agents** | **Create & edit**, **Run**, and **Delete**, applied to the agents in the role's set. |
| **Beam AI** | **Projects**, **Skills**, and **Views**, each with its own nested **Delete**. |
| **Integrations** | Connecting integrations, managing other people's connections, and building custom integrations. |
| **Workspace Settings** | General settings, notifications, billing, and SSO. |
| **API Keys** | Creating and revoking API keys. |
| **Inbox** | Reading and clearing workspace notifications. |
Some capabilities depend on others, and Beam keeps them consistent for you. **Create & edit** covers running an agent, because you cannot build one without testing it, so ticking it ticks **Run**. Deleting is always its own checkbox and never comes along with anything else. Untick a capability that others depend on and those are unticked too.
The role appears in the Roles table straight away and can be assigned from that point on.
A role has to grant at least one capability, and a role set to **Selected agents** has to have at least one agent ticked. If either is missing, **Save role** refuses and tells you what to add.
Two things never appear in the Capabilities list. Managing people and roles is limited to owners and admins and cannot be handed to a role you create. Deleting the workspace, changing the payment method, and transferring ownership belong to the owner alone. Both sets are visible, greyed out, when you open a locked role, so you can see what Owner and Admin hold.
The Roles table summarises agent access in its **Agent access** column: **All agents** for an unrestricted role, a row of agent icons for a narrowed one, with a count such as **+1** when there are more than three, and **No access** for a role that has been cut off from every agent.
### Invite someone with a role
Every invitation carries a role. Inviting is also covered in [Workspace Setup](/01-getting-started/workspace-setup/workspace-setup#inviting-team-members); this section adds the role step.
Go to **Workspace settings**, open the **Access** tab, and stay on **People**.
The button is in the page header. The **Invite members** dialog opens.
Type an address under **Enter email**, then select it from the suggestion that appears beneath the field to add it. Repeat for each person. Everyone in the batch receives the same role.
![The Invite members dialog with two email addresses added and Role set to Member]()
Open **Role** and choose the role these people should hold.
**Member** is filled in for you unless you change it. If you send the invite without touching this field, everyone in it arrives as a Member.
Each person gets an invitation email and appears in the People list with a **Pending invitation** badge until they accept.
### Change someone's role
On the **People** sub-tab, each row shows the person's current role on the right. Select it to open the list of roles you can move them to, and choose one. The change takes effect immediately.
![The People list with the role dropdown open on a teammate's row, showing Owner, Admin, Member and the custom roles]()
You cannot change your own role, so no control appears on your own row. That prevents an admin from demoting themselves out of the workspace they administer. Ask another owner or admin if your own role needs to change.
You can only move someone to a role below your own. Making someone an owner is separate: it goes through transferring ownership, and only the current owner can start it.
### Give one agent to specific roles
You do not have to work from the role side. Open an agent and select **Manage access** in the header to decide which roles reach that one agent.
![The Agent access dialog on an agent, set to Selected roles with the roles that already reach it listed under Allowed roles]()
The dialog mirrors the role editor from the other direction. **All roles** makes the agent available to everyone, **Selected roles** limits it to the roles you tick under **Allowed roles**, and **Save changes** applies it. Whichever side you edit from, you are changing the same thing, so an agent removed here also disappears from that role's **Allowed agents** list.
Switching to **Selected roles** does not hand you an empty list. **Allowed roles** fills in with every role that already reaches this agent, including roles you never pointed at it by name, because a role set to **All agents** reaches it too. Read the list as "who can get to this agent today", then remove the ones who should not.
**Owner** never appears in the list. Owners reach every agent and that cannot be taken away. **Manage access** is only available to owners and admins.
### Delete a role
Open the role actions menu at the end of a role's row in the Roles table and choose **Delete**. Only roles you created can be deleted: the **Member** row offers **Edit** alone, and the locked **Owner** and **Admin** rows have no menu at all.
A role cannot be deleted while people still hold it. Move everyone to another role first. The **Members** count in the Roles table tells you how many there are, and selecting that number opens the People list filtered to that role.
## Troubleshooting
**Cause**: Roles are managed by owners and admins only.
**Solution**:
* Check the role on your own row under **Workspace settings** → **Access** → **People**.
* Ask an owner or admin to make the change, or to move you to **Admin**.
**Cause**: The role is missing something it needs.
**Solution**:
* A role must grant at least one capability. Tick something under **Capabilities**.
* A role set to **Selected agents** must have at least one agent ticked under **Allowed agents**.
* If the agent list is still loading, wait a moment and select **Save role** again.
**Cause**: People are still assigned to it.
**Solution**:
* Select the number in the **Members** column to open the People list filtered to that role.
* Move each person to another role, then delete it.
**Cause**: Their role no longer reaches that agent. An agent outside a role's set is hidden rather than shown as blocked, so it disappears from their lists.
**Solution**:
* Open the role and check **Agent access**. If it is set to **Selected agents**, add the agent to **Allowed agents**.
* Or open the agent, select **Manage access**, and add their role under **Allowed roles**.
**Cause**: The person's role does not grant that capability. Restricted controls stay visible and explain themselves rather than disappearing.
**Solution**:
* Publishing a workflow needs the **Create & edit** capability under **Agents**.
* Running one needs **Run**.
* Add the capability to their role, or move them to a role that has it.
**Cause**: This is deliberate. The role control does not render on your own row, so nobody can remove their own access by accident.
**Solution**:
* Ask another owner or admin to change it for you.
* Becoming the owner is a separate flow. The current owner starts a transfer of ownership, and you accept it from the People list.
## Next steps
Create or join a workspace and invite your first teammates.
Let your team sign in with your organization's existing credentials.
Build the shared data views a role can be given access to.
Browse the reusable capabilities available in your workspace.
# Azure SSO Setup
Source: https://docs.beam.ai/05-resources/team-management-sso/team-management-sso
Configure Azure Single Sign-On integration with Beam AI platform for enterprise authentication
Configure Single Sign-On (SSO) with Azure Entra ID (formerly Azure Active Directory) to enable your team to access Beam using your organization's existing credentials.
## Workspace settings
Open **Workspace settings** from the workspace menu to manage shared workspace configuration. The current settings surface includes **General**, **Access**, **Notifications**, **SSO**, and **Usage** tabs.
* Use **General** to update the workspace name, icon, and domain.
* Use **Access** to invite teammates, search the workspace by name or email, and change who holds which role. Owners and admins also get a **Roles** tab here for building roles of their own. See [Roles and Permissions](/05-resources/roles-and-permissions/roles-and-permissions).
* Use **SSO** to access this Azure SSO configuration.
The **SSO** tab only appears for people whose role can manage SSO. If you cannot see it, ask
an owner or admin to give your role that permission, or to run the setup for you.
## Prerequisites
Before configuring SSO, ensure you have:
* A workspace on the **Pro** plan. Single sign-on is not available on Free
* A role that can manage SSO, which is how the **SSO** tab becomes visible
* Administrative access to Microsoft Entra ID
* Administrative access to your Beam workspace
* Access to your organization's Azure tenant
On the Free plan the **SSO** tab still appears in **Workspace settings**, with a padlock beside
it, but you cannot open it. Hovering the tab explains that single sign-on is available on Pro.
Upgrade the workspace first, then come back and follow this guide from the top.
**Authentication Method**: Beam uses SAML 2.0 for SSO integration with Azure Entra ID. This guide walks through the complete setup process in both Azure and Beam.
## Configure Azure Entra ID
Log into the Azure Portal and navigate to **Microsoft Entra ID**.
![Enterprise Application]()
![New application]()
![Create your own Application]()
![Set up single sign on]()
![Choose SAML]()
**Identifier (Entity ID)**:
```text theme={null}
urn:production:sp:beam:
```
**Reply URL**:
```text theme={null}
https://app.beam.ai/api/auth/saml/callback
```
![Basic SAML Configuration]()
![Attributes and claims]()
![Download Federation Metadata XML]()
## Configure Beam Platform
**Attribute Mappings**:
```text theme={null}
email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
family_name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
given_name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
nickname: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nickname
```
Upload the **Federation Metadata XML** file you downloaded from Azure.
Click **Save** to enable SSO for your workspace.
**SSO Activation**: Once saved, users can access Beam by clicking "Sign in with SSO" on the login page and entering their company email address.
## Testing Your SSO Setup
After configuration, test the SSO integration:
Log out of Beam (if currently logged in), navigate to [app.beam.ai](https://app.beam.ai), and click **Sign in with SSO**. Enter a user's company email address. The user should be redirected to Azure for authentication, then logged into Beam after successful Azure login.
Check that user profile information is correctly populated, verify email and name match the Azure profile, and confirm workspace access is granted appropriately.
## Troubleshooting
**Cause**: The Beam application may be blocked by your organization's Azure security policies.
**Solution**:
* Have an Azure administrator locate the Beam application in the Enterprise Applications list
* Grant necessary permissions for the application
* Ensure users or groups are assigned to the application
* Verify the application is not blocked by Conditional Access policies
**Cause**: Attribute claim names in Azure don't match the expected format in Beam.
**Solution**:
* Verify the attribute mappings in Azure match exactly
* Check that source attributes are available in user profiles
* Re-download and re-upload the Federation Metadata XML file
* Contact Beam support if issues persist
**Cause**: SSO configuration may not be saved correctly or needs time to propagate.
**Solution**:
* Verify SSO configuration is saved in Beam workspace settings
* Wait 5-10 minutes for configuration to propagate
* Clear browser cache and try again
* Check that Federation Metadata XML was uploaded successfully
**Cause**: Users may not have workspace access or proper role assignments.
**Solution**:
* Ensure users are invited to the Beam workspace
* Check user role assignments in workspace settings
* Verify email addresses match between Azure and Beam invitations
* Have users check spam/junk folders for invitation emails
## Next Steps
Configure workspace settings and invite team members
Build your first AI agent after SSO is configured
# Workspace Skills
Source: https://docs.beam.ai/05-resources/workspace-skills/workspace-skills
Browse, search, and start creating reusable capabilities from the workspace Skills module.
Skills are reusable capabilities that Beam uses to get work done. Open **Skills** from the workspace navigation to browse the skills available in your workspace and start using one in chat.
## Browse skills
The Skills page has **Active Skills** and **All Skills** tabs. Use **Listing** to filter the catalog, or search by skill name.
Skill cards identify whether a skill is **Personal** or a **System skill**. Select **Try in chat** on a card to use that skill in a Beam conversation.
## Start creating a skill
1. Open **Skills** from the workspace navigation.
2. Select **New skill**.
3. In the guided Beam chat, describe what you want the skill to do.
Beam asks for a one- or two-sentence description of the task or problem the skill should handle.
## See also
Navigate the workspace and its shared modules.
Start an agent from a reusable template.
# Workspace Views
Source: https://docs.beam.ai/05-resources/workspace-views/workspace-views
Create and search workspace views for an agent's node input and output data tables.
Views are workspace-level pages for searching an agent's node input and output data tables. Open **Views** from the workspace navigation to create and manage the views available in your workspace.
![The empty Workspace Views page with Create a view controls]()
## Browse views
The Views page lists the views in your workspace. Use **Search** or the **Search by name & description** field to find a view.
When your workspace has no views, select **Create a view** from the empty state or the page header.
## Create a view
1. Open **Views** from the workspace navigation.
2. Select **Create a view**.
3. Enter a **Name**.
4. Select an **Agent**.
5. Add a **Description** and select **Submit**.
## See also
Navigate the workspace and its shared modules.
Browse reusable capabilities available in your workspace.
# Delete Context File
Source: https://docs.beam.ai/08-reference/api/agent-context-files/delete-context-file
delete /context/agent/{agentId}/file/{fileKey}
Delete a context file for an agent by file key.
# Download Context File
Source: https://docs.beam.ai/08-reference/api/agent-context-files/download-context-file
get /context/agent/{agentId}/file/{fileId}/download
Generate a download link for an agent context file.
# Upload Context File
Source: https://docs.beam.ai/08-reference/api/agent-context-files/upload-context-file
post /context/agent/{agentId}/file
Upload context files for an agent.
# Add Edge to Graph
Source: https://docs.beam.ai/08-reference/api/agent-graph/add-edge-to-graph
post /agent-graphs/add-edge
Add a new edge (connection) between two nodes in the agent workflow graph. Edges define the flow of execution between nodes.
# Add Node to Graph
Source: https://docs.beam.ai/08-reference/api/agent-graph/add-node-to-graph
post /agent-graphs/add-node
Add a new node to an agent workflow graph. Nodes represent individual steps or actions in the agent execution flow.
# Create a complete agent graph
Source: https://docs.beam.ai/08-reference/api/agent-graph/create-complete-graph
post /agent-graphs/complete
Creates a new agent with its complete graph structure including nodes, edges, and tool configurations. Both an active/published graph and a draft graph are created.
# Get Agent Graph
Source: https://docs.beam.ai/08-reference/api/agent-graph/get-agent-graph
get /agent-graphs/{agentId}
Retrieve the workflow graph configuration for a specific agent.
# Get Agent Graph with nodes
Source: https://docs.beam.ai/08-reference/api/agent-graph/get-agent-graph-with-nodes
get /agent-graphs/{agentId}/nodes/lite
Retrieve graphs and its nodes (without configuration)
# Get detailed information for a specific node
Source: https://docs.beam.ai/08-reference/api/agent-graph/get-detailed-information-for-a-specific-node
get /agent-graphs/{agentId}/nodes/{nodeId}
Retrieves comprehensive details of a specific node within an agent graph, including its tool configuration, input/output parameters, position coordinates, and execution settings. The node must belong to a graph associated with the specified agent in the current workspace.
# Get Task Nodes by Tool
Source: https://docs.beam.ai/08-reference/api/agent-graph/get-task-nodes-by-tool
get /agent-graphs/agent-task-nodes/{toolFunctionName}
Retrieve task nodes that use a specific tool function for analysis and optimization.
# Publish agent graph
Source: https://docs.beam.ai/08-reference/api/agent-graph/publish-agent-graph
patch /agent-graphs/{graphId}/publish
# Test Graph Node
Source: https://docs.beam.ai/08-reference/api/agent-graph/test-graph-node
post /agent-graphs/test-node
Test a specific node in the agent graph to validate its configuration and behavior.
# Update agent and its draft graph
Source: https://docs.beam.ai/08-reference/api/agent-graph/update-agent-graph
put /agent-graphs/{agentId}
Updates an existing agent (name, description, settings) and replaces all nodes and edges in its draft graph.
# Update Edge in Graph
Source: https://docs.beam.ai/08-reference/api/agent-graph/update-edge-in-graph
put /agent-graphs/update-edge/{edgeId}
Update an existing edge properties such as condition in the agent workflow graph.
# Update Graph Node
Source: https://docs.beam.ai/08-reference/api/agent-graph/update-graph-node
patch /agent-graphs/update-node
Update Graph Node
# Update input/output parameters for a node tool configuration
Source: https://docs.beam.ai/08-reference/api/agent-graph/update-inputoutput-parameters-for-a-node-tool-configuration
patch /agent-graphs/{agentId}/nodes/{nodeId}/input-output-params
Updates the input and/or output parameters of a tool configuration associated with a specific node in the agent graph. Input parameters define how data flows into the tool (e.g., AI-filled, user-provided, static values, or linked from other node outputs). Output parameters define the data structure returned by the tool. Only the parameters provided in the request body will be updated; omitted parameters remain unchanged.
# Update prompt of the tool
Source: https://docs.beam.ai/08-reference/api/agent-graph/update-prompt-of-the-tool
patch /agent-graphs/{agentId}/nodes/{nodeId}/prompt
Update prompt of the tool used in the node
# Add context files to an existing agent
Source: https://docs.beam.ai/08-reference/api/agent-setup/add-context-files
post /agent-setup/{agentId}/context-file
Upload one or more context files (up to 10) to an existing agent. Supported file types include documents (txt, csv, pdf, xls, xlsx, docx, doc, ppt, pptx) and images (png, jpeg, jpg, tiff, heif, bmp).
# Get agent setup session
Source: https://docs.beam.ai/08-reference/api/agent-setup/get-agent-setup-session
get /agent-setup/session/{agentId}
Retrieves the current setup session state for a specific agent, including configuration and progress.
# Process agent setup steps
Source: https://docs.beam.ai/08-reference/api/agent-setup/process-agent-setup-steps
post /agent-setup
Multi-step agent configuration endpoint. Use this after agent creation (via /agent-context and /agent-creation).
**GENERATE_SOP**: Generates Standard Operating Procedures for the agent
- Required: agentId, query
- Returns: nextStep (GRAPH_GENERATION)
**GRAPH_GENERATION**: Creates agent workflow graph
- Required: agentId
- Returns: nextStep (TOOL_MATCHING)
**TOOL_MATCHING**: Matches existing tools to agent needs
- Required: agentId
- Returns: nextStep (TOOL_GENERATION)
**TOOL_GENERATION**: Generates new custom tools if needed
- Required: agentId
- Returns: nextStep (TOOL_INTEGRATION)
**TOOL_INTEGRATION**: Integrates selected tools with the agent
- Required: agentId
- Returns: nextStep (UPDATE_AGENT)
**UPDATE_AGENT**: Finalizes and updates the agent configuration
- Required: agentId
- Returns: nextStep (AGENT_UPDATED)
Note: Use /agent-context first to get threadId, then /agent-creation to create the agent and get agentId before using this endpoint.
# Submit feedback on the provided context
Source: https://docs.beam.ai/08-reference/api/agent-setup/submit-context-feedback
post /agent-setup/agent-context/feedback
# Provide feedback for a specific setup step
Source: https://docs.beam.ai/08-reference/api/agent-setup/submit-step-feedback
post /agent-setup/{agentId}/{setupStep}/feedback
# Upload context files during agent setup
Source: https://docs.beam.ai/08-reference/api/agent-setup/upload-context-files
post /agent-setup/upload
Upload one or more files (up to 10) to provide context during agent setup. Supported file types include documents (txt, csv, pdf, xls, xlsx, docx, doc, ppt, pptx) and images (png, jpeg, jpg, tiff, heif, bmp).
# Import a skill from a zip file
Source: https://docs.beam.ai/08-reference/api/agent-skills/import-skill
post /agent/{agentId}/skills/import
Import a skill into an agent from a zip file. The zip file should contain the skill configuration and any associated assets. The skill will be added to the specified agent.
# Approve Task Execution
Source: https://docs.beam.ai/08-reference/api/agent-task/approve-task-execution
post /agent-tasks/execution/{taskId}/user-consent
Provide user consent for a task to continue execution when approval is required.
# Create Agent Task
Source: https://docs.beam.ai/08-reference/api/agent-task/create-agent-task
post /agent-tasks
Create a new task for an agent to execute. The task will be queued and processed according to the agent workflow.
# Get Agent Analytics
Source: https://docs.beam.ai/08-reference/api/agent-task/get-agent-analytics
get /agent-tasks/analytics
Retrieve analytics data for agent task execution including success rates, performance metrics, and usage statistics.
# Get Latest Task Executions
Source: https://docs.beam.ai/08-reference/api/agent-task/get-latest-task-executions
get /agent-tasks/latest-executions
Retrieve the most recent task executions for monitoring and debugging purposes.
# Get Next Task
Source: https://docs.beam.ai/08-reference/api/agent-task/get-next-task
get /agent-tasks/iterate
Iterate through tasks based on filters. Useful for task queue processing and navigation.
# Get Task Details
Source: https://docs.beam.ai/08-reference/api/agent-task/get-task-details
get /agent-tasks/{taskId}
Retrieve detailed information about a specific task including execution status and results.
# Get Task Updates (SSE)
Source: https://docs.beam.ai/08-reference/api/agent-task/get-task-updates-sse
get /agent-tasks/{taskId}/updates
Subscribe to real-time updates for a specific task using Server-Sent Events (SSE). Returns a stream of task execution status changes and results.
# Get Tool Output Schema
Source: https://docs.beam.ai/08-reference/api/agent-task/get-tool-output-schema
get /agent-tasks/tool-output-schema/{graphNodeId}
Retrieve the expected output schema for a specific tool in the agent graph.
# List Agent Tasks
Source: https://docs.beam.ai/08-reference/api/agent-task/list-agent-tasks
get /agent-tasks
Retrieve a paginated list of agent tasks with filtering and grouping options.
# Rate Task Output
Source: https://docs.beam.ai/08-reference/api/agent-task/rate-task-output
patch /agent-tasks/execution/{taskId}/output-rating
Submit a rating for task execution output to improve agent performance.
# Reject Task Execution
Source: https://docs.beam.ai/08-reference/api/agent-task/reject-task-execution
post /agent-tasks/execution/{taskId}/rejection
Reject a task execution that requires user consent. The task will be marked as rejected and stop execution.
# Retry Task Execution
Source: https://docs.beam.ai/08-reference/api/agent-task/retry-task-execution
post /agent-tasks/retry
Retry a failed or incomplete task execution with optional modifications.
# Submit User Input
Source: https://docs.beam.ai/08-reference/api/agent-task/submit-user-input
patch /agent-tasks/execution/{taskId}/user-input
Provide user input for a task that requires human interaction to continue execution.
# Get a view by ID
Source: https://docs.beam.ai/08-reference/api/agent-views/get-a-view-by-id
get /agent-views/{viewId}
# List all views
Source: https://docs.beam.ai/08-reference/api/agent-views/list-all-views
get /agent-views
# List linked records for a link column
Source: https://docs.beam.ai/08-reference/api/agent-views/list-linked-records-for-a-link-column
get /agent-views/{viewId}/columns/{columnId}/links/{recordId}
# List records from a view
Source: https://docs.beam.ai/08-reference/api/agent-views/list-records-from-a-view
get /agent-views/{viewId}/records
# List Agents
Source: https://docs.beam.ai/08-reference/api/agents/list-agents
get /agent
Retrieve a paginated list of agents available in your workspace. Filter by type, category, or search query.
# Update Agent
Source: https://docs.beam.ai/08-reference/api/agents/update-agent
put /agent/{agentId}
Update an agent by id within the current workspace.
# Authentication
Source: https://docs.beam.ai/08-reference/api/authentication/authentication
Learn how to authenticate with the Beam AI public API using your API key
The Beam AI public API uses API key authentication. Include your API key in the `x-api-key` header with every request.
## Base URL
```
https://api.beamstudio.ai
```
## Authentication Header
All API requests require the `x-api-key` header:
```bash theme={null}
x-api-key: your-api-key-here
```
Most endpoints also require a `current-workspace-id` header:
```bash theme={null}
current-workspace-id: your-workspace-id
```
## Example Authenticated Request
```bash cURL theme={null}
curl -X GET https://api.beamstudio.ai/v2/user/me \
-H "x-api-key: your-api-key-here" \
-H "current-workspace-id: your-workspace-id"
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.beamstudio.ai/v2/user/me', {
headers: {
'x-api-key': 'your-api-key-here',
'current-workspace-id': 'your-workspace-id'
}
});
const data = await response.json();
```
```python Python theme={null}
import requests
response = requests.get(
'https://api.beamstudio.ai/v2/user/me',
headers={
'x-api-key': 'your-api-key-here',
'current-workspace-id': 'your-workspace-id'
}
)
data = response.json()
```
## Getting Your API Key
1. Log in to [Beam AI](https://app.beam.ai)
2. Navigate to your workspace settings
3. Go to the **API Keys** section
4. Create a new API key or copy an existing one
Keep your API key secure. Do not share it publicly or commit it to version control.
# Get preferred models
Source: https://docs.beam.ai/08-reference/api/custom-tool/get-preferred-models
get /custom-tool/preferred-models
# MCP Connection
Source: https://docs.beam.ai/08-reference/api/mcp-connection/mcp-connection
Connect to Beam AI using the Model Context Protocol (MCP) for seamless AI assistant integration
Connect Beam AI to your AI assistant using the Model Context Protocol (MCP). This enables you to access all Beam AI capabilities directly from Claude Desktop, Cursor, or any MCP-compatible client.
## What is MCP?
The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and services. By connecting Beam AI via MCP, you can:
* 📋 List and view your AI agents
* 🚀 Create and execute agent tasks
* 📊 Monitor task progress and get real-time updates
* ✅ Approve or reject tasks requiring user consent
* 📈 Access agent analytics and performance metrics
* 📁 Download agent context files
## Prerequisites
Before connecting, you'll need:
1. **A Beam AI account** - Sign up at [app.beam.ai](https://app.beam.ai)
2. **An API key** - Generate one from your Beam Dashboard
3. **An MCP-compatible client** - Such as Claude Desktop, Cursor, or another MCP client
## Getting Your API Key
Go to [app.beam.ai](https://app.beam.ai) and sign in to your account
Click on your workspace icon in the top left corner and select **Personal settings**
In the settings menu, navigate to the **API Keys** section
Click **Create New API Key** and give it a descriptive name
Copy the generated API key and store it securely - you'll need it for the connection setup
Keep your API key secure! Never share it publicly or commit it to version control. Treat it like a password.
## Connecting to Beam AI via MCP
### Using Claude Code CLI
The easiest way to connect is using the Claude Code CLI:
```bash theme={null}
claude mcp add --transport http beam-server https://api.beamstudio.ai/mcp --header "Authorization: Bearer YOUR_API_KEY"
```
Replace `YOUR_API_KEY` with the API key you generated in the previous step.
After running this command, restart your AI assistant (Claude Desktop, Cursor, etc.) to activate the connection.
### Manual Configuration (Claude Desktop)
If you prefer to configure manually, edit your Claude Desktop configuration file:
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
Add the following configuration:
```json theme={null}
{
"mcpServers": {
"beam-server": {
"command": "uvx",
"args": [
"mcp-proxy",
"https://api.beamstudio.ai/mcp",
"--transport",
"streamablehttp",
"-H",
"Authorization",
"Bearer YOUR_API_KEY"
]
}
}
}
```
Replace `YOUR_API_KEY` with your actual API key.
### Verifying the Connection
After connecting, you can verify the connection is working by asking your AI assistant:
```
Can you list my Beam AI agents?
```
If connected successfully, the assistant will retrieve your agents from Beam AI and display them.
## Available MCP Tools
Once connected, your AI assistant will have access to the following Beam AI capabilities:
### User Management
* `getCurrentUser` - Get your user profile and workspace information
### Agent Management
* `listAgents` - List all your AI agents
* `downloadContextFile` - Download agent context files
### Agent Configuration
* `getAgentGraph` - Get agent workflow configuration
* `testGraphNode` - Test specific workflow nodes
* `getTaskNodesByTool` - Find tasks using specific tools
### Task Operations
* `createAgentTask` - Create new agent tasks
* `listAgentTasks` - List all agent tasks
* `getTaskDetails` - Get detailed task information
* `getTaskUpdates` - Stream real-time task updates
### Task Execution Control
* `submitUserInput` - Provide input for paused tasks
* `approveTaskExecution` - Approve tasks requiring consent
* `rejectTaskExecution` - Reject task execution
* `retryTaskExecution` - Retry failed tasks
### Analytics & Optimization
* `getAgentAnalytics` - Get agent performance metrics
* `rateTaskOutput` - Rate task execution quality
* `optimizeTool` - Optimize tool configurations
* `getToolOptimizationStatus` - Check optimization progress
## Example Usage
Here are some example commands you can use with your AI assistant once connected:
### Create an Agent Task
```
Create a task for my "Customer Support" agent to analyze the latest support tickets
```
### Monitor Task Progress
```
Show me the status of my running agent tasks
```
### Get Agent Analytics
```
What's the performance analytics for my Sales Outreach agent from the last 7 days?
```
### Manage Workflows
```
Show me the workflow configuration for my Data Analysis agent
```
## Troubleshooting
### Connection Failed
If you're unable to connect:
1. **Verify your API key is correct** - Try generating a new one
2. **Check your internet connection** - Ensure you can reach api.beamstudio.ai
3. **Restart your AI assistant** - Close and reopen the application
4. **Check the configuration file** - Ensure the JSON syntax is correct
### Tools Not Appearing
If the Beam AI tools don't appear in your assistant:
1. **Restart your AI assistant completely** - Quit and relaunch
2. **Check the connection status** - Ask "What MCP servers are connected?"
3. **Verify API key permissions** - Ensure your API key hasn't been revoked
### API Key Issues
If you're getting authentication errors:
1. **Generate a new API key** - Old keys may have expired
2. **Check for extra spaces** - Ensure no whitespace in your API key
3. **Verify the header format** - Should be `Authorization: Bearer YOUR_API_KEY`
## Security Best Practices
Periodically generate new API keys and revoke old ones for enhanced security
Create different API keys for different environments (development, production)
Regularly check API key usage in your Beam Dashboard
Immediately revoke any API key you suspect has been compromised
## Need Help?
If you encounter any issues or have questions:
* 📧 Email: [support@beam.ai](mailto:support@beam.ai)
* 💬 Discord: [Join our community](https://discord.gg/beam-ai)
* 📚 Documentation: [docs.beam.ai](https://docs.beam.ai)
***
MCP connection enables powerful AI-to-AI integration, allowing your assistant to leverage Beam AI's full capabilities seamlessly.
# API Overview
Source: https://docs.beam.ai/08-reference/api/overview/overview
Complete API reference for Beam AI platform integration and automation
Welcome to the Beam AI API documentation. This API allows you to programmatically interact with the Beam platform to create, manage, and execute AI agents.
## Base URL
All API requests should be made to:
```
https://api.beamstudio.ai
```
## Authentication
The Beam AI API uses API key authentication. You'll need to:
1. Include your API key in the `x-api-key` header
2. Include your `current-workspace-id` header for workspace-specific operations
Learn more in the [Authentication](/08-reference/api/authentication/authentication) section.
## Quick Start
Here's a simple example to get you started:
```javascript JavaScript theme={null}
const taskResponse = await fetch('https://api.beamstudio.ai/agent-tasks', {
method: 'POST',
headers: {
'x-api-key': 'your-api-key',
'current-workspace-id': 'your-workspace-id',
'Content-Type': 'application/json'
},
body: JSON.stringify({
agentId: 'agent_123456',
input: { message: 'Hello, agent!' }
})
});
const task = await taskResponse.json();
```
```python Python theme={null}
import requests
task_response = requests.post(
'https://api.beamstudio.ai/agent-tasks',
headers={
'x-api-key': 'your-api-key',
'current-workspace-id': 'your-workspace-id'
},
json={
'agentId': 'agent_123456',
'input': {'message': 'Hello, agent!'}
}
)
task = task_response.json()
```
## API Sections
### Users
Retrieve information about authenticated users and their workspaces.
* [Get Current User](/08-reference/api/user/get-current-user)
### Agents
List and manage AI agents in your workspace.
* [List Agents](/08-reference/api/agents/list-agents)
### Agent Graphs
Access agent workflow structures and configurations.
* [Get Agent Graph](/08-reference/api/agent-graph/get-agent-graph)
### Agent Tasks
Create, monitor, and analyze agent task executions.
* [Create Task](/08-reference/api/agent-task/create-agent-task)
* [List Tasks](/08-reference/api/agent-task/list-agent-tasks)
* [Get Analytics](/08-reference/api/agent-task/get-agent-analytics)
## Error Handling
The API uses standard HTTP status codes:
* `200` - Success
* `201` - Created
* `400` - Bad Request (invalid parameters)
* `401` - Unauthorized (invalid or missing token)
* `403` - Forbidden (insufficient permissions)
* `404` - Not Found
* `500` - Internal Server Error
## Support
Need help with the API?
* Check our [documentation](/01-getting-started/welcome/welcome)
* Join our [Discord community](https://discord.gg/beam-ai)
* Contact support at [support@beam.ai](mailto:support@beam.ai)
## Changelog
Stay updated with the latest API changes in our [Changelog](/05-resources/changelog/changelog).
# Get Active Tools
Source: https://docs.beam.ai/08-reference/api/tool/get-active-tools
get /tool/active-tools
Retrieve all active tools for the current workspace.
# Get Tool Optimization Status
Source: https://docs.beam.ai/08-reference/api/tool/get-tool-optimization-status
post /tool/optimization-status/thread/{threadId}
Check the status of an ongoing tool optimization process.
# Optimize Tool
Source: https://docs.beam.ai/08-reference/api/tool/optimize-tool
post /tool/optimize/{toolFunctionName}
Optimize a tool's performance and configuration based on usage patterns and feedback.
# Get Current User
Source: https://docs.beam.ai/08-reference/api/user/get-current-user
get /v2/user/me
Retrieve the profile information of the currently authenticated user, including their workspaces and permissions.