English mirror

This English page is generated from the current Chinese documentation so every route, anchor, code sample, and language switch stays available on agently.tech. Human-edited English copy can replace this generated body page by page.

Read the Chinese source page

Context Engineering

模型只看得见上下文窗口里的内容。Context Engineering 解决的是“什么应该出现在窗口里、以什么身份出现、什么时候不该放进去”。

很多应用出问题，不是因为上下文少，而是所有东西都塞进 input：固定规则、用户问题、检索片段、历史对话、工具说明混成一团。Agently 的槽位、Session、Knowledge Base 和 Workspace 是为了把这些来源拆开。

常见上下文来源

来源	放在哪里	生命周期
模型角色和硬规则	role / system	agent 持久
固定枚举、产品资料、格式约定	info(always=True)	agent 持久
一类任务的处理步骤	instruct(always=True)	agent 持久
本次用户输入或业务 payload	input	单次
本轮检索片段	info(always=False)	单次
多轮对话历史	Session chat history	跨请求
自定义摘要记忆	Session memo	跨请求
大规模知识资料	Knowledge Base + 检索	按需
多轮任务证据和 artifact	Workspace records	持久
Action / MCP 调用结果	tool/action 结果	本次 request

先按职责选位置，再写 prompt。不要先拼一个大字符串。

固定内容放 info

agent.info({
    "severities": ["P0", "P1", "P2", "P3"],
    "reply_policy": "客户回复不超过 120 字，不承诺未确认修复时间。",
}, always=True)

dict 比手写一段 JSON 字符串更适合 review，也更容易被框架稳定渲染。

本次内容放 input

result = (
    agent
    .input({
        "ticket_id": "T-104",
        "message": "Enterprise billing export failed twice.",
    })
    .output({...})
    .get_result()
)

每次都变的业务 payload 放 input。不要把它写进 agent 级 info，否则后续请求会继续携带旧数据。

检索片段只放本次

result = (
    agent
    .info({"retrieved_snippets": chunks}, always=False)
    .input(question)
    .output({...})
    .get_result()
)

不传 always=True，这份 info 只属于当前 execution。RAG 场景通常应该这样做：Knowledge Base 负责检索，检索到的片段进入本次 prompt。

Session、KB、Workspace 怎么分

场景	最合适的位置
用户刚刚在这次对话里说过订单号	Session chat history
用户长期偏好	应用层用户画像，或自定义 Session memo
100k tokens 公司文档	Knowledge Base，不直接塞 prompt
当前轮检索到的 3 个相关片段	单次 info
测试输出、patch、运行日志、decision record	Workspace
模型可调用的工具列表	Actions 自动注入，不手抄进 info

Session 管当前对话，KB 管可检索知识，Workspace 管多轮任务证据。

渐进式披露是一条通用原则

Agently 里很多能力都在解决同一个问题：上下文窗口有限，不能把所有规则、工具、资料、日志和产物都常驻给模型。

对象	常驻什么	用到时再取什么
Skills	name、description、decision card	完整 SKILL.md、references、scripts、assets
Workspace	record ref、summary、scope、checkpoint	artifact 全文、日志、报告、历史 decision
Knowledge Base	collection、query、检索配置	本轮相关片段
Actions / MCP	本轮可见 action schema	action 执行结果、外部资源内容

这个原则能同时降低 token 成本和误用风险：模型只看见当前任务需要的能力和证据，调用、读取、写回都能留下记录。

压缩优于截断

上下文窗口快满时，直接截断往往会丢掉关键事实。

可选策略：

• Session 默认只做长度裁剪；需要摘要时注册自定义 resize handler。
• 大文档先检索，再把相关片段放进单次 info。
• 命令输出和 artifacts 存 Workspace，prompt 里只放摘要和 record refs。
• 长输入先分段处理，再把中间结构化结果交给下一步。

不要手抄工具目录

用了 Actions 或 MCP 后，框架会在模型规划工具调用时注入工具目录。手工把工具描述写进 info 容易和真实 action surface 不一致。

继续读：Actions 概览

常见误用

• 所有背景都塞进 input。
• 检索片段用 always=True，导致下一轮继续污染上下文。
• 把知识库全文塞进 prompt。
• 把 Workspace 里的长日志直接塞进 prompt，而不是摘要和引用。
• 把 Skill 正文、资源和脚本说明全量塞进每次请求。
• 手抄工具目录，和实际 Actions 注册不一致。

下一步

• Prompt 槽位：Prompt 管理
• 会话历史：会话记忆
• 知识库：知识库
• 多轮任务记录：Workspace
• Actions 工具目录：Actions 概览