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
• one or more assigned tools
• optional automatic tool assignment from matching MCP catalog labels
• an optional search-and-run tool mode for hiding most tools from MCP tools/list
• optional delegation targets to other agents
• one or more assigned knowledge sources

Tool Assignment Mode

An agent has a tool assignment mode: Manual (default) or Automatic.

In Manual mode, you pick each tool directly. In Automatic mode, the agent receives tools from MCP catalog entries that share at least one key: value label pair with the agent. For example, an agent labeled department: finance automatically receives tools from catalog items tagged department: finance.

Use Automatic mode when labels already describe which MCP servers belong to a team, department, app, or environment and you want new matching catalog entries to be picked up without editing every agent.

See MCP Gateway - Tool Assignment Mode for the full behavior and constraints.

Search-and-Run Tool Mode

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

For larger toolsets, you can switch the agent to search-and-run tool mode. In that mode, MCP clients only see the built-in search_tools and run_tool tools. Those two tools are enabled implicitly by the mode 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.

See MCP Gateway - Search-and-Run Tool Mode for the MCP-client-facing behavior and the same mode on gateways.

Invocation Paths

Agents can be triggered through:

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

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

Knowledge Sources

Agents can be assigned one or more Knowledge Bases or knowledge connectors. This gives the agent retrieval access to your internal docs and connected systems without hardcoding those sources into the prompt.

When at least one knowledge source is assigned, Archestra automatically adds the built-in query_knowledge_sources tool to that agent. The model can call it during a run to search across the assigned sources and pull relevant context into its answer.

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.

Delegation

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)
• assigned tools are listed under a Recommended tools section so the activating agent knows what 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

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.

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