Acontext：从存储到自我学习，构建更可靠的AI代理系统

在AI代理技术快速发展的今天，如何让代理更稳定、更高效地完成任务，同时不断积累经验实现自我提升，成为许多开发者关注的核心问题。Acontext作为一款上下文数据平台，正是为解决这些问题而生。它不仅能存储代理的对话和工件，还能观察任务进度、收集用户反馈，并通过学习将经验转化为长期技能，最终帮助你构建更具可扩展性的代理产品。

一、Acontext是什么？

简单来说，Acontext是一个围绕AI代理工作流程设计的上下文数据平台，它主要做四件事：

• 「存储」：保存代理的对话线程（包括多模态消息）和各种工件（如文件、数据等）；
• 「观察」：通过后台代理跟踪任务的状态、进度和用户偏好，记录代理的每一步操作；
• 「自我学习」：将代理在任务中积累的经验（标准操作流程，即SOP）提炼并存储到长期记忆中，让代理越用越“聪明”；
• 「可视化」：提供本地仪表板，让你直观查看消息记录、任务状态、工件内容和学习到的技能。

Acontext的核心逻辑：存储、观察和学习的闭环

为什么需要这样一个平台？因为在实际开发中，AI代理常常面临这些问题：任务执行到一半忘记之前的步骤、重复犯同样的错误、无法根据用户偏好调整行为……Acontext通过构建“存储-观察-学习”的闭环，帮助代理解决这些痛点，提高成功率，减少不必要的运行步骤，最终为用户创造更大价值。

二、Acontext的核心概念：理解平台的“积木”

要熟练使用Acontext，首先需要了解它的几个核心组件。这些组件就像积木，相互配合支撑起整个平台的功能。

1. Session：代理的“对话笔记本”

Session是一个对话线程，相当于代理的“笔记本”，用来记录用户与代理之间的所有交互。它支持文本、图片等多模态消息的存储，无论你使用OpenAI、Anthropic还是其他模型，都能统一存储对话内容。

比如，当用户让代理“写一篇iPhone 15 Pro Max的 landing page文案”时，从用户提出需求、代理给出计划，到后续的每一次沟通，都会被完整记录在Session中。

2. Task Agent：后台的“任务追踪员”

每个Session都会自动关联一个Task Agent，它就像一个后台“任务追踪员”，负责从对话中提取任务、跟踪进度，并记录用户的偏好。

例如，当代理提出“1. 搜索iPhone 15 Pro Max最新资讯；2. 初始化Next.js项目；3. 部署页面”的计划时，Task Agent会自动识别这三个任务，实时更新每个任务的状态（待处理、进行中、完成），并记录用户是否有特殊要求（如“先收集资讯再汇报，再开始编码”）。

3. Disk：代理的“文件柜”

Disk是专门用于存储代理工件的“文件柜”，你可以像管理本地文件一样，用文件路径来组织和访问这些工件（如文档、代码、数据表格等）。

比如，代理在执行任务时生成的“待办清单.md”“设计草图.png”，都可以按路径（如“/project/iphone-landing/”）存储到Disk中，后续需要时直接通过路径读取。

4. Space：代理的“技能知识库”

Space是一个类似Notion的结构化系统，相当于代理的“技能知识库”，用来存储从经验中提炼出的技能（SOP）。它以文件夹、页面和块的形式组织内容，方便代理快速检索和使用。

举个例子，关于“GitHub操作”的技能可能会这样存储：

/
└── github/（文件夹）
    └── GTM（页面）
        ├── find_trending_repos（SOP块）
        └── find_contributor_emails（SOP块）
    └── basic_ops（页面）
        ├── create_repo（SOP块）
        └── delete_repo（SOP块）

每个SOP块包含具体的操作指南，比如“给GitHub仓库点赞”的技能可能是这样的：

{
    "use_when": "star a repo on github.com",
    "preferences": "use personal account. star but not fork",
    "tool_sops": [
        {"tool_name": "goto", "action": "goto github.com"},
        {"tool_name": "click", "action": "find login button if any. login first"},
        ...
    ]
}

5. Experience Agent：技能的“提炼师”

Experience Agent是Space的“幕后助手”，负责从完成的任务中提炼SOP、判断技能的复杂度（是否值得保存），并将合格的技能存储到Space中。它不需要人工干预，会在后台自动完成这些工作。

这些组件如何协同工作？

它们的关系可以用一个简单的流程图表示：

