> ## 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](https://docs.labelbox.com/recursion/organizations-and-roles.md). Every session runs in an environment's sandbox. See [Environments](https://docs.labelbox.com/recursion/environments.md).

## 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.

> [tab] 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] 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."
>   }'
> ```

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 take time to save.

> [accordion] 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." |

### 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](https://docs.labelbox.com/recursion/agent-file-history.md).

> [accordion] Metadata rules
>
> * A write that includes `metadata` is kept at once rather than at the end of the turn, so it doesn't take time to save.
> * 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.

## 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`.

> [tab] 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] 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"
> ```

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] 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.

## 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](https://docs.labelbox.com/recursion/files.md#download-session-deliverables).

For a session an automation started, the [run's result](https://docs.labelbox.com/recursion/automations.md#get-a-runs-result) also lists its deliverables with their `fileId`s once the run is finished.

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] 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. |
> | A structured result | Give an automation a result file, and each run's result returns the JSON the agent saved there. See [Ask for a structured result](https://docs.labelbox.com/recursion/automations.md#ask-for-a-structured-result). |
> | 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](https://docs.labelbox.com/recursion/referenced-sessions.md). |
> | 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](https://docs.labelbox.com/recursion/vaults.md). |

## 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] 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.

## 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. While files are being saved, the session header shows **Saving files: 200 of 251**. Saving goes on in batches until every new or changed file is saved, for up to about ten minutes. If time runs out, a batch saves nothing, or a message arrives while files are saving, a warning in the transcript says how many files were saved and how many wait: for example, "Saved 1,300 of 1,351 files. The other 51 will be saved after the agent's next reply." A message sent while files are saving lets the batch in progress finish, then the agent starts its reply; the remaining files are saved when that reply ends. A file that can't be kept is reported as a warning; the session keeps running.

A file that can't be saved appears in **Outputs** as **Not saved**, with the reason in place of its size, for example **Not saved: 1.5 GiB is over the 1 GiB limit**. It has no download or preview, and an earlier saved copy of it is removed, so the **Files** page no longer lists it. Ask the agent to split or compress an oversized file. Once the file can be saved again, its row returns to normal.

> [accordion] 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.
> * **Progress.** While files save, the session adds `session_status` events with `event_status` `saving_files` and the counts `saved` and `total`, which cover only new or changed files: one when saving starts and at most one every 10 seconds after that. They are notices, not state changes: the session stays `running`. A turn with nothing new or changed adds none.
> * **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.
> * **No stale copies.** If a kept file is later emptied, grows past the size limit, or becomes unreadable, its earlier kept copy is removed. The **Outputs** row says why the current file was not saved.

### Limits

One deliverable can be at most 1 GiB on managed computes or 64 MiB on self-hosted workers. Each batch saves at most 200 files and normally 512 MiB. A single file over the batch byte budget can still be saved as its first file. More batches run while new or changed files remain, for about ten minutes; a batch already started may finish after that. Files that wait for a later turn are kept only if the session has one.

> [accordion] 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 saved per batch | 200 | Another batch runs, for up to about ten minutes per turn; the rest wait for the end of the next turn. |
> | Bytes saved per batch | 512 MiB | Another batch runs, for up to about ten minutes per turn; 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](https://docs.labelbox.com/recursion/limits.md).

## 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] 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 1 GiB 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: "the file 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. |

## Next steps

> [card] [Files](https://docs.labelbox.com/recursion/files.md)
>
> Attach input files and download session outputs.

> [card] [Referenced sessions](https://docs.labelbox.com/recursion/referenced-sessions.md)
>
> Read an earlier session's deliverables from a new one.

> [card] [Teams](https://docs.labelbox.com/recursion/teams.md)
>
> Have several agents produce parts of one deliverable.

> [card] [Research team tutorial](https://docs.labelbox.com/recursion/use-cases/research-team.md)
>
> A team session that ends in a report.
