Agents

​

The questions an agent file answers

​

Anatomy of an agent file

# Who it is
name: issue-fixer
harness: claude-code
model:
  provider: anthropic
  id: claude-sonnet-5
reasoningEffort: high
identity:
  displayName: Issue Fixer
  username: issue-fixer
  description: Fixes issues labeled auto-fix and opens pull requests.

# Where it runs: an inline environment compiles into its own resource
environment:
  name: node-runtime
  image:
    kind: preset
    name: node24
  resources:
    memoryMB: 8192
  steps:
    - RUN npm install -g tsx

# What it can touch
env:
  SENTRY_AUTH_TOKEN:
    $secret: sentry-auth-token
    optional: true
mounts:
  - kind: git
    repository: acme/widgets
    mountPath: /workspace/widgets
    ref: main
    auth:
      kind: githubApp
      capabilities:
        contents: write
        pullRequests: write
workingDirectory: /workspace/widgets
tools:
  auto:
    kind: local
    implementation: auto
  github:
    kind: github   # omitting `tools:` grants the curated default allowlist

# What it knows at start
systemPrompt: |
  You fix bugs in acme/widgets. Work from the mounted checkout on a fresh
  branch, keep changes minimal, and open a pull request that references the
  originating issue. Address review feedback on your own PR when it arrives.
displayTitle: "Fix #{{github.issue.number}}: {{github.issue.title}}"

# Session policy: archive after a day of inactivity
session:
  archiveAfterInactive:
    seconds: 86400

# PRs this agent opens auto-bind to this session; the platform holds the
# binding until the closed-PR trigger below releases it.
bindings:
  github.pull_request:
    lifecycle: held
    bind: onAttributedEvent

# When it runs, and how events route
triggers:
  - event: github.issue.labeled
    connection: github-acme
    where:
      $.github.label.name: auto-fix
    message: |
      Issue #{{github.issue.number}} was labeled auto-fix: {{github.issue.title}}
      {{github.issue.htmlUrl}}

      Reproduce it, fix it on a branch, and open a pull request.
    routing:
      kind: spawn
      bind:
        target: github.issue
  - events:
      - github.issue_comment.created
      - github.pull_request_review.submitted
    connection: github-acme
    where:
      $.github.auto.authored: false
    message: |
      New feedback on your PR #{{github.pullRequest.number}}. Read it and
      address anything actionable.
    routing:
      kind: bind
      target: github.pull_request
      onUnmatched: drop
  - event: github.pull_request.closed
    connection: github-acme
    message: |
      Your PR #{{github.pullRequest.number}} was merged or closed
      (merged={{github.pullRequest.merged}}). Wrap up and archive this session.
    routing:
      kind: bind
      target: github.pull_request
      onUnmatched: drop
      release: true

• The inline environment becomes its own resource. The compiler splits it out and leaves only the environment’s name on the agent spec, so several agents can converge on identical inline environments — identical content under the same name deduplicates; conflicting content fails the apply.
• $secret references never put values in YAML. SENTRY_AUTH_TOKEN resolves from the project’s envelope-encrypted secret store at session launch; optional: true means a missing secret omits the variable instead of failing the launch.
• connection: github-acme names the GitHub connection whose webhook events this trigger consumes. GitHub Sync injects the right connection name as a context variable when you use managed templates, so most real files write connection: "{{ $githubConnection }}".
• where filters run before routing. $.github.label.name: auto-fix means only that label wakes the agent; $.github.auto.authored: false keeps the agent from reacting to comments auto itself posted. All clauses in a where block AND together.
• Templates render against the event payload. {{github.issue.number}} in message and displayTitle resolves from the normalized event; a missing path renders as an empty string.
• The spawn trigger binds at birth. bind: { target: github.issue } records that this session owns that issue. The bindings.github.pull_request block then auto-binds any PR the session opens (bind: onAttributedEvent), and lifecycle: held prevents the session from unbinding or self-archiving while the PR is open — the closed-PR trigger’s release: true is what frees it. Declaring lifecycle: held requires at least one bind-routed trigger on that target with release: true; the compiler enforces the pair.
• onUnmatched: drop silences bind-routed events whose subject has no bound session (for example, review comments on a PR this agent did not open).

​

Identity and presence

​

Composition: imports, fragments, templates

• imports: pulls in other documents — relative paths to fragments under .auto/fragments/, or managed-template specifiers like @auto/agents@latest/pr-review.yaml. Imports merge in listed order, remove: directives prune named tools/triggers/env entries from the merged result, and the document’s own fields merge last and win.
• variables: declared on the entry document substitute {{ $name }} tokens inside imported content, so one fragment serves many repositories.
• Shared environments live in fragments: this repository’s own agents import .auto/fragments/environments/agent-runtime-base.yaml rather than repeating the runtime definition.

​

From file to running agent

• The agent resource is versioned by apply, but sessions snapshot it at creation. Every session copies the agent spec, its environment, and its tool wiring at spawn time; a later apply changes future sessions, never in-flight ones.
• An agent is passive until an event or a person wakes it. Applying an agent creates no session. Sessions come from triggers firing, from a person starting one in the web app, or from another agent calling auto.sessions.spawn — the subject of sessions.

​

Where to go next