┌──────┐    ┌────────────┐    ┌──────────────┐    ┌───────────────┐
│ 用户 │◄──►│ 你的代理   │◄──►│   Session    │    │ 工件Disk      │
└──────┘    └─────▲──────┘    └──────┬───────┘    └───────────────┘
                  │                  │
                  │         ┌────────▼────────┐
                  │         │ 观察到的任务    │
                  │         └────────┬────────┘
                  │                  │
                  │         ┌────────▼────────┐
                  │         │  Space（学习）  │
                  │         └────────┬────────┘
                  │                  │
                  └──────────────────┘
                  技能指导代理

简单来说：用户与代理的交互被记录在Session中；Task Agent从Session中提取任务并跟踪进度；代理生成的文件存到Disk；当任务完成后，Experience Agent会从任务过程中提炼技能，存到Space；下一次代理执行类似任务时，会从Space中获取相关技能，指导操作。

三、如何开始使用Acontext？

使用Acontext的第一步是搭建本地环境。整个过程并不复杂，只需按照以下步骤操作：

1. 安装Acontext CLI

Acontext提供了命令行工具（CLI），方便快速初始化项目和管理后端。打开终端，运行以下命令安装：

curl -fsSL https://install.acontext.io | sh

2. 准备必要的依赖

在启动Acontext后端前，需要确保你的电脑上已经安装了两个工具：

• 「Docker」：用于运行Acontext的后台服务（下载地址）；
• 「OpenAI API密钥」：Acontext需要调用大语言模型处理任务，推荐使用gpt-5.1或gpt-4.1（可在OpenAI官网申请）。

3. 启动Acontext后端

安装好依赖后，在终端中运行以下命令启动Acontext服务：

acontext docker up

启动成功后，你可以访问以下地址：

• Acontext API地址：http://localhost:8029/api/v1（用于SDK调用）；
• Acontext仪表板：http://localhost:3000/（用于可视化查看数据）。

仪表板可展示代理的成功率、任务进度等关键指标

四、Acontext的具体使用方法

Acontext提供了Python和TypeScript两种SDK，方便不同技术栈的开发者使用。下面以Python为例，详细介绍如何利用Acontext实现存储、观察和学习功能。

第一步：安装SDK并初始化客户端

首先安装Python SDK：

pip install acontext

然后初始化客户端，连接到本地的Acontext服务：

from acontext import AcontextClient

client = AcontextClient(
    base_url="http://localhost:8029/api/v1",
    api_key="sk-ac-your-root-api-bearer-token"  # 默认密钥
)
# 测试连接是否成功
client.ping()  # 成功会返回确认信息

❝

提示：Acontext也提供异步客户端，适合需要高并发的场景，具体可参考官方文档。

❞

第二步：存储功能：保存对话和工件

Acontext的存储功能主要包括两部分：对话消息存储和工件存储。

1. 保存对话消息

无论你使用OpenAI、Anthropic还是其他模型，都可以将对话消息存储到Session中。例如：

# 创建一个新的Session（对话线程）
session = client.sessions.create()

# 准备对话消息（格式与OpenAI SDK兼容）
messages = [
    {"role": "user", "content": "我需要写一篇iPhone 15 Pro Max的landing page文案"},
    {
        "role": "assistant",
        "content": "好的，我的计划如下：\n1. 搜索iPhone 15 Pro Max的最新资讯\n2. 初始化Next.js项目\n3. 将页面部署到网站",
    }
]

# 逐条保存消息到Session
for msg in messages:
    client.sessions.send_message(session_id=session.id, blob=msg, format="openai")

除了文本，Acontext还支持图片、音频等多模态消息的存储，具体可参考多模态消息文档。

2. 加载历史消息

当需要继续对话时，可以从Session中加载历史消息，作为新请求的上下文：

# 从Session中获取已保存的消息
response = client.sessions.get_messages(session.id)
history_messages = response.items

# 添加新的用户消息
history_messages.append({"role": "user", "content": "你现在进展如何？"})

# 调用OpenAI模型生成回复（需先安装openai SDK：pip install openai）
import openai
openai_client = openai.OpenAI(api_key="你的OpenAI密钥")
reply = openai_client.chat.completions.create(
    model="gpt-4.1",
    messages=history_messages
)

# 将新回复保存到Session
client.sessions.send_message(
    session_id=session.id,
    blob=reply.choices[0].message
)

你可以在仪表板的“消息查看器”中查看所有保存的对话：

在仪表板中查看Session的对话历史

3. 存储和管理工件

代理在执行任务时生成的文件（如文档、代码、数据等），可以通过Disk功能管理：

from acontext import FileUpload

# 创建一个新的Disk（文件柜）
disk = client.disks.create()

