Agents
Status: Accepted on 2026-10-28, revised on 2026-10-29.
An agent is what people talk to: the pull-request agent reviews a pull request, answers
a question about it and fixes it. One file, agents/<name>/agent.yaml, defines an agent:
- its defaults: the model, prompts, sandbox and credentials of every step;
- its triggers: which work items start it, and at which step;
- its steps: each step's request and overrides, and which step follows each outcome.
The code defines the building blocks an agent file names:
- Tools, which an agent calls to write to the subject, such as
github_post_review. - Activities, which a step runs without a model, such as
github_classify_intent.
Each tool and activity that ends a step declares the outcomes it can return. A rubric is a YAML file in the agent's own directory. It lists the yes-or-no questions that a rubric step asks TypeSafe's Jev.
| Term | Meaning |
|---|---|
| agent | One agent.yaml, with its defaults, triggers and steps |
| step | One unit of an agent's work. It runs an agent loop, an activity or a rubric. |
| agent loop | The model's loop of calls and tool calls inside a step |
| agent run | One execution of an agent, from the trigger that starts it to its end |
| step run | One step's execution in an agent run |
| session | The workflow for one subject, such as a pull request, which runs every agent run on it |
The session workflow runs agent runs. An agent run is a loop in the subject's session workflow, so each step uses the session's sandboxes, conversations and run budget.
An agent file
The agent's fields
| Field | Meaning |
|---|---|
name, description | The agent's name, which is its directory's name, and what it does |
enabled_by_default | Whether every session runs it. SessionConfig.agents names the agents a session runs in addition. |
model, model_settings, max_model_calls | The model of every agent step, the keyword arguments bound to it, and the most model calls one step run makes |
max_minutes | The minutes after which a step run is told to finish. Default 60. |
instructions | The files of the system prompt, joined in order |
prompt | The prompt template of every agent step. A step's request fills its $request. |
skills_prompt, memory_prompt | Templates that replace Deep Agents' description of skills and of the repository's instruction files |
read_limit | The lines a read_file call returns when it passes no limit |
sandbox, repo_context, plugin_pins | The sandbox, and the repository context the agent loads |
settings | Defaults for the settings the agent's tools read. A repository overrides them in .auto-swe/config.yaml, under the agent's name. |
tools | The tools of every step |
credentials, allow_sandbox_writes | What the sandbox's commands can reach. They are the most any step may get. |
mcp_servers | The MCP servers whose tools every step can call |
triggers | The work items that start the agent. Each trigger matches type, event, actions and when, names the step it starts, and may set request. |
steps | The agent's steps, by name |
configuration.md describes the fields that are not about steps in full.
A step's fields
A step runs an activity, a rubric or an agent loop with the agent's defaults. An agent step may set these fields, and nothing else:
| Field | Effect |
|---|---|
request | What the step asks for. It fills the prompt's $request. A trigger's request replaces it for the step that the trigger starts. |
instructions | Files appended to the agent's instructions |
tools | Tools added to the agent's tools |
model, model_settings, max_model_calls, max_minutes | Replace the agent's |
settings | Replace the agent's settings that it names. The repository's .auto-swe/config.yaml overrides apply after them. |
credentials | Narrow the agent's credentials: each grant is the agent's grant or its read-only grant |
conversation | The name of the conversation the step continues and saves. Without it, the step starts from its prompt alone, and its conversation is not kept. |
on | The next step for each outcome, or end |
max_rounds, after_max_rounds | How many times one agent run may enter this step, and the step it enters instead after that |
An activity step sets activity and only on, max_rounds and after_max_rounds.
A rubric step sets rubric and state, and only on, max_rounds and
after_max_rounds besides. Rubric steps
describes:
- the rubric file;
- how code decides the step's outcome;
- how later steps read the step's explanation.
The paths in instructions, prompt, skills_prompt, memory_prompt and rubric are
relative to the agent's directory. Prompt files that more than one agent uses live in
agents/_shared/, which the loader does not load as an agent: the pull-request agent
and the implementation agent's review step both use ../_shared/review-procedure.md and
../_shared/review-rules.md.
Conversations
The session keeps each agent's named conversations. A step with conversation: build
starts from the agent's build conversation in this session, when the session has one,
and saves its own conversation as build when it ends. Several steps can share a
conversation, so fix and open-pr can build on what implement did while review,
which sets none, starts fresh each time.
How the session runs an agent run
A work item is only an outside event. For a work item, the session matches the triggers of the agents it runs. For each agent with a matching trigger, in name order, it starts an agent run at the step that the trigger names, and runs the agent run to its end:
- Run the step: an agent loop, an activity or a rubric.
- Take the step's outcome, and find the next step in the step's
on. - When the next step has run
max_roundstimes in this agent run, take itsafter_max_roundsinstead. - Run the next step, until the next step is
end.
The session handles one work item at a time, so a work item that arrives during an agent run waits in the queue until the agent run ends. A second trigger for the same agent therefore starts a second agent run after the first, never alongside it.
The session runs the context type's acknowledge activity at two points:
- When a work item that matches an agent's trigger arrives during an agent run, with the
stage
queued. On GitHub the acknowledgement is 👀. - When an agent run starts, before its first step, with the stage
started.
Both acknowledgements come before the context type checks that the sender has write access, so an item the context skips is still acknowledged.
Stopping
When a terminal work item or end_session arrives during an agent run, the session is
stopping. From then on, every tool whose spec sets writes refuses its calls, and tells
the agent that the session is stopping. Commands the agent runs in its sandbox are not
covered: an agent with allow_sandbox_writes can still push. The step run in progress is
not cancelled. When it ends, the agent run ends without running the next step, and the
session handles the queue.
Limits
During an agent run, every other work item waits. A "stop" or "status?" comment is
therefore handled only after the agent run ends, and only a terminal work item or
end_session ends an agent run early. Cancelling the step run in progress, and an intent
the session checks between steps to end an agent run, are possible later additions.
The state of an agent run
An AgentRun is the only state of an agent run in progress:
| Field | Meaning |
|---|---|
agent | The agent's name |
id | The agent run's id, which its records and LangSmith runs carry |
start | The work item that started the agent run |
step | The step that runs now |
rounds | How many times the agent run has entered each step |
data | The data of every outcome so far, each outcome's data merged over the previous |
steps | The steps that have finished, in order |
started_at, usage_at_start, cost_at_start | When the agent run started, and the session's usage and cost_usd counters then. The agent run's spending is what the counters added since. |
A step runs on the starting work item's context, with the agent run's data merged over
the work item's payload. The context type therefore reads an outcome's data as it reads
the payload.
The session continues as new between work items, and also at a step boundary when
Temporal suggests it or the deployment's target version changes. It saves the
AgentRun and the agents its work item matched that had not started. Its next run
resumes the agent run at that step and starts those agents' runs before it handles the
queue.
The session reads the agent files in the load_agents activity, so a replay reads the
agents from the workflow's history. A session continued as new after the target version
changes starts on the new version, and resumes the saved AgentRun at its step name
under that version's agent file. When that agent file no longer has the step, the agent
run ends with a failed lifecycle event.
Outcomes
A step run has an outcome and data. They come from:
-
The step's outcome tool. A tool's spec lists the outcomes it can return, and its activity returns one with its data. For example,
submit_reviewreturnsfindingswith the findings, orpassedwith the review. The rule that picks the outcome is code in the tool, so the model cannot pass a review that has an important finding open. A step has at most one outcome tool. -
The step's activity, for an activity step. Its spec lists its outcomes in the same way.
-
The step's rubric, for a rubric step. The outcome is
passed,rejectedorunsettled, and its data holds the step's explanation asrubric_explanation. -
The session, for an outcome of the step run itself:
Outcome When failedThe step run, its context load or the step's activity raised over_budgetThe session was over its run budget, so no agent loop ran no_outcomeThe agent loop ended without calling its outcome tool The agent run ends on one of these unless the step maps it in
on.
Round caps
A step with max_rounds: N runs at most N times in one agent run. When an outcome leads
to the step an (N+1)th time, the session runs the step that after_max_rounds names
instead. In the implementation agent, fix has max_rounds: 2 and
after_max_rounds: open-pr, so a third review with findings opens the pull request with
the findings still open.
Waiting
The session runs the next step as soon as a step ends, so an agent run does not wait
between steps. To wait for a person, an agent run ends. The session then waits up to
idle_timeout for its next work item, and the person's next comment or label starts an
agent run through a trigger.
The cost of an agent run
The session records each step run and each agent run:
- A
StepRunRecordholds one step run's agent, step, model, tokens, cost and LangSmith run id, and the id of its agent run. - An
AgentRunRecordholds one agent run's steps in order, how it ended, and the total tokens and cost of its step runs and of its activities' model requests.
The agent_run_started and agent_run_finished lifecycle events bracket an agent run,
and agent_run_finished shows its total cost. The question "what did this review cost"
is therefore one number on one record.
In LangSmith, a run named <agent> agent run holds a run named <agent>/<step> step run
for each step, and each step run holds its agent loop. Every one of them has the agent
run's id in its metadata as agent_run_id. After the session continues as new partway
through an agent run, the rest of its step runs are under a second <agent> agent run
with the same agent_run_id.
Load checks
The loader refuses an agent file in which:
- a step's tools or activity declare an outcome that
ondoes not map; onmaps an outcome that the step cannot return;- a trigger, an
onor anafter_max_roundsnames a step that does not exist; - no trigger leads to a step, directly or through other steps;
- a step names an activity, a tool or a file that does not exist;
- a step has more than one outcome tool;
- a step sets
max_roundswithoutafter_max_rounds, or the reverse; - a step's
credentialsgrant more than the agent's; - an activity step or a rubric step sets a field of an agent step;
- a rubric file does not validate, or its Jev model has no price;
- a rubric step's
statenames a field that the context type of one of the agent's triggers does not provide.
It also runs every check of the agent's own fields, such as the model's price and the prompt's fields, against each step as the step runs the agent.
A step whose credentials differ from the agent's runs in a different sandbox, since the session keeps one sandbox per snapshot, set of credentials and egress.
Examples
The implementation agent
agents/implement/agent.yaml
runs the steps plan-check, plan-ready or plan-needs-work, implement, review, fix, open-pr
and link-pr.
The implementation agent describes them. The GitHub tools return
their outcomes and do not call Linear. The link-pr step posts the pull request's link
on the issue and moves the issue to In Review.
One agent run, started by the work item d-1 (the issue labeled), in which the first
review finds what to fix:
| Step | Round | Outcome | Data added |
|---|---|---|---|
plan-check | 1 | passed | rubric_explanation |
plan-ready | 1 | posted | |
implement | 1 | pushed | branch, commit, base_commit |
review | 1 | findings | findings, review |
fix | 1 | pushed | commit |
review | 2 | passed | review |
open-pr | 1 | opened | pull_request_url |
link-pr | 1 | posted |
review starts from its prompt each time, so it never reads the conversation that wrote
the code. fix and open-pr continue the build conversation that implement started.
Every step of the implementation agent has the same snapshot, credentials and egress, so they share one sandbox.
After open-pr, every event on the pull request goes to the pull request's own session,
which runs the pull-request agent.
The pull-request agent
agents/pull-request/agent.yaml
starts at review or review-and-fix on a label, and at the classify activity step on
a mention. Each intent of What a mention asks for
is an outcome of classify. When the classification fails, the mention goes to
review-or-answer.
Every step after classify maps its outcomes to end, or maps none, so each agent run
ends after one agent loop.
One session over a pull request's life:
| When | Work item | What runs | Then |
|---|---|---|---|
| Day 0 | auto-swe:review label | review | The agent run ends, and the session waits |
| Day 0 | A reply to a finding | No step. The session records the feedback. | The session waits |
| Day 1 | @ai-auto-swe fix the null check | classify, then fix | The agent run ends, and the session waits |
| Day 1 | A second fix comment, while fix runs | Gets 👀 as it arrives. Waits in the queue until the first agent run ends, then classify and fix. | The session waits |
| Day 3 | The pull request is merged | No step | The session ends |
Triage
The triage agent has one step, diagnose, and is off by default, so no session runs it.
The DagsterTriage workflow runs that step itself: its budget overflow and prematch run
before any agent, per deployment, which an agent file cannot express.
What an agent file cannot express
An agent file has defaults, triggers, steps, outcome mappings and round caps, and nothing else:
- no conditions or expressions on an outcome;
- no variables;
- no parallel steps;
- no timers, or waits for a specific event;
- no retry policies.
An agent that needs any of these is a workflow written in Python, as DagsterTriage is.
Temporal is the general workflow engine, and the agent file does not duplicate it.
Decisions
Decisions 1, 8, 11, 16, 17 and 18 were revised on 2026-10-29. The agent is the concept people use, and one file per agent replaces the split between agent types and flows.
| # | Decision | Reason | Rejected |
|---|---|---|---|
| 1 | The code defines tools and activities. An agent file defines one agent: its defaults, its triggers and its steps. Revised on 2026-10-29. | The branching was in three places: trigger conditions, tools that built the next work item, and the triage workflow. People talk to an agent, so one file describes all of it. | Tools that build the next work item themselves. Agent types connected by separate flow files. |
| 2 | The session workflow runs each agent run as a loop over its steps. A work item is only an outside event, never a step. | Steps share the subject's sandboxes, conversations and run budget. Temporal is the durable state machine: the workflow's history records each step, so the session does not queue its own steps as events to make them durable. | Each step as a work item in the session's queue. A child workflow per agent run, which would need that state passed to it. A workflow per subject and agent, which gives two agents on one subject two sandboxes and two budgets. A Python workflow per agent, which makes every agent a code change. |
| 3 | A step runs an agent loop or an activity | Classifying a comment and posting a link need no model | Agent steps only |
| 4 | Intent classification is an activity step, and each intent is an outcome | One mention trigger replaces one per intent. Only agents that need classification run it. | Classifying every mention before routing |
| 5 | A step's outcome is on its step run. The outcome tool, the activity or the session sets it. | The rule that picks an outcome stays in code | The model declares the outcome |
| 6 | An agent file has only defaults, triggers, steps, outcome mappings and round caps | Temporal already provides conditions, timers and parallelism | Adding them to the agent file |
| 7 | DagsterTriage stays its own workflow, and runs the triage agent's single step | Its budget overflow and prematch run before any agent, per deployment | Running triage in sessions now |
| 8 | Triggers are in the agent file, and each names the step an agent run starts at. Revised on 2026-10-29. | Only a trigger's step can start an agent run, so an outside event cannot start an agent at a later step | Triggers in a separate flow file |
| 9 | Every outcome a step can return from its tool or activity is mapped, or the agent does not load. The session's own outcomes end the agent run unless mapped. | A missing mapping is found at load time, before a session runs | Ending the agent run on any unmapped outcome |
| 10 | max_rounds and after_max_rounds are on the repeated step | The cap belongs to the loop between steps, not to the review tool | A cap in the review tool's settings |
| 11 | A step's conversation names the conversation it continues and saves. A step without one starts fresh. Revised on 2026-10-29. | One agent continues a conversation in some steps and starts fresh in others. A name lets fix and open-pr continue implement's conversation after review ran in between. | keep_transcript per agent. context: continue of the agent's latest conversation, which would continue review's. Pointing at the step whose conversation to continue. |
| 12 | A step can narrow the agent's credentials and replace its settings, never widen its credentials | The agent states the most any of its steps may get | Steps that widen credentials |
| 13 | A work item that arrives during an agent run waits in the queue until the agent run ends. A terminal work item or end_session makes write tools refuse at once, and ends the agent run at the next step boundary. | A second label or comment is not lost, and two agent runs never change one branch at once. A closed subject gets no more writes, and does not wait for the rest of the agent run. | Refusing the trigger. Holding triggers in a list of their own. Cancelling the step run in progress. |
| 14 | An AgentRun (the agent, the starting work item, the step, the rounds, the outcome data and the spending so far) is the only state of an agent run. The session saves it when it continues as new at a step boundary. | Continuing as new between steps keeps a long agent run's history short, and the saved AgentRun is all a resumed agent run needs | Keeping an agent run's state in the work item's payload. Continuing as new only between work items. |
| 15 | The session acknowledges a matching work item when it arrives during an agent run, and once when each agent run starts, before its first step | The person sees that a request was received before any context loads or model request runs, and gets one acknowledgement per request | Acknowledging every step. Acknowledging a queued request only when its agent run starts. Acknowledging after the context loads, which can take longer than Linear allows a Linear agent session before its first thought. |
| 16 | An agent is agents/<name>/agent.yaml. Its paths are relative to its directory, and it reaches another agent's files by a relative path. Revised on 2026-10-29. | The agent's prompts and instructions are its own files | A flow file outside the agent's directory. Copying a shared file into each agent. |
| 17 | enabled_by_default is on the agent, and SessionConfig.agents names more agents to run. Revised on 2026-10-29. | An agent is what a session runs | Enabling flows |
| 18 | The names are agent, step, agent loop, agent run, step run and session. Revised on 2026-10-29. | People talk to an agent. "Workflow" names a Temporal workflow, "pipeline" names a data pipeline in this repo, and "loop" already names the agent loop inside a step. | Flow, workflow, pipeline, loop, state machine |
| 19 | An agent has one prompt. Each step adds its request, instructions and tools, and may replace the model, its settings and the model call limit. | The steps of one agent share how it is told about its work. A step's own text is its request. Steps differ in what they may write and in how much reasoning they need. | A prompt per step. Steps that change the sandbox or the repository context. |
| 20 | Cost is recorded per step run, and totaled per agent run | "What did this review cost" is one number | Summing step runs in LangSmith by hand |
| 21 | A rubric step asks Jev a rubric file's questions in one activity on the worker, and code maps the answers to passed, rejected or unsettled | No model runs only to start a script. Code decides the outcome. The TypeSafe key stays on the worker. | An agent step that runs a rubric script from a skill. An activity per rubric. |
| 22 | A rubric step's explanation is given to later steps as $rubric_explanation, a field the session sets for every context type, and as the outcome's data | An agent step's prompt reads only template fields, and an activity step reads the payload. One field serves every context type. | Replacing $last_reply with the explanation, which would lose the previous agent step's reply. A field in each context type. |