How to Define an Ellipsis Agent with YAML Config Files

You define an Ellipsis agent by committing a YAML file (for example agent.yaml, standup-automator.yaml, or triage-issues.yaml) into your repository. The file declares the agent's name, description, trigger, session harness and model, prompt, environment, repositories, hooks, and budget. Ellipsis reads that config and runs the agent in its managed cloud infrastructure, so you never provision compute or wire up permissions yourself. This works if you have the Ellipsis app installed on GitHub and are comfortable editing repo files; the examples below follow the structure shown in Ellipsis's own documentation.

The core shape of an agent file

Every agent file starts with an ellipsis block and then describes what the agent is and when it runs. The fields you'll use most:

Step 1: Create the file and name the agent

Add a YAML file to your repo. The ellipsis key is the root, and kind: agent tells Ellipsis this is an agent definition rather than something else.

ellipsis:
  kind: agent
  name: triage-issues
  prompt: Label new issues and find duplicates.
  environment:
    repositories:
      - name: web-repo

The name is how you and the platform refer to the agent; prompt is the actual task. The environment.repositories list scopes which repos the agent can touch.

Step 2: Choose a trigger

Triggers decide when the agent runs. Two forms appear in the docs:

Cron (scheduled): run on a fixed schedule.

trigger:
  type: cron
  schedule: "30 8 * * 1-5"

This fires at 08:30 on weekdays — the pattern used by the standup-automator example, which posts a daily digest of merged PRs, pending reviews, and failing CI to Slack.

React (event-driven): run in response to repository activity such as a pushed pull request.

trigger:
  type: react
  pull_request:
    on: [pushed]
  repositories: [api-repo]

The check-api-changes example uses this to inspect changed API routes for missing test coverage whenever a PR is pushed.

Step 3: Pick a harness and model

The session block selects the coding harness and the model. Switching between them is a one-line change — you don't rebuild the agent.

session:
  claude_code:
    model: claude-opus-5-5

To move to a different harness and model, swap the block:

session:
  codex:
    model: gpt-6-sol

The rest of the file (name, prompt, environment) stays the same. This is the mechanism behind Ellipsis's "any agent, any model" claim — the config, not the code, decides what runs.

Step 4: Configure the environment and hooks

The environment block controls what the agent has access to and any setup it needs before running. repositories lists the repos; hooks run shell commands at defined points, such as after checkout.

environment:
  repositories:
    - name: api-repo
  hooks:
    after_checkout: |
      cd api-repo

Use hooks for setup steps your agent needs before it starts its task — installing dependencies, checking out a branch, or preparing a working directory.

Step 5: Set a budget

The budget block caps how much a session can consume, so a runaway agent doesn't keep running.

budget:
  session: 2

Set this deliberately for scheduled or event-driven agents that could otherwise fire repeatedly.

A complete example

Putting the pieces together, a scheduled digest agent looks like this:

ellipsis:
  name: standup-automator
  description: Posts a daily standup digest to Slack
  trigger:
    type: cron
    schedule: "30 8 * * 1-5"
  session:
    claude_code:
      model: claude-opus-4-8
  prompt: |
    Each weekday, summarize yesterday's merged PRs, the reviews still
    waiting, and any failing CI, then post the digest to #engineering
    and @ the right owners.
  budget:
    session: 2

How to verify it works

After committing the file, confirm the agent is registered and triggered as expected. The docs reference an API surface for this — POST /v1/agents to create an agent, POST /v1/agents/{id}/sessions to start a session, and POST /v1/sessions/{id}/messages to message a running session. Use these to check that your YAML parsed into an agent and to start a test session before relying on the trigger.

Common sticking points

• Trigger type mismatch. A cron trigger needs a valid schedule; a react trigger needs the event (for example pull_request.on) and the repos to watch. Mixing fields from both will fail.
• Repo scope. If the agent can't see a repository, check that it's listed under environment.repositories — the trigger's repositories and the environment's list serve different purposes.
• Hooks failing silently. A broken after_checkout command stops the agent before its prompt runs. Test the command locally first.
• Missing budget. Scheduled agents without a budget.session cap can accumulate sessions; set one for anything that fires on a timer.

Once the file is committed and the agent is registered, Ellipsis handles the infrastructure, permissions, logging, and budgets — your job is keeping the YAML accurate as the agent's task changes.