# agent-file: The .af Format for Portable, Stateful AI Agents

> Agent File (.af) is an open file format from letta-ai for serializing stateful AI agents. A single .af file packages the system prompt, editable memory blocks, tool definitions with source code, model configuration, and complete message history, making it possible to share, checkpoint, and import agents via the Letta server's ADE, REST API, or Python and TypeScript SDKs.

**letta-ai/agent-file** — Agent File (.af): An open file format for serializing stateful AI agents with persistent memory and behavior. Share, checkpoint, and version control agents across compatible frameworks.

- Repository: https://github.com/letta-ai/agent-file
- Website: https://agentfile-directory.vercel.app
- Stars: 1,201 · Forks: 117
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/letta-ai-agent-file

## What Agent File Solves for AI Agent Developers

A stateful AI agent accumulates configuration that is hard to move: a system prompt that defines its behavior, memory blocks that hold what it has learned about the user, tool definitions including source code and JSON schemas, the specific model and context-window settings it was tuned against, and the complete message history of its interactions. Most frameworks store this state in their own proprietary formats or in a running server's database. Moving an agent between environments, sharing it with another developer, or rolling back to a previous version requires framework-specific tooling.

Agent File (.af) is letta-ai's attempt at a standard that packages all of these components into a single portable file. The goal is to make agents as shareable as code: you export a .af file, share it, and the recipient imports it into a compatible server without reconstructing the agent's configuration by hand. The format is designed primarily for the Letta framework but is defined as an open standard so other frameworks can implement import and export if they choose.

## What a .af File Contains

The README documents the schema components:

- Model configuration: context window limit, model name, and embedding model name
- Message history: the complete chat history with an in_context field indicating whether each message is currently in the context window
- System prompt: the initial instructions that define the agent's behavior
- Memory blocks: in-context memory segments for personality, user information, and other editable content that the agent updates over time
- Tool rules: definitions of how tools should be sequenced or constrained
- Environment variables: configuration values needed for tool execution
- Tools: complete tool definitions including source code and the JSON schema

The full Pydantic schema is maintained in the main Letta repository at letta/serialize_schemas/pydantic_agent_schema.py. The README notes that Passages (the units of Archival Memory in the Letta/MemGPT lineage) are not currently included but are on the roadmap.

The file format is TypeScript-based in the repository's implementation, and the agent directory follows a conventional path structure:

```text
agents/
└── @{owner}/
    └── {agent-name}/
        ├── {agent-name}.af
        └── {agent-name}.webp
```

## Importing a .af File into a Letta Server

Deployment assumes a running Letta server. With the server running at http://localhost:8283, three import paths are available.

Using the Python SDK:

```python
# Install SDK with `pip install letta-client>=1.0.0`
from letta_client import Letta

client = Letta(base_url="http://localhost:8283")
agent_state = client.agents.import_file(file=open("/path/to/agent/file.af", "rb"))
print(f"Imported agent: {agent_state.id}")
```

Using the TypeScript SDK:

```typescript
// Install SDK with `npm install @letta-ai/letta-client@^1.0.0`
import { LettaClient } from '@letta-ai/letta-client'
import { readFileSync } from 'fs';
import { Blob } from 'buffer';

const client = new LettaClient({ baseUrl: "http://localhost:8283" });
const file = new Blob([readFileSync('/path/to/agent/file.af')])
const agentState = await client.agents.importFile(file, {});
console.log(`Imported agent: ${agentState.id}`);
```

Using cURL directly:

```sh
curl -X POST "http://localhost:8283/v1/agents/import" -F "file=/path/to/agent/file.af"
```

To export an existing agent, the ADE has an Export Agent button. The API endpoint is a GET request to /v1/agents/{AGENT_ID}/export. The Python and TypeScript SDKs expose client.agents.export_file(agent_id="<AGENT_ID>") and client.agents.exportFile("<AGENT_ID>") respectively.

## Contributing Agents to the Community Directory

The repository doubles as a public directory of trained and tuned agents. As of the README, the only featured agent is Loop, from @letta-ai, described as a ChatGPT alternative focused on memory that is direct, dry, and remembers everything. The directory structure places contributed agents under agents/@{github-handle}/{agent-name}/.

