> ## 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, before any grading, so the grader and later sessions can use them. The TypeScript samples assume the `rl` client from [Client setup](/managed-agents/api#client-setup). ## Before you begin * To start sessions, you need the Developer or Admin role in the organization. See [Organizations and roles](/managed-agents/organizations-and-roles). * Every session runs in an environment's sandbox. See [Environments](/managed-agents/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. ```mermaid theme={"theme":"css-variables"} flowchart LR ask["You ask for a named deliverable"] write["Agent writes it to the deliverables folder"] turnEnd["The turn ends"] kept["Deliverables are kept with the session"] graded["The outcome is graded"] use["You read the result"] ask --> write --> turnEnd --> kept --> graded --> use graded -->|"needs revision"| write ``` ## 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. 1. In the sidebar, click **Sessions**, then click **Launch session**. 2. Choose the **Agent** and **Environment**. 3. Under **Task**, select **Grade this session against a rubric**. 4. In **Rubric**, list the checks, including the file names. 5. In **Opening message**, describe the task and name the deliverables. 6. Click **Launch session**. ```typescript theme={"theme":"css-variables"} 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.', }, }, }); ``` ```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": "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`: ```json theme={"theme":"css-variables"} { "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](/managed-agents/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. 1. In the sidebar, click **Sessions**, then open the session. 2. Find the `share_file` row in the transcript and click the thumbnail. ```typescript theme={"theme":"css-variables"} 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'); ``` ```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" ``` An `artifact` event carries the caption and the image: ```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": "", "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. 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**. ```typescript theme={"theme":"css-variables"} const { files } = await rl.managedAgents.listFiles({ source: 'session_output', scope_session_id: 'b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38', }); ``` ```bash theme={"theme":"css-variables"} 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](/managed-agents/files#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](/managed-agents/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](/managed-agents/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](/managed-agents/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 Grade deliverables against a rubric. Read an earlier session's deliverables from a new one. Have several agents produce parts of one deliverable. A team session that ends in a graded report.