> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deliverables and artifacts

> Ask agents for named deliverables, understand which files are kept and when, show images inline, and get results out of a session.

A deliverable is a file an agent produces for you, such as a report, a CSV, or a patch. Agents already know where to save deliverables, so you only need to ask for a named file. At the end of each turn, the files in the deliverables folder are kept with the session, so you and later sessions can use them.

<Note>
  To start sessions, you need the Developer or Admin role in the organization. See [Organizations and roles](/recursion/organizations-and-roles). Every session runs in an environment's sandbox. See [Environments](/recursion/environments).
</Note>

## Ask for a deliverable

Name the file and its format in the task, and say what it must contain. This session asks for a CSV and a short summary.

<Tabs>
  <Tab title="Console">
    1. In the sidebar, click **Sessions**, then click **Launch session**.
    2. Choose the **Agent** and **Environment**.
    3. In **Opening message**, describe the task and name the deliverables.
    4. Click **Launch session**.
  </Tab>

  <Tab title="cURL">
    ```bash theme={"theme":"css-variables"}
    curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions' \
      -H "Authorization: Bearer $RECURSION_API_KEY" \
      -H 'Idempotency-Key: q3-price-audit-2026-09-25' \
      -H 'Content-Type: application/json' \
      -d '{
        "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
        "environment_id": "9d3e7b52-1a4c-4f80-b6e9-2c8a5d0f7e13",
        "message": "Audit the Q3 price exports. Save price-changes.csv and summary.md as deliverables. The price exports are in /workspace/exports. Keep scratch work in /workspace/scratch."
      }'
    ```
  </Tab>
</Tabs>

The API answers `202 Accepted`:

```json theme={"theme":"css-variables"}
{
  "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "status_path": "/managed-agents/v1/sessions/b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38"
}
```

In the transcript, the agent's `write_artifact` call answers with the path and "it is captured as a session output when this turn ends". A call that includes `metadata` answers that the file was stored as a session output instead. When the session finishes, [download the deliverables](#download-deliverables).

<Tip>
  Keep scratch work out of the deliverables folder. Everything in it is kept, so intermediate files there clutter the result and count toward the per-turn limits.
</Tip>

<Accordion title="Prompt patterns that work">
  | Where | Pattern |
  | - | - |
  | Agent system prompt | "When a task asks for a report, save it as a Markdown deliverable named after the task, and put your working notes in `/workspace/scratch`." |
  | Task message | "Save the comparison as `vendor-comparison.md` with one table row per vendor." |
  | Done criteria | "You're done when `vendor-comparison.md` is saved as a deliverable and has a row for each of the three vendors." |
  | Many outputs | "Save each chart as a PNG under `charts/` in the deliverables and share the most important one." |
</Accordion>

### Label deliverables with metadata

An agent can attach key/value `metadata` when it calls `write_artifact`, for example `{"kind": "report", "ticket": "OPS-12"}`. The metadata is stored on the deliverable's file, returned as `metadata` beside `path` when you list or get the file, and shown under **Metadata** in the file preview. Ask for it in the task: "Save `summary.md` with metadata `kind` set to `summary` and `quarter` set to `Q3`."

Later sessions of the same agent can find deliverables by their metadata when the agent has **File history** on. See [Agent file history](/recursion/agent-file-history).

<Accordion title="Metadata rules">
  * A write that includes `metadata` is kept at once rather than at the end of the turn, so it doesn't count toward the per-turn limits.
  * A write that includes `metadata` replaces the deliverable's earlier metadata, and `{}` clears it. A write that leaves it out keeps it.
  * The metadata stays when the file is changed later by another tool or command.
  * The rules are the same as for uploaded files: at most 32 keys, each up to 64 characters of letters, digits, `_`, `.`, and `-`, and at most 64 KiB of JSON in total. The `path` key is reserved.
</Accordion>

## Show images inline

Ask the agent to share a chart or screenshot: "Plot weekly signups and share the chart." The agent saves the image under `/workspace` and calls `share_file`.

<Tabs>
  <Tab title="Console">
    1. In the sidebar, click **Sessions**, then open the session.
    2. Find the `share_file` row in the transcript and click the thumbnail.

    The image opens at full size, with its caption and path, and you can page through every image in the session.
  </Tab>

  <Tab title="cURL">
    Through the API, a shared image is an `artifact` event. List events with `image_urls=signed` to add a short-lived `url` to each image block.

    ```bash theme={"theme":"css-variables"}
    curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38/events?image_urls=signed' \
      -H "Authorization: Bearer $RECURSION_API_KEY"
    ```
  </Tab>
