Customising agents

Agent personas in relay are defined in an agent pool. Each /relay:relay session selects a task-optimised team from the pool via conversational team composition.

File structure

your-project/
└── .relay/
    └── agents.pool.yml   # your agent pool (edit this file)

Copy agents.pool.example.yml (shipped with relay) to .relay/agents.pool.yml to get started.

Basic structure of agents.pool.yml

agents:
  fe:
    name: "Frontend Engineer"
    emoji: "💻"
    description: "React, TypeScript, and UI implementation"
    tags: [frontend, react, typescript]
    tools:
      - get_messages
      - claim_task
      - update_task
      - post_artifact
      - send_message
      - request_review
      - broadcast_thinking
    systemPrompt: |
      You are a Frontend Engineer specialising in React and TypeScript.
      ...

Supported fields

Field	Required	Description
name	Yes	Display name of the agent
emoji	Yes	Emoji shown in the dashboard and messages
tools	Yes	List of MCP tools the agent is allowed to call
systemPrompt	Yes	The agent’s base system prompt
description	No	Short summary used for team selection suggestions
tags	No	Taxonomy tags for smart team matching in /relay:relay
language	No	Force response language (e.g. "Korean", "English")
disabled	No	When true, excludes this agent from the registry
extends	No	Inherit all fields from another pool agent; override only what differs
validate_prompt	No	Declarative validation criteria injected into the system prompt before task completion — agents verify all criteria before calling update_task(status: "done")

Agent IDs must use only alphanumeric characters, hyphens, and underscores ([a-zA-Z0-9_-]).

Top-level language field

Set a default response language for all agents in the pool:

language: "Korean" # all agents respond in Korean unless overridden per-agent

agents:
  fe:
    name: "Frontend Engineer"
    # ... inherits language: "Korean"
  pm:
    name: "Product Manager"
    language: "English" # overrides the top-level default for this agent only
    # ...

extends

Inherit and extend another agent’s configuration. This is useful for running multiple instances of the same role:

agents:
  fe:
    name: "Frontend Engineer"
    emoji: "💻"
    tags: [frontend]
    tools: [claim_task, update_task, post_artifact, send_message]
    systemPrompt: |
      You are a Frontend Engineer specialising in React and TypeScript.
      ...

  fe2:
    extends: fe # inherit from the fe persona
    name: "Frontend Engineer (Reviewer)"
    emoji: "🔍"

extends is resolved in a second pass, so declaration order in the YAML file does not matter. Session-file agents can also extends a pool agent by ID.

tags field

Tags are used by /relay:relay for smart team suggestion matching. Add tags that describe the agent’s domain and skills:

agents:
  security:
    name: "Security Engineer"
    emoji: "🔐"
    tags: [security, owasp, vulnerability]
    description: "Security vulnerability analysis and remediation"
    tools:
      - get_messages
      - update_task
      - get_artifact
      - post_artifact
      - send_message
    systemPrompt: |
      You are a security expert.
      Review code against the OWASP Top 10 and
      identify vulnerabilities with recommended fixes.

tools field

Specifies the list of MCP tools the agent is allowed to call. Common tools to assign:

tools:
  # Messaging
  - send_message
  - get_messages
  # Tasks
  - create_task
  - update_task
  - claim_task
  - get_all_tasks # supports optional assignee filter
  # Artifacts
  - post_artifact
  - get_artifact
  # Reviews
  - request_review
  - submit_review
  # Memory
  - read_memory
  - write_memory
  - append_memory
  # Visibility
  - broadcast_thinking
  # Orchestrator state (for context compaction resilience)
  - save_orchestrator_state
  - get_orchestrator_state

An agent cannot call any MCP tool not listed in its tools array. It is recommended to grant only the minimum tools necessary for each role.