agent.yaml Reference

The agent config file declares everything about your agent: what model to use, which plugins to load, and runtime constraints.

# Full Example

▓ agent.yaml

version: "1"
agent:
  name: research-bot
  model: "anthropic:claude-sonnet-4-20250514"
  system: "You are a research assistant."
plugins:
  - sandbox-e2b
  - memory-rolling-summary
  - security-basic
  - budget-cap:
      daily: 25
  - plugin: "@parel/channel-api"
    config:
      webhook: "https://hooks.example.com/notify"
runtime:
  maxSteps: 200
  maxTurns: 50
  checkpointInterval: 10

# version

Required. Currently only "1" is supported.

# agent

Field	Type	Description
name	string	Agent display name (required)
model	string	Sugar: "provider:model-id" — expands to model plugin
system	string	Sugar: system prompt — expands to system-static plugin

# plugins

Array of plugin declarations. Three formats supported:

▓ formats

plugins:
  # String shorthand — no config
  - sandbox-e2b

  # Object shorthand — with config
  - budget-cap:
      daily: 25

  # Full form
  - plugin: "@parel/model-anthropic"
    config:
      model: "claude-sonnet-4-20250514"
      temperature: 0.7

Short names like sandbox-e2b resolve to @parel/sandbox-e2b.

# Available Plugins

Name	Type	Description
model-anthropic	Model	Claude models via Anthropic API
model-openai	Model	GPT/o-series via OpenAI API
sandbox-e2b	Sandbox	Isolated cloud VMs via E2B
sandbox-local	Sandbox	Local execution (dev only)
memory-rolling-summary	Memory	LLM-compressed context window
security-basic	Guard	Command blocklist + secret redaction
budget-cap	Guard	Daily cost / per-request step limits
channel-api	Channel	REST webhook notifications
system-static	System	Static system prompt
steering-immediate	Steering	Mid-turn user intervention

# runtime

Field	Type	Default	Description
maxSteps	number	200	Max steps per turn before force-stop
maxTurns	number	∞	Max turns per session
checkpointInterval	number	10	Steps between auto-checkpoints
durability	string	event-sourced	"event-sourced" or "ephemeral"

# Environment Variables

Use ${VAR_NAME} syntax to reference environment variables:

▓ agent.yaml

plugins:
  - plugin: "@parel/model-openai"
    config:
      apiKey: "${OPENAI_API_KEY}"

Missing env vars will throw at deploy time — never at runtime.