Background agent dashboard reference
Open Build > Background Agents. Select an agent to inspect its definition, capabilities, deployment, and sessions. For a guided setup, use Create your first background agent.
The list page
The Background Agents list is your organization's inventory of agents. Open Build > Background Agents to reach the inventory at /manage/background-agents.
The header has these actions:
| Action | What it does |
|---|---|
| Settings (gear icon) | Opens Background Agent Settings. |
| Refresh | Reloads the list and clears the search. |
| Create Agent | Opens the create dialog. See Create and configure an agent. |
| Discover | Opens the catalog of ready-made agents. |
Views
A toggle at the top right switches between two views:
- Table view: one row per agent. This is the default. Columns are Name, Platform, Status, Content, Traffic (30d), Groups, Requests, Owners, and Created, and Table settings controls which columns are visible. Group by groups groups the inventory by group assignment.
- Grid view: one card per agent, showing its name, platform, and owners. The card links to the same detail page as the table row.
Search and Advanced Filters work in both views. Export and the column controls are table-only.
Search and filters
The search box filters by agent name. Select Advanced Filters to narrow the list further:
| Filter | Filters by |
|---|---|
| Group | Agents assigned to a selected group. |
| Owner | Agents assigned to a specific owner. |
| Platform | The runtime the agent runs on. See Platforms. |
| MCP Server | Agents that have at least one tool from the selected server. |
| Status | active or disabled. |
| Risk Level | The highest risk among the agent's capabilities: Critical, High, Medium, Low, or Not Assessed. |
A badge shows how many filters are active, and Clear filters resets them all.
Requests
The inventory's Requests tab lists requests from agent owners for extra tools, skills, or triggers. It has Pending, Approved, Rejected, and All filters and a search by agent, requester, or tool. See Capability requests for review.
Capabilities
Capabilities are the allowlist. Each entry can be individually enabled or disabled:
| Capability | What it grants |
|---|---|
| Tools | Gateway tools the agent may call, identified by integration and tool slug. |
| Skills | Skills attached to the agent. Enabled skills are uploaded to the external platform on sync. |
| Rules | Rules in the API capability model; they have no separate detail-page tab. |
| Integration auth | Per-integration connected-auth configuration. The selected identity determines which account is used for tool calls. See Agent credentials. |
The agent detail page
Selecting an agent opens its detail page. The header shows the agent's name, its platform badge, its status, a deployment button, and an Active toggle. Labels include Deploy, Redeploy, and Deploy changes, depending on the agent and where the action appears. Work is organized into Overview, Tools, Skills, Triggers, Sessions, and Settings, each showing a count where one applies. When modes are enabled for your organization, the beta Modes tab appears between Triggers and Sessions.
Overview
A Synced badge sits beside the heading. The identity card repeats the name, platform, and status, and adds the Version (for example v1), how long ago the agent was deployed, and its slug. Two actions sit on that card:
| Action | What it does |
|---|---|
| Test | Opens a test of the agent so you can check its behavior. On Willow Agents this starts a session and consumes a credit. |
| Connect | Opens the connection details — the MCP endpoint and the Authorization header to send. |
Below the identity card, a System Prompt editor with its own Save is the first thing on the page: the prompt defines how the agent behaves before you add tools, skills, and triggers. Then summary cards for Tools, Skills, and Triggers, an Active Guards card listing the guards that apply and their action (with Manage), Owners, and Recent Sessions with View all.
Tools
Tools are grouped by MCP server. Each server group has an enabled-tool count, an authentication control such as Auth not set, and a toggle for its tools. Individual rows show the tool name and slug, usage count, risk band, enabled state, and edit/remove controls.
Add Tools opens a picker with Your MCP servers, Willow connectors, MCP catalog, and Custom API call tabs. See Give an agent access to tools for assignment and authentication.
The Agent Communication section lists linked agents. Linking adds a send_message tool and an API trigger on the receiving agent.
Tool editor
The agent tool editor exposes Name, Description, Slug, Enabled, Annotation, HTTP method/path, and the input schema and request mapping. Form and JSON views describe the same tool document. JSON includes action, inputSchema, annotations, and ai_risk.
Schema properties include name, type, description, Required, and Constant value. Generate from JSON Example supplies an initial schema. AI Generate opens the tool-generation dialog. Save stores an edit; managed runtimes receive it on deployment. See Edit a tool for the task.
Skills
The skills assigned to the agent. Skills shape how the agent reasons; they don't call APIs. Add or remove skills, and re-run risk assessment per skill.
Triggers
Triggers start the agent automatically. The tab is split into three kinds, each with its own add action:
| Kind | What fires it |
|---|---|
| API triggers | A call you make to the agent's trigger endpoint. |
| Scheduled triggers | A schedule you define. |
| Webhook triggers | An external event delivered to a webhook, for example a new GitHub issue. |
Add API trigger asks for a Name, a Message (the prompt delivered to the agent when the trigger fires), an optional Mode (beta, see Modes), and an optional Session ID JSONata expression. The expression is evaluated against the request body to correlate the conversation: matching an existing session resumes it, and leaving it empty starts a new conversation on each call.
Channels
On an agent with Slack selected, Triggers also contains Channels. Channel rows and defaults control response modes and direct messages. The dedicated Slack app must be connected before channels can be added. See Slack setup.
Slack workflow steps
When this beta feature is enabled for your organization, Slack workflow steps in Triggers lets you turn on the default step and configure custom steps for the agent's Slack app. See Slack workflow steps for setup, inputs, and outputs.
Modes
A beta tab that appears between Triggers and Sessions when modes are enabled for your organization. It holds the agent's named extra system prompts, which you then pick per Slack channel, Slack workflow step or trigger.
Sessions
The conversation sessions the agent has run, with their events. The Overview card reads "No sessions yet — they appear once this agent runs."
Settings
The Settings tab separates these sections:
| Section | Contents |
|---|---|
| General | Avatar, name, slug, description, and a short description for the agent's Slack app. |
| Gateway | The gateway used by the agent. |
| Platform Configuration | Runtime, model (for example Claude Sonnet 5.5 (recommended)), system prompt, and platform-specific configuration. |
| Slack App | The agent's dedicated Slack app. See Slack setup. |
| Tokens | Platform, manual, and legacy gateway tokens. See Agent credentials. |
| Deployment & Sync | Platform deployment state, action, and credit information where applicable. |
| Budget | Spend and the daily, weekly, or monthly cap for Willow Agents and Claude Managed Agents. See Agent Budgets. |
| Limits | Per-tool call limits and caps on new sessions and messages. See Agent Limits. |
| Owners | People assigned to the agent. |
| Danger Zone | Agent deletion. |
Deployment state
Synced, the version, and the deployment time describe the definition on the runtime. Before the first deployment, a managed agent has no deployed definition. Deployment state is separate from the Active toggle and tool authentication.
The Admin API's sync_state includes the last sync status, external agent ID/version, AWS ARN where applicable, MCP server URL, last successful sync time, and error. See Sync Background Agent for the response contract.
Invoke and sessions
The Admin API invoke operation sends a message to the agent on its platform and starts or resumes a conversation. It requires the agent to be active and synced, on either claude-managed-agents or aws-agentcore.
Conversations are correlated by a session key: a stable identifier you choose for the thing the conversation is about, such as a ticket ID or a pull request URL. Reusing a session key resumes that conversation; a new key starts a fresh one. This is what lets an agent accumulate context per ticket rather than per call.
The dashboard has a Sessions tab and Recent Sessions on Overview. The Admin API documents listing sessions and reading session events. Consult those contracts for platform applicability; the dashboard Test action and the Admin API invoke operation are separate entry points.
Organization settings
The gear icon in the list header opens Background agent settings. These settings control available runtimes and what owners and end users may do.
Enabling and disabling
Toggle an agent between active and disabled from the detail page header.
| Status | Meaning |
|---|---|
active | The agent can call tools and receive messages. |
disabled | The agent cannot call tools or receive messages. |
A disabled agent keeps its configuration but cannot authenticate to the gateway or run, which is a fast way to pause an agent without deleting it.
A new agent is created active and has its own gateway identity, before it has been deployed to any platform. Active is not the same as deployed: until the first deploy the agent has a definition and status but no deployed definition on its managed runtime.
What end users see
Users open Background Agents in the Connect portal to see the agents assigned to them, with the connection details for each. The page appears only when the Background Agents toggle is on under End-User Settings > Sidebar Pages.
Users are not given agents automatically. Until an admin assigns one, the page reads:
No background agents assigned. Contact your administrator to get a background agent assigned to you.
Permissions
Access is controlled by the Background Agents permission scope, which offers View, Create, Edit, and Delete. See Roles.
API
The Admin API operations below manage agent definitions and runs. Each link contains the request and response contract. The dashboard's deployment operation uses Sync Background Agent.
| Operation | Reference |
|---|---|
| List | List Background Agents |
| Create | Create Background Agent |
| Get | Get Background Agent |
| Get by slug | Get Background Agent By Slug |
| Update | Update Background Agent |
| Delete | Delete Background Agent |
| Deploy | Sync Background Agent |
| Rotate secret | Rotate Background Agent Secret |
| Invoke | Invoke Background Agent |
| List sessions | List Background Agent Sessions |
| Session events | Get Background Agent Session Events |
Custom runtime integration describes runtime access to the gateway. Harness delivery API describes the requests Willow sends to an external runtime. These are separate interfaces.