agent.yaml Reference

The agent config file declares an agent's runtime intent: which model to use, which plugins to load, and the runtime constraints.

# Full Example

▓ agent.yaml

version: "1"
agent:
  name: research-bot
model:
  provider: anthropic
  model: claude-sonnet-5
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
  reasoning:
    enabled: true
    budgetTokens: 4096

# version

Required. Only "1" is supported for now.

# agent

Optional block. When omitted, the display name defaults to the agent id. When present, name is required.

Field	Type	Description
name	string	Agent display name (required inside the agent block)

# model

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

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

# plugins

An array of plugin declarations. Three formats are 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"
    version: "0.1.0"
    config:
      key: value

A short name like sandbox-e2b resolves to @parel/sandbox-e2b.

# Model Providers

Provider	Adapter	Description
openai	OpenAI Chat Completions	Managed or BYOK OpenAI credential provider
openai-responses	OpenAI Responses	For Responses API models and replay artifacts
anthropic	Anthropic Messages	For the Claude Messages API
openai-compatible	OpenAI Chat Completions shape	Requires config.baseUrl; the BYOK key is looked up via config.credentialProvider or openai-compatible
anthropic-compatible	Anthropic Messages shape	Requires config.baseUrl; the BYOK key is looked up via config.credentialProvider or anthropic-compatible

▓ compatible endpoint

model:
  provider: openai-compatible
  model: llama-3.3-70b
  config:
    baseUrl: https://api.groq.com/openai/v1
    credentialProvider: groq

# Available Plugins

Name	Type	Description
sandbox-e2b	Sandbox	Provides 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
subagent	Tool	Synchronous and async child-agent delegation

When a sandbox plugin is declared but no security plugin is, the runtime auto-injects security-basic (command blocklist + secret redaction) as a safety net; bring your own security plugin to keep full control.

# runtime

Field	Type	Default	Description
maxSteps	number	200	Maximum steps per turn; force-stop beyond this
maxTurns	number	∞	Maximum turns per session
checkpointInterval	number	10	Step interval for automatic checkpoints
maxParallelToolCalls	number	8	Maximum tool calls executed in parallel within a step
toolResultMaxBytes	number	65536	Maximum bytes of a single tool result; truncated beyond (64 KiB)
durability	string	event-sourced	"event-sourced" or "ephemeral"
reasoning.enabled	boolean	-	Enable model reasoning controls when the provider supports them
reasoning.budgetTokens	number	-	Token budget when reasoning is enabled

# Secrets and Provider Keys

Don't put secret values in agent.yaml. Any plugin config field (including nested ones) and model.config can be written as a ${NAME} reference; PAREL resolves the value from the encrypted secret store at session start, and the config text only ever keeps the ${NAME} form.

▓ agent.yaml

plugins:
  - sandbox-e2b:
      apiKey: ${E2B_API_KEY}

Set values in one of two ways: store them explicitly with parel secrets set E2B_API_KEY (org-scoped by default; --agent overrides for a single agent), or just export E2B_API_KEY=… and let parel deploy encrypt and upload the referenced values. Model provider credentials (Anthropic, OpenAI, or compatible endpoints) are a separate chain — via provider keys (BYOK) or platform billing.

A reference is a whole-value match (${NAME} as a field's entire value); it does not do string interpolation — https://${HOST}/x is not expanded. A field declared as a secret in a plugin manifest that is written as a plaintext literal is rejected at deploy (400).