agent.yaml Schema

Every Selu agent is defined by an agent.yaml file at the root of the agent’s project directory. This file uses a flat YAML structure (no Kubernetes-style apiVersion/kind/metadata/spec nesting). The orchestrator reads this file to identify the agent, resolve its model, wire up capabilities, and configure session and automation behavior.

The agent’s system prompt is loaded from a separate agent.md file in the same directory — it is not a field in agent.yaml.

Top-level fields

Field	Type	Required	Default	Description
id	string	Yes	—	Unique identifier for the agent. Used internally for routing and storage.
name	string	Yes	—	Human-readable display name shown in the UI.
i18n	object	No	—	Internationalization config. See i18n.
model	object	No	—	LLM model config. See model. If omitted, resolved at runtime via per-agent DB overrides or global default fallback.
routing	string	No	"auto"	How the orchestrator routes messages to this agent. One of "inline", "delegate", or "auto". See routing.
session	object	No	—	Session lifecycle config. See session.
capabilities	list	No	[]	Capabilities the agent can invoke. See capabilities.
install_steps	list	No	[]	Setup wizard steps shown during agent installation. See install_steps.
automation	object	No	—	Scheduled automation config. See automation.

---

i18n

Internationalization settings for agents that support multiple locales.

Field	Type	Required	Default	Description
default_locale	string	Yes	—	The default locale code (e.g. en, de).
supported_locales	list	Yes	—	List of locale codes the agent supports.

i18n:
  default_locale: en
  supported_locales: [en, de]

---

model

LLM provider and model configuration. This entire section is optional. When omitted, the platform resolves the model at runtime using per-agent database overrides or the global default model.

Field	Type	Required	Default	Description
provider	string	Yes	—	LLM provider identifier (e.g. openai, anthropic, bedrock, ollama).
model_id	string	Yes	—	Model identifier at the provider (e.g. gpt-4o, claude-sonnet-4-20250514).
temperature	float	No	0.7	Sampling temperature.

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

---

routing

Controls how the orchestrator delivers messages to this agent. Set as a top-level string field.

Value	Description
"inline"	The agent processes the message synchronously within the current request.
"delegate"	The orchestrator delegates the message to the agent asynchronously.
"auto"	The orchestrator decides the best strategy at runtime. This is the default.

routing: delegate

---

session

Configures the agent’s session lifecycle.

Field	Type	Required	Default	Description
trigger	string	No	"mention"	How the agent is activated.
idle_timeout_minutes	int	No	30	Minutes of inactivity before the session expires.
isolation	string	No	"shared"	Session isolation mode. "shared" or "per_thread".

session:
  trigger: mention
  idle_timeout_minutes: 60
  isolation: per_thread

---

capabilities

A list of capability references. Each entry tells the orchestrator which capabilities this agent is allowed to invoke.

Field	Type	Required	Description
id	string	Yes	The capability identifier, matching the capability’s registered ID.

capabilities:
  - id: web-search
  - id: file-writer
  - id: pdf-render

---

install_steps

A list of setup wizard steps that run when the agent is installed. Use these to collect credentials, API keys, or other configuration from the user, and to verify that external services are reachable.

Each step has the following fields:

Field	Type	Required	Description
id	string	Yes	Unique identifier for this step.
type	string	Yes	Step type: "input" (collect a value) or "test" (verify a connection).
label	string	Yes	Short label shown to the user in the setup wizard.
description	string	No	Longer explanatory text shown below the label.
default	string	No	Pre-filled default value for input steps.
validation	string	No	Validation rule or regex applied to user input.
store_as	object	No	Where to store the collected value. See store_as.
request	object	No	HTTP request to execute for test steps. See request.
depends_on	list	No	List of step IDs that must complete before this step runs.

store_as

Defines where a collected install step value is persisted as a credential.

Field	Type	Required	Description
scope	string	Yes	Credential scope.
capability_id	string	Yes	The capability this credential belongs to.
credential_name	string	Yes	Name of the credential.

request

Defines an HTTP request used by "test" type install steps to verify connectivity.

