agent.yaml Schema

Every Selu agent is defined by an agent.yaml file at the root of the agent’s project directory. This file tells the orchestrator how to run the agent, which model to use, and what capabilities it has access to.

Schema reference

Field	Type	Required	Description
apiVersion	string	Yes	Schema version. Currently selu.io/v1.
kind	string	Yes	Must be Agent.
metadata.name	string	Yes	Unique identifier for the agent. Lowercase, alphanumeric, hyphens allowed.
metadata.version	string	Yes	SemVer version string (e.g. 1.0.0).
metadata.description	string	No	Short human-readable description shown in the marketplace.
metadata.author	string	No	Author name or organization.
metadata.license	string	No	SPDX license identifier (e.g. MIT, Apache-2.0).
spec.model.provider	string	Yes	LLM provider: openai, anthropic, bedrock, or ollama.
spec.model.name	string	Yes	Model identifier (e.g. gpt-4o, claude-sonnet-4-20250514).
spec.model.temperature	float	No	Sampling temperature. Default 0.7.
spec.model.maxTokens	int	No	Maximum tokens per response. Default 4096.
spec.systemPrompt	string	Yes	The system prompt that defines the agent’s personality and instructions.
spec.capabilities	list	No	List of capability references the agent may invoke.
spec.capabilities[].name	string	Yes	Capability name as declared in the capability’s manifest.yaml.
spec.capabilities[].version	string	No	Version constraint (e.g. ^1.0.0). Defaults to latest.
spec.capabilities[].config	map	No	Key-value config passed to the capability at runtime.
spec.runtime.image	string	No	Custom Docker image. Defaults to the official Selu agent runtime.
spec.runtime.resources.cpu	string	No	CPU limit (e.g. 500m). Default 250m.
spec.runtime.resources.memory	string	No	Memory limit (e.g. 512Mi). Default 256Mi.
spec.channels	list	No	Channels the agent listens on. Values: web, imessage, telegram.

Full example

agent.yaml

apiVersion: selu.io/v1
kind: Agent
metadata:
  name: research-assistant
  version: "1.2.0"
  description: An agent that searches the web and summarizes findings.
  author: selu-community
  license: MIT

spec:
  model:
    provider: anthropic
    name: claude-sonnet-4-20250514
    temperature: 0.5
    maxTokens: 8192

  systemPrompt: |
    You are a research assistant. When the user asks a question,
    search the web for relevant sources, summarize your findings,
    and cite your sources with URLs.

  capabilities:
    - name: web-search
      version: "^2.0.0"
    - name: file-writer
      config:
        outputDir: /data/reports

  runtime:
    image: ghcr.io/selu-platform/agent-runtime:latest
    resources:
      cpu: "500m"
      memory: "512Mi"

  channels:
    - web
    - telegram

Validation

Run selu agent validate from the directory containing your agent.yaml to check for schema errors before publishing. The CLI validates required fields, version format, and capability references against the local registry.

Notes

• The metadata.name field must be unique within your Selu instance. If you publish to the marketplace, it must be globally unique.
• Capability version constraints follow the same semantics as npm SemVer ranges.
• Resource limits are enforced by Docker. If an agent exceeds its memory limit, the container is restarted automatically.