</Tabs>

In the console, the transcript row for a shared image shows a thumbnail. Through the API, the `artifact` event carries the caption and the image.

<Accordion title="What an image event looks like">
  ```json theme={"theme":"css-variables"}
  {
    "event_id": "0192d4f1-8c3e-7a5b-b1d0-4e6f2a9c7d58",
    "event_type": "artifact",
    "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
    "tool_name": "share_file",
    "created_at": "2026-09-25T17:21:40Z",
    "content": {
      "blocks": [
        {"type": "text", "text": "Weekly signups, last 12 weeks"},
        {
          "type": "image",
          "media_type": "image/png",
          "width": 1280,
          "height": 720,
          "byte_size": 84211,
          "uri": "<private image URI>",
          "url": "<short-lived image URL>",
          "url_expires_at": "2026-09-25T17:36:40Z"
        }
      ],
      "metadata": {
        "artifact_kind": "sandbox_file",
        "path": "/workspace/charts/signups.png",
        "caption": "Weekly signups, last 12 weeks",
        "media_type": "image/png",
        "byte_size": 84211,
        "width": 1280,
        "height": 720
      }
    }
  }
  ```

  A signed `url` is omitted when none can be issued for that read. The image is always available through the authenticated session image endpoint, `GET /managed-agents/v1/sessions/{sessionId}/images`, with the image block's `uri` as the `uri` query parameter.
</Accordion>

## Download deliverables

Every kept deliverable is a file in your organization's library with `source: "session_output"`, listed under the root session, including deliverables that subagents and teammates saved.

Open the session and choose the **Files** tab in the side panel. **Outputs** shows each deliverable with its path under the deliverables folder. Click it to preview it, and download it from the preview. Through the API, list a session's deliverables with `listFiles` and `scope_session_id`, then download each with `getFileContent`. See [Download session deliverables](/recursion/files#download-session-deliverables).

Each output keeps its path under the deliverables folder, such as `reports/q3.md`. Saving to the same path again replaces the earlier version at the end of the turn, or at once when the `write_artifact` call includes `metadata`.

<Accordion title="Other ways to use results">
  | Method | How |
  | - | - |
  | The final message | Ask the agent to end with the key result, for example "End with the five largest increases as a table." Read it in the transcript or from the session's events. |
  | Inline images | Ask the agent to `share_file` charts and screenshots. |
  | A follow-up session | Start a new session that references this one. It can list and read the earlier session's deliverables. See [Referenced sessions](/recursion/referenced-sessions). |
  | Your own storage or repository | Grant a credential for your storage, repository host, or API in a vault, allow its host in the environment's network policy, and ask the agent to upload or push the file. See [Vaults](/recursion/vaults). |
</Accordion>

## Where work happens

| Path | What it's for |
| - | - |
| `/workspace` | The agent's workspace. Repositories, scratch files, and build output go here. The session keeps these files after its sandbox stops or is released; they can be used when its workspace reopens. |
| `/workspace/.managed-agents/outputs` | Deliverables. Every file in this folder is kept with the session. |

Files outside the deliverables folder stay in the session workspace for later turns when it reopens, but aren't saved separately as deliverables or shown in the **Files** tab. Deleting the session removes access to its workspace.

<Accordion title="Tools you'll see in transcripts">
  Agents use these tools on their own. You can also name them in prompts.

  | Tool | What it does |
  | - | - |
  | `write_artifact` | Writes a deliverable. Takes a `path` relative to the deliverables folder, such as `report.md` or `tables/prices.csv`, non-empty text `content`, and optional `metadata`. |
  | `read_artifact` | Reads a deliverable back by the same relative path. |
  | `write_file` | Writes any file in the sandbox by absolute path, such as `/workspace/notes.md`. Use it for scratch work. |
  | `read_file` | Reads a file in the sandbox. PNG, JPEG, and WebP files come back as images the agent can see, when its model accepts images. |
  | `share_file` | Shows a PNG, JPEG, or WebP file from the sandbox to you inline in the session, with an optional one-line caption. The agent doesn't see the image again. |

  `write_artifact` takes text. For a binary deliverable, such as a PDF or a spreadsheet, the agent creates the file with a command and saves it anywhere under `/workspace/.managed-agents/outputs`. Files placed there by any tool are kept the same way.
</Accordion>

## What gets kept

At the end of each turn, once the agent stops and nothing is queued, the deliverables folder is checked and every new or changed file is kept. A file that can't be kept is reported as a warning; the session keeps running.