# 准备一个文件（例如待办清单）
file = FileUpload(
    filename="todo.md",
    content=b"# 冲刺计划\n\n## 目标\n- 完成用户认证功能\n- 修复关键bug"
)

# 将文件存储到Disk的指定路径（如“/todo/”）
artifact = client.disks.artifacts.upsert(
    disk.id,
    file=file,
    file_path="/todo/"
)

# 列出指定路径下的文件
print(client.disks.artifacts.list(
    disk.id,
    path="/todo/"
))

# 读取文件内容和下载链接
result = client.disks.artifacts.get(
    disk.id,
    file_path="/todo/",
    filename="todo.md",
    with_public_url=True,  # 获取下载链接
    with_content=True  # 获取文件内容
)
print(f"文件内容：{result.content.raw}")
print(f"下载链接：{result.public_url}")

在仪表板的“工件查看器”中，你可以直观地浏览和管理所有存储的文件：

在仪表板中查看和管理存储的工件

第三步：观察功能：跟踪任务进度和用户偏好

Acontext会自动观察代理的任务执行过程，无需额外配置。当你向Session发送消息时，Task Agent会后台提取任务、跟踪状态，并记录用户偏好。

以下是一个完整的示例，展示如何通过SDK获取观察到的任务信息：

from acontext import AcontextClient

# 初始化客户端
client = AcontextClient(
    base_url="http://localhost:8029/api/v1", 
    api_key="sk-ac-your-root-api-bearer-token"
)

# 创建Session
session = client.sessions.create()

# 模拟一段包含任务的对话
messages = [
    {"role": "user", "content": "我需要写一篇iPhone 15 Pro Max的landing page文案"},
    {
        "role": "assistant",
        "content": "好的，我的计划如下：\n1. 搜索iPhone 15 Pro Max的最新资讯\n2. 初始化Next.js项目\n3. 将页面部署到网站",
    },
    {
        "role": "user",
        "content": "听起来不错。在开始编码前，先收集资讯并汇报给我。",
    },
    {
        "role": "assistant",
        "content": "没问题，我会先收集资讯再汇报，然后再开始编码。",
        "tool_calls": [
            {
                "id": "call_001",
                "type": "function",
                "function": {
                    "name": "search_news",
                    "arguments": "{\"query\": \"iPhone 15 Pro Max 最新资讯\"}"
                }
            }
        ]
    },
]

# 发送消息到Session
for msg in messages:
    client.sessions.send_message(session_id=session.id, blob=msg, format="openai")

# 等待Task Agent完成任务提取（开发环境用，生产环境无需调用）
client.sessions.flush(session.id)

# 获取提取到的任务
tasks_response = client.sessions.get_tasks(session.id)
for task in tasks_response.items:
    print(f"\n任务 #{task.order}：")
    print(f"  标题：{task.data['task_description']}")
    print(f"  状态：{task.status}")
    
    # 显示进度更新
    if "progresses" in task.data:
        print(f"  进度更新：{len(task.data['progresses'])}条")
        for progress in task.data["progresses"]:
            print(f"    - {progress}")
    
    # 显示用户偏好
    if "user_preferences" in task.data:
        print("  用户偏好：")
        for pref in task.data["user_preferences"]:
            print(f"    - {pref}")

运行后，你会看到类似这样的输出：

任务 #1：
  标题：搜索iPhone 15 Pro Max的最新资讯并在开始编码前向用户汇报
  状态：success
  进度更新：2条
    - 已确认第一步是先汇报再开始编码
    - 已收集所有资讯并汇报给用户，等待下一步指示
  用户偏好：
    - 用户希望在开始landing page编码前，先收到iPhone 15 Pro Max的最新资讯汇报

任务 #2：
  标题：初始化Next.js项目用于iPhone 15 Pro Max的landing page
  状态：pending

任务 #3：
  标题：将完成的landing page部署到网站
  状态：pending

在仪表板的“任务查看器”中，你可以更直观地看到任务的状态和进度：

在仪表板中查看任务的状态和进度

第四步：自我学习功能：让代理积累技能

Acontext的核心价值之一是让代理通过经验学习技能。这一过程通过Space实现，无需人工干预，后台自动完成。

1. 创建Space并关联Session

要启用学习功能，需要先创建一个Space（技能知识库），并将Session关联到这个Space：

# 创建一个Space（技能知识库）
space = client.spaces.create()
print(f"创建的Space ID：{space.id}")

# 创建一个关联到该Space的Session
session = client.sessions.create(space_id=space.id)

# 向Session发送代理的工作内容（对话、工具调用等）
# ...（与前面的消息发送步骤相同）

2. 学习的过程是怎样的？

当任务完成后，Acontext会按以下流程自动学习：

