• Frontmatter
  • What parses
  • When it doesn't parse
  • Reading it back
• Bulk import
• Records API
• Search Query Fields

An agent file is a single file stored inside an agent filesystem volume.

In normal use you don't create or edit these records directly. Files are written through the filesystem command set – by an AI agent using its agent_terminal tool, or by a worker in Setup » Developers » Agent Filesystem Terminal. The record type exists so files are searchable, linkable, and reportable like any other record.

Frontmatter

A Markdown file can open with a --- fenced YAML block. It's parsed and stored separately in frontmatter_json, which lets a volume of documents carry structured metadata – a title, tags, an owner – that can be listed without opening each file.

/runbooks/refund.md:

---
title: Refund a customer
description: How to issue a refund and notify the customer.
tags:
  - billing
  - support
version: 3
reviewed: 2026-07-14
is_public: false
owner:
  team: Support
  email: support@example.com
---

# Refund a customer

1. Open the ticket and confirm the charge in the billing portal.
2. Issue the refund.

That file's frontmatter_json (stored minified, shown here expanded):

{
  "title": "Refund a customer",
  "description": "How to issue a refund and notify the customer.",
  "tags": ["billing", "support"],
  "version": 3,
  "reviewed": "2026-07-14",
  "is_public": false,
  "owner": { "team": "Support", "email": "support@example.com" }
}

Values keep their YAML types: version is a number, is_public is a boolean, a list becomes an array, and a nested map becomes a nested object. Dates are the exception – reviewed stays a string.

What parses

When it doesn't parse

Nothing happens, and that's the thing to know: a malformed block, a block below line 1, or an unsupported extension stores frontmatter_json as null. The file still saves normally, with no error and no warning. If you added frontmatter and nothing came of it, this is why – check the extension first, then the position.

Reading it back

There's no frontmatter: search filter, and no content: filter either, so this metadata isn't something you can query a worklist by. It's read through the filesystem commands instead:

ls /runbooks --fields title,tags

--fields prints per-key values as columns without opening any file, on both ls and find. A list joins with commas; a nested map joins its values. A missing key prints empty – and so does a false boolean, which makes the two indistinguishable in a listing.

Piped rows carry the decoded map as meta, which is always a map and empty rather than absent when a file has no frontmatter – so a fallback is safe across a volume where only some files carry it:

search refund | results|map(r => r.meta.title ?? r.path)

In scripting, the frontmatter_json placeholder is the raw JSON string rather than a map, so there's no per-key access through it.

The field is also writable through the Records API, and an explicit value wins over the one parsed from the content – so it's possible, deliberately or otherwise, for the stored metadata to disagree with the file it describes.

Bulk import

Files arrive in bulk by uploading a ZIP archive to a volume, which is imported in the background as a queue job. Each import is tracked so a volume's card can show the history of past imports.

Records API

These fields are available in the Records API and packages:

Search Query Fields

These filters are available in agent file search queries: