智能体上下文工程：面向自我改进语言模型的动态上下文

---

🎯 概述

ACE（智能体上下文工程）是一个框架，它通过将上下文视为不断演化的行动手册，使大型语言模型能够自我改进。这些行动手册会以模块化的方式积累、提炼和组织策略，经过生成、反思和精选的过程逐步完善。与传统方法因简短性偏差和上下文坍塌而受限不同，ACE引入了结构化的增量更新机制，遵循“增长与精炼”的原则，在保留详细领域知识的同时，确保在整个适应过程中保持全面性和可扩展性。

最新消息

• 2025年11月：ACE 论文及代码库正式发布！

核心特性

• 🔄 三角色智能体架构：生成器、反思者和精选者协同工作，持续优化上下文
• 📈 增量式差异更新：局部编辑在保留原有知识的同时，不断积累新见解
• 🎓 自监督学习：无需标注数据即可有效适应，利用自然执行反馈进行学习
• 🚀 高效性：相比现有自适应方法，平均适应延迟降低86.9%
• 💰 成本效益：所需迭代次数显著减少，总成本更低，同时实现更高的准确性

教程

• 📚 添加评估数据集 链接
• ✨ 扩展ACE以支持工具调用（即将推出）

📊 性能表现

ACE在各项任务中均显著优于基准模型，无论是离线还是在线适应场景下，都能在代理任务上取得平均**+10.6%的提升，在领域特定基准测试中则达到+8.6%**的改进。

基准测试结果

任务类别	数据集	提升幅度	详情
代理任务	AppWorld	+10.6%	在平均表现上媲美顶级生产级代理模型（GPT-4.1），并在更具挑战性的测试集上超越其表现，且仅使用较小规模的开源模型
金融领域	FiNER + XBRL Formula	+8.6%	面向领域的推理能力，结合结构化信息抽取

效率提升

• 离线（AppWorld）：相较于GEPA，延迟降低82.3%，迭代次数减少75.1%
• 在线（FiNER）：相较于Dynamic Cheatsheet，延迟降低91.5%，token成本减少83.6%

工作原理

1. 生成器为新查询生成推理路径，揭示有效策略及常见陷阱。
2. 反思者将评估与洞察提取从精选过程中分离出来，从而提升上下文质量。
3. 精选者将经验教训转化为结构化的增量更新，并附带有益与有害标记，采用确定性合并方式去除重复内容并进行修剪。

这一设计有效避免了上下文坍塌问题——即反复改写导致细节逐渐丢失的现象。

🚀 快速入门

安装步骤

# 克隆仓库
git clone https://github.com/ace-agent/ace.git
cd ace

# 安装uv（若尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装ACE及相关依赖
uv sync

# 设置API密钥
cp .env.example .env
# 编辑.env文件，填入所需的API密钥

基本用法

from ace import ACE
from utils import initialize_clients

# 初始化API客户端
api_provider = "sambanova" # 或 "together", "openai", "commonstack"

# 初始化ACE系统
ace_system = ACE(
    api_provider=api_provider,
    generator_model="DeepSeek-V3.1",
    reflector_model="DeepSeek-V3.1",
    curator_model="DeepSeek-V3.1",
    max_tokens=4096
)

# 准备配置
config = {
    'num_epochs': 1,
    'max_num_rounds': 3,
    'curator_frequency': 1,
    'eval_steps': 100,
    'online_eval_frequency': 15,
    'save_steps': 50,
    'playbook_token_budget': 80000,
    'task_name': 'your_task',
    'json_mode': False,
    'no_ground_truth': False,
    'save_dir': './results',
    'test_workers': 20,
    'use_bulletpoint_analyzer': false,
    'api_provider': api_provider

}

# 离线适应
results = ace_system.run(
    mode='offline',
    train_samples=train_data,
    val_samples=val_data,
    test_samples=test_data,  # 可选
    data_processor=processor,
    config=config
)

# 在线适应
results = ace_system.run(
    mode='online',
    test_samples=test_data,
    data_processor=processor,
    config=config
)

# 仅评估
results = ace_system.run(
    mode='eval_only',
    test_samples=test_data,
    data_processor=processor,
    config=config
)

💼 金融领域示例

训练脚本使用

finance/run.py脚本提供了一个统一的接口，用于金融分析任务的训练与评估。

# 离线训练（自动进行初始与最终测试）
uv run python -m eval.finance.run \
    --task_name finer \
    --mode offline \
    --save_path results

# 在线训练与测试
uv run python -m eval.finance.run \
    --task_name finer \
    --mode online \
    --save_path results

# 仅对测试集进行评估。可提供预训练好的剧本，或留空initial_playbook_path以评估未初始化的剧本。
uv run python -m eval.finance.run \
    --task_name finer \
    --mode eval_only \
    --initial_playbook_path results/ace_run_TIMESTAMP_finer_offline/best_playbook.txt \
    --save_path test_results

# 使用自定义配置进行训练
uv run python -m eval.finance.run \
    --task_name finer \
    --mode offline \
    --save_path results \
    --num_epochs 3 \
    --eval_steps 100 \
    --max_tokens 4096

