Skip to main content

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.

TermMeaning
agentOne agent.yaml, with its defaults, triggers and steps
stepOne unit of an agent's work. It runs an agent loop, an activity or a rubric.
agent loopThe model's loop of calls and tool calls inside a step
agent runOne execution of an agent, from the trigger that starts it to its end
step runOne step's execution in an agent run
sessionThe 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​

FieldMeaning
name, descriptionThe agent's name, which is its directory's name, and what it does
enabled_by_defaultWhether every session runs it. SessionConfig.agents names the agents a session runs in addition.
model, model_settings, max_model_callsThe model of every agent step, the keyword arguments bound to it, and the most model calls one step run makes
max_minutesThe minutes after which a step run is told to finish. Default 60.
instructionsThe files of the system prompt, joined in order
promptThe prompt template of every agent step. A step's request fills its $request.
skills_prompt, memory_promptTemplates that replace Deep Agents' description of skills and of the repository's instruction files
read_limitThe lines a read_file call returns when it passes no limit
sandbox, repo_context, plugin_pinsThe sandbox, and the repository context the agent loads
settingsDefaults for the settings the agent's tools read. A repository overrides them in .auto-swe/config.yaml, under the agent's name.
toolsThe tools of every step
credentials, allow_sandbox_writesWhat the sandbox's commands can reach. They are the most any step may get.
mcp_serversThe MCP servers whose tools every step can call
triggersThe work items that start the agent. Each trigger matches type, event, actions and when, names the step it starts, and may set request.
stepsThe 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:

FieldEffect
requestWhat the step asks for. It fills the prompt's $request. A trigger's request replaces it for the step that the trigger starts.
instructionsFiles appended to the agent's instructions
toolsTools added to the agent's tools
model, model_settings, max_model_calls, max_minutesReplace the agent's
settingsReplace the agent's settings that it names. The repository's .auto-swe/config.yaml overrides apply after them.
credentialsNarrow the agent's credentials: each grant is the agent's grant or its read-only grant
conversationThe name of the conversation the step continues and saves. Without it, the step starts from its prompt alone, and its conversation is not kept.
onThe next step for each outcome, or end
max_rounds, after_max_roundsHow 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:

  1. Run the step: an agent loop, an activity or a rubric.
  2. Take the step's outcome, and find the next step in the step's on.
  3. When the next step has run max_rounds times in this agent run, take its after_max_rounds instead.
  4. 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:

FieldMeaning
agentThe agent's name
idThe agent run's id, which its records and LangSmith runs carry
startThe work item that started the agent run
stepThe step that runs now
roundsHow many times the agent run has entered each step
dataThe data of every outcome so far, each outcome's data merged over the previous
stepsThe steps that have finished, in order
started_at, usage_at_start, cost_at_startWhen 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_review returns findings with the findings, or passed with 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, rejected or unsettled, and its data holds the step's explanation as rubric_explanation.

  • The session, for an outcome of the step run itself:

    OutcomeWhen
    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 StepRunRecord holds one step run's agent, step, model, tokens, cost and LangSmith run id, and the id of its agent run.
  • An AgentRunRecord holds 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 on does not map;
  • on maps an outcome that the step cannot return;
  • a trigger, an on or an after_max_rounds names 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_rounds without after_max_rounds, or the reverse;
  • a step's credentials grant 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 state names 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:

StepRoundOutcomeData added
plan-check1passedrubric_explanation
plan-ready1posted
implement1pushedbranch, commit, base_commit
review1findingsfindings, review
fix1pushedcommit
review2passedreview
open-pr1openedpull_request_url
link-pr1posted

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:

WhenWork itemWhat runsThen
Day 0auto-swe:review labelreviewThe agent run ends, and the session waits
Day 0A reply to a findingNo step. The session records the feedback.The session waits
Day 1@ai-auto-swe fix the null checkclassify, then fixThe agent run ends, and the session waits
Day 1A second fix comment, while fix runsGets 👀 as it arrives. Waits in the queue until the first agent run ends, then classify and fix.The session waits
Day 3The pull request is mergedNo stepThe 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.

#DecisionReasonRejected
1The 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.
2The 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.
3A step runs an agent loop or an activityClassifying a comment and posting a link need no modelAgent steps only
4Intent classification is an activity step, and each intent is an outcomeOne mention trigger replaces one per intent. Only agents that need classification run it.Classifying every mention before routing
5A 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 codeThe model declares the outcome
6An agent file has only defaults, triggers, steps, outcome mappings and round capsTemporal already provides conditions, timers and parallelismAdding them to the agent file
7DagsterTriage stays its own workflow, and runs the triage agent's single stepIts budget overflow and prematch run before any agent, per deploymentRunning triage in sessions now
8Triggers 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 stepTriggers in a separate flow file
9Every 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 runsEnding the agent run on any unmapped outcome
10max_rounds and after_max_rounds are on the repeated stepThe cap belongs to the loop between steps, not to the review toolA cap in the review tool's settings
11A 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.
12A step can narrow the agent's credentials and replace its settings, never widen its credentialsThe agent states the most any of its steps may getSteps that widen credentials
13A 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.
14An 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 needsKeeping an agent run's state in the work item's payload. Continuing as new only between work items.
15The session acknowledges a matching work item when it arrives during an agent run, and once when each agent run starts, before its first stepThe person sees that a request was received before any context loads or model request runs, and gets one acknowledgement per requestAcknowledging 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.
16An 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 filesA flow file outside the agent's directory. Copying a shared file into each agent.
17enabled_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 runsEnabling flows
18The 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
19An 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.
20Cost is recorded per step run, and totaled per agent run"What did this review cost" is one numberSumming step runs in LangSmith by hand
21A rubric step asks Jev a rubric file's questions in one activity on the worker, and code maps the answers to passed, rejected or unsettledNo 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.
22A 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 dataAn 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.