Agent Roles

Agent roles are named personas that sub-agents can be assigned to in a swarm. Each role carries a system prompt, optional tool restrictions, and preferred skills that shape the agent's behaviour and expertise.

How Roles Work

When you create a swarm task with { agentRoleName: "Developer", prompt: "..." }:

• If "Developer" matches a configured role, the agent inherits that role's system prompt, tool restrictions, and preferred skills.
• If the name doesn't match any configured role, it simply creates a generic agent with that name — this is not an error, but the agent won't have specialized behaviour.

The role name is a free-form string, not a fixed enum. You can invent any name, but it only carries special behaviour if it matches a role you've configured.

Listing Roles

agent_roles(action: "list")

This returns all roles (both built-in and custom), showing their name, description, allowed tools, and system prompt. Always check the list before assigning roles in a swarm plan — a matching role gives your agents the right expertise and guardrails.

Creating a Custom Role

agent_roles(action: "add", name: "SecurityReviewer", roleDescription: "Reviews code for security vulnerabilities", systemPrompt: "You are a security expert...", allowedTools: ["file_read", "grep", "bash"], preferredSkills: ["security-review"], model: "anthropic/claude-3.5-sonnet")

Parameter	Description
name	Role name (used as agentRoleName in swarm tasks)
roleDescription	Short human-readable description
systemPrompt	Full system prompt defining the agent's persona and instructions
allowedTools	List of allowed tool names (empty = all tools)
preferredSkills	List of skill IDs to inject (empty = auto-detection via prompt keywords)
model	Model to use (optional, defaults to current model)
timeoutSeconds	Absolute execution cap (default: 1800s = 30 min)

Updating a Role

agent_roles(action: "update", roleId: "security-reviewer", systemPrompt: "Updated prompt...")

You can update any field — system prompt, allowed tools, preferred skills, model, or timeout.

Removing a Role

agent_roles(action: "remove", roleId: "security-reviewer")

Only custom roles can be removed. Built-in roles are always available.

Best Practices

• Prefer existing roles — Check list first. Using a configured role ensures agents get the right system prompt and tool restrictions automatically.
• Restrict tools — For roles like "Researcher" that only need read access, set allowedTools to a minimal set (file_read, grep, web_browse). This reduces risk and cost.
• Inject skills — Use preferredSkills to give agents domain expertise (e.g., swift-ios for a Swift developer role) instead of writing long system prompts.
• Set realistic timeouts — Most tasks finish within 5 minutes. Only override timeoutSeconds for tasks genuinely expected to exceed 30 minutes.