Overview

Agents are reusable AI workers with instructions, tool access, and optional knowledge retrieval. You can invoke the same agent from chat, external integrations, or automation without rebuilding the workflow each time.

An agent can include:

• a system prompt that defines behavior
• suggested prompts for common tasks in chat
• a Tools & Knowledge Sources setting: Auto (every tool and knowledge source the chatting user can access, minus an exclusion list) or Custom (only assigned tools and sources)
• optional Load tools when needed mode for keeping MCP tools/list small
• a When someone is missing a tool connection setting for teammates who have not connected one of the agent's MCP servers
• a Subagents setting: Auto (delegate to any agent the chatting user can access, minus a disabled list) or Custom (only assigned delegation targets)
• one or more assigned knowledge sources

Load Tools When Needed

By default, an agent exposes every assigned tool through MCP tools/list.

For larger toolsets, enable Load tools when needed. This keeps the initial tool list small. MCP clients see the built-in search_tools and run_tool tools first. Those two tools are enabled implicitly and do not need normal tool assignment.

• search_tools can still discover them
• run_tool can still execute them

Use this when the full tool menu is too large to send to the model on every turn, but you still want the agent to keep access to the same assigned toolset.

An agent's Tools & Knowledge Sources setting is Auto or Custom — tabs in the agent dialog. The tabs govern both tools and knowledge sources; this section covers the tools half. In Custom mode the agent uses only its explicitly assigned tools; new agents get a default set assigned by the backend, and the create form pre-selects that same set. Custom assignments resolve credentials at call time by default; you can pin a specific connection per server instead. In Auto mode, discovery is not limited to assigned tools: search_tools can find and run_tool can run every tool the signed-in user can access — Archestra built-in tools and tools from MCP servers — except tools on the agent's exclusion list. User permissions still apply. run_tool executes such a tool directly with credentials resolved at call time, following the MCP server's Default credential setting: on behalf of the user by default (each person's own connection), or one shared account when the server is configured that way. A caller without a connection gets an actionable prompt to connect — nothing is borrowed from team or organization credentials. Nothing is assigned to the agent, so no permission to modify the agent is involved. This lets Agent Skills reference tools without pre-assigning every tool to every agent.

Tool call policies still apply to the target tool. If the model calls run_tool to execute send_email, Archestra evaluates policies for send_email with the same arguments and context it would use for a direct tool call. See AI Tool Guardrails - Load Tools When Needed.

See MCP Gateway - Load Tools When Needed for the MCP-client-facing behavior and the same mode on gateways.

Excluding Servers and Tools

Auto can be too broad: it gives the agent everything the calling user can reach. To carve out exceptions, each agent has an exclusion list — edit it under Disabled tools on the Auto tab of the agent dialog (or via GET/PUT /api/agents/:id/tool-exclusions), excluding whole MCP servers or individual tools. Use this for an agent that should see everything except, say, a payments server or a single destructive tool.

While the tools setting is Auto, exclusions cover the agent's entire surface:

• excluded tools do not appear in search_tools results and cannot be executed by run_tool or called directly by an MCP client
• the agent's MCP resources and prompts from an excluded server are also unreachable
• tools explicitly assigned to the agent are excluded too — the assignments stay in place and take effect again in Custom mode

Built-in tools are excluded by default. When an agent is created in Auto mode or switched to it, the exclusion list is pre-filled with every built-in tool that is not assigned to the agent — except a small set that always stays available: search_tools, run_tool, the sandbox and file tools (run_command, upload_file, download_file, search_files, read_file, save_file, edit_file, delete_file), and query_knowledge_sources. So by default an Auto-mode agent cannot use the built-ins that manage the platform itself (creating agents, managing teams, policies, and so on) until an admin removes them from the list. The pre-fill runs on every switch to Auto — to keep a built-in usable across switches, assign it to the agent. When a platform update ships a new built-in tool, agents already in Auto mode get it excluded by default; admins opt in by un-excluding it. Agents that were in Auto mode before exclusions existed keep exactly their capabilities: the unassigned built-ins they could not use are now on their exclusion list, visible and editable.

Only search_tools and run_tool can never be excluded; everything else can. Agent delegation tools sit outside the exclusion list — manage them through delegation itself — and the built-in server cannot be excluded as a whole, only tool by tool.