可用参数

点击此处查看可用参数

参数	描述	默认值
--task_name	要训练的任务（例如 finer、formula）	必填
--save_path	保存结果的目录	必填
--initial_playbook_path	初始 playbook 的路径	可选
--mode	运行模式：'offline' 表示离线训练并进行验证，'online' 表示在线训练并在测试集上测试，'eval_only' 表示仅评估	offline
--api_provider	LLM 调用的 API 提供者。可选 ['sambanova', 'together', 'openai', 'commonstack']	sambanova
--num_epochs	训练轮数	1
--max_num_rounds	错误答案的最大反思轮数	3
--curator_frequency	每 N 步运行一次策展人	1
--eval_steps	每 N 步评估一次	100
--online_eval_frequency	在在线模式下，每 N 个样本更新一次 playbook 以用于评估	15
--save_steps	每 N 步保存一次中间 playbook	50
--max_tokens	LLM 响应的最大 token 数	4096
--playbook_token_budget	playbook 的总 token 预算	80000
--test_workers	测试的并行工作线程数量	20
--generator_model	生成器使用的模型	DeepSeek-V3.1
--reflector_model	反思者使用的模型	DeepSeek-V3.1
--curator_model	策展者使用的模型	DeepSeek-V3.1
--json_mode	启用 JSON 模式以获得结构化输出	False
--no_ground_truth	反思时不使用真实答案	False
--use_bulletpoint_analyzer	启用项目符号分析器以去重和合并 playbook	False
--bulletpoint_analyzer_threshold	项目符号分析器的相似度阈值（0-1）	0.9

📈 结果与输出

以离线训练为例，训练完成后，ACE 会生成以下内容：

results/
└── ace_run_TIMESTAMP_finer_offline/
    ├── run_config.json                # 训练配置
    ├── final_results.json             # 所有阶段的汇总结果
    ├── initial_test_results.json      # 使用空 playbook 的初始测试结果（基线）
    ├── final_test_results.json        # 使用最佳 playbook 的最终测试结果
    ├── train_results.json             # 训练结果
    ├── val_results.json               # 验证结果及错误日志
    ├── pre_train_post_train_results.json     # 每个训练样本的详细预训练和后训练生成器输出
    ├── final_playbook.txt             # 最终演化的上下文
    ├── best_playbook.txt              # 性能最佳的上下文（仅限于离线训练）
    ├── bullet_usage_log.jsonl         # 项目符号使用情况跟踪
    ├── curator_operations_diff.jsonl  # 策展人操作跟踪
    ├── detailed_llm_logs/             # 详细的 LLM 调用日志
    └── intermediate_playbooks/        # 中间 playbook

理解 playbook 格式

演化的上下文（playbook）遵循以下结构：

## 策略与见解
[str-00001] helpful=5 harmful=0 :: 处理数据前务必验证数据类型
[str-00002] helpful=3 harmful=1 :: 考虑金融数据中的边界情况

## 公式与计算
[cal-00003] helpful=8 harmful=0 :: 净现值 = Σ(现金流 / (1+r)^t)

## 需要避免的常见错误
[mis-00004] helpful=6 harmful=0 :: 不要忘记时区转换

每个项目符号包含：

• ID：[section_slug-00000] 用于追踪
• 计数：helpful=X harmful=Y 由反思者更新
• 内容：:: 实际建议或策略

📬 支持的任务

代理任务

• AppWorld：模拟的应用交互数字环境

领域特定任务

• FiNER：金融信息抽取
• XBRL Formula：结构化金融数据处理

🛠️ 扩展 ACE

ACE 设计为易于扩展到新的任务和领域。要添加您自己的任务：

1. 准备您的数据：创建包含训练/验证/测试划分的 JSONL 文件
2. 实现 DataProcessor：只需实现 3 个方法——process_task_data()、answer_is_correct()、evaluate_accuracy()
3. 创建训练脚本：初始化 ACE 并使用 run() 方法进行训练
4. 自定义提示词（可选）：根据您的领域调整提示词

评估编排（并行测试执行、结果聚合）由 utils.py 中的可重用工具处理，因此您只需专注于任务特定的逻辑。

快速示例

class DataProcessor:
    def process_task_data(self, raw_data):
        # 将您的数据格式转换为标准化格式
        return [{"context": ..., "question": ..., "target": ..., "others": {...}}]
    
    def answer_is_correct(self, predicted, ground_truth):
        # 您的比较逻辑
        return predicted.strip() == ground_truth.strip()
    
    def evaluate_accuracy(self, predictions, ground_truths):
        # 计算准确率
        return sum(self.answer_is_correct(p, g) for p, g in zip(predictions, ground_truths)) / len(predictions)

📖 阅读完整扩展指南 →

🤝 贡献

我们欢迎贡献！请按照以下步骤操作：

1. 分支仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m '添加惊人功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

📚 更多资源

• 博客文章：
  • Medium: 代理式上下文工程
  • MarkTechPost 报道
  • InfoQ 文章

🙏 致谢