Contributing requires forking the repository, creating the agent directory, exporting the .af file from Letta, adding a square .webp avatar, and submitting a pull request. The detailed guidelines are in agents/CONTRIBUTING.md. The agentfile-directory website at agentfile-directory.vercel.app hosts a browsable interface for the directory.

## Framework Support and the Portability Limitation

The README FAQ addresses the framework question directly: theoretically, other frameworks could implement .af import by mapping Agent File components to their own representations. The caveat is that some concepts in .af, specifically the context window blocks that can be edited or shared between agents, do not exist in most other frameworks and would need adaptation.

In practice, this means .af portability is real within the Letta ecosystem and theoretical outside it. A developer who exports a .af file from a Letta server and wants to import it into a LangChain or AutoGen workflow cannot do so today without writing the mapping code themselves. The README does not document any third-party framework that has implemented .af support. Teams evaluating .af as a cross-framework standard should treat it as a format defined by one framework's architecture, not an independently ratified specification.

## Maintenance Status and Schema Stability

The last push to this repository was on 2026-03-24. The repository has no GitHub releases and no versioned changelog. The schema is defined by the Pydantic model in the main Letta repository, which is maintained separately. Changes to the Letta framework's internal agent representation could change what a .af file contains without a corresponding commit to the agent-file repository.

The Passages (Archival Memory) gap noted in the README is a concrete limitation: an agent that uses long-term archival memory cannot be fully serialized into a .af file today. The README states this has support planned. Developers building tooling that reads or writes .af files should verify the current schema against the Pydantic source at the time of development, since the README's table of components may not reflect all fields present in exported files.

## Compared to OpenAI's Custom GPTs for Agent Sharing

OpenAI's Custom GPTs provide a way to create, configure, and share agents through a hosted interface. The sharing model is URL-based: you publish a GPT and share a link. The configuration (instructions, capabilities, actions) is stored on OpenAI's servers, so the recipient accesses the agent through OpenAI's platform rather than owning a file they can deploy or modify.

Agent File's approach is fundamentally different: the agent is a file you hold, move, and control. You can store it in a repository, inspect its contents, diff two versions, and import it into your own server. The trade-off is that you also need to run a Letta server to use the file, rather than pointing someone at a URL. For teams that need data ownership, air-gapped deployment, or framework-level access to the agent's internal state, .af is the more flexible approach. For teams who want the easiest sharing experience and are comfortable with OpenAI's platform, Custom GPTs require no server to operate.

## Conclusion

Developers working within the Letta ecosystem who want to share tuned agents with colleagues, checkpoint agent state for later resumption, or version-control an agent's personality and memory over time will find the .af format the most direct way to do that. Teams working in other frameworks should verify that their framework implements .af import before treating the format as framework-agnostic: as of the repository's own FAQ, only Letta ships an implementation. The last push to the repository was on 2026-03-24. Check docs.letta.com for the current state of the schema before building tooling that depends on it.

## FAQ

### What is an agent file (.af)?

An agent file (.af) is an open file format from letta-ai that packages all the state needed to recreate a stateful AI agent: the system prompt, memory blocks, tool definitions with source code, model configuration, and complete message history. It is designed for sharing, checkpointing, and version-controlling agents.

### What is the difference between an agent file and a SKILL file?

An agent file (.af) serializes a complete stateful agent, including its memory, tools, and message history, for portability and sharing. A SKILL file (as used in Agent Skills systems) contains instructions for one phase of a workflow and is read by an AI coding agent to guide its behavior. They serve different purposes: .af files capture agent state, while skill files are instructions for an agent to follow.

### What is an AI agent file and how do I use it?

An AI agent file in the context of agent-file is a .af file exported from a Letta server. To use it, run a Letta server, then import the file via the ADE drag-and-drop interface, the REST endpoint /v1/agents/import, or the Python or TypeScript SDK client.agents.import_file call.

## Sources

- [Issues](https://github.com/letta-ai/agent-file/issues)
- [letta-ai/agent-file on GitHub](https://github.com/letta-ai/agent-file)
- [License: Apache-2.0](https://github.com/letta-ai/agent-file/blob/main/LICENSE)
- [Project website](https://agentfile-directory.vercel.app)
- [README](https://github.com/letta-ai/agent-file/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/letta-ai-agent-file