> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Create many purpose-built Agents in Runlayer and configure each one with the right model, tools, and triggers.

## Why Agents

Runlayer lets you build **multiple Agents**, each for a different job.
Instead of one general assistant with broad access, you create focused agents
for specific workflows, teams, or risk levels.

Each Agent combines:

* Instructions (main prompt + optional skills)
* A chosen model
* A curated set of MCP connectors and tools
* Optional deployment channels (Slack, schedules, webhooks)

This gives you reusable, policy-governed automation you can scale across use
cases.

## Agents for any purpose

You can create agents for almost any internal workflow, for example:

* Support agent: summarize tickets, query product docs, draft replies
* Incident agent: triage alerts, pull logs, post status updates
* RevOps agent: collect CRM context, prep account briefs
* Security agent: review policy denials, summarize risk events
* Platform ops agent: monitor MCP health and failed tool calls
* Leadership reporting agent: weekly usage + adoption summaries
* Code review agent: receive GitHub pull request webhooks, use GitHub MCP tools to fetch the diff, and draft review feedback

Pattern: one purpose per agent, minimal tool scope, clear prompt contract.

Agents can also generate and [publish artifacts](https://docs.runlayer.com/platform-artifacts.md) (reports,
datasets, files) during their runs, so automated report generation and document
distribution workflows are covered as part of the same agent run.

