Internals
This page describes how the code under workflows/auto_swe/src/auto_swe/ carries out a
session. How a session runs describes what a session does, and
Security model explains why the sandbox and the tokens are set up
as they are.
Registries
The workflow calls every activity by its name string. Three registries map the names in an agent's YAML to those activity names.
| Registry | Key | Entry | Activity it names |
|---|---|---|---|
CONTEXT_TYPES (context/registry.py) | a work item's type, which a trigger's type matches | ContextType | activity, which loads the prompt context |
TOOLS (tools/registry.py) | a tool name under the agent's or a step's tools: | ToolSpec | name, which is also the name of the activity that runs the tool |
STEP_ACTIVITIES (agents/registry.py) | a step's activity: | StepActivitySpec | name, which is also the name of the activity the step runs |
PROVIDERS (credentials/registry.py) maps a key under credentials: to a
CredentialProvider. It names no activity: the one refresh_credentials activity calls
every provider. Credentials describes it.
MCP_SERVERS (mcp_servers/registry.py) maps a key under mcp_servers: to the
server's entry in mcp_servers/servers.json. The mcp_list_tools and mcp_call_tool
activities in mcp_servers/activities.py handle every server. Before the sandbox is
created, list_mcp_tools in mcp_servers/client.py executes mcp_list_tools for each
of the agent's servers. mcp_tool in harness/deep_agents/tools.py runs each of
the agent's tool calls as an mcp_call_tool activity. MCP tools
describes the activities.
Each registry is used in two places:
- When the agents load,
agents/loader.pyrejects an agent that:- triggers on a work-item type that has no
CONTEXT_TYPESentry; - names a tool that is not registered, or a step activity that is not in
STEP_ACTIVITIES; - names a tool or a step activity whose
work_item_typesexclude a work-item type one of its triggers names; - leaves out of a step's
onan outcome that the step's tool or activity declares in its spec'soutcomes; - uses a template field that the context type does not provide.
- triggers on a work-item type that has no
- During a session, the workflow looks the name up and passes the entry's activity
name to
workflow.execute_activity:- the functions in
context/client.pycall the context type's activities.load_contextfails the item when its result lacks a field of the context type's fields model. An acknowledgment or reaction collection that fails is logged, and the item is handled without it; harness/deep_agents/tools.pycalls a tool's activity when the agent calls the tool;session/workflow.pycalls a step activity when an agent run enters its step.
- the functions in
The activity runs on the worker. For example, post_comment in
adapters/github/tools.py is decorated with @tool_activity(POST_COMMENT), from
tools/models.py. The decorator registers the activity under POST_COMMENT.name. The
activity takes a ToolRequest, which tool_call reads into the ToolCall that
post_comment takes. tool_call refuses a work item of a type the tool does not act on,
and validates the arguments against the tool's args model. The ToolCall holds the
validated arguments. It also gives the repository, the step run, the commit and its
base, the checkout, and the tool's settings as its settings_model. Each of the
repository, the commit, the base and the checkout raises when the request lacks it.
For a ToolSpec with writes=True, registered_tool in harness/deep_agents/tools.py
does not retry the activity, because a failed attempt may already have written. In a dry
run registered_tool does not run the activity, unless the ToolSpec sets
runs_in_dry_run. It then runs the activity with ToolRequest.dry_run set, and the
activity writes nothing. For a ToolSpec whose max_calls_per_step_run is not None,
registered_tool refuses each call past that number in a step run. A call whose
ToolResult sets counted=False does not count toward that number. An activity sets
counted=False when it refuses its arguments and writes nothing, so the model can call
the tool again with other arguments.
Each ToolRequest has step_run, an StepRunInfo. StepRunner sets:
- the agent and the model;
- the commit and its base;
- the LangSmith run id;
- the step run's registered tools, the agent's followed by the step's;
- the settings, with the repository's overrides (
agent_runs/settings.py).
The activity of a ToolSpec with needs_checkout reads the step run's checkout. The
loader refuses such a tool on an agent whose sandbox does not check out the
repository.
At each call, registered_tool adds the model calls and the estimated cost so far. The
RunProgress middleware (harness/deep_agents/middleware.py) reads them from the
agent's state when the tool call starts. A ToolSpec's settings_model declares the
settings its activity reads. The loader checks an agent's settings against them.
worker/registrations.py registers the activity on the session queue.
tests/worker/test_registrations.py checks that every name CONTEXT_TYPES, TOOLS
and the workflow use is registered. It does not check the names in STEP_ACTIVITIES.
Each new work-item type, tool or step activity therefore takes three changes:
- an activity;
- a registry entry naming it;
- its registration in
worker/registrations.py.
The add-auto-swe-context-type and add-auto-swe-tool skills list the steps.
The Temporal integrations auto_swe uses
auto_swe uses these parts of temporalio.contrib.deepagents and
temporalio.contrib.langsmith:
DeepAgentsPlugin, on the worker function's client and worker (worker/plugins.py), and not on the webhook function's client. The plugin registers the model activity. It also adds LangChain's modules to the workflow sandbox's passthrough modules.create_temporal_deep_agent, which builds the agent (harness/deep_agents/agent_loop.py). The agent's model is aTemporalModel, which runs each model call as an activity.LangSmithPlugin, which propagates the trace context from the workflow into each activity (worker/plugins.py).mock_model_provider, in the session tests.
auto_swe does not use the tool and backend helpers of temporalio.contrib.deepagents:
TemporalBackendstores the wrapped backend in the memory of one worker process, under a key that the workflow generates. On a worker process that did not run that workflow code, thedeepagents.backend_opactivity fails with a non-retryable error.tool_as_activitystores the tool in the memory of one worker process, keyed by the tool's name alone. On a worker process that did not store the tool, thedeepagents.invoke_toolactivity fails with a non-retryable error.activity_as_tooltakes the tool's schema from the activity's parameters, so the model supplies every argument of the activity.
Lambda runs the worker in many execution environments at once. Temporal dispatches each activity task to whichever worker polls the task queue for it. An activity can therefore run in a process that did not run the workflow code.
Each auto_swe activity identifies the object it acts on from its input:
- a sandbox activity, by a sandbox id;
- a registered tool's activity, by a work item;
mcp_call_tool, by a server key and a tool name.
The workflow sets a registered tool's work item, so the model cannot choose the repository or pull request that the tool reads.
auto_swe does not use these other features of Deep Agents and its Temporal integration:
run_deep_agent, which continues as new within an agent loop. The session continues as new between work items instead. Aftermax_model_callsmodel calls, or oncemax_minuteshave passed since the agent loop started, the agent loop adds a message that tells the model to finish. The model can then make two more calls with tools and one call without tools.- Deep Agents'
tasktool, which runs a subagent. The agent loop removes it from the agent's tools. Security model gives the reason. - Streaming.
interrupt_on.
The sandbox layer
Temporal runs activities and keeps history. It provides no machine to check out a
repository on and run commands in. temporalio.contrib.deepagents runs each model call
as an activity. It expects the application to provide Deep Agents' sandbox backend.
auto_swe implements that backend with its own Daytona activities. auto_swe defines
these activity names; Temporal and Deep Agents define none of them.
The layer has three parts:
sandbox/activities.py, the activities, which run on the worker and call the Daytona SDK. Each request names its sandbox by id.sandbox/client.py,SandboxClient, which runs in the workflow. It holds one sandbox id and calls the activities with their timeouts and retry policies. It also builds the commands for checkout, setup and prepare.harness/deep_agents/backend.py,SessionSandbox, which implements Deep Agents'BaseSandboxwithSandboxClient. Deep Agents implements its file tools (ls,read_file,write_file,edit_file,glob,grep) andexecutewith three methods:aexecute,aupload_filesandadownload_files. Each of the three calls one activity.
| Activity | Called by | Does |
|---|---|---|
sandbox_start_or_create | the session, at the start of each step run | starts the session's sandbox, or creates one |
sandbox_exec | every command: checkout, plugin fetch, setup, prepare, the repository-context listing, skill staging, script tools, hooks, and SessionSandbox.aexecute | runs one command and returns its exit code, stdout and stderr |
sandbox_upload | SessionSandbox.aupload_files | writes files into the sandbox |
sandbox_upload_scripts | the session, after the sandbox starts | writes the packaged scripts in sandbox/scripts/ into the sandbox |
sandbox_download | SessionSandbox.adownload_files, and repository context resolution | reads files from the sandbox |
sandbox_stop | the session, after each agent loop | stops the sandbox |
sandbox_delete | the session, when it ends | deletes the sandbox |
Activity options
SandboxClient uses two sets of activity options:
- For every activity except
sandbox_exec: a start-to-close timeout ofattempt_timeout, and at mostmax_attemptsattempts._quickreturns these options, andstart_or_createbuilds the same options itself. - For
sandbox_exec, from_command(limit): a start-to-close timeout ofattempt_timeout, unlimited attempts, a heartbeat timeout, and a schedule-to-close timeout of the command's own limit plusCOMMAND_MARGIN.
A command can run longer than one attempt. A retried sandbox_exec attempt waits for
the command that the first attempt started, instead of running it again:
- The first attempt starts the command as an asynchronous Daytona session command. It records the Daytona session id and command id in its heartbeat details.
- While the command runs, the attempt heartbeats and calls
refresh_activity, which resets the sandbox's auto-stop timer. - A retried attempt reads the ids from the heartbeat details and waits for the same
command. When Daytona no longer has that command, the attempt fails with the
non-retryable error
SandboxCommandLost. The agent gets the error as the command's result.
The command runs under the timeout command, with the command's own limit as the
duration. COMMAND_MARGIN gives timeout time to end the command before the
schedule-to-close timeout ends the activity. The activity then returns the command's
result with timed_out set, as Commands describes.
Starting or creating the sandbox
The session records its sandbox id in workflow state, and passes it to
sandbox_start_or_create at the start of each step run. The activity:
- gets the sandbox by id and starts it, if it exists and is in a state that can be started;
- otherwise, lists the sandboxes labeled with the request's
key, and starts the one it finds; - otherwise, creates a sandbox labeled with
key.
Daytona's create waits for the new sandbox to start, so an attempt can time out after
Daytona has created the sandbox. Step 2 keeps the next attempt from creating a second
sandbox. The workflow generates key once per call, with workflow.uuid4(). Temporal
retries an activity with the input it scheduled, so every attempt of one call sends the
same key.
Commands
Every command runs as
timeout --verbose --kill-after=10 <seconds> bash -c '<command>' < /dev/null in the
sandbox user's environment, which holds the placeholders of the sandbox's Secrets.
Daytona keeps a session command's stdin open. Without the redirect, a program that
reads stdin when it is given no path, such as rg or grep, waits until timeout ends
it.
ExecResult.timed_out is set when the command exits 124 or 137 and its stderr holds the
line timeout --verbose writes when it signals the command. A command killed for
another reason, such as running out of memory, also exits 137, but has no such line.
When the sandbox stops one of the agent's commands, SessionSandbox adds a line to its
output that says so, and gives the command's limit and the sandbox's
command_timeout_seconds.
Credentials
credentials/ turns an agent's credentials: into Daytona Secrets.
-
credentials/registry.pymaps each key to aCredentialProvider. For an access level and a work item, a provider returns aCredentialSpec. TheCredentialSpecstates what to mint and lists theSecretSpecof each Daytona Secret that holds the value. On the worker, the provider mints one value for the credential. It then returns the form of that value that each Secret holds. The GitHub provider is inadapters/github/credentials.py. It mints one token for two Secrets. -
The
refresh_credentialsactivity incredentials/activities.pytakes the agent type'scredentials:, the work item and the dry-run flag. It lists the Daytona Secrets whose names containauto-swe-, once for all credentials. It mints a new value for a credential when any of these holds:- the store has no expiry for the credential;
- one of the credential's Secrets does not exist;
- the credential has no
refresh_before, such asdagster; - the value expires within the credential's
refresh_before.
It then creates each of the credential's Secrets that does not exist. It updates an existing Secret only when the new value's version differs from the version in the store. It reads and writes each credential's expiry and version in the store from
credentials/store.py. It returns:- the Secret names to mount;
- the providers' non-secret environment variables;
refresh_at, the earliest time a Secret needs a new value.
No value enters the workflow history.
-
CredentialRefresherincredentials/refresher.pyrunsrefresh_credentialsfrom the workflow and holds its latest result.StepRunnerinagent_runs/runner.pycallsrefresh_credentialsbefore it starts or creates the sandbox, and passes the mounts tosandbox_start_or_create. It gives theSandboxClientthe refresher'skeep_freshasbefore_command, which callsrefresh_credentialsagain onceworkflow.now()reachesrefresh_at. -
The session mounts a sandbox's Secrets only when it creates the sandbox. It keys its sandboxes by snapshot and by a hash of the mounts. Two agents with different credentials therefore never share a sandbox.
See Credentials in the sandbox for
what the Secrets protect against, and the risk that remains. The
add-auto-swe-credential skill lists the steps for a new provider.
A work item, by module
| Stage | Module |
|---|---|
| Load the agents | the load_agents activity in agents/loader.py |
| Match the work item to each agent's first matching trigger | agents_for in work_items/routing.py |
| Run an agent run's steps, and pick each next step from the outcome | _run_agent and _advance in session/workflow.py |
| Resolve an agent step's fields from the agent's and the step's | Agent.for_step in agents/models.py |
| Load the prompt context | the context type's activity, such as adapters/github/context.py |
| List the agent's MCP tools | list_mcp_tools in mcp_servers/client.py, which executes the mcp_list_tools activity in mcp_servers/activities.py |
| Create or refresh the agent's Daytona Secrets | the refresh_credentials activity in credentials/activities.py |
| Start or create the sandbox | SandboxClient.start_or_create |
| Check out and run setup | SandboxClient.checkout and setup, running sandbox/scripts/*.sh |
| Resolve the repository context | agents/repo_context.py, and the resolve_plugins activity in agents/plugins.py |
| Run prepare | SandboxClient.prepare, running the agent's prepare script |
| Run the agent loop | harness/deep_agents/agent_loop.py, with SessionSandbox as the backend |
| Stop the sandbox | SandboxClient.stop |
session/workflow.py matches the work item, runs the agent runs and loads the context
of each agent step. StepRunner.run in agent_runs/runner.py runs each later stage, in
this order.