Field	Type	Required	Description
method	string	Yes	HTTP method (e.g. GET, POST).
url	string	Yes	Target URL. May reference variables collected in prior steps.
expect_status	int	Yes	Expected HTTP status code (e.g. 200).

install_steps:
  - id: api_key
    type: input
    label: API Key
    description: Enter your service API key. You can find it at https://example.com/settings.
    validation: "^sk-[a-zA-Z0-9]{32,}$"
    store_as:
      scope: agent
      capability_id: web-search
      credential_name: api_key

  - id: verify_api
    type: test
    label: Verify API access
    depends_on: [api_key]
    request:
      method: GET
      url: https://api.example.com/v1/ping
      expect_status: 200

---

automation

Defines scheduled tasks that the agent runs automatically. Contains a single schedules list.

automation.schedules[]

Field	Type	Required	Description
id	string	Yes	Unique identifier for the schedule.
label	string	Yes	Human-readable label for this schedule.
prompt	string	Yes	The prompt sent to the agent when the schedule fires.
cron_expression	string	Yes	Standard cron expression (e.g. 0 9 * * 1-5).
cron_description	string	Yes	Human-readable description of the cron schedule.

automation:
  schedules:
    - id: daily_summary
      label: Daily summary
      prompt: Generate a summary of all open tasks and send it to the team channel.
      cron_expression: "0 9 * * 1-5"
      cron_description: Every weekday at 9:00 AM

---

Full example: simple agent

A minimal agent with i18n support and a custom session timeout. No model is pinned — the platform resolves it at runtime.

agent.yaml

id: pdf
name: PDF Creator
i18n:
  default_locale: en
  supported_locales: [en, de]
routing: delegate
session:
  trigger: mention
  idle_timeout_minutes: 60
capabilities:
  - id: pdf-render

The system prompt lives in a separate agent.md file alongside agent.yaml.

Full example: agent with install steps and automation

A more complete agent that collects credentials during setup, verifies API connectivity, and runs a daily scheduled task.

agent.yaml

id: report-builder
name: Report Builder
i18n:
  default_locale: en
  supported_locales: [en, de, fr]
model:
  provider: anthropic
  model_id: claude-sonnet-4-20250514
  temperature: 0.3
routing: delegate
session:
  trigger: mention
  idle_timeout_minutes: 120
  isolation: per_thread
capabilities:
  - id: web-search
  - id: file-writer
  - id: pdf-render
install_steps:
  - id: datasource_url
    type: input
    label: Data source URL
    description: The base URL of the reporting API.
    default: https://api.example.com/v2
    store_as:
      scope: agent
      capability_id: web-search
      credential_name: datasource_url

  - id: datasource_key
    type: input
    label: API key
    description: Authentication key for the reporting API.
    validation: "^rk-[a-zA-Z0-9]{40}$"
    store_as:
      scope: agent
      capability_id: web-search
      credential_name: api_key

  - id: verify_datasource
    type: test
    label: Verify data source connectivity
    depends_on: [datasource_url, datasource_key]
    request:
      method: GET
      url: https://api.example.com/v2/health
      expect_status: 200
automation:
  schedules:
    - id: weekly_report
      label: Weekly report
      prompt: >
        Pull data for the past 7 days, generate a PDF report with charts,
        and post it to the #reports channel.
      cron_expression: "0 8 * * 1"
      cron_description: Every Monday at 8:00 AM
    - id: daily_digest
      label: Daily digest
      prompt: Summarize yesterday's key metrics and post to #daily-digest.
      cron_expression: "0 9 * * 1-5"
      cron_description: Every weekday at 9:00 AM

Notes

• The id field must be unique within your Selu instance.
• The model section is entirely optional. When omitted, the platform resolves the model at runtime using per-agent database overrides or the global default. This lets administrators change models without editing agent files.
• The system prompt is always loaded from a separate agent.md file in the same directory as agent.yaml. It is never specified inline in the YAML.
• Capability references use only id — there are no version constraints or inline config maps on the capability reference itself.
• Install steps run in dependency order. Use depends_on to ensure credentials are collected before connectivity tests execute.