agent-file

把智能体存成一个文件，随时分享、回滚、换框架。

开源 free 智能体

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1209

维护状态活跃

是否开源是

定价模式 free

项目预览

项目数据

分类智能体

开发团队letta-ai

所属国家

官网地址https://agentfile-directory.vercel.app

GitHubhttps://github.com/letta-ai/agent-file

定价模式free

价格说明开源开放文件格式，免费使用

访问状态

是否开源是

开源协议Apache-2.0

主要语言TypeScript

技术栈/模型

GitHub 星标★ 1209

30天Star增速

HF 下载量

上线时间2025-03-23 00:00:00

代码更新—

仓库体积—

本站数据更新—

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-10-19

浏览次数0

项目介绍

agent-file 定义了一种名为 .af 的开放文件格式，用于把有状态 AI 智能体的完整信息序列化到单个文件中，包括持久记忆、行为配置和运行状态。它解决的是智能体难以迁移、备份和协作的问题：不同框架各自保存状态，导致智能体无法跨平台共享，也无法像代码一样做版本管理。核心能力包括：将智能体状态导出为可读文件，支持检查点保存与恢复，便于用 Git 等工具追踪变更；在兼容该格式的框架之间导入导出，实现智能体分发与复用。项目用 TypeScript 实现，提供格式规范与工具链，适合需要长期运行、需要记忆延续或需要团队协作调试智能体的开发者。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

正在加载星标数据…

技术标签

使用教程

—

难度：入门约 15 分钟部署方式：库/依赖 6 步

环境要求

Python 环境（用于 pip 安装 letta-client>=1.0.0）
一个已在 http://localhost:8283 运行的 Letta Server
Node.js 与 npm（仅本地运行 agents 目录站点时需要）
准备一个 .af 智能体文件（可从本仓库 agents/ 目录下载）

安装与启动步骤

1安装 Letta SDK

用 pip 安装 1.0.0 及以上版本的官方 Python SDK，用于导入导出智能体文件。
```
pip install letta-client>=1.0.0
```
2确认服务已运行

README 假设 Letta Server 已在本地 8283 端口运行；未运行需先自行启动该服务，README 未给出启动命令。
3导入 .af 文件

用 curl 以 multipart 形式把 .af 文件 POST 到导入接口，成功后服务端会创建对应智能体。
```
curl -X POST "http://localhost:8283/v1/agents/import" -F "file=/path/to/agent/file.af"
```
4用 Python SDK 连接

安装好 SDK 后，用 base_url 指向本地服务，即可通过客户端管理已导入的智能体。
```
from letta_client import Letta

client = Letta(base_url="http://localhost:8283")
```
5导出智能体

通过导出接口按智能体 ID 取回 .af 文件内容，便于备份、分发或提交到本仓库目录。
```
curl -X GET "http://localhost:8283/v1/agents/{AGENT_ID}/export"
```
6本地运行目录站点

在本仓库根目录安装依赖并启动开发服务器，用于浏览 agents/ 下的智能体目录。
```
npm install
npm run dev
```

关键配置

配置项	必填	说明	示例
`base_url`	是	Letta Server 地址，SDK 与 curl 都需指向它	`http://localhost:8283`
`file`	是	导入接口中 .af 文件的本地路径	`/path/to/agent/file.af`
`AGENT_ID`	是	导出接口中要导出的智能体 ID	`agent-xxxxxxxx`

如何确认成功

导入接口返回成功响应即表示智能体已创建；npm run dev 后浏览器打开终端输出的本地地址能看到目录。

常见问题

Q：没有 Letta Server 能直接用吗？

A：不能。README 中的导入导出示例都假设服务运行在 http://localhost:8283，需先自行部署 Letta 服务。

Q：.af 文件可以从哪里获取？

A：可从本仓库 agents/@{owner}/{agent-name}/ 目录下载示例文件，或从 Letta 的 ADE 或导出接口自行导出。

Q：如何把智能体提交到目录？

A：Fork 仓库，在 agents/@{your-github-handle}/{agent-name}/ 下放入 .af 文件和 webp 头像，再提 PR。

Q：npm 相关命令是做什么的？

A：用于本地运行本仓库的目录浏览站点，与智能体导入导出无关，可按需执行。

注意事项

Agent File 是为 Letta 框架设计的开放格式，导入时目标框架需兼容该格式
命令中的路径与智能体 ID 需替换为你自己的真实值
提交目录时头像必须是方形 webp 图片，格式不符会被拒

核心亮点

用单一 .af 文件封装记忆与行为状态，便于备份和迁移
格式开放且与框架解耦，支持跨兼容框架导入导出
可纳入 Git 版本管理，智能体变更可追踪、可回滚

不足之处

生态尚早期，实际支持该格式的框架数量有限
状态序列化的安全与隐私边界（如记忆中的敏感信息）缺少明确方案

适用场景

团队协作开发智能体时共享可复现的状态快照
长期运行的个人助手定期检查点保存，故障后恢复记忆
把智能体从原型框架迁移到生产框架时保留行为与记忆

替代项目

LangGraph、Letta

上一篇：OrcaReplay

下一篇：agent-skills