Agent schema 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

ellipsis:
  kind: agent
  name: nightly-tests
  description: Check the API test suite every night

trigger:
  type: cron
  schedule: '0 2 * * *'

session:
  claude_code:
    prompt: |
      Run the tests in api-repo. Report failures with the test
      name and error. Do not modify code.
    model: claude-sonnet-5
  environment:
    repositories:
      - name: api-repo
  permissions:
    github:
      permissions: read_only
  budget:
    session: 3
    day: 10
    week: 50

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

React to a pull request

ellipsis:
  kind: agent
  name: check-api-changes

trigger:
  type: react
  pull_request:
    on: [pushed]
    repositories: [api-repo]
    paths: ['src/routes/**']
    draft: false

session:
  claude_code:
    prompt: |
      Check the changed API routes for missing test coverage.
      Add focused regression tests where needed, run them,
      and report the results.
  environment:
    repositories:
      - name: api-repo
  budget:
    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

ellipsis:
  kind: agent
  name: classify-change

input:
  json_schema:
    type: object
    properties:
      description:
        type: string
    required: [description]
    additionalProperties: false
  message: 'Classify this change: {{description}}'

session:
  claude_code:
    prompt: |
      Classify the requested change as bugfix, feature, or maintenance.
      Explain the classification in one sentence.
    model: claude-opus-5
  output:
    json_schema:
      type: object
      properties:
        category:
          type: string
          enum: [bugfix, feature, maintenance]
        reason:
          type: string
      required: [category, reason]
      additionalProperties: false
  budget:
    session: 1

Run 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:

session:
  codex:
    prompt: Use the release-checks skill to review the release.
    model: gpt-6-sol
  skills:
    - path: skills/release-checks
      repository:
        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.

Identity and triggers

Field	Meaning
`ellipsis.name`	Agent name, unique within the account
`ellipsis.description`	Description shown in the dashboard
`ellipsis.enabled`	Whether the agent is active
`ellipsis.metadata`	`labels` and `annotations` for your own use
`trigger`	One cron or react trigger; omit to run only on demand
`input.json_schema`	Schema the run's `input` must match
`input.message`	First-message template; omit to send the input as JSON

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.

Session settings

Field	Meaning
`session.claude_code` or `session.codex`	Exactly one; chooses Claude Code or Codex
`session.claude_code.prompt` or `session.codex.prompt`	The task
`session.claude_code.model` or `session.codex.model`	Model ID; see Models
`session.claude_code.effort` or `session.codex.effort`	Reasoning effort; see Claude Code or Codex
`session.claude_code.max_turns`	Most turns the agent takes on each message
`session.environment`	Saved environment name or inline environment
`session.permissions`	GitHub and Ellipsis access
`session.budget`	Spend limits in dollars
`session.conversation.interactive`	Whether the session stays open for follow-ups; default `true`
`session.metadata`	String keys and values stored on every session
`session.output.json_schema`	Schema for the final JSON result
`session.skills`	Skills from a repository (Codex)

See Models, the Environment schema reference, and Permissions.

Budgets

session:
  claude_code: {}
  budget:
    session: 5
    day: 20
    week: 100
    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.