> ## 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.
# Agent file history
> Let an agent's sessions search and read the deliverables its earlier sessions saved, by path, metadata, date, and text.
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](/managed-agents/organizations-and-roles).
* Deliverables are what a history holds. See [Deliverables and artifacts](/managed-agents/artifacts).
## How it works
```mermaid theme={"theme":"css-variables"}
flowchart LR
earlier["Earlier session saves a deliverable"] --> history["Agent's file history"]
history --> search["New session calls search_agent_files"]
search --> read["read_agent_file on the files that matter"]
```
* **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
1. In the sidebar, click **Agents** and open the agent.
2. On **Configuration**, under **Tools**, select **File history**.
3. 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](/managed-agents/agents#update-an-agent). A field left out of a new version is cleared.
```bash theme={"theme":"css-variables"}
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](/managed-agents/artifacts#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
1. In the sidebar, click **Agents** and open the agent.
2. Click **Files**.
3. Search file contents, filter by path or metadata, and click a file to preview or download it.
```bash theme={"theme":"css-variables"}
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:
```json theme={"theme":"css-variables"}
{
"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. |
## Next steps
Save deliverables and label them with metadata.
Read specific earlier sessions' transcripts and deliverables.