.af

Agent File (.af)

An open standard file format for exporting, sharing, and importing stateful agents across AI platforms.

Export .af Import .af See Examples

What is Agent File?

Agent File (.af) is an open standard file format for serializing stateful agents. Originally designed for the Letta framework, Agent File provides a portable, standardized way to share agents with persistent memory and behavior.

Agent Files encapsulate all of the components of a stateful agent:

By standardizing these components in a single file format, Agent File enables seamless transfer of agents between systems, promotes collaboration among developers, and simplifies deployment across environments.

Why Agent File?

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

What can I do with it?

Agent File enables powerful workflows for AI agent development and deployment:

Share complete agents with the community

Export your carefully crafted agents with their full memory and personality intact, allowing others to build upon your work.

Move agents between environments

Develop on your local machine, then seamlessly deploy to production environments without losing agent state.

Create agent templates

Build reusable starting points for specialized agents by creating base configurations that others can import and customize.

Archive agent states

Save point-in-time snapshots of your agents as they learn and evolve, allowing you to revert to previous states if needed.

Import agents across frameworks

While designed for Letta, the Agent File specification is framework-agnostic, allowing other AI systems to adopt the standard for agent interoperability.

Cross-Server Agent Sharing

Agent File (.af) enables seamless transfer of agents between different Letta servers. This allows you to:

When you export an agent as a .af file, all of its essential components—memory, tools, configuration, and history—are preserved. When imported on a new server, the agent continues functioning with its full personality and capabilities intact.

This seamless portability makes Agent File a powerful tool for:

Creating an Agent File

You can export Agent Files from Letta in two ways:

From the Agent Development Environment (ADE)

  1. Open your agent in the Letta ADE
  2. Click the Export button in the top right menu
  3. Select Export as Agent File (.af)
  4. Choose a destination to save your file

Using the Letta API

Use the dedicated export endpoint to generate an Agent File programmatically:

curl -X GET https://app.letta.com/v1/agents/{agent_id}/export \
     -H "Authorization: Bearer <token>" \
     -o my-agent.af

from letta_client import Letta

client = Letta(token="YOUR_TOKEN")
agent_file = client.agents.export(agent_id="agent_id")

# Save to file
with open("my-agent.af", "w") as f:
    f.write(agent_file)

import { LettaClient } from "@letta-ai/letta-client";

const client = new LettaClient({ token: "YOUR_TOKEN" });
const agentFile = await client.agents.export("agent_id");

// Save to file
import fs from "fs";
fs.writeFileSync("my-agent.af", agentFile);

Importing an Agent File

You can import Agent Files into Letta using similar methods:

From the Agent Development Environment (ADE)

  1. Navigate to the Agents page in the Letta ADE
  2. Click the Import Agent button
  3. Select your .af file
  4. Review and confirm the agent configuration

Using the Letta API

Use the import endpoint to create a new agent from an Agent File:

curl -X POST https://app.letta.com/v1/agents/import \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d @my-agent.af

from letta_client import Letta

client = Letta(token="YOUR_TOKEN")

# Read file content
with open("my-agent.af", "r") as f:
    agent_file_content = f.read()

# Import agent
agent = client.agents.import_agent(agent_file=agent_file_content)
print(f"Imported agent ID: {agent.id}")

import { LettaClient } from "@letta-ai/letta-client";
import fs from "fs";

const client = new LettaClient({ token: "YOUR_TOKEN" });

// Read file content
const agentFileContent = fs.readFileSync("my-agent.af", "utf8");

// Import agent
const agent = await client.agents.importAgent(agentFileContent);
console.log(`Imported agent ID: ${agent.id}`);

Learn More

For a detailed breakdown of the Agent File schema, see the Schema Documentation.

Contributing

Agent File (.af) is an open standard, and we welcome contributions from the community. If you'd like to suggest improvements or report issues: