---
title: AgentFile (.af) | Letta Docs
description: Define agent configurations as code using AgentFile
---

For a complete list of example agents, additional documentation, and to contribute to the AgentFile standard, visit the [AgentFile repository on GitHub](https://github.com/letta-ai/agent-file).

AgentFile (`.af`) is an open standard file format for serializing stateful agents. It provides a portable way to share agents with persistent memory and behavior across different environments.

You can import and export agents to and from any Letta server (including both Docker servers and the Letta API) using the `.af` file format.

[![AgentFile logo](https://github.com/letta-ai/agent-file/raw/main/assets/agentfile.png)](https://github.com/letta-ai/agent-file)

## What is AgentFile?

AgentFiles package all components of a stateful agent:

- System prompts
- Editable memory (personality and user information)
- Tool configurations (code and schemas)
- LLM settings

By standardizing these elements in a single format, AgentFile enables seamless transfer between compatible frameworks, while allowing for easy checkpointing and version control of agent state.

## Why Use AgentFile?

The AI ecosystem is experiencing rapid growth in agent development, with each framework implementing its own storage mechanisms. AgentFile addresses the need for a standard that enables:

- **Portability**: Move agents between systems or deploy them to new environments
- **Collaboration**: Share your agents with other developers and the community
- **Preservation**: Archive agent configurations to preserve your work
- **Versioning**: Track changes to agents over time through a standardized format
- **Testing**: Run reproducible evaluations by using agent files as [eval targets](/guides/evals/concepts/targets/index.md)

## What State Does `.af` Include?

A `.af` file contains all the state required to re-create the exact same agent:

| Component             | Description                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------ |
| Model configuration   | Context window limit, model name, embedding model name                                                 |
| Message history       | Complete chat history with `in_context` field indicating if a message is in the current context window |
| System prompt         | Initial instructions that define the agent’s behavior                                                  |
| Memory blocks         | In-context memory segments for personality, user info, etc.                                            |
| Tool rules            | Definitions of how tools should be sequenced or constrained                                            |
| Environment variables | Configuration values for tool execution                                                                |
| Tools                 | Complete tool definitions including source code and JSON schema                                        |

The schema also includes fields for `groups`, `files`, `sources` (folders), and `mcp_servers`. Archival memory passages are [planned](https://github.com/letta-ai/agent-file#roadmap).

You can view the complete `.af` schema in the [Letta repository](https://github.com/letta-ai/letta/blob/main/letta/schemas/agent_file.py).

## Using AgentFile with Letta

### Importing Agents

You can import `.af` files using the Agent Development Environment (ADE), REST APIs, or developer SDKs.

#### Using ADE

Upload downloaded `.af` files directly through the ADE interface to easily re-create your agent.

![Importing AgentFile Demo](https://github.com/letta-ai/agent-file/raw/main/assets/import_demo.gif)

Importing an AgentFile through the ADE interface

- [TypeScript](#tab-panel-96)
- [Python](#tab-panel-97)
- [curl](#tab-panel-98)

```
// Install SDK with `npm install @letta-ai/letta-client`
import { Letta, toFile } from "@letta-ai/letta-client";
import { readFileSync } from "fs";


// Create a client to connect to Letta
const client = new Letta({ apiKey: process.env.LETTA_API_KEY });


// Import your .af file from any location
const file = await toFile(readFileSync("/path/to/agent/file.af"), "agent.af");
const importResult = await client.agents.importFile({ file });


console.log(`Imported agent: ${importResult.agent_ids[0]}`);
```

```
# Install SDK with `pip install letta-client`
from letta_client import Letta
import os


# Create a client to connect to Letta
client = Letta(api_key=os.getenv("LETTA_API_KEY"))


# Import your .af file from any location
imported_agent = client.agents.import_file(file=open("/path/to/agent/file.af", "rb"))


print(f"Imported agent: {imported_agent.id}")
```

Terminal window

```
curl -X POST "https://app.letta.com/v1/agents/import" \
     -H "Authorization: Bearer LETTA_API_KEY" \
     -F "file=@/path/to/agent/file.af"
```

### Exporting Agents

You can export your own `.af` files to share by selecting “Export Agent” in the ADE.

![Exporting AgentFile Demo](https://github.com/letta-ai/agent-file/raw/main/assets/export_demo.gif)

Exporting an AgentFile from the ADE interface

- [TypeScript](#tab-panel-93)
- [Python](#tab-panel-94)
- [curl](#tab-panel-95)

```
// Install SDK with `npm install @letta-ai/letta-client`
import Letta from "@letta-ai/letta-client";


// Create a client to connect to Letta
const client = new Letta({ apiKey: process.env.LETTA_API_KEY });


// Export your agent into a serialized schema object (which you can write to a file)
const schema = await client.agents.exportFile("<AGENT_ID>");
```

```
# Install SDK with `pip install letta-client`
from letta_client import Letta
import os


# Create a client to connect to Letta
client = Letta(api_key=os.getenv("LETTA_API_KEY"))


# Export your agent into a serialized schema object (which you can write to a file)
schema = client.agents.export_file(agent_id="<AGENT_ID>")
```

Terminal window

```
curl -X GET "https://app.letta.com/v1/agents/{AGENT_ID}/export" \
     -H "Authorization: Bearer LETTA_API_KEY"
```

## Using AgentFiles for Evaluations

Agent files are the recommended way to define [evaluation targets](/guides/evals/concepts/targets/index.md) in Letta Evals. When you use an agent file as a target, the evaluation framework creates a fresh agent instance for each test case, ensuring isolated and reproducible results.

suite.yaml

```
target:
  kind: agent
  agent_file: ./agents/my_agent.af
  base_url: https://api.letta.com
```

This approach is preferred over using `agent_id` because:

- **Reproducibility**: Each test case gets a clean agent state
- **Parallel execution**: Test cases can run concurrently since they don’t share state
- **Version control**: Agent files can be committed alongside your test suites

See the [Letta Evals documentation](/guides/evals/overview/index.md) for more on setting up automated testing for your agents.

## FAQ

### Does `.af` work with frameworks other than Letta?

Theoretically, other frameworks could also load in `.af` files if they convert the state into their own representations. Some concepts, such as context window “blocks” which can be edited or shared between agents, are not implemented in other frameworks, so may need to be adapted per-framework.

### How does `.af` handle secrets?

Agents have associated secrets for tool execution in Letta. When you export agents with secrets, the secrets are set to `null` for security reasons.

## Contributing to AgentFile

The AgentFile format is a community-driven standard that welcomes contributions:

- **Share Example Agents**: Contribute your own `.af` files to the community
- **Join the Discussion**: Connect with other agent developers in our [Discord server](https://discord.gg/letta)
- **Provide Feedback**: Offer suggestions and feature requests to help refine the format

For more information on AgentFile, including example agents and the complete schema specification, visit the [AgentFile repository](https://github.com/letta-ai/agent-file).