Skip to main content

ContextEngineering

心智模型​

上下文工程的核心是：在 Agent 循环的每个步骤（模型调用、工具执行）以及步骤之间，通过中间件从 State（短期记忆）、Store（长期记忆）和 Runtime Context（静态配置）三个数据源中动态注入或修改上下文，以确保 LLM 在每次调用时都能获得完成任务所需的“恰好正确”的信息。控制分为瞬态的（单次模型调用可见）和持久的（写入状态，影响后续所有步骤）。

二级标题及内容​

  • 【模型上下文】Model Context

    • 系统提示：可从 State、Store、Runtime Context 动态生成，以根据会话长度、用户偏好或角色调整 Agent 基础行为指令。
    • 消息：通过中间件在模型调用前瞬态注入或修改消息列表，例如添加上传文件摘要、用户写作风格或合规性要求。
    • 工具：可动态筛选可用工具集，根据认证状态、用户权限（Runtime Context）或功能开关（Store）来限制模型可调用的工具。
    • 模型：可根据会话长度（State）、用户偏好（Store）或成本/环境要求（Runtime Context）动态切换不同能力或成本的底层 LLM。
    • 响应格式：可通过 response_format 强制模型输出符合特定 Pydantic 模式的结构化数据，模式本身也可根据 State 或用户偏好动态选择。

  • 【工具上下文】Tool context

    • 读取：工具可通过 ToolRuntime 读取 State、Store 和 Runtime Context，以获取用户 ID、API 密钥、会话状态等业务所需信息。
    • 写入：工具不仅能返回结果，还能通过 Command 持久地更新 State（如标记认证成功），或直接写入 Store（如保存用户偏好）。

  • 【生命周期上下文】Life-cycle context 控制 Agent 循环步骤之间发生的事，例如内置的 SummarizationMiddleware，可在会话过长时自动调用另一个 LLM 进行摘要，并用摘要持久地替换 State 中的旧消息。

最佳实践​

  • 从简单开始：先用静态提示和工具，仅在需要时添加动态逻辑。
  • 增量测试：一次只添加一个上下文工程特性，便于定位问题。
  • 监控性能：密切关注模型调用次数、Token 用量和延迟。
  • 优先使用内置中间件：如 SummarizationMiddleware、LLMToolSelectorMiddleware 等。
  • 记录上下文策略：明确记录了传递了哪些上下文及其原因。
  • 理解瞬态与持久：模型上下文修改通常是瞬态的（每次调用），而生命周期上下文修改则会持久化到状态。

上下文工程并非某项独立功能，而是贯穿整个 Agent 开发过程的核心实践。它主要应用在以下几个场景：

1. 多用户 SaaS 应用​

根据不同用户的身份、偏好和权限，提供个性化的服务体验。

  • 场景示例：一个客服 Agent，面对 VIP 用户时回复更详尽，面对普通用户时更简洁；或只给付费用户开启高级分析工具。
  • 实现方式：通过 Runtime Context 传入用户角色和 ID，中间件动态调整系统提示词、工具集，甚至切换更强大的模型。

2. 长对话或多轮交互​

在长时间对话中，避免超出模型上下文窗口，并让 Agent 记住关键信息。

  • 场景示例：一个持续数小时的调试会话，Agent 需要总结之前的讨论，或记住用户在前几轮提到的技术栈。
  • 实现方式：使用 SummarizationMiddleware 自动摘要旧消息；用 Store 跨会话记住用户偏好；用 State 跟踪当前会话的认证状态。

3. 复杂、多阶段的业务流程​

处理有先后顺序和条件依赖的复杂任务，如数据查询与分析。

  • 场景示例：用户要求“分析上个季度的销售数据并生成报告”。Agent 需要先查询权限（工具写 State），再拉取数据（工具读 Runtime Context 获取数据库连接），最后调用不同模型生成总结（中间件动态切换模型）。
  • 实现方式：工具通过 Command 写入 State 来标记流程状态，后续步骤根据 State 决定下一步操作。

4. 安全与合规要求严格的应用​

在金融、医疗、法律等领域，确保 Agent 操作安全、数据脱敏、输出合规。

  • 场景示例：在处理医疗咨询时，Agent 必须对患者姓名（PII）脱敏，且其最终回复需要通过内容安全审查。
  • 实现方式：利用 PIIMiddleware 自动脱敏，并通过 after_agent 的模型护栏二次检查输出内容。

5. 集成动态外部数据与工具​

根据实时会话状态或外部系统，动态决定可用的工具和数据。

  • 场景示例：一个智能家居 Agent，只有在用户完成设备绑定（State 更新）后，才开放设备控制工具。
  • 实现方式：通过 wrap_model_call 中间件，在每次模型调用前根据 State 动态过滤工具列表。

简单来说，当你的 Agent 需要“因时、因地、因人”而表现出差异时，就需要用到上下文工程。 它解决了仅凭一个固定 Prompt 无法让 Agent 灵活、可靠地应对现实世界复杂需求的问题。