Agents

An agent saves a prompt, an environment, permissions, and a budget. Each run starts a new session. A trigger makes it run automatically.

Define an agent

ellipsis:
  kind: agent
  name: test-repair

session:
  claude_code:
    prompt: |
      Run the tests in api-repo. Fix one failing test without
      weakening its assertions. Run the affected tests again
      and open a pull request with the change and test results.
    model: claude-sonnet-5
  environment:
    repositories:
      - name: api-repo
  budget:
    session: 5

This agent fixes one failing test and opens a pull request. It has no trigger, so it runs only when you start it.

Deploy from git

Commit a .yaml or .yml file with ellipsis.kind: agent anywhere under .ellipsis/ on the default branch. It appears on the dashboard's Agents page. Your organization can also keep these files in a repository named .ellipsis.

If an update is invalid, the last valid version keeps running and the agent's page shows the error. Deleting the file disables the agent.

Create through the API

POST /v1/agents creates an agent without a repository file. Send the same fields as JSON under agent.

Each agent is edited in one place: its git file or the API. Use link to move an API-created agent into git, or unlink to edit a git-managed one through the API.

Run an agent

Choose Run on its dashboard page, or start it through the API:

curl https://api.ellipsis.dev/v1/agents/test-repair/sessions -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" -H "Content-Type: application/json" -d '{}'

It runs as written, and its session stays open for follow-ups. If it declares input, send input in the body. To change settings for one run, see Override settings for a run.

Override settings for a run

A run starts from the agent's session settings. Its request body takes the fields of Start a session plus input: each field you send replaces the agent's value for that field, and each field you leave out keeps it. Lists, maps such as metadata, and environment are replaced whole, never merged.

This agent sets a model, prompt, environment, budget, and metadata:

ellipsis:
  kind: agent
  name: repo-summary

session:
  claude_code:
    model: claude-sonnet-5
    prompt: Summarize api-repo.
  environment: api-environment
  budget:
    session: 2
    day: 10
  metadata:
    team: platform

Started with an empty body, repo-summary runs Claude Sonnet 5 in api-environment with its saved prompt, stops at $2, and sets the session's metadata to team: platform. The day limit caps the agent's total spend at $10 over the last day, and the session stays open for follow-ups.

Replace the prompt for one run; the model, environment, budget, and metadata stay as the file sets them:

{
  "claude_code": {
    "prompt": "Focus on the tests."
  }
}

Set the cap for one run to $5; the day limit still applies. A request's budget takes only session, and day, week, or month returns 422:

{
  "budget": {
    "session": 5
  }
}

Replace the metadata; the session gets exactly these keys, and team is not kept:

{
  "metadata": {
    "ticket": "ENG-42"
  }
}

Run in other repositories by sending a whole environment; api-environment is not used, and nothing is merged into it:

{
  "environment": {
    "repositories": [
      {
        "name": "api-repo"
      },
      {
        "name": "web-repo"
      }
    ]
  }
}

Scheduled and event-triggered runs use the same settings, so they stay open for follow-ups too, and anyone with write access to sessions can message a scheduled run because it has no owner. Set conversation.interactive to false, in the file or in a run's body, to run once:

session:
  conversation:
    interactive: false

Add a trigger

trigger:
  type: cron
  schedule: '0 9 * * 1'

This runs every Monday at 09:00 UTC. An agent has at most one trigger. See Triggers for schedules and events, or the Agent schema reference for complete examples.

Handlers

Handlers answer @ellipsis mentions in GitHub, Slack, and Linear, and investigate Sentry alerts. Each service has one handler file (github.yaml, slack.yaml, linear.yaml, or sentry.yaml) at the root of your organization's .ellipsis repository. Its session block works like an agent's, including budgets.

Open Handlers in the dashboard to see each handler's file, sync status, sessions, and cost, or list them with GET /v1/handlers.