graph LR
    A[任务完成] --> B[提取任务详情]
    B --> C{是否关联Space？}
    C -->|是| D[加入学习队列]
    C -->|否| E[跳过学习]
    D --> F[提炼SOP]
    F --> G{任务是否足够复杂？}
    G -->|否（太简单）| H[跳过学习]
    G -->|是（有价值）| I[存储为技能块]
    I --> J[供未来任务使用]

简单来说，只有关联了Space的Session，且任务足够复杂（有学习价值）时，Acontext才会将其提炼为技能，存储到Space中。整个过程有10-30秒的延迟，无需人工操作。

3. 从Space中搜索技能

当代理需要执行新任务时，可以从Space中搜索相关技能，作为操作指南：

# 从Space中搜索与“实现用户认证”相关的技能
result = client.spaces.experience_search(
    space_id=space.id,
    query="我需要实现用户认证",
    mode="fast"  # 快速模式，基于嵌入匹配
)

# 输出搜索到的技能
for skill in result:
    print(f"适用场景：{skill['use_when']}")
    print(f"偏好设置：{skill['preferences']}")
    print("操作步骤：")
    for step in skill['tool_sops']:
        print(f"  - {step['tool_name']}：{step['action']}")
    print("\n")

Acontext支持两种搜索模式：

• fast：基于嵌入快速匹配相关技能，适合需要即时响应的场景；
• agentic：通过Experience Agent深度探索Space，覆盖所有相关技能，适合复杂任务。

你可以在仪表板的“技能查看器”中浏览Space中的所有技能：

在仪表板中查看Space中的技能

快速开始：使用模板项目

如果想快速体验Acontext的功能，可以使用官方提供的模板项目。根据你的技术栈，运行以下命令之一：

技术栈	命令
Python + OpenAI SDK	acontext create my-proj --template-path "python/openai-basic"
TypeScript + OpenAI SDK	acontext create my-proj --template-path "typescript/openai-basic"
Python + OpenAI Agent SDK	acontext create my-proj --template-path "python/openai-agent-basic"
Python + Agno	acontext create my-proj --template-path "python/agno-basic"
TypeScript + vercel/ai-sdk	acontext create my-proj --template-path "typescript/vercel-ai-basic"

更多模板可参考Acontext-Examples仓库。

五、常见问题解答（FAQ）

1. Acontext需要什么硬件配置才能运行？

Acontext通过Docker运行，对硬件要求不高，普通个人电脑（4GB内存以上）即可满足本地开发需求。如果需要处理大量会话或复杂任务，建议提高内存（8GB以上）以保证流畅性。

2. 除了OpenAI，Acontext还支持其他大语言模型吗？

目前Acontext主要推荐使用OpenAI的gpt-5.1或gpt-4.1，但它的消息存储格式支持多模型（如Anthropic），未来会逐步扩展对更多模型的支持。

3. 本地仪表板可以查看哪些数据？

仪表板支持查看：

• 所有Session的对话历史；
• 任务的状态、进度和用户偏好；
• Disk中存储的工件（文件）；
• Space中的技能（SOP）；
• 代理的成功率、任务完成时间等指标。

4. 如何确保存储的对话和工件数据安全？

Acontext默认在本地运行，所有数据存储在你的电脑中，不会上传到云端。如果需要团队协作，可以部署到私有服务器，具体可参考部署文档。

5. Space中的技能会一直累积吗？会不会越来越多导致混乱？

Acontext的Experience Agent会自动筛选有价值的技能，简单或重复的技能不会被存储。同时，Space支持类似文件管理器的组织方式（文件夹、页面），你也可以手动整理或删除不需要的技能。

6. 可以将Acontext集成到已有的代理系统中吗？

可以。Acontext提供了Python和TypeScript SDK，通过简单的API调用即可与现有系统集成，无需重构整个代理逻辑。具体可参考集成指南。

六、总结

Acontext通过“存储-观察-学习”的闭环，为AI代理提供了一个完整的上下文管理和自我提升解决方案。它不仅能帮你记录代理的每一步操作，还能从中提炼经验，让代理越用越高效。

无论是构建需要长期运行的企业级代理产品，还是优化个人开发的小工具，Acontext都能通过减少重复劳动、提高任务成功率，为你节省时间和精力。

如果你想体验Acontext，可以按照本文的步骤安装并启动服务，也可以访问官方文档了解更多细节。加入Discord社区，还能与其他开发者交流使用经验，获取最新更新信息。

让Acontext成为你的AI代理的“记忆中枢”和“学习助手”，一起构建更可靠、更智能的代理系统吧。