Exclusions are stored per agent and have no effect in Custom mode. Cloning an agent copies them. Agent export does not carry them — server and tool IDs are not portable across organizations — so an imported agent starts with no exclusions and they must be re-created. Exclusions track the specific tool record: if an MCP server renames a tool, the renamed tool counts as new and is no longer excluded.

Missing Tool Connections

An agent's tools can come from MCP servers that each person connects with their own account. Share that agent, and a teammate who has not connected one of those servers finds out only when a tool from it runs.

When someone is missing a tool connection sits in Custom mode, under Tools & Knowledge Sources:

• Let them continue — the default. Nothing is shown up front.
• Let them continue, with a warning — the chat names the servers they have not connected, and offers to connect them.
• Stop them from using the agent — the agent is marked unavailable in the chat picker, and the run is refused wherever it is triggered from.

A server counts as connected when the person's own connection covers it, when a team or organization connection does, or when the agent pins one shared account. Servers that need no credentials never count as missing.

The setting does nothing in Auto mode, where each caller's tools come from what they can already reach.

Invocation Paths

Agents can be triggered through:

• Archestra Chat UI
• Webhook (A2A)
• Incoming Email
• Slack
• MS Teams
• Telegram

Trigger setup is managed from Agent Triggers. Slack, MS Teams, Telegram, and Incoming Email each have their own setup flow, and Incoming Email also owns the per-agent email invocation settings.

Knowledge Sources

Knowledge follows the same Auto / Custom setting as tools (Tools & Knowledge Sources in the agent dialog). In Auto mode the agent can search every Knowledge Base and connector the chatting user can access, in its environment. In Custom mode it searches only the sources you assign to it. Either mode is still filtered by each user's own visibility.

Whenever an agent has at least one reachable knowledge source, Archestra adds the built-in query_knowledge_sources tool so the model can search across them during a run.

The output of query_knowledge_sources is treated as sensitive by default, which can impact the ability to use subsequent tools. See Archestra MCP Server, and AI Tool Guardrails, for more details.

See Knowledge Bases for how retrieval works and how sources are assigned. See Archestra MCP Server for the built-in tool behavior and RBAC requirements.

Environments

An agent can be assigned to an environment. This does two things: its code sandbox runs under that environment's egress network policy (the same machinery that governs self-hosted MCP server pods), and the tools, knowledge, skills, and subagents it can use are scoped to that environment — the agent only sees tools, knowledge connectors, skills, and delegation targets in the same environment (built-in servers and built-in skills excepted). With no environment assigned, the agent uses the Default environment.

See Environments for the isolation model and network egress policies for how policies are configured.

Skills

An agent consumes Agent Skills through two built-in tools: list_skills returns the catalog, load_skill pulls one skill's instructions into context. Users can also invoke a skill directly with a /skill-name slash command in chat. Either way, the agent only sees skills in its environment that the calling user can access.

A skill that names an agent in its frontmatter runs in that subagent instead — the agent calls the skill's skill__<name> tool and receives the result. See Running a Skill in a Subagent.

Delegation

An agent can delegate work to other agents — its subagents. Like Tools & Knowledge Sources, delegation has an Auto or Custom setting, under the Subagents tabs in the agent dialog.

In Custom mode the agent delegates only to the subagents you assign. In Auto mode it can delegate to any agent the calling user can access — new agents included automatically — minus a disabled list. Disable specific agents under Disabled subagents on the Auto tab (or via GET/PUT /api/agents/:id/subagent-exclusions). Each user's own access still applies, so Auto never means any agent can call any agent — a caller only reaches agents it could already see. Both modes stay within the agent's environment: only same-environment agents are eligible.

Auto delegation resolves per calling user. It applies in chat and other flows that carry a signed-in user; automated runs without one — a scheduled trigger, for example — fall back to the explicitly assigned targets.

When an agent delegates work to another agent, Archestra tracks the full call chain for observability. Delegated agents also inherit the current tool guardrails trust state, so downstream tool policy enforcement does not reset mid-run.

Convert to Skill

An agent can be converted into an Agent Skill — a reusable SKILL.md instruction set that any agent can activate from chat. Use this when the agent's value is mostly in its instructions and you want them available as a /slash-command rather than as a separate agent to switch to.

