Define agents as files

Agents can be defined as files with structured metadata and a system prompt. This makes them shareable, reviewable, and version-controllable — useful for teams that want agents in git rather than only in the API.

Markdown with front matter

The most readable format. The YAML front matter holds metadata; the body becomes the system prompt.

---
name: "hackernews-reader"
description: "An agent that browses HackerNews autonomously"
tags:
  - demo
  - hackernews
capabilities:
  - web_fetch
  - current_time
  - session_file_system
---
You are a HackerNews reader agent. You autonomously browse
Hacker News to find interesting stories, read discussions,
and research authors.

Import via the SDK:

with open("hackernews-reader.md") as f:
    agent = await client.agents.import_agent(f.read())

Or via the CLI:

everruns agents create -f hackernews-reader.md

TOML

name = "research-assistant"
description = "Helps with research tasks"
system_prompt = """
You are a helpful research assistant.
Always cite your sources.
"""
tags = ["research", "assistant"]

[[capabilities]]
ref = "current_time"

[[capabilities]]
ref = "web_fetch"

If ./agent.toml exists in the current directory and you don’t pass inline flags, everruns agents create picks it up automatically.

YAML

name: "research-assistant"
description: "Helps with research tasks"
system_prompt: |
  You are a helpful research assistant.
  Always cite your sources.
capabilities:
  - ref: current_time
    config: {}
  - ref: web_fetch
    config: {}
tags:
  - research

Shorthand form (capability IDs only):

capabilities:
  - current_time
  - web_fetch

The long form (ref + config) is required for per-agent capability configuration.

JSON

JSON is supported for tooling that generates agent definitions programmatically. It has no special features over TOML/YAML — pick the format your team prefers.

everruns agents create -f agent.json

Seed sessions with initial files

To pre-populate the session workspace, either pass --initial-files-dir on the CLI or use the initial_files front matter field:

---
name: "a11y-audit"
capabilities:
  - daytona
initial_files:
  - .
  - .agents/*
---
Run axe-core audits...

Entries can be:

. — the entire current directory (non-hidden files plus .agents/).
A subdirectory — walked recursively. Glob suffixes like /* are stripped.
A single file path.

Hidden files outside .agents/ are skipped; symlinks outside the base directory are rejected; binary files are ignored.

Update vs. create

everruns agents update accepts the same file formats. Passing an explicit <id> positional disables implicit agent.toml selection so you can update a different agent from the same directory.