Agent schema reference

Complete agent examples, typed inputs and outputs, and field reference.

An agent file has 4 top-level blocks: ellipsis, optional trigger, optional input, and session. Set ellipsis.kind to agent. Unknown fields fail validation. See Agents for how files deploy and run.

Scheduled test checks

1
ellipsis:
2
kind: agent
3
name: nightly-tests
4
description: Check the API test suite every night
5
6
trigger:
7
type: cron
8
schedule: '0 2 * * *'
9
10
session:
11
claude_code:
12
prompt: |
13
Run the tests in api-repo. Report failures with the test
14
name and error. Do not modify code.
15
model: claude-opus-5-5
16
environment:
17
repositories:
18
- name: api-repo
19
permissions:
20
github:
21
permissions: read_only
22
budget:
23
session: 3
24
day: 10
25
week: 50

Every night at 02:00 UTC, a session runs the tests and reports failures without changing code.

React to a pull request

1
ellipsis:
2
kind: agent
3
name: check-api-changes
4
5
trigger:
6
type: react
7
pull_request:
8
on: [pushed]
9
repositories: [api-repo]
10
paths: ['src/routes/**']
11
draft: false
12
13
session:
14
claude_code:
15
model: claude-opus-5-5
16
prompt: |
17
Check the changed API routes for missing test coverage.
18
Add focused regression tests where needed, run them,
19
and report the results.
20
environment:
21
repositories:
22
- name: api-repo
23
budget:
24
session: 5

Each push to a non-draft pull request in api-repo that changes src/routes/ starts a session. The trigger decides which events match; the environment decides which repositories are checked out.

Typed input and output

1
ellipsis:
2
kind: agent
3
name: classify-change
4
5
input:
6
json_schema:
7
type: object
8
properties:
9
description:
10
type: string
11
required: [description]
12
additionalProperties: false
13
message: 'Classify this change: {{description}}'
14
15
session:
16
claude_code:
17
prompt: |
18
Classify the requested change as bugfix, feature, or maintenance.
19
Explain the classification in one sentence.
20
model: claude-opus-5-5
21
output:
22
json_schema:
23
type: object
24
properties:
25
category:
26
type: string
27
enum: [bugfix, feature, maintenance]
28
reason:
29
type: string
30
required: [category, reason]
31
additionalProperties: false
32
budget:
33
session: 1

Start it with {"input":{"description":"Reject expired reset tokens"}} instead of a prompt. Read the validated result from GET /v1/sessions/{session_id}/output.

Structured output works with the models that list it in GET /v1/account/models.

Add a Codex skill

A skill is a directory with a SKILL.md file that gives Codex a reusable procedure and its supporting files:

1
session:
2
codex:
3
prompt: Use the release-checks skill to review the release.
4
model: gpt-6-sol
5
skills:
6
- path: skills/release-checks
7
repository:
8
name: api-repo

SKILL.md needs YAML frontmatter with a description. Ellipsis reads the skill from the session's checkout of that repository, or from its default branch when the repository isn't in the session. A missing or invalid skill fails the session.

A session can have up to 10 skills. Each skill can have up to 50 files, 64 KiB per file, and 512 KiB in total.

Budgets

1
session:
2
claude_code:
3
model: claude-opus-5-5
4
budget:
5
session: 5
6
day: 20
7
week: 100
8
month: 300

Values are US dollars. session caps each session. day, week, and month cap this agent's total spend over the last 1, 7, and 28 days. Handlers take the same fields. Account limits also apply; see Budgets.

Fields

Identifies the file.

One cron or react trigger; omit to start only on demand. See Triggers.

Typed input for sessions you start; see Typed input and output.

The session each run starts.

In input.message, {{field}} inserts a field from the input. Triggered agents can insert event fields the same way. Every reference must exist in the input schema or the trigger's event.

See Models, the Environment schema reference, and Permissions.

On this page

Scheduled test checksReact to a pull requestTyped input and outputAdd a Codex skillBudgetsFields
Schedule a demo