<Accordion title="How files are kept">
  * **Changes.** A file saved again under the same path replaces the earlier version. A file that hasn't changed isn't kept twice.
  * **Children.** Subagents and teammates share the root's sandbox, so their deliverables count as the root session's deliverables.
  * **Problems are reported, not fatal.** A file that can't be kept adds a `session_status` event with `event_status` `warning`, the code `session_output_degraded`, and a message naming the file. The session keeps running. A file refused once is not reported again until it changes.
  * **Earlier versions survive a bad rewrite.** If a kept file is later emptied, grows past the size limit, or becomes unreadable, the earlier kept version stays.
</Accordion>

### Limits

One deliverable can be at most 1 GiB on managed computes or 64 MiB on self-hosted workers. Each turn keeps at most 200 files and normally 512 MiB. A single file over the turn byte budget can still be kept as the first file of that turn. Files that wait for a later turn are kept only if the session has one.

<Accordion title="Every deliverable limit">
  | Limit | Value | What happens past it |
  | - | - | - |
  | Size of one file | 1 GiB on managed computes; 64 MiB on self-hosted workers | The file isn't kept, and a warning names it. |
  | Files kept per turn | 200 | The rest wait for the end of the next turn. |
  | Bytes kept per turn | 512 MiB | The rest wait for the end of the next turn. |
  | Files in the folder | 10,000 | Only the first 10,000 are considered each turn. |
  | File name | 255 characters, no control characters | The file isn't kept, and a warning names it. |
  | Empty file | Not allowed | `write_artifact` refuses it; a file made another way isn't kept, and a warning names it. |
  | Images shown with `share_file` | PNG, JPEG, or WebP; up to 5 MiB, 8,192 pixels on a side, and 40 megapixels | The tool call fails and the agent is told why. |

  A session also has an overall image budget, shared by every tool that returns images, of 500 images and 100 MiB. See [Limits](/recursion/limits).
</Accordion>

## What can go wrong

The most common problems:

* **A deliverable is missing from the Files tab.** It was saved outside the deliverables folder. Ask for it by name as a deliverable, or save it under `/workspace/.managed-agents/outputs`.
* **`session_output_degraded` warning about the per-file limit.** A deliverable exceeds the limit for its compute provider. Split or compress the file.
* **`share_file` fails with "supports PNG, JPEG, and WebP images".** The file is another format, such as SVG or PDF. Ask the agent to render a PNG first.

<Accordion title="Every deliverable error">
  | Symptom or message | Cause | Fix |
  | - | - | - |
  | "content is empty; an artifact must hold something" | `write_artifact` was called with empty content. | Ask the agent to write the file's content. |
  | "is an absolute path, which is a sandbox file" | `write_artifact` got an absolute path outside the deliverables folder. | Use a relative path such as `report.md`, or save with `write_file` if it's scratch. |
  | "must be a plain relative path with no . or .. segments" | The path contains `..`, `./`, a doubled slash, or a trailing slash. | Use a clean relative path such as `reports/q3.md`. |
  | "cannot be a file name" | The last part of the path is empty, too long, or has control characters. | Use a short, printable file name. |
  | "metadata key "path" is reserved" | `write_artifact` got `metadata` with a `path` key, which the platform uses for the deliverable's path. | Use another key name. |
  | `session_output_degraded` warning: "over the 1024 MiB limit" or "over the 64 MiB limit" | A deliverable exceeds the 1 GiB managed-compute limit or the 64 MiB self-hosted limit. | Split or compress the file. |
  | `session_output_degraded` warning: "is empty" | A file in the deliverables folder has no content. | Remove it or write its content. |
  | "The container changed during the artifact write" | The sandbox changed during the write. The file may or may not have been written. | Check whether the file was written before writing it again. For more sandbox work, start a new session. |
  | A deliverable isn't in the **Files** tab | It was saved outside the deliverables folder. | Ask for it by name as a deliverable, or save it under `/workspace/.managed-agents/outputs`. |
  | `share_file` fails with "supports PNG, JPEG, and WebP images" | The file is another format, such as SVG or PDF. | Ask the agent to render a PNG first. |
</Accordion>

## Next steps

<CardGroup cols={2}>
  <Card title="Files" href="/recursion/files">
    Attach input files and download session outputs.
  </Card>

  <Card title="Referenced sessions" href="/recursion/referenced-sessions">
    Read an earlier session's deliverables from a new one.
  </Card>

  <Card title="Teams" href="/recursion/teams">
    Have several agents produce parts of one deliverable.
  </Card>

  <Card title="Research team tutorial" href="/recursion/use-cases/research-team">
    A team session that ends in a report.
  </Card>
</CardGroup>