docs(agents): E2B/Daytona sandboxes, fleshed-out examples, design patterns first (#115)

Amp-Thread-ID: https://ampcode.com/threads/T-af28ce42-6c01-4358-8608-8c5c7f7e3150

Co-authored-by: Sree Narayanan <sree@rivet.gg>
Co-authored-by: Amp <amp@ampcode.com>

Author: 3 people

agents/docs/content/docs/.amp/portals/.service-metadata

@@ -0,0 +1,15 @@
+{
+  "adHocServices": {
+    "rivet-website": {
+      "name": "rivet-website",
+      "command": "cd /home/user/workspace/repos/website && ./node_modules/.bin/tsx scripts/assemble.ts && ./node_modules/.bin/tsx scripts/generate-markdown.ts && ./node_modules/.bin/astro dev --host 0.0.0.0 --port 4321",
+      "env": {},
+      "portals": [],
+      "health": null,
+      "review": true,
+      "agent": "off",
+      "cwd": "/home/user/workspace/repos/website/agents/docs/content/docs",
+      "port": 31227
+    }
+  }
+}

agents/docs/content/docs/.amp/portals/.service-ports

@@ -0,0 +1,5 @@
+{
+  "servicePorts": {
+    "rivet-website": 31227
+  }
+}

agents/docs/content/docs/agent-to-agent.mdx

@@ -32,10 +32,12 @@ A tool can send another agent a message. Here a coder agent hands a finished bra
 <CodeGroup>
 <CodeSnippet file="examples/agent-to-agent/coder.ts" title="coder.ts" />
 <CodeSnippet file="examples/agent-to-agent/server.ts" title="server.ts" />
+<CodeSnippet file="examples/agent-to-agent/client.ts" title="client.ts" />
 </CodeGroup>
 
 - The reviewer is keyed by repository, so every coder working on the same repository reaches the same reviewer, and its session remembers past reviews.
-- `requestReview` schedules the reviewer's `prompt` and returns, so the coder's tool doesn't wait for the review. The schedule is saved with the reviewer, so the review runs even if the coder's request goes away.
-- `streamingBehavior: "followUp"` queues the request when the reviewer is busy with another review. Use it with `prompt`, not the `followUp` action, which only queues on an idle agent and never starts a run.
+- The `requestReview` action schedules the reviewer's `prompt` and returns, so the coder's tool doesn't wait for the review. The schedule is saved with the reviewer, so the review runs even if the coder's request goes away.
+- Passing `streamingBehavior: "followUp"` queues the request when the reviewer is busy with another review. Use it with `prompt`, not the `followUp` action, which only queues on an idle agent and never starts a run.
+- The reviewer runs on a different model family than the coder.
 
 To wait for the other agent's answer instead, see [Subagents](/agents/docs/subagents). See [Schedules](/actors/docs/schedule) for more on `c.schedule`.

agents/docs/content/docs/api-keys.mdx

@@ -5,7 +5,7 @@ description: "Give agents model access with your own provider keys, from the env
 
 An agent calls the model from your worker, so its keys stay in your backend and never enter the sandbox. It looks for a key in this order:
 
-1. `apiKeys` passed to `pi()`.
+1. The `apiKeys` option passed to `pi()`.
 2. The `credentials` Actor, when your users [bring their own subscriptions](/agents/docs/user-subscriptions).
 3. The worker's environment.
 
@@ -62,16 +62,16 @@ Set the key for your model provider in the environment of the process that runs
 ANTHROPIC_API_KEY=sk-ant-...
 ```
 
-Pi reads the provider-named variable, such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, or `OPENROUTER_API_KEY`. See Pi's [provider list](https://github.com/earendil-works/pi) for the rest.
+Pi reads the provider-named variable, such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY`, `DEEPSEEK_API_KEY`, `GROQ_API_KEY`, or `OPENROUTER_API_KEY`. See Pi's [provider list](https://github.com/earendil-works/pi) for the rest.
 
 ## Keys in code
 
-Pass `apiKeys` to set keys by provider id in code, for example when they come from a secret manager or differ per deployment. Here it's added to the [Quickstart](/agents/docs/quickstart) agent. The keys stay in the Actor's memory and win over every other source.
+Pass `apiKeys` to set keys by provider id in code, for example when they come from a secret manager or differ per deployment. The keys stay in the Actor's memory and win over every other source.
 
 <CodeSnippet file="examples/credentials/api-keys.ts" title="server.ts" />
 
 ## Custom providers
 
 To use a provider Pi does not know, register it with `providers`, in the shape of Pi's `models.json`, and give it a key the same way.
 
-**Next:** [Custom Tools](/agents/docs/custom-tools), tools that run in your backend.
+**Next:** [Sandboxes](/agents/docs/sandboxes), where the agent's tool calls run.

agents/docs/content/docs/architecture.mdx

@@ -5,7 +5,7 @@ description: "The states an agent moves through, and what survives sleep, crashe
 
 ## States
 
-An agent is idle until a prompt starts a run, and goes back to idle when the run ends or is cancelled. When the context fills up during a run, the agent compacts it and keeps going. Tool calls run in the sandbox.
+An agent is idle until a prompt starts a run, and goes back to idle when the run ends or is cancelled. When the context fills up during a run, the agent compacts it and keeps going.
 
 <div style="overflow-x:auto">
 <svg viewBox="0 0 640 300" role="img" aria-label="Agent states: a prompt moves Idle to Running, and the run ending or being cancelled moves it back. Running moves to Compacting when the context is full and back when compaction is done. Idle moves to Sleeping when idle, and the next action wakes it back to Idle. Running sends tool calls to the sandbox." style="width:100%;min-width:520px;max-width:640px;height:auto;display:block;margin:2.5rem auto;font-family:system-ui,sans-serif">
@@ -47,7 +47,7 @@ An agent is idle until a prompt starts a run, and goes back to idle when the run
 
 ## Sleep
 
-An idle agent sleeps and frees its memory. The next action on its key wakes it: the agent reloads its session and reconnects to the same sandbox, so clients don't do anything different. While the agent sleeps, an E2B or Daytona sandbox is suspended, and an agentOS VM sleeps on its own.
+An idle agent sleeps and frees its memory. The next action on its key wakes it: the agent reloads its session and reconnects to the same sandbox, so clients don't do anything different. While the agent sleeps, its sandbox is suspended.
 
 <div style="overflow-x:auto">
 <svg viewBox="0 0 640 280" role="img" aria-label="The agent loop runs in memory and saves each step to the Actor&#x27;s SQLite database, which also holds the sandbox id. On wake, the loop is restored from SQLite and reconnects to the same sandbox. Sleep, a crash, or a deploy clears memory, and SQLite is kept." style="width:100%;min-width:520px;max-width:640px;height:auto;display:block;margin:2.5rem auto;font-family:system-ui,sans-serif">
@@ -86,6 +86,6 @@ An idle agent sleeps and frees its memory. The next action on its key wakes it:
 | Sleep | Every message so far. | Reconnected on wake. |
 | Crash | Every message written before the crash. | Reconnected on wake. |
 | Deploy | Every message so far. Old Actors get up to 30 minutes to finish before the agent wakes on the new code. See [Versions](/docs/versions). | Reconnected on wake. |
-| Destroy | Deleted. | E2B and Daytona sandboxes are deleted. An agentOS VM and its files are left in place. |
+| Destroy | Deleted. | Deleted. |
 
 A model chosen with `setModel` is restored too, if it's still allowed. If the sandbox no longer exists when the agent wakes, a new one is created and the old files are lost.

agents/docs/content/docs/built-in-tools.mdx

@@ -1,16 +1,18 @@
 ---
 title: "Built-in Tools"
-description: "The file and shell tools every agent gets, where they run, and how to limit them."
+description: "Pi's file and shell tools for agents with a sandbox, where they run, and how to limit them."
 ---
 
-With a sandbox, an agent gets seven built-in tools that run in the sandbox, not on your worker.
+Built-in tools are Pi's own [coding tools](https://github.com/earendil-works/pi/tree/main/packages/coding-agent), with the same names, parameters, and output as in Pi. They run in the agent's sandbox instead of on your worker.
 
 | Tool | What it does |
 | --- | --- |
 | `read`, `write`, `edit` | Read, create, and change files. |
 | `grep`, `find`, `ls` | Search files and list directories. |
 | `bash` | Run a shell command. |
 
+A sandbox is optional. Without one, the agent has no built-in tools and only uses the [custom tools](/agents/docs/custom-tools) you pass. Pi's tools run with the permissions of the process they run in, which is your worker, so they're only turned on when a [sandbox](/agents/docs/sandboxes) gives them somewhere else to run.
+
 <div style="overflow-x:auto">
 <svg viewBox="0 0 640 200" role="img" aria-label="client.ts calls executeBash on the reviewer agent to check out the branch. The reviewer&#x27;s read and search tools run in its sandbox. bash, edit, and write are excluded." style="width:100%;min-width:520px;max-width:640px;height:auto;display:block;margin:2.5rem auto;font-family:system-ui,sans-serif">
   <defs>
@@ -37,9 +39,8 @@ With a sandbox, an agent gets seven built-in tools that run in the sandbox, not
 <CodeSnippet file="examples/built-in-tools/client.ts" title="client.ts" />
 </CodeGroup>
 
-- `excludeTools` turns tools off by name, so this reviewer can read and search files but can't run commands or change them. `tools` does the opposite and enables only the tools you list.
-- `executeBash` runs a command in the agent's sandbox from your backend, without the model. It works even though the reviewer can't run `bash` itself. `excludeFromContext` keeps the output out of the conversation.
-- File tools only reach paths inside the sandbox's working directory. `bash` accepts a timeout, and long output is truncated before it reaches the model.
-- Without a sandbox, the agent has no built-in tools. See [Sandboxes](/agents/docs/sandboxes).
+- The `excludeTools` option turns tools off by name, so this reviewer can read and search files but can't run commands or change them. The `tools` option does the opposite and enables only the tools you list.
+- The `executeBash` action runs a command in the agent's sandbox from your backend, without the model. It works even though the reviewer can't run `bash` itself. Its `excludeFromContext` option keeps the output out of the conversation.
+- File tools only reach paths inside the sandbox's working directory. The `bash` tool accepts a timeout, and long output is truncated before it reaches the model.
 
 To give an agent your own tools, see [Custom Tools](/agents/docs/custom-tools).

agents/docs/content/docs/client-sdk.mdx

@@ -41,19 +41,19 @@ Call an agent from your backend, a script, or any JavaScript runtime with `rivet
 
 ## Handles and connections
 
-- `createClient()` reads `RIVET_ENDPOINT`, `RIVET_NAMESPACE`, and `RIVET_TOKEN` from the environment, and defaults to a local Rivet at `localhost:6420`.
-- `getOrCreate` returns a handle to the agent with that key, and creates the agent on first use. Actions called on the handle, like `getMessages`, are single requests.
-- `connect()` opens a live connection that receives the session's events. Actions called before it opens wait until it does.
-- A dropped connection reconnects on its own. `onStatusChange` reports `connecting`, `connected`, and `disconnected`, and `idle` after `dispose()` closes the connection for good.
+- With no options, `createClient()` reads `RIVET_ENDPOINT`, `RIVET_NAMESPACE`, and `RIVET_TOKEN` from the environment, and defaults to a local Rivet at `localhost:6420`.
+- The `getOrCreate` method returns a handle to the agent with that key, and creates the agent on first use. Actions called on the handle, like `getMessages`, are single requests.
+- Calling `connect()` opens a live connection that receives the session's events. Actions called before it opens wait until it does.
+- A dropped connection reconnects on its own. The `onStatusChange` callback reports `connecting`, `connected`, and `disconnected`, and `idle` after `dispose()` closes the connection for good.
 
 ## Events
 
-`on("event", ...)` receives every event of the session as the agent works. See [Session Lifecycle](/agents/docs/session-lifecycle#events) for the event types.
+A listener added with `on("event", ...)` receives every event of the session as the agent works. See [Session Lifecycle](/agents/docs/session-lifecycle#events) for the event types.
 
 ## Results and errors
 
-- `prompt` resolves when the run ends. Read the reply with `getLastAssistantText` or `getMessages`.
-- `prompt` rejects with an `ActorError` when the action itself fails. For example, another prompt is already running (pass `streamingBehavior` to queue it instead), the model has no credential (`model_unavailable`), or the run passes the ten-minute action timeout (`action_timed_out`).
+- The `prompt` action resolves when the run ends. Read the reply with `getLastAssistantText` or `getMessages`.
+- The `prompt` action rejects with an `ActorError` when the action itself fails. For example, another prompt is already running (pass `streamingBehavior` to queue it instead), the model has no credential (`model_unavailable`), or the run passes the ten-minute action timeout (`action_timed_out`).
 - A model error doesn't reject. The run ends with an assistant message whose `stopReason` is `"error"`, and `errorMessage` explains why.
 
 ## Browsers
@@ -65,8 +65,8 @@ A browser shouldn't hold your Rivet credentials. Your backend checks who the use
 <CodeSnippet file="examples/client-sdk/token.ts" title="token.ts" />
 </CodeGroup>
 
-- `token.ts` resolves the user's agent and calls `issueToken`, which returns a token for that one agent that expires in 15 minutes.
-- `browser.ts` connects with `getForId`. `getToken` fetches a new token whenever the old one expires, so the connection stays up.
+- In `token.ts`, your backend resolves the user's agent and calls `issueToken`, which returns a token for that one agent that expires in 15 minutes.
+- In `browser.ts`, the client connects with `getForId`, and `getToken` fetches a new token whenever the old one expires, so the connection stays up.
 
 See [JWTs](/docs/jwt) and [Authentication](/docs/authentication).
 

agents/docs/content/docs/connectors/discord.mdx

@@ -88,7 +88,7 @@ Under **General Information**, set the interactions endpoint URL to `https://<yo
 
 - The route verifies Discord's Ed25519 signature against the raw body with the application's public key.
 - Each Discord channel gets its own agent. Every `/ask` in the channel continues the same session.
-- Discord expects a response within three seconds and an agent run takes longer, so the route hands the command to the agent's `receive` action and defers the reply. `receive` schedules `reply`, which prompts the agent and edits the deferred message. Interaction tokens stay valid for 15 minutes, and a message holds up to 2,000 characters. The schedule is saved with the agent, so the reply still runs if the request that delivered the message goes away.
+- Discord expects a response within three seconds and an agent run takes longer, so the route hands the command to the agent's `receive` action and defers the reply. The `receive` action adds the message to the agent's queue and schedules `drain`, which prompts the agent with the oldest message and edits the deferred message. Interaction tokens stay valid for 15 minutes, and a message holds up to 2,000 characters. A message that arrives while the agent is answering waits in the queue. The queue is saved with the agent, so replies still run if the request that delivered a message goes away.
 
 ## Configure
 
@@ -97,7 +97,7 @@ Under **General Information**, set the interactions endpoint URL to `https://<yo
 | `DISCORD_PUBLIC_KEY` | **Required.** Verifies that requests come from Discord. |
 | `DISCORD_APPLICATION_ID` | Registers the command. Not needed by the server. |
 | `DISCORD_BOT_TOKEN` | Registers the command. Not needed by the server. |
-| `ANTHROPIC_API_KEY` | **Required.** The agent's model key. See [API Keys](/agents/docs/api-keys). |
+| `ANTHROPIC_API_KEY` | **Required.** The agent's model key. For another provider, change `model` and set its key instead, such as `OPENAI_API_KEY` or `OPENROUTER_API_KEY`. See [LLM API Keys](/agents/docs/api-keys). |
 
 ## Supported events
 

agents/docs/content/docs/connectors/github.mdx

@@ -76,7 +76,7 @@ In the repository's **Settings > Webhooks**, add a webhook with the payload URL
 - The route verifies GitHub's `X-Hub-Signature-256` signature against the raw body.
 - Each issue or pull request gets its own agent, keyed by owner, repository, and number. Every mention in the thread continues the same session.
 - The route only answers new comments that mention the bot, and never the bot's own comments, so replies do not loop.
-- GitHub times out a delivery after ten seconds, so the route only hands the comment to the agent's `receive` action and returns. `receive` schedules `reply`, which prompts the agent and posts the answer as a comment with Octokit. The schedule is saved with the agent, so the reply still runs if the request that delivered the message goes away.
+- GitHub times out a delivery after ten seconds, so the route only hands the comment to the agent's `receive` action and returns. The `receive` action adds the message to the agent's queue and schedules `drain`, which prompts the agent with the oldest message and posts the answer as a comment with Octokit. A message that arrives while the agent is answering waits in the queue. The queue is saved with the agent, so replies still run if the request that delivered a message goes away.
 
 ## Configure
 
@@ -85,7 +85,7 @@ In the repository's **Settings > Webhooks**, add a webhook with the payload URL
 | `GITHUB_WEBHOOK_SECRET` | **Required.** Verifies that deliveries come from GitHub. |
 | `GITHUB_TOKEN` | **Required.** Posts replies as the bot account. |
 | `GITHUB_BOT_LOGIN` | **Required.** The bot's username. Comments that mention it start a reply. |
-| `ANTHROPIC_API_KEY` | **Required.** The agent's model key. See [API Keys](/agents/docs/api-keys). |
+| `ANTHROPIC_API_KEY` | **Required.** The agent's model key. For another provider, change `model` and set its key instead, such as `OPENAI_API_KEY` or `OPENROUTER_API_KEY`. See [LLM API Keys](/agents/docs/api-keys). |
 
 ## Supported events
 

agents/docs/content/docs/connectors/linear.mdx

@@ -76,7 +76,7 @@ In Linear's **Settings > Administration > API**, which needs admin rights, creat
 - The route verifies the `Linear-Signature` HMAC against the raw body and rejects deliveries older than a minute.
 - Each Linear issue gets its own agent. Every comment with the trigger continues the same session.
 - The route never answers the agent's own comments, so replies do not loop.
-- The route only hands the comment to the agent's `receive` action and returns. `receive` schedules `reply`, which prompts the agent and posts the answer as a comment with the Linear SDK. The schedule is saved with the agent, so the reply still runs if the request that delivered the message goes away.
+- The route only hands the comment to the agent's `receive` action and returns. The `receive` action adds the message to the agent's queue and schedules `drain`, which prompts the agent with the oldest message and posts the answer as a comment with the Linear SDK. A message that arrives while the agent is answering waits in the queue. The queue is saved with the agent, so replies still run if the request that delivered a message goes away.
 
 ## Configure
 
@@ -85,7 +85,7 @@ In Linear's **Settings > Administration > API**, which needs admin rights, creat
 | `LINEAR_WEBHOOK_SECRET` | **Required.** Verifies that deliveries come from Linear. |
 | `LINEAR_API_KEY` | **Required.** Posts replies as the agent's Linear user. |
 | `LINEAR_TRIGGER` | Text that makes a comment start a reply. Defaults to `@agent`. |
-| `ANTHROPIC_API_KEY` | **Required.** The agent's model key. See [API Keys](/agents/docs/api-keys). |
+| `ANTHROPIC_API_KEY` | **Required.** The agent's model key. For another provider, change `model` and set its key instead, such as `OPENAI_API_KEY` or `OPENROUTER_API_KEY`. See [LLM API Keys](/agents/docs/api-keys). |
 
 ## Supported events