agent.yaml Reference

agent.yaml is the heart of every agent package. It tells the Selu orchestrator who the agent is, how it should be routed, and which capabilities it can use.

Minimal example

id: hello-world
name: Hello World

That is all you need to get started. Every other field is optional and has sensible defaults.

Full schema

Top-level fields

Field	Type	Required	Description
id	string	Yes	Unique identifier. Lowercase, hyphens allowed.
name	string	Yes	Human-readable display name.
i18n	object	No	Localization config (default_locale, supported_locales).
model	object	No	LLM model suggestion. The user’s configured default model is used if omitted.
routing	string	No	Routing mode: inline, delegate, or auto (default).
session	object	No	Session management and isolation settings.
capabilities	list	No	Capabilities this agent can use.
install_steps	list	No	Post-install setup wizard steps.
automation	object	No	Schedule presets users can opt into.

model

The model section is a suggestion to the orchestrator. If the user has configured a default model, that takes precedence.

model:
  provider: anthropic
  model_id: claude-sonnet-4-20250514
  temperature: 0.7

Field	Type	Required	Description
provider	string	No	Provider name, e.g. anthropic, openai, bedrock.
model_id	string	No	Model identifier, e.g. claude-sonnet-4-20250514.
temperature	float	No	Sampling temperature (0.0 - 2.0). Default 0.7.

routing

Routing controls how the orchestrator decides to involve this agent when a message arrives.

routing: delegate

Mode	Description
auto	The orchestrator decides at runtime whether to inline or delegate (default).
inline	The agent processes messages inline within the current conversation flow.
delegate	The orchestrator delegates the full conversation turn to this agent.

auto mode heuristics

When routing is auto (the default), the orchestrator evaluates the agent on each request and chooses inline or delegate automatically:

• Inlines when all of the following are true: the agent has 3 or fewer tools, no custom model is configured, and the resolved system prompt is under 2000 characters.
• Delegates otherwise.

This means lightweight agents stay fast and low-overhead, while agents with many tools or a custom model get their own dedicated context window.

See Routing & Sessions for full details.

session

session:
  trigger: mention              # mention | always | auto
  idle_timeout_minutes: 30     # session cleanup timeout
  isolation: per_thread        # shared | per_thread

Field	Type	Required	Description
trigger	string	No	When to activate this agent. Default mention.
idle_timeout_minutes	int	No	Minutes before idle sessions are cleaned up. Default 30.
isolation	string	No	Session isolation mode. Default shared.

Session isolation modes

• shared (default) — Reuses active sessions for the same user+agent across threads. Capability containers and workspaces are shared between conversations.
• per_thread — Forces dedicated sessions per thread. Each conversation thread gets its own capability containers and isolated workspaces.

:::tip When to use per-thread isolation Use isolation: per_thread for stateful agents like coding assistants or workspace managers where you want to prevent cross-thread state collisions. This ensures that work in one conversation doesn’t interfere with another. :::

:::caution Resource usage Per-thread isolation uses more memory and CPU since each thread runs separate capability containers. Only use it for agents that genuinely need workspace isolation. :::

capabilities

Capabilities are listed by id reference.

capabilities:
  - id: weather
  - id: calendar

Field	Type	Required	Description
id	string	Yes	Capability identifier.

install_steps

Install steps define a post-install setup wizard that runs when a user adds the agent. Each step can collect credentials, configure settings, or verify that prerequisites are met.

install_steps:
  - id: api_key
    type: input
    label: OpenWeatherMap API Key
    description: Enter your API key from openweathermap.org
    validation: "^[a-f0-9]{32}$"
    default: ""
    store_as:
      scope: system
      capability_id: weather
      credential_name: OPENWEATHER_API_KEY
  - id: test_key
    type: test
    label: Verify API Key
    depends_on: [api_key]
    request:
      method: GET
      url: "https://api.openweathermap.org/data/2.5/weather?q=London&appid={{api_key}}"
      expect_status: 200

Steps run in order. Use depends_on to express dependencies between steps so the wizard can skip or retry as needed.

Step fields

Field	Type	Required	Description
id	string	Yes	Unique step identifier. Referenced by depends_on and template variables.
type	string	Yes	Step type: input or test.
label	string	Yes	Short label shown in the wizard UI.
description	string	No	Help text shown below the input field.
depends_on	list	No	List of step ids that must complete before this step runs.
validation	string	No	Regex pattern the input value must match.
default	string	No	Default value pre-filled in the input field.
store_as	object	No	Where to persist the collected value (see below).
request	object	No	HTTP request definition for test steps (see below).

store_as (credential target)

Field	Type	Required	Description
scope	string	Yes	Storage scope, e.g. system.
capability_id	string	Yes	The capability that owns this credential.
credential_name	string	Yes	Environment variable name exposed to the capability at runtime.

request (test step)

Field	Type	Required	Description
method	string	Yes	HTTP method (GET, POST, etc.).
url	string	Yes	URL to call. Supports {{step_id}} template variables that resolve to the value collected by a previous step.
expect_status	int	Yes	Expected HTTP status code. The step passes when the response matches.

automation

The automation section lets you define schedule presets that users can opt into after installing the agent.

automation:
  schedules:
    - id: daily_forecast
      label: Daily Weather Forecast
      prompt: Give me today's weather forecast for my location
      cron_expression: "0 0 7 * * 1-5"
      cron_description: Every weekday at 7:00 AM

Field	Type	Required	Description
schedules	list	No	List of schedule presets.

Each schedule entry:

Field	Type	Required	Description
id	string	Yes	Unique identifier for this schedule.
label	string	Yes	Human-readable label shown to the user.
prompt	string	Yes	The prompt sent to the agent on each trigger.
cron_expression	string	Yes	6-field cron expression (see below).
cron_description	string	No	Human-readable description of the schedule.

Cron format

Selu uses a 6-field cron format: second minute hour day-of-month month day-of-week. This differs from traditional 5-field cron by adding a leading second field. For example, 0 0 7 * * 1-5 means “at 07:00:00 every weekday.”

Full example

id: weather-agent
name: Weather Agent
i18n:
  default_locale: en
  supported_locales: [en, de]
model:
  provider: anthropic
  model_id: claude-sonnet-4-20250514
  temperature: 0.5
routing: inline
session:
  trigger: mention
  idle_timeout_minutes: 30
  isolation: shared
capabilities:
  - id: weather
install_steps:
  - id: api_key
    type: input
    label: OpenWeatherMap API Key
    description: Enter your API key from openweathermap.org
    validation: "^[a-f0-9]{32}$"
    store_as:
      scope: system
      capability_id: weather
      credential_name: OPENWEATHER_API_KEY
  - id: test_key
    type: test
    label: Verify API Key
    depends_on: [api_key]
    request:
      method: GET
      url: "https://api.openweathermap.org/data/2.5/weather?q=London&appid={{api_key}}"
      expect_status: 200
automation:
  schedules:
    - id: daily_forecast
      label: Daily Weather Forecast
      prompt: Give me today's weather forecast for my location
      cron_expression: "0 0 7 * * 1-5"
      cron_description: Every weekday at 7:00 AM

For the complete schema definition, see the agent.yaml Schema Reference.