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:
  provider: anthropic
  model: claude-sonnet-4-20250514
plugins:
  - system-static:
      prompt: "You are a research assistant."
  - sandbox-e2b
  - memory-rolling-summary
  - security-basic
  - budget-cap:
      max_usd: 25
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

Required. Selects the builtin model provider adapter and native provider model id.

Field	Type	Description
provider	string	"openai", "openai-responses", or "anthropic"
model	string	Provider-native model id
config	object	Optional provider adapter config, such as baseUrl

# plugins

Array of plugin declarations. Three formats supported:

▓ formats

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

  # Object shorthand — with config
  - budget-cap:
      max_usd: 25
      max_turns: 50

  # Full form — name any package explicitly (e.g. a third-party plugin)
  - plugin: "@scope/third-party-plugin"
    config:
      key: value

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

# Model Providers

Provider	Adapter	Notes
openai	OpenAI Chat Completions	Supports OpenAI-compatible baseUrl config
openai-responses	OpenAI Responses	Use for Responses API models and replay artifacts
anthropic	Anthropic Messages	Use for Claude Messages API

# Available Plugins

Name	Type	Description
sandbox-e2b	Sandbox	Isolated cloud VMs via E2B
memory-rolling-summary	Memory	LLM-compressed context window
security-basic	Guard	Command blocklist + secret redaction
budget-cap	Guard	Session cost / turn limits
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"

# Secrets and Provider Keys

Do not put provider API keys in agent.yaml. Add Anthropic, OpenAI, and E2B keys in Console > Settings; PAREL injects them into the matching model provider and sandbox plugin at session start.

${VAR_NAME} interpolation is not performed for deployed configs. Use workspace provider keys or plugin secrets instead.