> ## 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](#artifact-publishing) (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](/platform-deploy) instead.
## Set up an 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.
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, Web Fetch)
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](/platform-agent-accounts#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.
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))
Open the **Playground** tab to chat with your agent interactively. The playground streams responses in real time and shows tool calls inline so you can verify prompt behavior, connector access, and model output before deploying.
The playground automatically injects Runlayer tools (search, run, manage) so the agent can reason about your Runlayer workspace without you manually adding the Runlayer connector first.
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). Schedules sharing common cron times (e.g., top of hour) are spread across a short window via deterministic jitter to prevent resource contention. If a scheduled run fails, the agent owner 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 a scoped API key directly from the webhook dialog. 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
* **Slack** integration (if configured) — run result DMs can be set to Always, Errors only, or Never. The built-in say tool lets agents post messages to Slack from any trigger type (Slack, webhook, or schedule) as long as the Slack MCP connector is attached to the agent. 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
* **Event triggers** (if enabled in your workspace) — 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](/platform-audit-logs) stream — any audit event type can be selected, for example `tool_call`, `access_denied`, or `security_violation`. Each trigger selects one or more event types and can add an optional semantic condition prompt (max 2 000 chars) that filters which events actually start a run. 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 messages, optionally filtered by a semantic condition prompt
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, and event triggers and channel monitors filter with natural-language semantic condition prompts.
To test before going live, exercise the agent's prompt and connectors in the **Playground** 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 **Activity** 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, and return an error for Slack interactions. Re-enable the toggle to resume normal operation.
Check run history for status, token/cost usage, and execution trace.
Failed runs can be retried directly from the Activity view, and any past run can be **resumed** in the Playground — click the run to open it, then click **Resume** 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 Activity view.
Tighten prompt/tool scope before broad rollout.
## 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. There is no separate agent version history, so clone an agent first if you want a rollback point before risky changes. Agents can also be created and managed programmatically via [Runlayer MCP](/runlayer-mcp) tools (`create_agent`, `update_agent`) — including from inside another agent that has the Runlayer connector attached.
## 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, Created by me, Shared with me, or Drafts
* **Status filter** to show only active or disabled agents
* **Search** by agent name
* **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.
***
## 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 fetch when enabled
* 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
### 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 files from their workspace as shareable URLs using the built-in `publish_artifact` tool. Published artifacts persist beyond the run; who can open them is controlled by the agent's [artifact sharing](#artifact-sharing) setting.
Use cases:
* Share generated reports (PDFs, CSVs, HTML)
* Distribute compiled outputs or datasets
* Provide downloadable files to end users in Slack or other channels
The tool accepts a file path under `/tmp/workspace`, an optional title, optional MIME type override, and a disposition (`inline` for browser-viewable files or `attachment` for downloads). The response includes a stable URL you can share.
Agents can also visually inspect an artifact with the built-in `screenshot_artifact` tool: it renders the file (HTML, SVG, or image) in headless Chromium inside the sandbox and returns a PNG screenshot to the agent. Agents use this to verify layout, styling, and chart rendering before or after publishing.
Artifact publishing is enabled by default on new agents. Toggle it from the agent's advanced settings if you want to disable it.
Artifact sharing
Each agent has an **Artifact sharing** setting that controls who can open its published artifacts:
| Mode | Who can access |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Only me** | Only the agent owner |
| **Everyone with the link** | Anyone in your organization who has the artifact URL (default) — viewers must be signed in to your workspace; links are not public |
| **Everyone with access to this agent** | Follows the agent's own access settings |
Change the mode from the artifact sharing settings on the agent detail page.
Artifact links are never public. Every mode requires the viewer to be
authenticated to your Runlayer workspace, so artifact access sits behind
whatever sign-in your organization has configured — including SAML 2.0 / OIDC
SSO with providers like Okta, Auth0, or Azure AD. See
[Roles & Permissions](/platform-roles) and
[Security](/infrastructure/security).
### Viewing and deleting artifacts
Each agent has an **Artifacts** tab on its detail page showing all published artifacts. From there you can:
* View any artifact's content
* Delete artifacts you created (or delete any artifact if you're the agent owner or an admin with the **Manage Agents** capability)
There is also a workspace-wide **Artifacts** page listing artifacts across agents. It supports search, **Created by me** / **Shared with me** filters, and grid or list layouts, with inline previews for common artifact types (mini apps, decks, docs, spreadsheets, images, data files).
### 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, Node.js, npm, pnpm, TypeScript, Python 3,
uv, ruff, ripgrep, jq, yq, SQLite, PostgreSQL client tools, curl, wget, zip, and
unzip.
### 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](/platform-agent-accounts#session-grants), not environment
variables — you don't paste OAuth tokens into agent env vars.
### Runtime limits
* Agent runs are short-lived; long-running services and background daemons are
not a good fit.
* Runtime limits depend on the sandbox environment: 15 minutes on the standard
runtime, up to 8 hours on the long-running runtime (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 hooks
Runlayer's agent sandbox uses runtime plugin hooks to observe or control chat,
permission, shell, provider, and tool execution. These are internal sandbox
extension points; they are not the Runlayer Hooks SDK and not AI Watch client
hooks.
Available runtime hooks:
| Hook | Purpose |
| -------------------------------------- | ---------------------------------------------------------- |
| `dispose` | Cleanup when a plugin unloads |
| `event` | Observe raw runtime events |
| `config` | Observe resolved runtime config |
| `tool` | Register custom tools exposed to the agent |
| `auth` | Register provider auth methods |
| `provider` | Register or override provider model discovery |
| `chat.message` | Handle a new user message |
| `chat.params` | Modify model request parameters |
| `chat.headers` | Modify provider request headers |
| `permission.ask` | Decide a runtime permission request |
| `command.execute.before` | Intercept slash-command execution |
| `tool.execute.before` | Intercept tool arguments before execution |
| `shell.env` | Add environment variables for shell execution |
| `tool.execute.after` | Inspect or replace tool result after execution |
| `tool.definition` | Modify tool descriptions and schemas before model exposure |
| `experimental.chat.messages.transform` | Transform chat history sent to the model |
| `experimental.chat.system.transform` | Transform system prompt content |
| `experimental.provider.small_model` | Select a provider's small model |
| `experimental.session.compacting` | Customize compaction prompt/context |
| `experimental.compaction.autocontinue` | Enable or disable synthetic continue after compaction |
| `experimental.text.complete` | Modify completed assistant text parts |
Runlayer currently uses `config`, `tool.execute.before`, and
`tool.execute.after` for ToolGuard scanning and sandbox harness protection.
ToolGuard scans local tools and non-proxied MCP tools, rewrites masked args,
blocks denied input/output, and skips MCP tools already enforced by the
Runlayer proxy. Harness protection blocks local tool reads, writes, listings,
shell commands, or outputs that expose sandbox internals; MCP-namespaced tools
are outside that local harness check.
`tool.execute.before` receives the tool identity and mutable args:
```typescript theme={null}
"tool.execute.before": async (
input: { tool: string; sessionID: string; callID: string },
output: { args: unknown },
) => {
// mutate output.args or throw to block
}
```
`tool.execute.after` receives the original args and mutable result:
```typescript theme={null}
"tool.execute.after": async (
input: { tool: string; sessionID: string; callID: string; args: unknown },
output: { title: string; output: unknown; metadata: unknown },
) => {
// inspect/mutate output or throw to block
}
```
Throwing from either hook blocks the operation and surfaces the error to the
agent run. ToolGuard blocks if backend enforcement is reachable and denies a
tool call; if the run token is missing, ToolGuard does not call backend
enforcement for that tool. Treat `output.output` as a structured value; coerce
it before string comparison or logging.
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 pauses and approvers receive a Slack
notification. The run stays paused until an approver allows or denies the call,
then continues (or fails) accordingly. This lets you keep sensitive tools
available to agents without giving up a human checkpoint.
## 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** and apply to all agents.
To override limits for a specific model within an agent, open the agent's detail page and configure per-model run limits. Each override sets a separate daily and weekly cap for that model (the weekly cap must be greater than or equal to the daily cap). When an agent reaches its limit, new runs are rejected until the window resets.
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 on the agent detail page. 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 the window resets.
### 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 (there are no pre-threshold warnings for spend). Budget alerts are enabled by default and can be toggled per-agent in the agent detail page under **Budget alerts**.
## 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 4.8, Claude Sonnet 5, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 4.6, Claude Opus 4.5, Claude Sonnet 4.5, Claude Haiku 4.5 |
| **OpenAI** | Add your OpenAI API key | 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)" |
| **Azure Foundry** | Set Azure Foundry endpoint URL + API key + model list | Any models/deployments you list for the endpoint (e.g. GPT-5.5) |
| **OpenAI-compatible gateway** | Set a gateway URL + API key + model list | Any models the gateway exposes (e.g. OpenRouter) |
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.
For Bedrock, your IAM role's trust policy must allow the Runlayer service principal with the external ID shown in the provider form. You can include or exclude the default Bedrock model list, or add custom model IDs.
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-model [run limits](#run-limits) for hard caps, provider binding for team-level cost isolation (see above), and [Analytics](/platform-analytics) for cost visibility.
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+) | low, medium, high, max, xhigh |
| **Thinking budget tokens** | Earlier Claude models | 1 024 – 64 000 |
| **Reasoning effort** | OpenAI models | minimal, low, medium, high, 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.
Self-hosted deployments can also enable Bedrock-hosted Anthropic models via Terraform without the AI Providers UI. See [Agent Sandbox LLM Gateway](/deployment/terraform#optional-services) 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. Under the hood, it's a private per-agent database exposed to the
agent at run time; when memory is enabled, the runtime prompt tells the agent it
exists so it can read and write it as part of normal runs.
### 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** is a backend-owned system for long-term facts that persist across
conversations. When enabled, the agent can use `remember` to save facts (preferences,
feedback, project context) with scope types like user or channel, and `forget` to
retire outdated entries. Scoped memory appears as a dedicated block in the agent's
context, separate from the workbench snapshot.
## Skill distillation
When enabled in your workspace, each agent has an opt-in **skill distillation** 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.
How it works:
* After a run succeeds, Runlayer inspects the run trace. Only runs with enough
multi-step tool work are considered — short runs rarely encode a transferable
playbook.
* The run trace is distilled into a concise playbook: how to achieve the same
result next time in fewer steps, skipping the missteps observed in the trace.
* Distillation is aware of the agent's existing distilled skills — a run that
teaches nothing new is skipped, and one that adds an edge case refines an
existing skill instead of creating a duplicate. The number of distilled
skills per agent is capped.
* The result is stored as an agent-private skill and linked to the agent so
future runs use it 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 |
| [Skill distillation](#skill-distillation) | Automatically turning successful multi-step runs into reusable playbooks |
| Run **resume** in the Playground | 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). Skill distillation 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 20 subagents. You can edit or remove subagents from the same section. Subagents can also be managed programmatically through [Runlayer MCP](/runlayer-mcp) 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](/platform-policies)) |
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.
## 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. 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.
### 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](/platform-agent-accounts#session-grants) for the full resolution order and examples.
### Gradual rollout
Agents don't have to launch workspace-wide at once:
1. Create the agent as **Private** and validate behavior in the **Playground**.
2. Share it with a pilot user, group, or role at **Can use** level and monitor the **Activity** 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](/platform-policies) apply throughout, so broader visibility never bypasses access control.
## 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`.
* **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](/deployment/runlayer-operator) 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](/deployment/overview).
## 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."
Mutating Runlayer MCP actions are confirm-gated (for example `confirm=true`)
and permission-gated (admin/owner where required).
## Agents vs Agent Accounts
* **Agents**: UI-managed AI workers with prompt + tool curation
* **Agent Accounts**: OAuth client identities for programmatic/API access
If you are building machine-to-machine automation, see [Agent Accounts](/platform-agent-accounts).
## Related docs
Built-in MCP for analytics, audit logs, inventory, governance
Programmatic auth + delegated access model
Control what agents and users can do
Debug connector, auth, and permission failures