Deliverables and artifacts

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.

To start sessions, you need the Developer or Admin role in the organization. See Organizations and roles. Every session runs in an environment’s sandbox. See Environments.

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.

Console
cURL

In the sidebar, click Sessions, then click Launch session.
Choose the Agent and Environment.
In Opening message, describe the task and name the deliverables.
Click Launch session.

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:

{
  "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.

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.

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.

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.

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.

Console
cURL

In the sidebar, click Sessions, then open the session.
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.

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.

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.

What an image event looks like

{
  "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. 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.

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

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.

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. A file that can’t be kept is reported as a warning; the session keeps running.

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.

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.

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.

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.

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.

Next steps

Files

Attach input files and download session outputs.

Referenced sessions

Read an earlier session’s deliverables from a new one.

Teams

Have several agents produce parts of one deliverable.

Research team tutorial

A team session that ends in a report.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Deliverables and artifacts

Ask for a deliverable

Label deliverables with metadata

Show images inline

Download deliverables

Where work happens

What gets kept

Limits

What can go wrong

Next steps

Files

Referenced sessions

Teams

Research team tutorial

​Ask for a deliverable

​Label deliverables with metadata

​Show images inline

​Download deliverables

​Where work happens

​What gets kept

​Limits

​What can go wrong

​Next steps

Files

Referenced sessions

Teams

Research team tutorial

Ask for a deliverable

Label deliverables with metadata

Show images inline

Download deliverables

Where work happens

What gets kept

Limits

What can go wrong

Next steps