Agents

​

Why Agents

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

​

Agents for any purpose

• 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

​

Set up an agent

​

Allowing an agent to invoke other agents

• 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.

​

Cloning an agent

​

Version history

​

Browsing and filtering agents

• 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

​

Find an existing agent before you build

• 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 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 exposes list_agents, list_skills and list_servers, and the Runlayer Plugin 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.

​

Runtime capabilities

• 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)
• 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 is enabled and granted to the agent

​

Filesystem workspace

​

Artifact publishing

​

Artifact sharing

​

Viewing and deleting artifacts

​

Shell and code execution

​

Network access policy

• 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.

​

Source IP addresses

• 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). For a public MCP server, add it as a connector and allowlist those addresses. Tunnel and 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 connects from its provider’s network instead.

​

Cloud browsers

​

Environment variables

​

Waiting on external work

• 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

​

Human-in-the-loop approvals

• 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.
• Which decisions continue the run: Slack runs continue when the requester decides in the Slack thread. Web chat, schedule, webhook and MCP runs continue after a decision from the web app or a Slack DM. Runs started from Teams, 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.

​

Changes an agent makes to itself

​

Usage limits

​

Run limits

​

Cost budgets

​

Budget alerts

​

LLM providers

​

Bedrock with an IAM role

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.

​

Non-Claude models on Bedrock

• 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.

​

Runlayer Assistant model

​

Recommended model

​

Model access by role

• 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 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

​

Agent memory

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

​

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.

​

Memory scopes

• 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.

​

Self-improving agents

​

Improving agents over time

​

Subagents

​

Agent policies

​

Error notifications

​

Webhook receivers

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

​

Deployment pilot

​

Multi-agent strategy

• 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

​

Who can see an agent’s runs

1. Create a group for the department’s builders in your identity provider (or a team 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.

​

Shared agents and user credentials

​

Who does the agent run as?

​

Keep a team’s agent running when someone leaves

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.

​

Gradual rollout

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.

​

Improve one shared agent together

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 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).
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, 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).

​

Test an agent before production

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 or with Terraform (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 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 it, swap in the test connectors, and apply the change to the original once it works. Every save to the original is a version you can restore.
4. Replay real runs with offline evals. Offline evals 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 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).

​

Security and isolation

• Sandboxed execution — each agent runs in an isolated sandbox (see 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 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 with gVisor or Kata Containers on the sandbox nodes — see Runlayer Operator — K8s Agent Sandbox.
• 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 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).
• Per-agent memory — the optional workbench memory is scoped to a single agent; other agents cannot read it (see 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 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 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.

​

Use Runlayer MCP inside agents

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

• “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.”

​

Manage agents with Terraform

​

Agents vs Agent Accounts

​

Related docs