Agent file history

An agent’s file history is every deliverable its sessions saved: files written with write_artifact or placed in the deliverables folder, including those saved by the sessions’ subagents and teammates. Turn on File history for an agent, and each new session can search that history and read what it finds, so work from earlier runs is not lost or redone.

Before you begin

You need the Developer or Admin role to change an agent. The User role can view an agent’s Files tab. See Organizations and roles.
Deliverables are what a history holds. See Deliverables and artifacts.

How it works

The history belongs to the agent. A deliverable is kept in the history of the agent the session was started from, including deliverables saved by its subagents, teammates, and other agents it delegated to. Those helpers search the same history while they work in that session. A session started from another agent never sees it, and neither does an outcome grader.
Sessions search on demand. A session is told the history exists, but no files are loaded into it up front. The agent decides when a search is worth making.
Earlier sessions only. A session sees deliverables saved before it started, not its own work in progress.
Current access is checked every time. A deleted file, a deleted session’s deliverables, and deliverables of sessions with restricted access are left out. Turning File history off stops the next search of every running session.

Turn on file history

Console
cURL

In the sidebar, click Agents and open the agent.
On Configuration, under Tools, select File history.
Click Save.

fileHistoryEnabled is one more field of the definition. Send it in createAgent, or in createAgentVersion together with every other field and the current base_agent_version_id, as in Update an agent. A field left out of a new version is cleared.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/versions' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "base_agent_version_id": "e82b5d19-7c40-4a6f-91d3-3f5a2c8b0e64",
    "name": "Quarterly analyst",
    "model": "anthropic/claude-sonnet-5",
    "system": "You write the quarterly finance report.",
    "fileHistoryEnabled": true
  }'

Sessions started after the change get the tools. Sessions already running keep the tools they started with, but a search fails once the setting is off.

Make deliverables easy to find

Metadata makes a search exact. Ask the agent to label what it saves:

Where	Pattern
Agent system prompt	”Save each report with `write_artifact` and metadata `kind`, `quarter`, and `status`.”
Task message	”Save the review as `reviews/acme.md` with metadata `customer_id: acme` and `status: draft`.”

A search can then ask for kind equal to report and quarter equal to Q3 and get exactly those files. See Label deliverables with metadata.

What a session can do

The session’s agent uses two tools. You can also name them in prompts, for example “Search your file history for last quarter’s report before writing this one.”

Tool	What it does
`search_agent_files`	Finds files by `pathPrefix`, `filenamePrefix`, `mediaTypes`, `rootSessionIds`, a `createdAt` range, metadata conditions, and `text` found in the file. Without conditions it lists the newest files.
`read_agent_file`	Reads one file a search returned, by `file_id`. Text comes back in windows; images are shown.

Metadata conditions

Each condition names a top-level metadata key, an op, and usually a value. All conditions must hold.

`op`	Matches
`eq`	The stored value equals `value`, which is required. `null` matches a stored `null`, not a missing key.
`in`	The stored value equals any value in an array.
`exists`	The key is present, whatever its value, `null` included.
`gt`, `gte`, `lt`, `lte`	Numbers compared with numbers, and strings with strings.

Values are never converted between types: "3" does not match 3, and true does not match "true". Nested objects and arrays are stored and returned but are not compared.

Text search

text finds words in the contents of text files: Markdown, plain text, JSON, CSV, YAML, code, and similar. All words must appear; put a phrase in quotes, write OR between words to match either, and prefix a word with - to exclude it. Results can be ranked by relevance instead of newest first, and each result carries a short snippet. Some files can’t be text-searched in full: images, PDFs, and other binary formats, and text beyond the first 1 MiB of a file. The result’s coverage says how many candidates were not fully searched, so an empty result is never mistaken for a complete one. Set strictContent to fail instead when coverage is partial.

Pages

Results come in pages of up to 100 (20 by default, 50 for a session’s tool), newest first unless ranked by relevance. Every page reads the same snapshot, named by asOf: files saved after the first page are not added part-way through. Pass nextCursor back with an otherwise unchanged request for the next page. total counts the snapshot’s matches under current access, so a file deleted between pages lowers it. A cursor expires after an hour.

Browse an agent’s files

Console
cURL

In the sidebar, click Agents and open the agent.
Click Files.
Search file contents, filter by path or metadata, and click a file to preview or download it.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/files/search' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "pathPrefix": "reports/",
      "metadata": [
        {"key": "kind", "op": "eq", "value": "report"},
        {"key": "quarter", "op": "in", "value": ["Q2", "Q3"]}
      ]
    },
    "text": "revenue",
    "sort": "relevance",
    "limit": 20
  }'

The response lists the matching files with the session that saved each one:

{
  "items": [
    {
      "fileId": "8f966221-d636-4cd2-b905-ade8341e8844",
      "path": "reports/q3.md",
      "filename": "q3.md",
      "mediaType": "text/markdown",
      "byteSize": 4210,
      "sha256": "…",
      "metadata": {"kind": "report", "quarter": "Q3"},
      "ownerAgentId": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
      "rootSessionId": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
      "createdAt": "2026-09-25T17:21:40Z",
      "contentState": "indexed",
      "snippet": "…Revenue grew twelve percent over the quarter…"
    }
  ],
  "nextCursor": null,
  "total": 1,
  "asOf": "2026-09-28T02:40:00Z",
  "coverage": {"metadata": "complete", "content": "complete"}
}

GET /managed-agents/v1/agents/{agentId}/files/{fileId} returns one file of the history.

What can go wrong

Symptom or message	Cause	Fix
A session has no `search_agent_files` tool	File history was off when the session started.	Turn it on and start a new session.
”file history was turned off for this agent”	The setting was turned off while the session ran.	Turn it back on; the session’s next search works.
A file saved in this session is not found	A session sees only files saved before it started.	Use `read_artifact` for the session’s own deliverables.
`400` on a `filter` field, `text`, `sort`, or `limit`	A condition is malformed or repeated, `eq` has no `value`, an array filter is empty or repeats a value, or `path` is used as a metadata key.	Fix the named field; filter paths with `pathPrefix`.
`400` on `cursor`	The cursor belongs to a different request or has expired.	Repeat the search without a cursor.
`422` `content_index_incomplete`	`strictContent` was set and some candidates could not be text-searched.	Search without `strictContent`, or narrow the search to text files.
`404` for a file	The file is not in this agent’s history: another agent’s file, a deleted file, or a deleted or restricted session.	Search the history for the file you want.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Agent file history

Before you begin

How it works

Turn on file history

Make deliverables easy to find

What a session can do

Metadata conditions

Text search

Pages

Browse an agent’s files

What can go wrong

Next steps

Deliverables and artifacts

Referenced sessions

​Before you begin

​How it works

​Turn on file history

​Make deliverables easy to find

​What a session can do

​Metadata conditions

​Text search

​Pages

​Browse an agent’s files

​What can go wrong

​Next steps

Deliverables and artifacts

Referenced sessions

Before you begin

How it works

Turn on file history

Make deliverables easy to find

What a session can do

Metadata conditions

Text search

Pages

Browse an agent’s files

What can go wrong

Next steps