Agents are best as an automation layer on top of your existing systems, not a
replacement for them: runs are short-lived (see [Runtime limits](#runtime-limits))
and the agent workspace and memory should not replace your source-of-truth
systems. For long-running, stateful services, deploy a custom MCP server with
[Runlayer Deploy](https://docs.runlayer.com/platform-deploy.md) instead.

## Set up an agent

**1. Create the Agent**

Go to **Agents** and click **Create new**.

You can start from scratch or pick a **template**. Templates pre-fill the name, prompt, connectors, and built-in tools so you can get running faster. Templates are distilled from real workspace patterns — examples include 1:1 Prep, Release Notifier, Account Intelligence, Daily Briefing, and others. The available set may change as new patterns are added.

While you describe a new agent, Runlayer checks the agents you can already use. If one looks like it does the same job, a card points to it with **Use it** (open that agent), **Duplicate & edit** (clone it), or **Create anyway**. The hint never blocks creating your own agent.

In setup, define:

* Name
* Main prompt (required)
* Privacy: **Private** or **Public** (workspace-visible)
* Custom icon (optional — pick from the built-in icon library or upload your own; synced to Slack when a Slack app is configured)
* Built-in tools (for example, Memory or Code mode)

**2. Attach connectors and tools**

Add one or more connectors (MCP servers), then select which tools are enabled.
This is the core capability boundary for the agent. Connectors that require OAuth show a **Connect** button on the connector card or a guided setup dialog with per-connector status. Connecting creates a [session grant](https://docs.runlayer.com/platform-agent-accounts.md#session-grants) that shares your OAuth credentials with the agent. When you start your first interactive chat with an agent, a delegation is also auto-granted so the agent can act on your behalf without a separate authorization step.

**3. Configure model + behavior**

Open the agent detail page and set:

* Model — defaults to the workspace [recommended model](#recommended-model) when one is set; available models depend on which providers are configured in **Settings → AI Providers** (see [LLM providers](#llm-providers) below)
* Model settings — optional per-model reasoning tuning (see [Model settings](#model-settings))
* Instructions (prompt)
* Skills
* Optional env vars (see [Environment variables](#environment-variables))

**4. Test in chat**

Chat with your agent interactively. The chat streams responses in real time and shows tool calls inline so you can verify prompt behavior, connector access, and model output before deploying.

The chat automatically injects Runlayer tools (search, run, manage) so the agent can reason about your Runlayer workspace without you manually adding the Runlayer connector first.

**5. Choose deployment mode**

Use one or more:

* **Schedules** for recurring runs — each schedule includes a timezone and an interpretation mode: **UTC cron** (default — the cron expression is evaluated in UTC) or **Local wall clock** (the cron expression is evaluated in the selected timezone, automatically adjusting for DST). Runs triggered at common cron times (e.g., top of hour) may start a short time after the scheduled minute. Scheduled runs execute as the **schedule creator** — their identity, delegation, and connector credentials — so on a shared agent, each user with edit access can add their own schedule and get runs under their own identity (every schedule card shows a *Runs as …* badge). If the creator loses access to the agent or is deactivated, their schedule is disabled automatically. If a scheduled run fails, the schedule creator receives a Slack DM (when Slack is connected)
* **Webhooks** for event-driven runs — each webhook can optionally require authorization. Authorization is **off by default**: any caller with the full webhook URL (which contains a secret token) can trigger runs, so treat the URL as a secret. When authorization is enabled, callers must include a valid API key in the `x-runlayer-api-key` header (an `Authorization: Bearer` header is reserved for user session JWTs and does not accept API keys); unauthenticated requests are rejected. You can create one directly from the webhook dialog: on the **API Key** example, click **Create API key**. It is a personal API key, the same as one from **Settings → Personal API keys**, so there are no scopes to pick: it carries your identity, so runs it starts execute as you unless the webhook runs as the agent account (below). Organization API keys are not accepted. Send a JSON object. If it has an `input` field, that field must be a non-empty string and becomes the agent's input; otherwise the whole JSON body is passed to the agent as text, so payloads from tools like HubSpot or Stripe work as-is. Identical payloads sent to the same webhook within 30 seconds are treated as duplicate deliveries and ignored; different webhooks, including webhooks for different agents, are handled independently. Each webhook can also enable **Run as agent account** mode: when enabled, the run executes under the agent's own [agent account](https://docs.runlayer.com/platform-agent-accounts.md) identity instead of the webhook caller's identity, so sessions and audit logs attribute the run to the agent account. This is useful for true machine-to-machine automation where no human user triggers the webhook. To turn it on, open the agent and go to **Agent → Triggers → Add trigger → Webhook** (or open an existing webhook) and switch on **Run as Agent Account**. The toggle is on the agent's own page, so you only see it once Agents is enabled for your workspace. Switching it on needs the **Use agent accounts** permission, which every built-in role includes, and that permission is checked again on every call: against the API key's owner when authorization is required, or against the webhook's creator when it isn't. The API key is still a personal key, and its owner must be able to run the agent; the key only proves who may call the webhook, while the run itself executes as the agent account
* **Signed webhooks** — switch on **Sign payloads (HMAC)** in the webhook dialog to reject requests that don't carry a valid signature. Pick the scheme that matches the sender: **Standard Webhooks** (`webhook-id`, `webhook-timestamp` and `webhook-signature` headers; leave the secret blank and Runlayer generates one) for a sender you control, or **Jira / GitHub / Bitbucket** for senders that sign the raw body with a single `X-Hub-Signature-256: sha256=<hex>` (or `X-Hub-Signature`) header. That scheme has no generated secret: paste the secret you set in, or got from, the sender. A signed webhook can stay unauthenticated, so senders that can't add an `x-runlayer-api-key` header, such as GitHub, can still call it; the run then executes as the agent creator. Rotating a secret keeps the old one valid for a short overlap, unless you also switch schemes
* **GitHub events (for example a pull request label added or removed)** — point a GitHub repository or organization webhook at an agent webhook. In GitHub, open **Settings → Webhooks → Add webhook**, paste the agent's webhook URL as **Payload URL**, set **Content type** to `application/json`, enter a random string as **Secret**, and under **Let me select individual events** pick **Pull requests**. In Runlayer, turn on **Sign payloads (HMAC)** for that webhook with the **Jira / GitHub / Bitbucket** scheme and paste the same secret. GitHub sends one `pull_request` delivery per PR change, and the whole JSON body reaches the agent as its input, so say in the agent's prompt which deliveries to act on, for example "only continue when `action` is `labeled` or `unlabeled` and `label.name` is `ready-for-qa`; otherwise reply `skipped` and stop". Every delivery, including GitHub's initial `ping`, starts a run. To start runs only for label changes, send the request from a GitHub Actions workflow on `pull_request: types: [labeled, unlabeled]` instead, signed the way the webhook dialog's **HMAC** example shows. That workflow only works for pull requests opened from branches in the same repository: GitHub doesn't pass repository secrets to `pull_request` workflows for pull requests from forks or Dependabot, so those requests can't be signed and Runlayer rejects them. Use the repository webhook above when you need those pull requests too
* **API** for runs started from your own code, such as a CI job or an orchestrator that starts a run, polls its status and cancels it. See [Agent runs](https://docs.runlayer.com/platform-api.md#agent-runs)
* **Slack** integration (if configured) — run result DMs (**Notifications → Run results** in the agent's Slack settings) can be set to Always, Errors only, or Never. Errors only and Always also cover the DM sent when a scheduled run fails to start; Never turns it off. These DMs come from the agent's own Slack app. Agents without their own app still get run failure and budget DMs from the workspace Slack app, with **Budget alerts** and **Run failures** toggles on the agent's Slack card. **Run failures** DMs the person a scheduled or webhook run runs as when it fails to start or fails mid-run. The built-in say tool lets agents post messages to Slack from any trigger type (Slack, playground, webhook, or schedule) as long as the agent has a connected Slack app; no Slack MCP connector is required. It can DM a person by Slack user ID or by email, so a run started outside Slack can still reach people, for example **DM me when you're done** in the playground or DMing the assignee named in a webhook payload. The say tool returns the posted message's Slack `ts`, which the agent can pass back as `thread_ts` on a later call to post threaded follow-ups in the same conversation. It can also share files the agent wrote in its workspace (reports, exports, images) by passing their paths as `attachments` — up to 10 files of 10 MB each, attached to that same Slack message. To read files back from Slack, see [Files an agent can read from Slack](https://docs.runlayer.com/platform-slack-notifications.md#files-an-agent-can-read-from-slack). A companion react tool adds or removes emoji reactions as the agent bot, by default on the Slack message that started the run, so you can tell an agent in its prompt to react :white\_check\_mark: once a PR is open or :triangular\_flag\_on\_post: when it is blocked. It can also react to another message by channel ID and message timestamp, and follows the same outbound messaging controls as say; turn off **Emoji reactions** in the agent's Slack settings to stop it reacting at all. The say tool posts **as the agent** (its Slack app bot); Slack MCP connector send tools like `slack_send_message` instead post **as the connected user** — see [Message identity](https://docs.runlayer.com/platform-slack-notifications.md#message-identity-as-the-agent-vs-as-you). Admins can restrict where agents post using [outbound messaging controls](https://docs.runlayer.com/platform-slack-notifications.md#outbound-messaging-controls) — block DMs, channel posts, or specific channels per agent
* **Event triggers** — in the agent's **Agent → Triggers** section, choose **Add trigger → Audit event** to run the agent when selected Runlayer platform events fire. Unlike webhooks (which external systems call in to), event triggers react to Runlayer's own [audit event](https://docs.runlayer.com/platform-audit-logs.md) stream — any audit event type can be selected, for example `tool_call`, `access_denied`, or `security_violation`. In the new or edit trigger dialog, use the optional **Semantic condition** field (max 2,000 characters) to describe which matching events should actually start a run. Leave it blank to run for every selected event. Trigger cards show a **Semantic condition** badge when one is set; open the card to view, edit, or clear the full prompt. Example: a security agent triggered on `access_denied` and `security_violation` events, with Runlayer MCP attached to pull surrounding audit context and summarize the incident (see [Use Runlayer MCP inside agents](#use-runlayer-mcp-inside-agents))
* **Slack channel monitors** (if enabled in your workspace) — the agent watches selected Slack channels (including private channels) and reacts to new top-level messages, optionally filtered by a semantic condition prompt. Replies inside a thread never trigger a monitor; the agent answers those only when mentioned or, if **Thread follow-ups** is on in its Slack settings, after a mention earlier in that thread or in a thread the agent started itself. The agent replies in the channel only when it has something to add; runs where it stays silent are still listed in the agent's activity

Each schedule and trigger can also pick its own **Model**, one the agent's AI provider serves, so frequent checks can run on a cheaper model and reports on a stronger one. Leave it on **Agent's model** to follow the agent. If the provider stops serving the chosen model, runs use the agent's model instead.

All trigger types are configured from the web UI — no code required. Schedules use cron expressions with a timezone picker, webhooks are set up in a dialog, event triggers use an event-type picker and optional **Semantic condition** field, and channel monitors can filter with a natural-language condition prompt.

To test before going live, exercise the agent's prompt and connectors in chat first. Webhooks can be tested immediately by sending a request to the webhook URL with `curl` or Postman (include the `x-runlayer-api-key` header if authorization is enabled). For schedules and event triggers, check the **Sessions** tab after the first trigger fires to confirm the run behaved as expected.

You can **disable** an agent at any time using the toggle on the agent detail page. Disabled agents skip scheduled runs, reject webhook calls, return an error for Slack interactions, and can't be chatted with: chat shows **This agent is turned off**. Re-enable the toggle to resume normal operation.

**6. Validate in Sessions**

Check run history for status, token/cost usage, and execution trace.
Failed runs can be retried directly from the Sessions view, and any past run can be **resumed** in chat — click the run to open it, then click **Open in chat** to continue the conversation with the full prior context loaded.
Runs triggered from Slack show conversation, channel, and trigger details with a link to the originating Slack message.

Each run also includes a collapsible **Security** section showing ToolGuard scan results — policy denials, security violations, and warnings — so you can audit security events inline without leaving the Sessions view.

Tighten prompt/tool scope before broad rollout.

## Allowing an agent to invoke other agents

In **Allowed agents** on the calling agent's detail page, choose **Add agents**
(or **+**). Search for agents, review their connections, then choose **Add agents**
in the dialog to grant access. You can
select up to 50 agents you have permission to use. **Approve always** stops
adding agents once a calling agent has 50; remove one first.

Agent accounts with no Runlayer-hosted agent behind them (external agents
using client credentials) can't hand work to Runlayer agents: there is no
agent to add under **Allowed agents**.

Adding authorizes the calling agent to invoke those targets on your behalf. The
first approved call establishes the target's access through your connected
accounts. Missing accounts still need to be connected. Each user of a shared
agent chooses their own selection; the owner's selection does not grant access for
other users.

Choose **Remove agent** from a target's menu to immediately block new calls from that agent. This keeps your
separate access to the target. Losing permission to use either agent also prevents
calls. If the target's connected access is revoked or expires, choose **Renew access**
from that target's menu to reauthorize it. Adding or removing another agent does
not renew existing permissions. These personal
permissions are not copied when an agent is cloned or restored from version
history.

The calling agent uses the **Runlayer MCP** `run_agent` tool and needs
**Can hand work to other agents** turned on under **Capabilities** on its
detail page. An existing target connection alone does not authorize
another agent to call it. Agents cannot grant themselves this permission.
Choosing an agent as your main agent in Go turns its delegation on, even if
you turned it off before.
With delegation on, an agent does the work its own tools cover and hands off
work another agent is built for, or that you name an agent for, without asking
whether it should; the approval below is where you decide. Your main agent
handles your email, calendar, messages, and documents itself.

What happens when the calling agent hands work to another agent:

* **Target disabled**: the handoff is refused without asking you, and the
  calling agent is told the target is disabled.
* **Target in Allowed agents**: the handoff runs without asking.
* **Your main agent in Go**: handoffs from your Go conversation with it run
  without asking. Choosing it as your main agent is your consent. Previously
  saved access that you removed, revoked, or let expire still needs approval.
  Other people who chat with it, and its scheduled, triggered or follow-up runs (including
  check-ins it schedules for itself), follow the rules below.
* **Target not in Allowed agents, you're in the conversation**: you get an
  approval showing the target, the exact task, and what the agent shares.
  Choose **Approve once** to run this handoff only, **Approve always** to add
  the target to **Allowed agents** for this calling agent, or **Deny**. The
  same choices appear on the approval card in chats, Slack, and Microsoft
  Teams; the Inbox offers Approve and Deny only.
* **Target not in Allowed agents, nobody is present** (schedules, webhooks,
  event triggers, channel monitors): the handoff is refused. Add the target to
  **Allowed agents** first.

Once a handoff starts, the calling agent doesn't have to wait or poll for it:
Runlayer wakes the calling agent's conversation in a new turn when the target's
run finishes (see [Waiting on external work](#scheduled-continuations)). If
an agent hands work to several agents at once, its conversation wakes once, when
the first run finishes, and checks the others then.

Cancelling a run also cancels every run it handed off that is still running, and
the runs those handed off in turn. Only that run's own handoffs are covered:
runs handed off by an earlier turn of the same conversation keep running. A
run that has ended can't hand off anything new, including a handoff that was
already starting when the cancel landed. A run that already finished isn't
affected, and cancelling a handed-off run leaves the run that started it
running.

Handoffs nest at most two levels deep: an agent, the agent it hands work to, and
that agent's own handoff. A handoff back to an agent already in the chain is
refused, so two agents can't keep handing the same work back and forth.

When this shipped, handoffs that scheduled and triggered runs made on your
behalf in the previous 30 days were added to your **Allowed agents** shortly
after the update, so they keep working: up to the 50 most recent targets per
calling agent. Handoffs you approved once in a conversation were not.

Approvals hide tokens and keys in the task and arguments they show. Other long
random-looking values show their first and last characters plus a fingerprint
that tells different values apart; UUIDs, payment record ids, and commit SHAs
in GitHub links or commit fields stay visible. The agent still sends the task as written.

This section selects existing saved agents. **Subagents** defines inline
assistants within the current agent's runtime.

## Cloning an agent

Any workspace member can clone an agent from the agent detail page (overflow menu → **Clone**) or from the agent card on the list page. Cloning copies the agent's configuration, attached connectors, and tools into a new agent owned by you. Only the agent owner can delete an agent; cloning is available to everyone.

Cloning is the supported way to create an independent copy of an agent — to roll back changes to the same agent, use [version history](#version-history) instead. A clone keeps no link to its source: changes made in the clone never flow back. To have a team improve one shared agent instead of each person keeping a copy, see [Improve one shared agent together](#improve-together). Agents can also be created and managed programmatically via [Runlayer MCP](https://docs.runlayer.com/runlayer-mcp.md) tools (`create_agent`, `update_agent`, and the `set/add/remove_agent_connectors` and `set/add/remove_agent_skills` tools) — including from inside another agent that has the Runlayer connector attached.

## Version history

Every saved change to an agent creates a new version. Open the overflow menu on the agent detail page and choose **Version history** to browse them — each version shows the agent's identity, model, instructions, capabilities, connectors and skills, subagents, and environment variables as they were at that point.

Anyone who can view the agent can browse its history. Restoring requires edit access and is non-destructive: it creates a new version from the one you selected (labeled "Restored from v*N*") rather than rewriting history. If the selected version references connectors or skills that no longer exist or that you can't access, those are skipped and the restore is reported as partial.

From an AI client, you can list, read and restore versions with the [Runlayer MCP](https://docs.runlayer.com/runlayer-mcp.md) tools `list_agent_versions`, `get_agent_version` and `restore_agent_version`.

Agent update entries in the [audit log](https://docs.runlayer.com/platform-audit-logs.md) include the version each change created.

## Browsing and filtering agents

The Agents list page supports:

* **Sorting** by newest, oldest, most runs, most used (unique users), last used, or alphabetical
* **Ownership tabs** — All agents, Owned by me, or Shared with me
* **Inventory tab** — every agent you can edit (the whole workspace for agent admins) with its owner, model, runs over the last 8 weeks, and upkeep issues: a model upgrade available, idle (no run in 30+ days), never run, or owner left. Select agents to upgrade their model, move them all to a model you pick (useful for models with no direct successor), disable them in bulk, or delete the disabled ones in bulk.
* **Status filter** to show only active or disabled agents
* **Search** by agent name or description
* **Owner avatar** on agent cards showing who owns the agent
* **Usage badges** on agent cards showing run count and how many people use the agent
* **Connector icons** on agent cards showing attached connectors
* **Failure badge** on agent cards when the latest run failed
* A **lock badge** on private agents you don't own

The list loads with infinite scroll, so large workspaces stay fast. Use these controls to quickly find agents in workspaces with many agents.

### Find an existing agent before you build

To reuse what your workspace already has instead of building a duplicate:

* **In the app:** search the Agents list for the job (for example "release notes"), sort by **Most used**, and open the closest match. Run it as is, or [clone it](#cloning-an-agent) and adapt your copy. Do the same on the **Skills** and **Connectors** pages.
* **With the Runlayer Assistant:** ask it to build an agent for the job. It's instructed to search your workspace's agents and skills for the same role before it builds, open the closest match, and build on it: an update to an agent you already own, a new agent modeled on a teammate's, or a skill instead of a new agent.
* **From your own tools:** [Runlayer MCP](https://docs.runlayer.com/runlayer-mcp.md) exposes `list_agents`, `list_skills` and `list_servers`, and the [Runlayer Plugin](https://docs.runlayer.com/runlayer-plugin.md) exposes `list_agents` and `search_skills`, so Claude, Cursor or an internal portal can check before creating anything. To build your own catalog page, see [Search agents, skills and connectors](https://docs.runlayer.com/platform-api.md#search-agents-skills-and-connectors).

Each option returns only what the person asking is allowed to see.

***

## Runtime capabilities

The main prompt you write is combined with Runlayer's runtime instructions. The
runtime prompt tells the agent what tools exist, how to use connected MCP
servers, where it can write files, and which environment limits apply.

Agents can use:

* Connected MCP server tools and resources selected on the agent
* Built-in local tools for shell commands, file reads, file writes, and edits
* Web browsing (a real Chromium browser for fetching and interacting with web pages; limit what it can reach with the [network access policy](#network-access-policy))
* Artifact publishing (shareable file URLs)
* Skills attached to the agent
* A persistent SQLite memory database, when memory is enabled
* A persistent workspace filesystem, scoped to that agent
* Subagents, when configured
* Slack message delivery tools, when Slack is connected
* Scheduled continuations, when enabled: the agent ends its run and is woken
  up later to continue the same conversation
* Git access to your GitHub repositories (clone, push, open pull requests) as
  your organization's GitHub App, when [GitHub access](https://docs.runlayer.com/platform-agents-github.md)
  is enabled and granted to the agent

### Filesystem workspace

Agents run in a sandbox with a writable workspace at `/tmp/workspace`. Files the
agent writes there are restored on future runs for the same agent, so recurring
agents can keep generated reports, scripts, checkpoints, small datasets, and
other working artifacts.

Filesystem persistence is scoped by agent ID. Other agents do not share those
files, and the workspace should not replace your source-of-truth systems. Use it
for working state and generated artifacts, then re-check external systems when
current data matters.

### Artifact publishing

Agents can publish reports, interactive HTML, images, and other files as persistent
Runlayer links. Artifact publishing is enabled by default for new agents.

See [Artifacts](https://docs.runlayer.com/platform-artifacts.md) for the overview and
[Create and update](https://docs.runlayer.com/artifacts/create.md#create-with-a-runlayer-agent) for example
prompts, publishing tools, limits, and updates at the same URL.

### Artifact sharing

Artifact viewers must sign in to your organization. Access can come from direct
artifact shares or the originating agent's **Artifact sharing** setting.
See [Share and control access](https://docs.runlayer.com/artifacts/sharing.md) for the available modes and how
inherited access works.

### Viewing and deleting artifacts

Open the agent's **Artifacts** tab or the main **Artifacts** library to browse
published files. See [Find and manage](https://docs.runlayer.com/artifacts/manage.md) for previews, downloads,
tags, version history, and deletion.

### Shell and code execution

Agents can run normal shell commands in the sandbox. This lets them inspect
files, transform data, install or use available packages, compile code, run test
suites, generate artifacts, and call command-line tools.

Common runtime tools include Bash, Git, Bun (`bun`, `bun x`), Python 3, uv,
ruff, ripgrep, jq, yq, SQLite, PostgreSQL client tools, curl, wget, zip, unzip,
and the GitHub CLI (`gh`). The TLA+ tools `tlc` (model checker), `sany`
(parser), and `pcal` (PlusCal translator) are also preinstalled, on a Java 21
runtime.

Bun is the only JavaScript runtime in the sandbox. Node.js, npm, and pnpm are
not installed, so agents run JavaScript and TypeScript code and package tooling
with `bun` and `bun x`.

For office files, the sandbox also includes headless LibreOffice (convert Word,
Excel, and PowerPoint files to and from PDF, and recalculate spreadsheet
formulas), qpdf, poppler PDF utilities, and the Python libraries openpyxl,
pandas, python-docx, python-pptx, XlsxWriter, and pypdf.

### Network access policy

Each agent can restrict which internet hosts its sandbox may reach. The policy
applies to the hosts the agent chooses to reach from anything it runs: shell
commands such as `curl` or `git clone`, package installs, the web fetch tool,
and the built-in browser, which every agent has. Traffic to Runlayer itself and to the agent's
connectors is never affected, and neither is the error reporting the sandbox
itself depends on unless a block list names it. Package registries and other
hosts the agent's tools reach follow the policy like any other host.

Open the agent's **Network access** section and choose **Edit**, then a mode:

* **Unrestricted** (default): the agent can connect to any public host.
* **Allow list**: the agent can only connect to the listed hosts. Every other
  connection it opens is blocked; with no hosts listed, the agent cannot
  connect to any host of its own choosing.
* **Block list**: the agent can connect to any public host except the listed
  ones.

Each entry is a hostname, optionally with a port. `github.com` matches exactly
that host. `*.githubusercontent.com` matches any subdomain, but not the apex
domain, so list both when you need both. Without a port only HTTPS on port 443
is allowed; a port such as `api.example.com:8443` allows TLS on that port. The
sandbox proxy carries TLS only, so an entry never grants SSH, plain HTTP, or
another protocol. IP addresses, private networks, and cloud metadata endpoints
are always blocked.

Changes apply to the agent's next run. A blocked request fails inside the
sandbox with an `egress_denied` error that names the host, and the agent is
instructed to report the block to the user rather than work around it. A
plain `http://` request (for example `curl github.com` with no scheme) is not
a block: it fails with `egress_https_required` and the agent is instructed to
retry the same URL over `https://`. The
policy controls which hosts the agent connects to; it does not inspect or
limit what data the agent sends to an allowed host.

> [!WARNING]
>
> A policy decides which host the agent connects to, not every site that host
> can pass traffic on to. A shared CDN or proxy behind an allowed host can route
> a connection to another site it serves, including a host on your block list:
> the site name travels inside encrypted traffic (the HTTP `Host` header, or the
> inner server name of an Encrypted Client Hello), which the sandbox proxy does
> not decrypt. Connection logs record the host the agent connected to, not the
> site reached through it. Allow only hosts whose service you trust, and prefer
> specific hostnames over broad CDN domains.

> [!NOTE]
>
> Network access policies are enforced by the sandbox egress proxy, which ships
> with the AgentCore sandbox runtime: Runlayer-hosted deployments and self-hosted
> AWS deployments that run the agent runtime in VPC networking mode with the proxy
> enabled. Where the proxy is not deployed, including the Kubernetes agent
> sandbox, the setting does not appear; an agent that already has a policy still
> shows it so it can be removed, and fails to run until it is. Where the proxy is
> deployed but does not yet enforce policies for your workspace, the setting
> shows that policies are not enforced and an allow list or block list cannot be
> saved. A policy is never silently ignored. Contact Runlayer if you are unsure
> which runtime your workspace uses.

Some websites block automated browsers on their own. A site behind bot
protection such as Cloudflare answers the agent with a "Just a moment..." or
"Verify you are human" page, a CAPTCHA, or an HTTP 403 or 503 instead of the
content. That block comes from the website, not from the agent's network access
policy or your firewall: a network access policy block always returns HTTP 403
with `egress_denied` in the response body. For research on sites like these,
add a search or crawling connector from the catalog to the agent, such as Exa,
Parallel, Firecrawl, or Perplexity, point the agent at the site's API, RSS
feed, or documentation pages, or switch the agent to a [cloud browser](#cloud-browsers).

### Source IP addresses

Restricting a system to an IP allowlist works differently for the two ways an
agent reaches it:

* **Connector tool calls.** When an agent calls a tool on one of its connectors,
  the request to the MCP server or API comes from the Runlayer platform, not the
  sandbox. On a Runlayer-hosted tenant, connectors reaching their upstream over
  the public internet use the tenant's static outbound addresses, which an
  admin copies from **Settings → Network Access** (see
  [Runlayer source IP addresses](https://docs.runlayer.com/network-firewall-requirements.md#runlayer-hosted-platform-egress)).
  For a public MCP server, add it as a connector and allowlist those addresses.
  [Tunnel](https://docs.runlayer.com/platform-connectors.md#tunnel-connector-network) and
  [AWS PrivateLink](https://docs.runlayer.com/platform-connectors.md#aws-privatelink) connections use private
  network paths instead; these public egress addresses do not apply.
* **Direct sandbox traffic.** Requests the agent opens itself (shell commands
  such as `curl`, the web fetch tool, the built-in browser) leave through the
  agent runtime's own network, which is separate from the platform's.
  **Settings → Network Access** does not list these addresses, and whether
  they stay fixed depends on how the runtime is networked. Contact Runlayer
  before you rely on them for an allowlist. A [cloud browser](#cloud-browsers)
  connects from its provider's network instead.

### Cloud browsers

On Runlayer's hosted cloud, when enabled for your workspace, agents can use a
hosted browser from
[Browserbase](https://www.browserbase.com) or
[Browser Use](https://browser-use.com), which solves CAPTCHAs and handles bot
protection that blocks the built-in browser. Runlayer provides and manages the
provider accounts; there is nothing to set up and no API key to bring. The
provider keys stay in Runlayer and never reach an agent's sandbox: when an
agent opens a cloud browser, Runlayer starts one provider session and hands the
agent only that session's connection, and stops the session when the agent's
browser closes.

Agents start with the built-in browser and switch to the cloud browser when a
site blocks them. To have an agent always use it, set the
[environment variable](#environment-variables) `AGENT_BROWSER_PROVIDER` to
`browseruse` (the default) or `browserbase`. Pages, cookies, and screenshots
from that browser pass through the provider.

Each run may create at most five cloud browser sessions per hour. Runlayer also
limits sessions per workspace and across all workspaces, so a new session can
be refused for a while when either limit is reached. Sessions can only be
released by the run that created them.

With an allow list [network access policy](#network-access-policy), add the
provider's hosts: `*.browser-use.com` for Browser Use, `*.browserbase.com` for
Browserbase.

> [!WARNING]
>
> A cloud browser loads pages from the provider's network, not the agent's
> sandbox, so the network access policy cannot limit which sites it visits. An
> agent that may reach a cloud browser provider can browse any site that provider
> can reach.

### Environment variables

Each agent can define optional environment variables in its advanced settings
(visible to the agent owner and admins). They are encrypted at rest and injected
into the agent's sandbox runtime, so shell commands and tools can read them
(for example `$MY_VAR`). Use them for non-OAuth configuration like API base URLs
or service tokens the agent needs in shell commands.

Credentials for OAuth-protected MCP connectors are handled separately through
[session grants](https://docs.runlayer.com/platform-agent-accounts.md#session-grants), not environment
variables — you don't paste OAuth tokens into agent env vars.

### Waiting on external work

An agent that has to wait for something outside its control, such as CI checks,
a deployment, a long job, or a person's reply, does not need to sleep or poll.
Every agent can call
`schedule_continuation` with a delay (1 minute to 24 hours) and a note about
what to check, then finish its run. Runlayer starts a new run at that time
that continues the same conversation, with the note as its input. The
continuation appears as its own run linked to the one that scheduled it.

* A conversation keeps one pending wake-up: calling `schedule_continuation`
  again, in this turn or a later one, replaces it;
  `cancel_scheduled_continuation` drops it. Either call is refused if that
  wake-up is already starting its run, and the tool result says so.
* Files under `/tmp/workspace` survive only if the runtime session is still
  warm when the continuation lands (short delays). The tool result tells the
  agent whether that is the case so it can save what it needs first.
* A continuation is not started if the original run was cancelled, or if the
  agent was disabled or deleted in the meantime.
* Slack-started conversations continue in the same thread; the agent uses
  `say` to post when the thread should hear from it.

### Runtime limits

* Agent runs are short-lived; long-running services and background daemons are
  not a good fit.
* Runs are limited to 8 hours (configurable per deployment).
* Interactive terminal programs that require a TTY are not supported.
* Writes outside `/tmp/workspace` should be treated as temporary.
* Hidden directories, dependency folders, and common build output directories
  are not intended for persistent file sync.
* Local tools and MCP calls still pass through Runlayer policy, scanning, and
  audit flows.
* Network access depends on the runtime environment and the configured
  connectors, credentials, and policies.

### Runtime enforcement inside the sandbox

ToolGuard scanning and sandbox protection are applied inside the agent runtime:
tool calls and tool results are inspected before and after execution, sensitive
arguments can be masked, and denied calls are blocked. A blocked call surfaces an
error to the agent run. MCP tool calls already enforced at the Runlayer proxy are
not enforced twice. See [ToolGuard](https://docs.runlayer.com/runlayer-toolguard.md).

Customer-facing extension points are documented in the
[Runlayer Hooks SDK](https://docs.runlayer.com/runlayer-hooks-sdk.md).

## Human-in-the-loop approvals

When a guarded tool call fires during a run (for example, a policy or security
scanner requires approval), the run stops at that call and Runlayer asks the
requester to allow or deny it. Once they decide, Runlayer starts a continuation
that tells the agent the outcome, and the agent carries on with the call or
without it. This lets you keep sensitive tools available to agents without
giving up a human checkpoint.

**Who approves.** Only the requester: the person the run executes as (see
[Who does the agent run as?](#who-does-the-agent-run-as)). For a Slack mention
that is whoever mentioned the agent, for a schedule the schedule's creator, and
for a webhook without auth the agent owner. Org admins and the agent owner
can't decide someone else's request, and there are no approver groups or
backup approvers yet. The exception is a rule whose approvers are **External
system**: your own approval system decides, and no Runlayer user can (see
[External approval system](https://docs.runlayer.com/platform-policies.md#external-approval-system)).

* **Where the request shows up**: in the Slack thread for Slack runs (buttons
  only the requester sees), in Teams for Teams runs, and otherwise as a Slack DM
  to the requester when their Slack account is linked. Web chats also show an
  inline card, and every pending request is listed in the requester's
  **Inbox**, except one routed to an External system, which shows on the
  request page and in chat as waiting on your approval system.
* **Which decisions continue the run**: Slack runs continue when the requester
  decides in the Slack thread. Teams runs continue when the requester approves
  or denies the request from the Teams card. Web chat, schedule, webhook and MCP
  runs continue after a decision from the web app or a Slack DM. Runs started
  from iMessage or an event trigger don't continue on their own yet; run the
  agent again once the call is approved.
* **Time limits**: a pending request lapses after 24 hours. Nobody is notified
  and the run doesn't continue, so start the action again. An approval lets the
  identical call through once within 1 hour; a denial blocks identical retries
  for 15 minutes.
* **Runs with no person behind them**: webhooks in **Run as agent account**
  mode have no requester, so approval-gated calls in those runs are blocked.

Callers outside Runlayer that nobody is watching (Claude Code `-p`, the Claude
Agent SDK, external on-behalf-of agent-account tokens, or a client such as Codex `exec` that
sends the `x-runlayer-unattended: true` header) cannot act on a prompt; they get a
structured blocked payload and a Slack DM goes to the approver instead. Runlayer
agent runs keep the flow above. See
[Unattended agents](https://docs.runlayer.com/platform-policies.md#unattended-agents).

### Changes an agent makes to itself

In chats, Slack, and Microsoft Teams, an agent's manager can ask the agent to
change its own setup. Runlayer asks the person in the conversation to approve
each such change before it applies: instructions, connectors, skills,
subagents, schedules, triggers, webhooks, Slack settings and channel monitors,
and, for MCP admins, a new connector for the workspace. Deleting the agent itself
also requires approval, as do evaluations that can replay a run with real tools.
Other Runlayer actions from this implicit connection require approval by default.
Known reads and removing individual connectors, skills or automation apply right
away; delegating to another agent keeps its own approval rules. An agent with the
Runlayer connector attached explicitly isn't asked. Neither is your own main agent
in Go, in any conversation: choosing it as your main agent is your consent. The
exception is setting up its schedules, triggers, webhooks or channel monitors from
a conversation, which still asks while it can hand work to other agents.

The approval shows every argument the agent sent, then the defaults that apply
to what it left out. When a change is too long to show in full in Slack or
Teams, the card links to the full request in Runlayer, where you approve it;
in a chat, **Review and approve** opens it. You can still deny it from the card.

## Usage limits

Agents support two independent limit types to prevent runaway usage: **run limits** and **cost budgets**. A run is rejected if either limit is exceeded.

### Run limits

Agents have daily and weekly run limits. Defaults are set at the workspace level in **Settings → General → Agent Run Limits** (default 100 runs per day and 500 per week) and apply to all agents.

To override limits for a specific agent, open the agent, go to its **Monitor** tab and click **Limits**. This needs the **Manage agents** capability. The override sets the agent's own daily and weekly cap, whatever model it uses (the weekly cap must be greater than or equal to the daily cap). People without that capability see **Ask to raise limit** on the agent once a run is rejected (when the Inbox is on for your workspace), which sends the request to everyone who can manage agents. Limits use rolling 24-hour and 7-day windows, so when an agent reaches its limit, new runs are rejected until older runs age out of the window.

### Cost budgets

Each agent can also have daily and weekly spending caps in USD, based on actual LLM token costs. Budgets are per-agent and independent — they are not pooled or shared across agents (run-limit *defaults* are workspace-wide, but each agent's spend counts only against its own budget). Set them from the **Limits** button on the agent's **Monitor** tab, which shows 24-hour and 7-day usage against each limit on its Runs and Cost tiles. Both values must be set together (or both cleared), and the weekly cap must be greater than or equal to the daily cap. When an agent's accumulated cost reaches the budget, new runs are rejected until older spend ages out of the window.

When agent runs send their LLM traffic through the Runlayer LLM gateway, a run is also capped while it runs. It starts with a per-run limit of \$250 by default, lowered to whatever is left of the agent's daily and weekly budget, and stops once it has spent that. To change the per-run default for your workspace, contact Runlayer support.

### Budget alerts

When Slack is connected, the agent owner receives a DM when an agent crosses 75%, 90%, or 100% of its daily or weekly **run limit**. For **cost budgets**, the owner is notified when a run is rejected because the budget was exceeded, and when a run stops at its spend limit (there are no pre-threshold warnings for spend). Budget alerts are enabled by default. Toggle them per agent under **Notifications → Budget alerts** in the agent's Slack settings, or, for an agent without its own Slack app, with the **Budget alerts** switch on its Slack card.

## LLM providers

Agents need at least one LLM provider configured to run. Admins manage providers in **Settings → AI Providers**.

| Provider | How to enable | Models |
| - | - | - |
| **Anthropic** | Add your Anthropic API key | Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5, Claude Sonnet 5, Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Sonnet 4.5, Claude Haiku 5.5, Claude Haiku 4.5 |
| **OpenAI** | Add your OpenAI API key. This covers the models ChatGPT runs on; there is no separate ChatGPT provider | GPT-6 Astra, GPT-6.1 Sol, GPT-6 Sol, GPT-6 Luna, GPT-5.6, GPT-5.5, GPT-5.4, GPT-5.4 Mini |
| **AWS Bedrock** | Configure an IAM AssumeRole (region + role ARN + external ID) — no static API keys stored | The same Claude models, labeled "(Bedrock)". Other models your AWS account enables (OpenAI GPT, Llama, Nova, DeepSeek...) need the agent LLM gateway, see [Non-Claude models on Bedrock](#non-claude-models-on-bedrock) |
| **Azure Foundry** | Set the Azure OpenAI v1 endpoint URL + API key, then **Fetch deployments** to pull the names of the chat deployments that are live on the resource (or type them by hand). This proxies models only: it doesn't import agents built in Foundry (connect those through [Agent platforms](https://docs.runlayer.com/agent-platforms.md#microsoft-foundry-agent-service)) | Any deployments you keep in the list for the endpoint (e.g. GPT-5.5) |
| **Google AI Studio** | Add a Gemini API key + model list (no endpoint URL; Runlayer calls Gemini's native API) | Any Gemini model IDs you list (e.g. `gemini-3.8-flash`) |
| **Thinking Machines** | Pick the **Thinking Machines** tile and paste a Tinker API key from the Tinker Console. This is an OpenAI-compatible gateway preset with the Tinker endpoint URL and models filled in | `thinkingmachines/Inkling-2-Small`, `thinkingmachines/Inkling`, `thinkingmachines/Inkling-Small` |
| **OpenAI-compatible gateway** | Set a gateway URL + API key + model list | Any models the gateway exposes (e.g. OpenRouter, Baseten) |

When multiple providers are configured, the model picker in the agent detail page shows all available models. Each agent can use a different model, and an agent can be bound to a specific provider configuration so it only sees (and routes through) that provider's models — useful for team-level cost isolation.

### Bedrock with an IAM role

The Bedrock provider never stores AWS keys. Runlayer calls `sts:AssumeRole` on a role you create in the AWS account that has Bedrock model access, and calls Bedrock with the short-lived credentials it gets back. Agents run in your Runlayer deployment's AWS account and call Bedrock from there, so the IAM roles your other workloads use (for example EKS IRSA or pod identity) don't apply to them. Give Runlayer a role it can assume instead:

1. In **Settings → AI Providers**, add **AWS Bedrock**. The form shows the AWS account ID Runlayer calls from, the external ID it will send, and a ready-made trust policy and permission policy.
2. In your AWS account, create the role from those two policies. The role name must start with `runlayer-bedrock-` or `RunlayerBedrock`: Runlayer's own IAM role may only assume roles with those names, so a role with any other name fails validation with an AssumeRole error.
3. Paste the role ARN and Region into the form and click **Validate connection**.

Validation checks the role and lists the models your AWS account has enabled in that Region. Every enabled model is checked by default and replaces the default Bedrock registry, so users only see models that will actually run; uncheck any you want to hide. This needs `bedrock:ListFoundationModels`, `bedrock:ListInferenceProfiles` and `bedrock:GetFoundationModelAvailability` on the role (included in the permission policy shown in the form). You can still add other model IDs by hand, or skip validation and use the default Bedrock model list. If you use a custom application inference profile ARN as the model, also grant `bedrock:GetInferenceProfile` so Runlayer can tell which model the profile serves: the model picker then names the profile after that model (for example *Claude Sonnet 4.6 · my-profile*) and runs show their cost. Without it the picker shows the raw ARN and those runs show "Cost unavailable". Anthropic models on Bedrock also need a one-time use case details form submitted in the account that role lives in — see [Bedrock model access](https://docs.runlayer.com/deployment/ecs-prerequisites.md#bedrock-access-before-first-startup).

### Non-Claude models on Bedrock

Agents run Claude models on Bedrock directly. Every other Bedrock model (OpenAI GPT, Meta Llama, Amazon Nova, DeepSeek and the rest) runs only through Runlayer's agent LLM gateway, which isn't on for every workspace. Without it, those models still show up after **Validate connection**, but an agent run on one fails with "Model credentials are not configured for this agent". Adding API keys doesn't change that: the Bedrock provider is already set up correctly.

Until the gateway is on for your workspace:

* Use the Claude models on Bedrock, or uncheck the non-Claude ones so nobody picks them.
* For GPT models, add an **OpenAI** provider with an OpenAI API key.
* For other vendors that offer an OpenAI-compatible API, add an **OpenAI-compatible gateway** provider.
* Ask your Runlayer contact to turn on the agent LLM gateway for your workspace.

To hide a model, uncheck it in the Bedrock provider form, or remove it from the model list of an Azure Foundry, Google AI Studio or OpenAI-compatible gateway provider. Anthropic and OpenAI providers have no model list; there, and anywhere else you want a model for some people only, use **Model access** in the provider form: it limits which roles can select each model, and a model with no roles set stays open to everyone.

### Runlayer Assistant model

The built-in Runlayer Assistant runs on Runlayer's Bedrock model by default (or, on deployments without Bedrock, on your recommended model). Admins can move it to any model one of the workspace's providers serves, such as an internal OpenAI-compatible gateway, with the **Runlayer Assistant model** picker in **Settings → AI Providers**. The same picker sits in the **Model** section of the assistant's own page, along with its model settings. The choice applies to the assistant in the web app and in Slack. When a newer model of the same family replaces the one you picked (for example Claude Opus 4.6 to Claude Opus 5.5), the assistant moves to it on the same provider, unless a role restriction reserves the newer model. Its prompt and connectors stay managed by Runlayer.

### Recommended model

Admins can set a workspace-wide **recommended model** in **Settings → AI Providers**. The recommended model is highlighted in the model picker and used as the default for new agents (when unset, new agents default to Claude Opus 4.8).

To manage spend, set a smaller model (for example Claude Haiku 4.5 or GPT-5.4 Mini) as the recommended model so new agents default to it, and reserve larger models for agents that need them — each agent can override the default from its own model picker. Pair this with [cost budgets](#cost-budgets) and per-agent [run limits](#run-limits) for hard caps, provider binding for team-level cost isolation (see above), and [Analytics](https://docs.runlayer.com/platform-analytics.md) for cost visibility.

### Model access by role

Admins can limit which roles may pick a model. In **Settings → AI Providers**, edit a saved provider and use **Model access**: choose roles for any model you want to restrict, and leave a model unset to allow every role. Workspaces on the newer **Settings → AI models** page set the same thing on its **Access** tab, a grid of models against roles.

* A restricted model is hidden from the agent model picker for users without one of its roles. Users who hold several roles can pick any model one of those roles allows.
* Creating or editing an agent with a model the user's roles don't allow fails with "Model '…' is not permitted for your role". The same check applies when agents are created or edited through the Runlayer MCP agent tools.
* Only newly selected models are checked. An agent that already uses a model that later becomes restricted keeps it until someone changes the model.
* If the [recommended model](#recommended-model) is restricted for a user's roles, it isn't highlighted or used as the default for their new agents.
* On the **Access** tab a model keeps at least one role. To take a model away from everyone, remove it from the provider's model list instead.

### Model settings

Each agent can optionally tune how its model reasons. The available knobs depend on the model family:

| Setting | Applies to | Values |
| - | - | - |
| **Adaptive thinking effort** | Newer Claude models (Opus 4.7+, Fable 5+) | low, medium, high, max, xhigh |
| **Thinking budget tokens** | Earlier Claude models | 1 024 – 64 000 |
| **Reasoning effort** | OpenAI models | minimal, low, medium, high, max, xhigh |
| **Gateway model options** | OpenAI-compatible gateways | Arbitrary JSON passed to the gateway |

Configure these on the agent detail page under the model picker. Leave them unset to use provider defaults.

> [!NOTE]
>
> Self-hosted deployments can also enable Bedrock-hosted Anthropic models via Terraform without the AI Providers UI. See [Agent Sandbox LLM Gateway](https://docs.runlayer.com/deployment/ecs-features.md#agent-sandbox-optional) for details.

## Agent memory

Agent memory provides persistence across runs through two complementary systems:

**Workbench memory** is an optional built-in persistent SQLite database an agent can use
to save structured notes and state between runs. Enable it from the agent's
advanced settings when the agent should remember information across runs.

Use workbench memory for things like:

* Durable preferences or instructions specific to that agent
* IDs, checkpoints, or summaries from earlier runs
* Lightweight working state for recurring tasks

The agent can write new rows, update earlier records, and query what it saved in
prior runs using the `run_agent_memory_sql` tool.

Results larger than 16 KB are not returned inline: the tool call fails with an
error that tells the agent to page with `LIMIT`/`OFFSET`, aggregate in SQL, or
pass `output_file` to write every row as JSON Lines to a file in its workspace.
Agents can also open the database read-only from bash or Python for large reads.

### Example prompts

* "Remember that Acme prefers weekly status updates every Monday."
  The agent can save that preference in its memory and use it in later runs for
  Acme-related work.
* "Store the last processed Zendesk ticket ID as 18423 and pick up from there next run."
  The agent can write that checkpoint, then retrieve it later to avoid starting
  from scratch.
* "What do you already remember about our Q2 board report workflow?"
  The agent can query its stored notes, summarize what it finds, and use that
  as context for the current task.

Workbench memory is scoped to a single agent. Other agents do not share it, and it
should not replace your source-of-truth systems. Use it to help an agent stay
consistent over time, then re-check live systems when current data matters.

**Scoped memory** stores long-term facts as notes that persist across conversations. When
enabled, the agent saves a fact (a preference, feedback, project context) with `write_note`
into one of the scopes below, looks notes up with `recall_notes`, and retires outdated ones
with `forget_note`. Later runs that can use the same scope get its pinned notes every time,
plus the notes that best match the incoming message; the agent can call `recall_notes` for
the rest.

### Memory scopes

**Memory context** (the settings icon next to the Memory toggle) chooses which
scopes an agent can use. The same scopes apply to both systems: each scope has
its own workbench database and its own scoped facts, and `run_agent_memory_sql`
takes an explicit `scope` on writes.

| Scope | Who shares it | Available in |
| - | - | - |
| **Agent** | Everyone who uses the agent, across all runs and conversations | Every run |
| **Channel** | Everyone in one Slack conversation. Each channel and each DM gets its own memory | Runs started from Slack |
| **User** | One person. It follows them into every conversation with the agent, including shared channels | Runs started by a signed-in person (Playground, API, MCP, Slack, Teams or [iMessage](https://docs.runlayer.com/platform-imessage.md)) |

Choosing a scope:

* **Channel** is the safest default for Slack-facing agents: what the agent learns in
  one channel or DM stays there.
* **User** is for personal preferences. Because it follows the person, anything the
  agent saved from a private DM can come up when that person talks to it in a
  shared channel.
* **Agent** is global. Use it for facts every user of the agent should benefit
  from, such as checkpoints or team conventions.

Runs that execute as an [agent account](https://docs.runlayer.com/platform-agent-accounts.md), such as webhook
or channel-monitor runs, have no person or Slack conversation bound to them, so
they can only use Agent memory. Including a person's ID in the input or sending
them a DM doesn't give the run that person's User or Channel memory.

A custom workbench table, for example one created with
`CREATE TABLE IF NOT EXISTS my_notes (...)`, lives inside the scope you write it to.
It doesn't make data visible to other scopes.

### Steering and correcting memory

The agent decides what to save and where, but you can tell it exactly:

* "Remember for everyone using this agent: our fiscal year starts in February." The agent
  writes an Agent note.
* "Remember in this channel: the digest goes out at 9am ET." The agent writes a Channel note.
* "Remember that I want bullet points, not prose." The agent writes a User note.
* "Pin that" keeps a note loaded in every run instead of only when a message matches it.

A scope works only if it's turned on in **Memory context** and the run has access to it
(see the table above). The agent can't write to a scope the run can't use.

When the agent remembered something wrong, correct it in either place:

* **In the conversation**: "That's wrong: Acme's renewal is in May, not March. Update your
  memory." The agent recalls the note, rewrites it, or retires it with `forget_note`.
* **On the Memories page**: **Memories** in the sidebar lists the notes agents keep about you
  and each agent's own notes. Edit, pin or delete a note there. You can always edit the notes
  about you; an agent's own notes need edit access to that agent and, in workspaces that redact
  run content, permission to view unredacted content.

Channel notes don't appear on the Memories page. Correct them by asking the agent in that
channel.

For a recurring flow such as a daily digest, add a line to the agent's instructions, for
example "When someone corrects a fact, update the matching note in the same scope it was
saved to before replying." That makes corrections stick for every later run without moving a
personal or channel fact into Agent memory, which everyone using the agent can see.

## Self-improving agents

Each agent has an opt-in **Self-improving agents** toggle. With it on, the agent automatically distills reusable skills from its successful runs. Distilled skills are private to that agent — they are managed automatically, don't appear in the shared skill picker, and can't be attached to other agents.

Distilled skills are managed for you — you don't create, edit, or attach them — and
future runs of that agent use them automatically.

## Improving agents over time

Several documented mechanisms let a recurring agent get better across runs:

| Mechanism | Use it for |
| - | - |
| [Agent memory](#agent-memory) | Durable preferences, checkpoints, and state the agent should recall in later runs |
| [Filesystem workspace](#filesystem-workspace) | Working files, generated scripts, and datasets restored on future runs |
| [Self-improving agents](#self-improving-agents) | Automatically turning successful multi-step runs into reusable playbooks |
| [Procedures](https://docs.runlayer.com/platform-agent-procedures.md) | Turning a connector workflow the agent repeats every run into tested code it calls as one tool |
| [Offline evals](https://docs.runlayer.com/platform-agent-evals.md) | Replaying past runs with a different model or prompt and scoring the results against a control |
| Run **resume** in chat | Continuing a past run with its full prior context to debug or iterate |

Memory and workspace usage are driven by the agent's instructions — prompt the
agent to save checkpoints or query what it already knows (see the
[example prompts](#example-prompts) above). Self-improving agents is the automatic
path: once opted in, it runs after successful runs without prompt changes.

## Subagents

An agent can delegate work to **subagents** — lightweight child agents that run inside the parent agent's sandbox with their own name, description, prompt, and optional model override. Subagents inherit the parent's connectors and tools but follow their own instructions, so you can split a complex workflow into focused sub-tasks without creating separate top-level agents.

To add subagents, open the agent detail page and look for the **Subagents** section. Click **Add subagent**, then fill in:

| Field | Required | Notes |
| - | - | - |
| **Name** | Yes | Lowercase, alphanumeric + hyphens (max 64 chars) |
| **Description** | Yes | Short summary (max 255 chars) |
| **Prompt** | No | Instructions for the subagent (max 10 000 chars) |
| **Model** | No | Override the parent's model; defaults to the parent model if unset |

Each agent supports up to 50 subagents. You can edit or remove subagents from the same section. Subagents can also be managed programmatically through [Runlayer MCP](https://docs.runlayer.com/runlayer-mcp.md) tools (`add_agent_subagent`, `update_agent_subagent`, `delete_agent_subagent`).

Subagents have no connector or tool configuration of their own — only a name, description, prompt, and optional model override. The parent's connectors and tools are resolved when a run starts, so changes to the parent agent's attached connectors or enabled tools apply automatically to the next run; there is no separate sync or versioning step.

## Agent policies

Each agent has a dedicated **Policies** section on its detail page where you can define access rules scoped to that agent's connectors and tools. Agent policies work like server-level policies but are managed directly from the agent rather than from each connector individually.

To add a policy, open the agent detail page, scroll to the **Policies** section, and click **Add policy**. Each policy includes:

| Field | Description |
| - | - |
| **Tools** | Select which tools the policy applies to (from the agent's attached connectors) |
| **Action** | Allow or Deny |
| **Conditions** | Optional runtime conditions (same condition language as [server-level policies](https://docs.runlayer.com/platform-policies.md)) |

Agent policies are visible only to the agent owner. Use them to restrict what a specific agent can do beyond the connector-level permissions — for example, allowing an agent to read but not write, or limiting queries to specific tables.

## Error notifications

When enabled for your deployment, **Agent → Error notifications** sends attention alerts to up to five destinations per agent: shared Slack channels, shared Microsoft Teams channels, or public HTTPS webhooks. Disabled destinations count toward this limit. Users with access to the agent can read masked destinations. Reading recent delivery history, managing destinations, testing them, rotating signing secrets, and discovering channels require **Manage organization settings** as well as agent access. Private managed assistants are excluded; existing personal Slack notices continue independently.

Choose **Add destination**, then **Destination type**. Slack uses the shared Runlayer App; select the workspace on Enterprise Grid, then the channel. An organization default channel and an agent-specific Slack app are not required. Invite the shared app to missing or private channels, then **Refresh channels**. Teams requires the shared app installed in the intended team and an observed channel message or mention. Only complete tenant, team, and channel references are selectable. Set up missing shared apps in **Workspace settings → Integrations**; notifications never fall back to a different channel.

The two conditions default on: **Run failures** and **Unresolved tool errors**. A failed run takes priority over tool warnings, with one attention event per persisted run and destination. A successful run with unresolved tool errors remains **Succeeded**. Recovery means an observable later success for the same connector, tool, and canonical input in that run. A success with different input or through a different tool does not prove recovery. Errors swallowed inside shell/code execution and unobserved child traces are outside this guarantee. Alerts contain bounded safe summaries, tool names/counts, source, time, and an agent/run link; they exclude prompts, arguments, outputs, exception text, and response bodies.

**All runs** is the default. **Automated runs only** includes scheduled, incoming webhook, event, and connector poll runs; manual Run now/Retry, REST, MCP, Slack, and Teams runs are excluded. The default **Cooldown (seconds)** is 900 (15 minutes). Enter whole seconds from 0 to 2,592,000 (30 days). Matching repeated alerts are suppressed after a successful send; failed sends do not consume cooldown. You can disable a destination, change conditions or cooldown with **Edit**, or **Remove** it. Operational notification settings are excluded from agent versions and clones. Restoring a version preserves current routes; transferring the agent preserves routes, and deleting the agent disables them and cancels pending work.

**Test** queues a generic `agent.notification.test` event. It has source/outcome `test`, a server-generated UUID, and no real run or accepted-attempt ID. It bypasses attention conditions, source scope, and ordinary cooldown, but requires an enabled route and agent and is throttled to once per destination per 60 seconds. **Test queued** confirms acceptance, not external delivery. **Recent deliveries** shows the latest 50 records, including queued, sending, sent, suppressed, cancelled, and failed states. Completed history is retained for 30 days. **Sent** means the receiver or channel service accepted the request.

Delivery is at least once: receivers must handle duplicates. Retries reuse the event ID and use a fresh signing timestamp. Retryable failures have bounded durable retries; permanent failures stop retrying. Route edits advance the revision and cancel pending sends for the old revision. An in-flight external request cannot be recalled by editing, disabling, deleting, or changing a flag. Invalid/unauthenticated requests, disabled-agent refusals, duplicate incoming requests, cancellations, and eval/simulated runs do not generate attention alerts. Accepted failures before run creation are covered when acceptance is captured durably; process death before any durable run/job/intent is outside the recovery guarantee. There is no historical backfill.

### Webhook receivers

Enter a public **Webhook URL** and an optional **Bearer token**. The stored URL stays masked and bearer tokens are never shown again. Creating a webhook, converting a Slack or Teams destination to webhook, or confirming **Rotate secret → Rotate signing secret** issues a fresh Standard Webhooks signing secret, shown only once. Copy it to your receiver before closing. **Replace destination** on an existing webhook retains its signing secret and replaces the URL and bearer token; leaving the replacement bearer blank removes it. Use **Rotate signing secret** to obtain a new key. Config-only edits preserve credentials. Rotation immediately invalidates the old key, so coordinate the receiver update. Closing clears the disclosure; an explicitly copied secret remains in your OS clipboard.

Receivers need public DNS and HTTPS with a valid certificate. Private, loopback, link-local, and metadata destinations are rejected. DNS is checked and an allowed address pinned before transmitting the body, with TLS hostname verification. Redirects are not followed. The request budget is ten seconds and responses are bounded; acknowledge promptly after durably accepting work. Deployment operators must permit backend DNS/public egress for destination validation and worker DNS/public HTTPS egress for delivery, and run the durable notification worker jobs. Use trusted TLS configuration; private-only receivers require a public HTTPS ingress.

Verify `webhook-id`, `webhook-timestamp`, and `webhook-signature` against the **exact raw request body** before parsing it. The following standard-library example checks HMAC-SHA256 and a five-minute timestamp window; pass your secret from a secret manager. Header names should be normalized to lowercase by your HTTP adapter.

```python theme={null}
import base64
import hashlib
import hmac
import json
import time


def verify_notification(raw_body: bytes, headers: dict[str, str], secret: str):
    event_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError("Stale webhook timestamp")
    if not secret.startswith("whsec_"):
        raise ValueError("Invalid signing key")
    key = base64.b64decode(secret.removeprefix("whsec_"), validate=True)
    signed = f"{event_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.digest(key, signed, hashlib.sha256)).decode()
    signatures = headers["webhook-signature"].split()
    if not any(hmac.compare_digest(signature, "v1," + expected)
               for signature in signatures):
        raise ValueError("Invalid webhook signature")
    payload = json.loads(raw_body)
    if payload["event_id"] != event_id:
        raise ValueError("Event ID mismatch")
    return payload
```

After verification, atomically deduplicate on `event_id` in durable storage while accepting work, then return a 2xx response. Check your expected organization and agent IDs, validate the versioned payload, impose a request-body limit, and treat missing or malformed headers as authentication failures. If configured, check the bearer token as well. Do not log the bearer, signing secret, full URL, or raw request/response content. Signature validation alone is not duplicate suppression.

### Deployment pilot

`agent-error-notifications` defaults off. Enable it in the backend and worker processes as well as the frontend; a frontend URL flag override alone cannot enable capture, API access, or delivery. While off, existing pending rows are preserved for resumption and new attention events are not captured. Operators can use an approved flagd override or a scoped `FF_ENABLE = "agents,agent-error-notifications"` process override for a deployment pilot. Apply the same opt-in to backend and worker and verify the deployed processes; keep the central default off until promotion.

## Multi-agent strategy

Use multiple agents instead of one overloaded agent:

* Split by business function (Support, Security, Ops, GTM)
* Split by data sensitivity (low-risk vs privileged systems)
* Split by trigger type (human chat vs scheduled vs webhook)
* Keep prompts short and role-specific
* Keep connector/tool permissions narrow per agent

## Ownership and access

* The agent owner is shown on the agent detail page (below the webhook section)
* Agent owners and admins with the **Manage Agents** capability can edit core settings (including the enable/disable toggle); advanced settings (model, environment variables, subagents) are visible only to admins and the agent owner
* Admins with the **Manage Agents** capability can transfer an agent to a new owner in the same organization from the Share modal
* When you create or update an agent, you automatically receive access to the connectors attached to it
* Public agents are accessible to workspace users
* Non-owners may have read/run access but not edit rights
* All calls still pass through your Runlayer policy model and scanner stack

### Sharing an agent

Agents are shared from the **Share** button on the agent detail page. Sharing supports two permission levels:

| Permission | What it allows |
| - | - |
| **Can use** | View and run the agent |
| **Can edit** | Also edit the agent's configuration |

Grants can target individual users, groups, or roles, so you can share an agent with a specific team at use-only or edit level. Users with **Can edit** access can also add their own schedules to the agent; each schedule runs under its creator's identity and connector credentials, so one shared agent can run on behalf of several users without duplicating it (each user still [grants connector access](#shared-agents-and-user-credentials) themselves first). The same Share modal controls general access — **Only people invited** (private) or **Everyone at your organization** — and lets admins with the **Manage Agents** capability transfer ownership. Advanced settings (model, environment variables, subagents) remain visible only to the agent owner and admins regardless of sharing.

### Who can see an agent's runs

A run belongs to the person it runs as (see [Who does the agent run as?](#who-does-the-agent-run-as)). Who else sees it on the agent's **Sessions** tab depends on their access to the agent:

| Who | Runs they see |
| - | - |
| Anyone who can use the agent | The runs they started: their chats, Slack and Teams messages, and the schedules, webhook calls and triggers that run as them |
| The owner, people with **Can edit**, and admins with **Manage Agents** | Every run of the agent, whoever started it and from wherever. On a Runlayer-managed agent such as the Runlayer Assistant, the owner also needs **Manage Agents**. |
| Anyone a [policy](https://docs.runlayer.com/access-control-resources.md#agents) grants **View all runs** on the agent | Every run of the agent, without edit access, except on Runlayer-managed agents such as the Runlayer Assistant, where a **View all runs** grant alone doesn't show other people's runs — only edit access (or **Manage Agents**) does |

**Can use** never shows other people's runs, even when the agent is shared with a whole group. A policy that denies **View all runs** on an agent hides other people's runs from whoever it applies to, the owner and editors included. Both the grant and the deny apply once [access control for agents](https://docs.runlayer.com/access-control-resources.md) (early access) is on for your workspace. Where [session content access](https://docs.runlayer.com/platform-session-content-access.md#view-all-runs-on-an-agent) is enabled, a **View all runs** grant also opens the content of the agent's runs.

When **Session privacy** is on (**Settings → Agent session monitoring**), other people's runs still appear, with status, duration, cost and tool counts, but their input, output, errors and timeline are hidden. Someone with the **View unredacted content** capability (Super Admin, Security Admin, IT Admin, Helpdesk or Analytics Admin) can open a hidden timeline with **View timeline**. The unlock lasts an hour and is recorded in the audit log.

To let a department troubleshoot its own agents without an admin role:

1. Create a group for the department's builders in your identity provider (or a [team](https://docs.runlayer.com/platform-teams.md) in Runlayer).
2. Share each of the department's agents with that group at **Can edit**. Members then see every run of those agents, including runs other people start from Slack or on a schedule.

Two limits apply. **Can edit** also lets them change the agent's configuration, because there is no view-only share level for runs; a [policy](https://docs.runlayer.com/platform-policies.md) granting **View all runs** gives run visibility without it. And with Session privacy on, reading the content of other people's runs needs **View unredacted content**, which works across the whole workspace, not per agent. Directory sync maps groups onto the built-in roles only (see [SCIM Role Sync](https://docs.runlayer.com/platform-roles.md#scim-role-sync)), so no role sits between **User** and the admin roles for this.

### Shared agents and user credentials

When multiple users use a shared agent against OAuth-protected connectors, credentials resolve per caller: if the calling user has connected the connector themselves (a **personal** session grant), their own OAuth credentials are used; otherwise the call falls back to a **shared** session grant if one exists. This keeps each user's data access governed by their own permissions where possible. See [Session grants](https://docs.runlayer.com/platform-agent-accounts.md#session-grants) for the full resolution order and examples.

#### Who does the agent run as?

The identity a run executes under depends on how it was triggered — and that identity is whose connections are used (personal grant first, shared grant as fallback):

| Trigger | Run identity |
| - | - |
| Chat / playground | The person chatting |
| Schedule | The schedule's creator |
| Webhook (with API key) | The API key's owner |
| Webhook (no auth) | The agent owner |
| Webhook (run as agent account) | The agent's [agent account](https://docs.runlayer.com/platform-agent-accounts.md) |
| Event trigger / Slack channel monitor | The trigger's creator |

The chip next to each OAuth connector says whose account its runs use. **Runs as each user** means every run uses the account of the user it executes as, per the table above (their chats, plus schedules, event triggers, channel monitors, and webhook calls they created). **Always runs as** a named user means that user shares their connection, and it is used for everyone's runs on that agent.

To have everyone who uses your agent run on your connection, so teammates don't each have to connect, open the agent, click the connector, and set **Account used** to **Always your account**. In the app, only the agent's owner can change this, and only after connecting the connector themselves. Switching replaces other users' own connections for that connector on this agent, including when the switch comes from the API or Terraform; see [Session grants](https://docs.runlayer.com/platform-agent-accounts.md#lifecycle). Every run then acts with your upstream permissions, and teammates still need access to the connector itself. To go back, choose **Each user's own account**.

#### Keep a team's agent running when someone leaves

**Always your account** shares one person's connection, so it works only while that person does. When the user whose account is shared is deactivated (offboarding, or access paused during leave), Runlayer stops using their connection, and every run that relied on it loses access to that connector until another user connects and shares theirs. Schedules run as their creator and are disabled when the creator is deactivated.

For an agent a whole team depends on, share a dedicated user's connection instead of a teammate's:

1. Create a user for the agent in your identity provider (for example `support-agent@yourcompany.com`) and keep its login with one or two admins, not the whole team.
2. An admin with the **Manage Agents** capability transfers the agent to that user from the agent's **Share** modal.
3. Sign in to Runlayer as that user once, connect each OAuth connector the agent uses, set **Account used** to **Always your account**, and create the agent's schedules.

Teammates keep using the agent as themselves: sessions and the audit log name the person who ran it, while the upstream app sees the dedicated user. The admins holding its login only need it again to reconnect a connector when its authorization expires.

For connectors that accept an API key or token, no user is needed: give the agent's [agent account](https://docs.runlayer.com/platform-agent-accounts.md) a Bearer Token connector (as in [Autonomous agent to Snowflake](https://docs.runlayer.com/cookbook-agent-accounts.md#snowflake-service-user)), and start runs that have no person behind them with a webhook in **Run as agent account** mode.

### Gradual rollout

Agents don't have to launch workspace-wide at once:

1. Create the agent as **Private** and validate behavior in chat.
2. Share it with a pilot user, group, or role at **Can use** level and monitor the **Sessions** tab; tighten prompt and tool scope as needed.
3. Widen general access to **Everyone at your organization** (or mark the agent Public) when you're confident.

[Agent policies](#agent-policies) and connector-level [access policies](https://docs.runlayer.com/platform-policies.md) apply throughout, so broader visibility never bypasses access control.

### Improve one shared agent together

Once an agent graduates from one person's use to a team or the whole company, keep one shared version that a few people maintain, instead of everyone cloning and tweaking their own copy:

1. **Name maintainers.** In **Share**, give a group or role of maintainers **Can edit** and set general access to **Everyone at your organization**, which gives everyone else **Can use**. Maintainers can change the instructions, connectors and skills. Model, environment variables and subagents stay with the owner and admins.
2. **Review changes in version history.** Every save is a [version](#version-history) that shows who made it and what changed, including a diff of the instructions. If a change makes things worse, a maintainer restores the earlier version; restoring adds a new version and keeps the history.
3. **Test before you save.** On the **Evals** tab, a maintainer can replay recent runs with the proposed instructions or model and compare the results against the current setup ([offline evals](https://docs.runlayer.com/platform-agent-evals.md)).
4. **Collect what isn't working.** Maintainers mark runs **Pass** or **Fail** with a note in the run drawer, then use **Analyze failures** on the **Evals** tab to group the failures. People with **Can use** can't label runs, so give them a place to send feedback to the maintainers, such as a Slack channel.
5. **Send improvements back, not forks.** Someone who wants to try a change can [clone the agent](#cloning-an-agent), experiment in their copy, and hand the working change to a maintainer, who applies it to the shared agent and runs an eval first.
6. **Point people at the shared agent.** When someone starts building a similar agent, the create flow suggests the existing one, and the Agents list can be sorted by **Most used** (see [Find an existing agent before you build](#discover-first)).

Not built yet: there's no way for **Can use** users to submit a suggested change for maintainers to accept or reject, and a maintainer's save applies to everyone's new runs right away (there's no separate draft to publish later).

## Test an agent before production

Agents run only inside your Runlayer workspace, because that's where their model access, connectors and policies live. You can't run one locally, and a workspace has no separate staging mode. To build and test without touching production data or people:

1. **Build it as a private draft.** Keep the agent **Private** and unlisted while you work on it. An unlisted agent is a draft: its schedules stay off and it can't receive webhooks. This works the same for agents you create in the app, with [Runlayer MCP](https://docs.runlayer.com/runlayer-mcp.md) or with [Terraform](https://docs.runlayer.com/platform-agents-terraform.md) (`listed_in_workspace = false`).
2. **Point it at test data.** Add your staging or sandbox MCP servers as their own connectors and attach those instead of the production ones. Connector [policies](https://docs.runlayer.com/platform-policies.md) are set per connector, so you can try a new rule on the test connector before you add it to the production one.
3. **Change a live agent on a copy.** [Clone](#cloning-an-agent) it, swap in the test connectors, and apply the change to the original once it works. Every save to the original is a [version](#version-history) you can restore.
4. **Replay real runs with offline evals.** [Offline evals](https://docs.runlayer.com/platform-agent-evals.md) replay past runs with a new prompt or model. By default, MCP tool calls are simulated instead of sent to your services, and memory isn't written. Shell commands and browser actions still execute with unrestricted network access by default, so [restrict network access](#network-access-policy) before replaying runs that could reach production services.
5. **Roll it out in stages.** Share it with a pilot group at **Can use** first ([Gradual rollout](#gradual-rollout)).

If you need a fully separate environment, for example to test organization-wide settings, ask your Runlayer contact about a second deployment for staging.

## Security and isolation

How agent execution is isolated, in one place:

* **Sandboxed execution** — each agent runs in an isolated sandbox (see [Runtime limits](#runtime-limits)) with a writable workspace at `/tmp/workspace`. On Runlayer-hosted deployments, AWS ECS deployments and the Runlayer Operator with `sandboxMode: agentcore`, the sandbox is [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html) in the AWS account your Runlayer deployment runs in: each conversation gets its own AgentCore session, a microVM with its own kernel and memory. Follow-up runs in the same conversation reuse that session until it has been idle for 15 minutes or reaches its 8-hour lifetime (both configurable per deployment); runs from other conversations or agents never share it. On Kubernetes (`sandboxMode: k8s`) the sandbox is [kubernetes-sigs Agent Sandbox](https://agent-sandbox.sigs.k8s.io/) with **gVisor or Kata Containers** on the sandbox nodes — see [Runlayer Operator — K8s Agent Sandbox](https://docs.runlayer.com/deployment/runlayer-operator.md#k8s-agent-sandbox-sandboxmode-k8s).
* **Network egress** — by default an agent can reach any public host from its shell, browser and web fetch tools, not only its connectors. Restrict that per agent with a [network access policy](#network-access-policy) where your deployment supports it.
* **Per-agent filesystem** — workspace persistence is scoped by agent ID; other agents do not share those files (see [Filesystem workspace](#filesystem-workspace)).
* **Per-agent memory** — the optional workbench memory is scoped to a single agent; other agents cannot read it (see [Agent memory](#agent-memory)). Scoped memory separates visibility by user or channel.
* **Policy, scanning, and audit on every call** — local tools and MCP calls pass through Runlayer policy, ToolGuard scanning, and audit flows, plus any [agent policies](#agent-policies) scoped to that agent.
* **Tenant isolation** — Runlayer deployments are isolated per tenant: dedicated-account and dedicated-VPC topologies isolate at the AWS account or network boundary, and the multi-tenant [Runlayer Operator](https://docs.runlayer.com/deployment/runlayer-operator.md) gives each tenant its own namespaces, database, Redis, and IAM roles on a shared EKS cluster. See the Account Strategy & Isolation section in [Deployment Overview](https://docs.runlayer.com/deployment/overview.md).

## Use Runlayer MCP inside agents

Runlayer MCP is a first-party connector that lets an agent reason about your
Runlayer workspace itself (analytics, audit logs, inventory, governance).

To use it in an agent:

1. Install/enable the **Runlayer** server in your workspace.
2. Add that connector to the agent.
3. Test with focused prompts (examples below).

Example prompts:

* "Use Runlayer MCP to export top tools used in the last 30 days and summarize top failure causes."
* "List recent policy denied events and group by connector."
* "Show all connectors with low usage but high error rate."
* "List pending access requests and summarize by team."

> [!NOTE]
>
> Mutating Runlayer MCP actions are confirm-gated (for example `confirm=true`)
> and permission-gated (admin/owner where required).

## Manage agents with Terraform

Agents can also be provisioned as code. The `runlayer_agent` resource in the Runlayer Terraform provider manages the prompt, model, connectors and tool allowlists, skills, built-in tools, tags, and environment variables; runtime settings such as triggers, sharing, and usage limits stay in the app. See [Manage Agents with Terraform](https://docs.runlayer.com/platform-agents-terraform.md).

## Agents vs Agent Accounts

Agents are the workers: a prompt, a model, a curated set of connectors and tools, and the triggers that run them. Agent accounts are the identity those workers carry. Every Agent is backed by an agent account that Runlayer creates for it, and runs that execute as the agent account (webhooks in **Run as agent account** mode) are attributed to it. For agents you build outside Runlayer, create an agent account yourself and authenticate with its client credentials. See [Agent Accounts](https://docs.runlayer.com/platform-agent-accounts.md).

## Related docs

> [card] [Runlayer MCP](https://docs.runlayer.com/runlayer-mcp.md)
>
> Built-in MCP for analytics, audit logs, inventory, governance

> [card] [Agent Accounts](https://docs.runlayer.com/platform-agent-accounts.md)
>
> Programmatic auth + delegated access model

> [card] [Agents as code](https://docs.runlayer.com/platform-agents-terraform.md)
>
> Provision agents with the Terraform provider

> [card] [Policies](https://docs.runlayer.com/platform-policies.md)
>
> Control what agents and users can do

> [card] [MCP Troubleshooting](https://docs.runlayer.com/mcp-troubleshooting.md)
>
> Debug connector, auth, and permission failures


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.