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, before any grading, so the grader and later sessions can use them. The TypeScript samples assume the rl client from Client setup.

Before you begin

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.

Where work happens

Path	What it’s for
`/workspace`	The agent’s workspace. Repositories, scratch files, and build output go here. It persists across turns while the sandbox exists.
`/workspace/.managed-agents/outputs`	Deliverables. Every file in this folder is kept with the session.

Anything outside the deliverables folder stays in the sandbox and isn’t kept when the sandbox is deleted.

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`, and non-empty text `content`.
`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.

Ask for a deliverable

Name the file and its format in the task, and name it again in the rubric so grading checks it. This session asks for a CSV and a short summary, and is graded on both.

Console
TypeScript
cURL

In the sidebar, click Sessions, then click Launch session.
Choose the Agent and Environment.
Under Task, select Grade this session against a rubric.
In Rubric, list the checks, including the file names.
In Opening message, describe the task and name the deliverables.
Click Launch session.

const started = await rl.managedAgents.startSession({
  'Idempotency-Key': 'q3-price-audit-2026-09-25',
  body: {
    agent_id: '5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55',
    environment_id: '9d3e7b52-1a4c-4f80-b6e9-2c8a5d0f7e13',
    message: 'The price exports are in /workspace/exports. Keep scratch work in /workspace/scratch.',
    outcome: {
      description: 'Audit the Q3 price exports. Save price-changes.csv and summary.md as deliverables.',
      rubric: '- price-changes.csv is a deliverable with columns sku, old_price, new_price, change_pct.\n- Every row has a numeric change_pct.\n- summary.md is a deliverable that names the five largest increases.',
    },
  },
});

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": "The price exports are in /workspace/exports. Keep scratch work in /workspace/scratch.",
    "outcome": {
      "description": "Audit the Q3 price exports. Save price-changes.csv and summary.md as deliverables.",
      "rubric": "- price-changes.csv is a deliverable with columns sku, old_price, new_price, change_pct.\n- Every row has a numeric change_pct.\n- summary.md is a deliverable that names the five largest increases."
    }
  }'

The API answers 202 Accepted:

{
  "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "status_path": "/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”.

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.”
Rubric	”`vendor-comparison.md` is 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.”

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.

What gets kept

When. 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. This happens before the outcome is graded, so the grader sees the same files.
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

Limit	Value	What happens past it
Size of one file	64 MiB	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.

Files that wait for a later turn are kept only if the session has one, so keep a session’s deliverables under the per-turn limits. A session also has an overall image budget, shared by every tool that returns images, of 500 images and 100 MiB. See Limits.

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. In the console, the transcript row for a shared image shows a thumbnail. Click it to open the image at full size, with its caption and path, and 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.

Console
TypeScript
cURL

In the sidebar, click Sessions, then open the session.
Find the share_file row in the transcript and click the thumbnail.

const page = await rl.managedAgents.listSessionEvents({
  session_id: 'b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38',
  image_urls: 'signed',
});
const shared = (page.events ?? []).filter((event) => event.event_type === 'artifact');

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"

An artifact event carries the caption and the image:

{
  "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/{session_id}/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.

Console
TypeScript
cURL

Open the session and choose the Files tab in the side panel. Each output shows its path under the deliverables folder. Click it to preview it, or download it. Files in the sidebar lists outputs from every session under Session outputs.

const { files } = await rl.managedAgents.listFiles({
  source: 'session_output',
  scope_session_id: 'b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38',
});

curl 'https://api.recursion.labelbox.com/managed-agents/v1/files?source=session_output&scope_session_id=b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38' \
  -H "Authorization: Bearer $RECURSION_API_KEY"
curl 'https://api.recursion.labelbox.com/managed-agents/v1/files/5c1e8a3f-2d97-4b60-8e14-a6f3c9d2b7e05/content' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -o report.md

Each file’s metadata.path is its path under the deliverables folder, such as reports/q3.md, and filename is its last part. getFileContent returns the bytes with the file’s media type. Saving to the same path again replaces the earlier version at the end of the turn. See Download session deliverables.

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.
Grading	Name the deliverable in the rubric. A satisfied outcome means the grader found the file and judged that it meets every criterion. See Outcomes.
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.

What can go wrong

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.
`session_output_degraded` warning: “over the 64 MiB limit”	A deliverable is larger than 64 MiB.	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 doesn’t appear to the grader	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

Outcomes

Grade deliverables against a rubric.

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

Before you begin

Where work happens

Tools you’ll see in transcripts

Ask for a deliverable

Prompt patterns that work

What gets kept

Limits

Show images inline

Download deliverables

Other ways to use results

What can go wrong

Next steps

Outcomes

Referenced sessions

Teams

Research team tutorial

​Before you begin

​Where work happens

​Tools you’ll see in transcripts

​Ask for a deliverable

​Prompt patterns that work

​What gets kept

​Limits

​Show images inline

​Download deliverables

​Other ways to use results

​What can go wrong

​Next steps

Outcomes

Referenced sessions

Teams

Research team tutorial

Before you begin

Where work happens

Tools you’ll see in transcripts

Ask for a deliverable

Prompt patterns that work

What gets kept

Limits

Show images inline

Download deliverables

Other ways to use results

What can go wrong

Next steps