Code-Over-API Pattern

当Agent直接调用API或工具时，所有中间数据都必须流经模型的上下文窗口。对于数据密集型工作流（如处理电子表格、过滤日志、转换数据集），这种方式会造成token的大量消耗，并导致延迟增加。一个获取10000行电子表格数据并进行过滤的工作流，仅仅是让数据在上下文窗口中流转这一步，就可能轻松消耗15万以上的token。

代理不会直接调用工具，而是编写并执行与工具交互的代码。数据的处理、筛选和转换在执行环境中完成，只有结果会回流到模型的context中。

直接API调用方案（Token成本高）：

# Agent发起工具调用
rows = api_call("spreadsheet.getRows", sheet_id="abc123")
# 全部10000行数据流入context → 约15万个Token

# Agent在context内处理数据
filtered = [row for row in rows if row.status == "active"]
# 处理过程消耗额外Token

return filtered

代码替代API方案（Token成本低）：

# Agent编写将在执行环境中运行的代码
def process_spreadsheet():
    # 工具调用在执行环境中完成
    rows = spreadsheet.getRows(sheet_id="abc123")

    # 筛选操作在代码中执行，而非在context内
    filtered = [row for row in rows if row.status == "active"]

    # 仅记录摘要信息供Agent查看
    print(f"处理了 {len(rows)} 行数据，找到 {len(filtered)} 条活跃数据")
    print(f"前5条活跃数据：{filtered[:5]}")

    return filtered

result = process_spreadsheet()
# 仅摘要信息和样本数据流入context → 约2000个Token

Agent仅能看到日志输出和返回值，完整数据集绝不会进入其context窗口。

最适用场景：

• 数据密集型工作流（电子表格、数据库、日志）
• 多步骤转换或聚合操作
• 中间结果无需模型检查的工作流
• 对token使用量敏感的成本优先型应用

前置条件：

• 具备沙箱机制的安全代码执行环境
• 执行环境内可访问工具/API
• 用于防止执行失控的资源限制（CPU、内存、时间）

实现模式：

1. Agent分析任务并确定数据处理需求
2. Agent编写代码，代码需满足：
   • 在执行环境内调用工具/API
   • 在代码中完成过滤、转换、聚合操作
   • 仅记录摘要或样本以保证可见性
   • 返回最终结果
3. 执行环境运行具备工具访问权限的代码
4. 仅日志和返回值回传给agent context

优势：

• 显著降低Token消耗（已有案例显示从15万降至2千）
• 延迟更低（减少大context API调用次数）
• 天然适配数据处理类任务
• 中间数据仅在执行环境内部流转

劣势：

• 需要安全的代码执行基础设施
• 配置流程比直接工具调用更复杂
• 要求Agent具备编写正确代码的能力
• 调试难度更高（错误发生在执行阶段而非context层面）
• 需要配套监控、资源限制与沙箱机制

运维要求：

• 沙箱化执行环境（容器、虚拟机、WebAssembly）
• 资源限制（CPU、内存、执行时长）
• 监控与日志记录基础设施
• 错误处理与故障恢复机制