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

name: hello-world
version: 0.1.0
display_name: Hello World
description: A simple greeting agent.
author: your-username
license: MIT
model:
  default: anthropic/claude-sonnet

Full schema

Top-level fields

Field	Type	Required	Description
name	string	Yes	Unique identifier. Lowercase, hyphens allowed. Must be unique in the marketplace.
version	string	Yes	Semantic version (MAJOR.MINOR.PATCH).
display_name	string	Yes	Human-readable name shown in the UI and marketplace.
description	string	Yes	One-line summary (max 160 characters).
author	string	Yes	Marketplace username or organisation.
license	string	Yes	SPDX license identifier (e.g. MIT, Apache-2.0).
model	object	Yes	LLM configuration.
routing	object	No	How the orchestrator routes messages to this agent.
capabilities	list	No	Capabilities this agent can invoke.
memory	object	No	Session and long-term memory settings.
events	object	No	Event subscriptions and emission rules.
tags	list[string]	No	Marketplace discovery tags.

model

model:
  default: anthropic/claude-sonnet
  fallback: openai/gpt-4o
  temperature: 0.7
  max_tokens: 4096

Field	Type	Required	Description
default	string	Yes	Provider/model identifier. The user’s configured provider takes precedence.
fallback	string	No	Used when the default is unavailable.
temperature	float	No	Sampling temperature (0.0–2.0). Default 0.7.
max_tokens	int	No	Maximum response tokens. Default 4096.

capabilities

Capabilities are listed by reference. They can point to a local directory or a remote Docker image.

Local capability

capabilities:
  - name: weather
    path: ./capabilities/weather

Remote image

capabilities:
  - name: weather
    image: ghcr.io/selu-bot/cap-weather:1.2.0

Field	Type	Required	Description
name	string	Yes	Identifier used in tool calls.
path	string	No	Relative path to a local capability directory.
image	string	No	Docker image URI. Used if path is not set.
parameters	object	No	Static key-value config passed to the capability at startup.

routing

routing:
  mode: inline          # inline | dedicated
  triggers:
    - mention: "@weather"
    - intent: weather_query
  priority: 10

See Routing & Sessions for full details.

memory

memory:
  session_ttl: 3600       # seconds
  max_history: 50         # messages
  long_term: true         # enable vector-backed long-term memory

Validation

Run selu validate in your agent directory to check your agent.yaml against the schema before publishing.

selu validate ./my-agent