The Convert to skill action on the agents page opens a confirmation dialog where you set the skill's description and choose whether to remove the source agent once the skill is created. The skill inherits the agent's scope. Conversion is lossy by nature: a skill carries instructions only, with no tools, model, or knowledge of its own. Each field is either carried over or annotated:

• the system prompt becomes the skill body, and the scope carries over directly; the name is normalized into a slug (for example Support Helper → support-helper) so it works as a /slash-command
• the description is required — the agent's own is prefilled, and you must supply one when the agent has none (an activating agent uses it to decide when to run the skill); Generate drafts one from the agent's prompt, tools, and example prompts via a single LLM call when you need a starting point
• if the system prompt uses Handlebars templating, the skill is flagged templated so its body is re-rendered with the activating user's context at runtime — otherwise the slug would bake one author's {{user.name}} into instructions every agent shares
• assigned tools are carried into the skill's allowed-tools frontmatter (the skill-runtime tools are dropped as noise), so the activating agent knows which tools to enable; the default model and knowledge sources have no skill equivalent and are reported as not carried, without cluttering the skill body
• suggested prompts, icon, and labels are folded into the body or metadata, and the origin agent is recorded in metadata so the skill stays linked back to it
• removing the source agent is optional and off by default; it is a soft delete, so the agent can be restored later from the deleted-agents filter

Deleting an Agent

Deleting an agent hides it everywhere and stops its scheduled runs. The agent is not destroyed — it moves to a trash. Switch the status filter to Deleted to see what is there, and Restore to bring one back.

Global admins can also delete an agent from the trash for good, with Delete permanently. This destroys its configuration, version history, hooks, and scheduled tasks. Nothing brings it back.

What the agent produced stays. Its chats and its LLM usage records survive the deletion and simply stop pointing at it, so your history and cost reporting stay intact.

Deleting an agent for good also clears it from anywhere it was set as a default — the organization default, the /connection defaults, and each member's personal default. Those fall back to unset, so pick a replacement afterwards.

Purging a busy LLM proxy has millions of usage records to detach and can take a few minutes. Past five it stops and leaves the agent in the trash, unharmed. Try again during a quieter period.

Version History

Archestra snapshots an agent's configuration every time it changes — prompt, tools, hooks, knowledge, or settings. A save that changes nothing does not create a version. MCP gateways and LLM proxies keep the same history.

Open Version history from the agent's row menu to browse the snapshots. Pick one to read its configuration. All settings shows the whole configuration; Changes shows only what moved since the version before.

The history is available through the API. GET /api/agents/:id/versions lists versions as metadata, newest first. GET /api/agents/:id/versions/:version returns one full configuration snapshot. Key material is never captured, so you can review what changed without exposing secrets.

Each agent keeps its last 100 versions. The oldest listed version can therefore be greater than 1.

Restoring a Version

Restore this version returns an agent to an earlier configuration. The restore forks forward: the old configuration becomes a new version. Nothing in the history is overwritten.

If someone else edits the agent while you preview it, the restore is refused.

A restore is all-or-nothing. If the version points at something that no longer exists — a deleted tool, for example — the restore fails and the agent is left exactly as it was. Recreate the missing piece, or restore a later version instead.

Over the API, POST /api/agents/:id/versions/:version/restore does the same. Send the agent's current latestVersion as baseVersion to anchor the restore. A 409 then tells you someone else changed the agent first. Built-in agents cannot be restored.

System Prompt Templating

Agent system prompts support Handlebars templating. Templates are rendered at runtime before the prompt is sent to the LLM, with the current user's context injected as variables. Agent Skills can opt into the same rendering with a templated: true frontmatter field (set automatically when converting a templated agent); their SKILL.md body is then rendered with the same variables and helpers each time the skill is loaded.

Variables

Helpers

All built-in Handlebars helpers (#each, #if, #with, #unless) are also available, along with Archestra helpers like includes, equals, contains, and json.

Example

You are a helpful assistant for
{{user.name}}. Today's date is
{{currentDate}}.

{{#includes user.teams "Engineering"}}
  You have access to engineering-specific tools and documentation.
{{/includes}}

{{#if user.teams}}
  The user belongs to:
  {{#each user.teams}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}.
{{/if}}