Skip to main content

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.

RegistryKeyEntryActivity it names
CONTEXT_TYPES (context/registry.py)a work item's type, which a trigger's type matchesContextTypeactivity, which loads the prompt context
TOOLS (tools/registry.py)a tool name under the agent's or a step's tools:ToolSpecname, which is also the name of the activity that runs the tool
STEP_ACTIVITIES (agents/registry.py)a step's activity:StepActivitySpecname, 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.py rejects an agent that:
    • triggers on a work-item type that has no CONTEXT_TYPES entry;
    • 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_types exclude a work-item type one of its triggers names;
    • leaves out of a step's on an outcome that the step's tool or activity declares in its spec's outcomes;
    • uses a template field that the context type does not provide.
  • 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.py call the context type's activities. load_context fails 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.py calls a tool's activity when the agent calls the tool;
    • session/workflow.py calls a step activity when an agent run enters its step.

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:

  1. an activity;
  2. a registry entry naming it;
  3. 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 a TemporalModel, 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:

  • TemporalBackend stores 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, the deepagents.backend_op activity fails with a non-retryable error.
  • tool_as_activity stores 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, the deepagents.invoke_tool activity fails with a non-retryable error.
  • activity_as_tool takes 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. After max_model_calls model calls, or once max_minutes have 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' task tool, 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' BaseSandbox with SandboxClient. Deep Agents implements its file tools (ls, read_file, write_file, edit_file, glob, grep) and execute with three methods: aexecute, aupload_files and adownload_files. Each of the three calls one activity.
ActivityCalled byDoes
sandbox_start_or_createthe session, at the start of each step runstarts the session's sandbox, or creates one
sandbox_execevery command: checkout, plugin fetch, setup, prepare, the repository-context listing, skill staging, script tools, hooks, and SessionSandbox.aexecuteruns one command and returns its exit code, stdout and stderr
sandbox_uploadSessionSandbox.aupload_fileswrites files into the sandbox
sandbox_upload_scriptsthe session, after the sandbox startswrites the packaged scripts in sandbox/scripts/ into the sandbox
sandbox_downloadSessionSandbox.adownload_files, and repository context resolutionreads files from the sandbox
sandbox_stopthe session, after each agent loopstops the sandbox
sandbox_deletethe session, when it endsdeletes the sandbox

Activity options​

SandboxClient uses two sets of activity options:

  • For every activity except sandbox_exec: a start-to-close timeout of attempt_timeout, and at most max_attempts attempts. _quick returns these options, and start_or_create builds the same options itself.
  • For sandbox_exec, from _command(limit): a start-to-close timeout of attempt_timeout, unlimited attempts, a heartbeat timeout, and a schedule-to-close timeout of the command's own limit plus COMMAND_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:

  1. 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.
  2. While the command runs, the attempt heartbeats and calls refresh_activity, which resets the sandbox's auto-stop timer.
  3. 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:

  1. gets the sandbox by id and starts it, if it exists and is in a state that can be started;
  2. otherwise, lists the sandboxes labeled with the request's key, and starts the one it finds;
  3. 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.py maps each key to a CredentialProvider. For an access level and a work item, a provider returns a CredentialSpec. The CredentialSpec states what to mint and lists the SecretSpec of 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 in adapters/github/credentials.py. It mints one token for two Secrets.

  • The refresh_credentials activity in credentials/activities.py takes the agent type's credentials:, the work item and the dry-run flag. It lists the Daytona Secrets whose names contain auto-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 as dagster;
    • 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.

  • CredentialRefresher in credentials/refresher.py runs refresh_credentials from the workflow and holds its latest result. StepRunner in agent_runs/runner.py calls refresh_credentials before it starts or creates the sandbox, and passes the mounts to sandbox_start_or_create. It gives the SandboxClient the refresher's keep_fresh as before_command, which calls refresh_credentials again once workflow.now() reaches refresh_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​

StageModule
Load the agentsthe load_agents activity in agents/loader.py
Match the work item to each agent's first matching triggeragents_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'sAgent.for_step in agents/models.py
Load the prompt contextthe context type's activity, such as adapters/github/context.py
List the agent's MCP toolslist_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 Secretsthe refresh_credentials activity in credentials/activities.py
Start or create the sandboxSandboxClient.start_or_create
Check out and run setupSandboxClient.checkout and setup, running sandbox/scripts/*.sh
Resolve the repository contextagents/repo_context.py, and the resolve_plugins activity in agents/plugins.py
Run prepareSandboxClient.prepare, running the agent's prepare script
Run the agent loopharness/deep_agents/agent_loop.py, with SessionSandbox as the backend
Stop the sandboxSandboxClient.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.