Agently 文档

中文

English

中文

English

Appearance

Context Engineering ​

语言：English · 中文

模型只看得见上下文窗口里的内容。Context engineering 就是决定「放什么、放哪、不放什么」的纪律。

上下文从哪来 ​

来源落在哪生命周期
role / system 槽system 消息agent 持久
info 槽system 或 user（实现细节）持久或单次
instruct 槽user 消息持久或单次
input 槽user 消息单次
Session chat historyuser/assistant 消息跨请求累积
Session memosystem 消息持久，由自定义 resize handler 写入
知识库检索检索代码注入单次按需
工具 / MCP 结果tool 消息单次工具循环内累积

按职责选槽：

  • role / system —— 模型是谁、硬性规则（语气、人设、拒绝模式）。
  • info —— 跨调用不变的事实（产品目录、严重度等级、格式约定）。
  • instruct —— 这类请求该怎么做（步骤、顺序、输出风格）。
  • input —— 每次调用都变的单一 payload。
  • chat history —— 当前会话里用户与模型说过的话。
  • memo —— 应用自定义压缩后的长期上下文。
  • KB —— 大规模、不总是相关的知识。

不要全往 input 塞。也不要把每次都变的 payload 写进 info。

何时用什么 ​

你有的内容放进
agent 的人设、语气、能力规则role（always=True）
模型必须知道的固定枚举（如严重度代码）info（always=True）
一类任务的步骤指令instruct（always=True 当 agent 只做这类任务）
一次调用的可变 payloadinput
上几轮对话session chat history
100k tokens 公司文档KB + 检索，不放进 prompt
当前轮检索到的相关事实仅本次请求的 info

让 info 可 diff ​

info 接受 dict，框架渲染。这比手工把 JSON 拼进 prompt 好 —— diff 可读，框架可一致地渲染成 YAML / JSON / 伪表格。

python
agent.info({
    "severities": ["P0", "P1", "P2", "P3"],
    "format": "用 markdown bullet，无开场白。",
}, always=True)

不要手抄工具目录 ​

用了 actions / tools 后，框架会在模型规划工具调用时自动注入工具目录。不要手工把工具描述抄进 info。详见 Action Runtime。

Session vs KB vs info ​

场景最合适的位置
「记住用户在这次对话里报的姓名」session chat history
「跨多次对话记住用户偏好」自定义 session resize / memo，或应用层用户画像
「从知识库里查到相关片段」KB 检索 → 把片段放进单次 info
「模型每次都要看的固定列表」info(always=True)
「用户刚发了 500 字的问题」input

压缩优于截断 ​

上下文窗口快满时：

  • 默认 session 只按 session.max_length 做窗口裁剪；需要摘要时，注册自定义 resize handler，把摘要写入 session memo。详见 会话记忆。
  • 一次性长输入，先摘要再请求，不要中间截断。

单次 info 而不污染 agent ​

python
result = (
    agent
    .info({"retrieved_snippets": chunks}, always=False)  # 仅本次
    .input(question)
    .output({...})
    .start()
)

不传 always=True，info 仅本次有效。

另见 ​