Best practices
Building agents
An agent is three things: a model, a loop that calls it, and the tools the loop runs. Most teams start by putting the loop and the tools in one sandbox per user, and keeping it running while the agent waits on the model or the person. The loop is your own code. Only the tools need a sandbox, and only while they run.
We work with many of the teams building agents at scale, and the ones that run efficiently have converged on the same practices: the loop runs outside the sandbox, many to a machine; each tool call gets its own short-lived compute; and the agent’s state lives somewhere both can see. This guide walks through those practices, with pi as the example harness, migrates an in-sandbox agent step by step, and does the arithmetic on what it saves. Where it needs a concrete implementation, it uses Archil’s.
Hunter LeathFounder & CEO, Archil
Checked November 2026The whole guide as Markdown
Contents
- 01Two places to run an agentRun the agent loop outside the sandbox, and send only the tool calls into one. The loop is code your team wrote, so many sessions can share a host, and each tool call needs isolated compute only for as long as it runs. Most loops stay inside because of files, so the design works only when the loop and every tool call see the same storage.
- 02Serverless tool callsA serverless tool call runs one of the model’s commands on fresh, isolated compute with the agent’s workspace already mounted, and leaves nothing running. It should let the harness decide per call what the command can reach and change, commit its writes before it returns, and bill for the call instead of a machine-hour. On Archil, that call is
disk.exec(). - 03Many agents, one machineRun the harness as ordinary multi-tenant server code. One process holds every open conversation, each command runs on per-call compute that sees only its tenant’s workspace, and each conversation’s history lives with that tenant’s files, so any process can pick it up. This chapter builds it with pi as the harness, and Archil’s serverless execution, S3 API, and disks underneath.
- 04Migrating from an in-sandbox agentMove an agent out of its sandbox in steps, not all at once. Inventory what the sandbox does, put each workspace on storage that outlives it, send the tools to serverless calls, move the loop to a shared host, give long-running processes a persistent sandbox, and roll out behind a per-session flag. Once the files live outside the sandbox, the old path and the new one work on the same files, so you can move sessions over a few at a time and move them back.
- 05What it savesMeasure what moving the harness out saves with your own numbers, because it depends on how much of each hour your tools spend running. A sandbox holds its vCPUs for the whole session, and a serverless tool call holds compute only while its command runs. This chapter’s calculator prices both, with Archil’s per-call price. Agents that edit their own environment, long-running services, heavy continuous compute, and calls over Archil’s 5-minute limit still belong in a sandbox.