Agent File (.af): a serialization format for Letta agents, and what it does not carry

The problem: agent state lives inside one server and cannot be moved

Every agent framework stores its own state in its own shape. Prompts, memory, tool source code and conversation history sit in a database behind an API, and moving an agent to another machine means writing a migration script against an undocumented schema. Agent File is an attempt to name that state and put it in one file. The README frames it as an open standard for serializing stateful AI agents, originally designed for Letta and providing a portable way to share agents with persistent memory and behavior. The audience is narrow and specific: people already running a Letta server who want to checkpoint an agent, hand a configured agent to a colleague, or keep a directory of tuned agents under version control. It is not a runtime, a scheduler, or an orchestration layer. The repository is mostly a directory of example agents plus contribution rules, with the format itself defined elsewhere, in the Letta codebase.

What a .af file actually contains, component by component

The README lists the state a .af file carries. Model configuration covers the context window limit, model name and embedding model name. Message history is the complete chat history, and each message carries an in_context field indicating whether it currently sits inside the context window. That flag is the interesting part: the file preserves messages that have aged out of context, so restoring an agent does not silently discard the tail of a long conversation. Memory blocks hold in-context segments such as personality and user information. System prompt, tool rules, environment variables and full tool definitions (source code plus JSON schema) round out the list. The README describes this as all the state required to re-create the exact same agent, with one stated exception: Passages, the units of archival memory in Letta and MemGPT, are not supported and are on the roadmap. That exception matters more than its one-line treatment suggests. An agent with a large archival store will import with its in-context memory intact and its long-term recall gone.

Import and export: the four paths the README documents

The README gives four ways in. In the Agent Development Environment, download the .af file, open app.letta.com, click Import Agent and select the file. Over cURL, against a server at http://localhost:8283, run curl -X POST "http://localhost:8283/v1/agents/import" -F "file=/path/to/agent/file.af". In Python, with pip install letta-client>=1.0.0, construct Letta(base_url="http://localhost:8283") and call client.agents.import_file(file=open("/path/to/agent/file.af", "rb")), which returns an agent_state whose .id you can print. In TypeScript, with npm install @letta-ai/letta-client@^1.0.0, wrap the bytes in a Blob and call client.agents.importFile(file, {}). Export runs the other direction: GET /v1/agents/{AGENT_ID}/export, or client.agents.exportFile("<AGENT_ID>") in TypeScript, or client.agents.export_file(agent_id="<AGENT_ID>") in Python, each returning a serialized schema object you write to disk yourself. Note that every example assumes a server already running on port 8283. Agent File does not start one, and the repository does not document how to install Letta itself.

The directory layout is a convention, not a registry

Sharing happens through the repository, not through a package manager. The README specifies agents/@{owner}/{agent-name}/ containing {agent-name}.af and a square {agent-name}.webp avatar. Contributing means forking the repository, creating that path with your GitHub handle, exporting the agent, adding both files and opening a pull request, with agents/CONTRIBUTING.md holding the detailed rules. There is no versioning scheme for individual agents beyond git history on the file, and no dependency resolution between an agent and the tools it references. The README also points to a separate directory site at agentfile-directory.vercel.app and a schema viewer in the Letta repository at letta/serialize_schemas/pydantic_agent_schema.py. Treat the schema file as the authority: the README's component table is a summary, and a field that matters to you may be defined in the Pydantic model without appearing in the table.

Portability is the claim, and it is the weakest part

The pitch is transfer between compatible frameworks. The FAQ is more candid: other frameworks could load .af files if they convert the state into their own representations, and it notes that concepts such as context window blocks, which can be edited or shared between agents, are not implemented elsewhere. That is a real design constraint, not a documentation gap. Memory blocks are mutable in-context state with their own semantics; a framework without that concept has nowhere to put them. So the practical portability boundary today is a Letta server to a Letta server, or an export you keep as an archive. The README does not name any framework that has implemented a loader. If cross-framework migration is your reason for caring about this format, the repository does not currently support that reason.

Where it is the wrong tool, and what to use instead

If your goal is to move a prompt plus a tool list between providers, Agent File is heavier than you need, because it also carries message history, environment variables and tool source code, and it assumes a Letta server on the other end. A plain JSON or YAML configuration committed to your own repository does that job with no server dependency, and you control the schema. The real difference in approach: Agent File is a snapshot of runtime state, including the conversation and the in-context memory blocks, while a config file is a description of how to construct an agent from scratch. Snapshots are what you want for checkpointing a long-running agent or reproducing a bug report; construction files are what you want for deploying the same agent to ten environments. Agent File also does not address orchestration, scheduling, or multi-agent coordination. If you need those, this repository is not the layer that provides them, and nothing in the README suggests it intends to be.

Maintenance cost and the licence you are accepting

The repository is TypeScript, licensed Apache-2.0, not archived, with its most recent push dated 2026-03-24 and no releases retrieved. There is no package to upgrade on a schedule: you consume the format through the Letta server and the letta-client SDKs, so your maintenance burden tracks Letta's release cadence rather than this repository's. The README pins SDK versions at letta-client>=1.0.0 and @letta-ai/letta-client@^1.0.0, and the caret on the npm package means minor versions are accepted automatically, which is worth knowing before you freeze a pipeline around it. Apache-2.0 permits commercial use and modification and includes a patent grant, with the usual requirements around preserving notices and stating changes. None of that is legal advice; if you redistribute .af files containing third-party tool source code, the licence of that code is a separate question the repository does not answer.

Who should adopt this, and the first thing to verify

Adopt it if you run Letta, you want to version agent configurations alongside code, and your agents' long-term recall lives in memory blocks rather than archival memory. Skip it if you need a framework-neutral interchange format, if your agents depend on Passages, or if you have no Letta server and no intention of running one, since every documented import path targets a running server. The first thing to verify is round-trip fidelity on your own agent: export it with client.agents.export_file(agent_id="<AGENT_ID>"), open the result, and check that your tool definitions, tool rules and environment variables are all present and that the in_context flags on your message history look right. Then import it into a fresh server and compare. The README's claim of re-creating the exact same agent is testable in an afternoon, and the Passages gap is the failure you are most likely to hit.

Editorial conclusion

Adopt Agent File if your agents already run on a Letta server and you want checkpoints, shared configurations, or a versioned directory of agents under agents/@{owner}/{agent-name}/. Do not adopt it as a cross-framework interchange format today: the README states that Passages are unsupported and that non-Letta support is only theoretical, since concepts like editable shared memory blocks have no counterpart elsewhere. Before committing, export one real agent and diff the resulting .af against the schema at letta/serialize_schemas/pydantic_agent_schema.py to confirm your tool definitions and environment variables survive the round trip.

Official sources

1. Issues
2. letta-ai/agent-file on GitHub
3. License: Apache-2.0
4. Project website
5. README