这项工作建立在 Dynamic Cheatsheet 的洞察之上，并融合了更广泛的 LLM 代理和上下文优化研究社区的思想。

📧 联系方式

如有疑问或反馈：

• 论文作者：请参阅 arXiv 论文，获取作者联系方式
• 问题报告：请在 GitHub 上提交 issue
• 讨论区：加入 GitHub Discussions

---

📝 引用

如果您在研究中使用 ACE，请引用我们的论文：

@misc{zhang2025agenticcontextengineeringevolving,
      title={Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models}, 
      author={Qizheng Zhang and Changran Hu and Shubhangi Upasani and Boyuan Ma and Fenglu Hong and Vamsidhar Kamanuru and Jay Rainton and Chen Wu and Mengmeng Ji and Hanchen Li and Urmish Thakker and James Zou and Kunle Olukotun},
      year={2025},
      eprint={2510.04618},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2510.04618}, 
}

ACE 快速上手指南

ACE (Agentic Context Engineering) 是一个让大语言模型通过“生长与优化”机制自我进化的框架。它将上下文视为不断演进的策略手册（Playbook），通过生成、反思和策展三个角色的协作，积累领域知识并避免传统方法中的“上下文崩塌”问题。

环境准备

• 操作系统: Linux / macOS / Windows (WSL2 推荐)
• Python: 3.10 或更高版本
• 包管理器: uv (ACE 推荐使用 uv 进行依赖管理，比 pip 更快)
• API Key: 需准备至少一个 LLM 服务商的 API Key (支持 Sambanova, Together, OpenAI, CommonStack 等)

国内开发者提示：由于网络原因，克隆仓库或下载依赖时若遇阻，建议使用国内镜像源或配置代理。uv 安装脚本若下载失败，可手动从 GitHub Releases 下载二进制文件。

安装步骤

1. 克隆项目代码

   git clone https://github.com/ace-agent/ace.git
   cd ace
   

2. 安装 uv 包管理器 (如已安装可跳过)

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   注：若上述命令超时，请手动下载 uv 并添加到 PATH。

3. 安装项目依赖

   uv sync
   

4. 配置 API 密钥

   cp .env.example .env
   

   编辑 .env 文件，填入你的 API Key：

   # 示例 (根据实际使用的服务商填写)
   OPENAI_API_KEY=sk-...
   # 或
   SAMBANOVA_API_KEY=...
   

基本使用

以下是最小化的 Python 调用示例，展示如何初始化 ACE 并运行离线适应任务。

1. Python 代码示例

创建一个 run_ace.py 文件：

from ace import ACE
from utils import initialize_clients

# 1. 选择 API 提供商 (支持: "sambanova", "together", "openai", "commonstack")
api_provider = "openai" 

# 2. 初始化 ACE 系统
# 这里以 DeepSeek-V3.1 为例，也可替换为其他支持的模型
ace_system = ACE(
    api_provider=api_provider,
    generator_model="DeepSeek-V3.1",
    reflector_model="DeepSeek-V3.1",
    curator_model="DeepSeek-V3.1",
    max_tokens=4096
)

# 3. 配置运行参数
config = {
    'num_epochs': 1,
    'max_num_rounds': 3,
    'curator_frequency': 1,
    'eval_steps': 100,
    'online_eval_frequency': 15,
    'save_steps': 50,
    'playbook_token_budget': 80000,
    'task_name': 'my_custom_task',
    'json_mode': False,
    'no_ground_truth': False,
    'save_dir': './results',
    'test_workers': 4, # 根据本地机器性能调整
    'use_bulletpoint_analyzer': False,
    'api_provider': api_provider
}

# 4. 准备数据 (需实现自定义的 DataProcessor，此处仅为占位示意)
# train_data, val_data, test_data 应为处理后的列表格式
# processor = MyDataProcessor() 

# 5. 运行离线适应模式
# results = ace_system.run(
#     mode='offline',
#     train_samples=train_data,
#     val_samples=val_data,
#     test_samples=test_data,
#     data_processor=processor,
#     config=config
# )

print("ACE 系统初始化完成，取消注释 run 方法即可开始训练。")

2. 金融领域快速测试 (命令行方式)

如果你希望直接体验 ACE 在金融数据分析（FiNER 任务）上的效果，可以使用内置脚本：

离线训练与评估：

uv run python -m eval.finance.run \
    --task_name finer \
    --mode offline \
    --save_path results \
    --api_provider openai \
    --num_epochs 1

仅评估（使用已生成的策略手册）：

uv run python -m eval.finance.run \
    --task_name finer \
    --mode eval_only \
    --initial_playbook_path results/ace_run_TIMESTAMP_finer_offline/best_playbook.txt \
    --save_path test_results

输出说明

运行完成后，结果将保存在 results/ 目录下，核心文件包括：

• best_playbook.txt: 进化后的最佳策略手册（核心产出）。
• final_test_results.json: 最终测试性能报告。
• detailed_llm_logs/: 详细的模型调用日志，便于调试。

策略手册 (playbook) 采用结构化格式，包含策略、公式及常见错误避免指南，每条记录均带有“有益/有害”计数器，由系统自动维护。