文档中心

Appearance

控制台

配置模型、提示词与上下文压缩 ​

智能体开发服务平台（AgentWorks）的模型和系统提示词决定智能体的基础行为。先用默认模型参数得到可验证结果，再根据固定测试和真实 Trace 调整随机性、思考和上下文压缩。

在 AgentWorks 管理控制台中打开要配置的智能体模板。你可以选择已有模板，也可以新建模板。

按钮会在新标签页打开控制台。若先进入登录页，控制台目前不会在登录后自动返回目标页面；请登录后返回本文，再次选择按钮。

打开智能体模板

选择模型凭证和模型 ​

在智能体模板的 模型配置 中选择：

  1. 模型凭证：保存模型服务的 API Key、Base URL 和可用模型。
  2. 模型：智能体实例根据该模板运行时调用的模型。

如果下拉列表中没有目标模型：

  1. 打开 凭证管理。

    打开凭证管理

  2. 检查凭证连接和模型列表。

不要通过在系统提示词中写模型名称来切换模型。

编写可验证的系统提示词 ​

系统提示词至少应说明：

  • 智能体的职责和不处理的范围。
  • 缺少信息时应如何提问。
  • 什么时候允许调用工具。
  • 返回格式、语气和必要字段。
  • 遇到高风险操作时应等待批准。

把可观察行为写成明确约束。例如：

language-text
你负责根据内部知识库回答合同条款问题。
只使用检索结果中的事实；没有结果时说明无法确认。
如果用户要求修改或删除业务数据，必须先等待工具批准。
回答末尾列出使用的文档标题。

如果不同智能体实例需要补充客户名称或环境信息，可以把相应提示词参数设为实例创建时可配置。

调整模型参数 ​

可以配置以下模型参数：

  • 温度：控制输出随机性。事实型任务通常从较低值开始。
  • 启用思考：请求模型使用思考能力，是否生效还取决于模型。
  • 存在惩罚：调整模型引入新内容的倾向。
  • 频率惩罚：调整重复词语或内容的倾向。
  • 最大生成长度：显示当前模型支持的生成上限。
  • 最大上下文长度：显示当前模型支持的上下文上限。

一次只调整少量参数，并在相同测试输入下比较 Trace。模型上限是只读信息，不能通过智能体模板表单扩大。

在长会话中启用压缩 ​

同一会话的历史会随着对话不断增长。未启用压缩时，长会话最终可能出现上下文超限，或者无法可靠地继续使用早期约束和任务信息。启用压缩后，AgentWorks 会把较早的对话整理成较短的摘要，并保留近期原始消息，为后续对话腾出上下文空间。

新建智能体模板时，启用压缩默认关闭。

注意

不确定时怎么选？

如果智能体面向聊天、渠道或持续协作场景，用户通常会反复使用同一会话，请在 压缩配置 中同时开启 启用压缩和 使用新版压缩。

如果每次请求相互独立，任务完成后会开始新会话，可以保持关闭。

压缩可以降低长会话触及上下文上限的风险，让对话持续更久，但不能扩大模型的上下文窗口，也不能保证逐字保留所有早期细节。压缩还可能增加模型用量和响应时间，因此仍应使用固定长会话验证关键事实和任务连续性。压缩不会使会话过期、清空会话历史或删除会话数据。

把长期稳定的行为要求写入系统提示词，把可重复检索的业务资料放入知识库。需要跨会话保存的用户事实使用记忆库或业务系统保存，不要把长会话历史当作唯一存储。

新版压缩使用主模型自动摘要；平台还会向模型提供 compact_conversation 工具，不需要单独选择压缩模型或设置阈值。

保存模板后，已有智能体实例不会自动采用新压缩方式。先同步或更新测试实例，必要时重启实例，再用固定长会话验证；验证通过后再更新生产实例。

选择新会话还是上下文压缩 ​

根据后续任务是否需要原对话，以及信息需要保存多久，选择会话、压缩或外部存储方式。

  • 后续任务不需要参考原对话：开始新会话。API 调用不发送原 session_id；渠道单聊使用 /session new。
  • 同一任务会持续很多轮，并需要保留早期信息：继续原会话并启用上下文压缩。
  • 稳定事实需要跨会话使用：保存到记忆库或业务系统。
  • 需要按期限清理会话历史：按照目标环境的数据保留和清理流程处理，不使用上下文压缩代替删除。

如果业务允许把长任务拆成多段，优先在用户、主题、任务或权限范围变化时开始新会话。只有连续上下文本身有价值时，才让会话持续增长并使用压缩控制上下文预算。

配置新版压缩 ​

  1. 开启 启用压缩。
  2. 开启 使用新版压缩。
  3. 保存智能体模板，并同步或更新测试智能体实例。
  4. 重新进入测试实例；如果实例仍使用旧配置，重启实例后再测试。
  5. 使用接近真实业务的长会话，确认自动摘要后仍能正确使用早期约束和近期工具结果。

新版压缩还会提供 compact_conversation，模型可以在需要时主动压缩当前会话。该工具由平台自动允许，不会产生工具权限审批。不要在提示词中要求每轮调用它，也不要把工具调用本身当作压缩正确性的证明；仍需验证压缩后的回答和任务连续性。

用长会话验证结果 ​

  1. 在会话前几轮加入后续必须使用的事实，例如订单号、用户约束和未完成任务。
  2. 在中间轮次修改其中一个事实，验证后续使用新值而不是旧值。
  3. 使用接近真实业务的中文消息、工具调用和大段工具返回延长会话。
  4. 在后续轮次要求智能体引用早期事实、近期工具结果并继续未完成任务。
  5. 分别使用关闭压缩和开启新版压缩的配置，比较事实保留、延迟、Token 用量和工具连续性。
  6. 继续延长会话，验证多次压缩后关键事实仍然正确。
  7. 每次只修改模型、提示词、工具或压缩开关中的一项，再重新比较结果。

以长会话的实际结果判断配置是否合适。Trace 可以帮助核对模型和工具调用，但不要仅凭一次调用成功判断压缩策略可用于生产。保留固定测试对话，在模型、提示词、工具或压缩配置变化后重新运行。

如果无法在预期会话长度内稳定保留关键事实，应继续缩短单个会话，或暂时关闭压缩并由业务系统主动创建新会话，再调整配置。

注意

上下文压缩不是记忆库，也不会扩大主模型的上下文窗口。它用于控制长会话中的上下文；需要保存和检索记忆条目时，配置记忆库。

旧版压缩 ​

旧版压缩（兼容模式）已弃用，不推荐用于新配置。仅在迁移或排查现有旧版配置时使用本节；新配置请按照在长会话中启用压缩配置新版压缩。

警告

仅用于迁移和排障

在已经开启压缩的配置中，关闭 使用新版压缩会启用旧版压缩。已有实例应规划迁移到新版压缩，并在更新生产实例前完成固定长会话验证。

新版压缩和旧版压缩不会同时生效。旧版压缩的压缩模型与主模型使用同一个模型凭证；迁移或排查前，确认该凭证可以调用所选压缩模型。

确定旧版压缩的可用上下文预算 ​

旧版压缩已弃用，不推荐用于新配置。仅在迁移或排查现有旧版配置时，关闭 使用新版压缩。压缩模型最大长度与压缩阈值共同控制何时尝试压缩。填写时取主模型和压缩模型可用上下文上限中较小的一个，并继续为以下内容留出空间：

  • 系统提示词和临时指令。
  • 工具定义、工具调用和工具返回。
  • 记忆库检索结果。
  • 图像等多模态输入。
  • 本轮模型输出。

降低最大长度或压缩阈值都会让压缩更早发生。上下文计量不等同于所选模型分词器的精确 Token 数；中文、工具密集型和多模态会话应留出更多余量，不要直接把模型公布的最大上下文长度当作可全部使用的历史预算。

配置旧版压缩策略 ​

上下文压缩配置中的新版压缩开关，以及兼容模式的模型、最大长度、压缩阈值、保留阈值和温度
  • 启用压缩：开启长会话压缩。需要停用时关闭此开关。
  • 使用新版压缩：推荐保持开启。仅在迁移或排查旧版压缩配置时关闭；关闭后显示的压缩模型和阈值字段只参与旧版压缩。
  • 压缩模型：选择用于处理长会话上下文的模型。优先选择指令遵循稳定，并且成本和延迟适合当前业务的模型。
  • 压缩模型最大长度：确定压缩模型可处理的长度，并参与计算触发位置。默认值为 131072；应按照较小的可用模型上下文和所需余量下调。此设置不会扩大主模型的上下文上限。
  • 压缩阈值：控制何时开始压缩。降低该值会更早压缩，通常增加压缩调用次数；提高该值会减少调用，但更接近上下文上限。先使用默认值 0.7。
  • 保留阈值：控制压缩后保留多少较新的原始历史。提高该值有助于保留近期细节，但会减少释放的空间。先使用默认值 0.3。
  • 压缩温度：控制压缩结果的随机性。事实型业务建议从默认值 0.1 开始。

需要停用压缩时，请关闭 启用压缩。阈值、温度和最大长度应填写有效的非零值。

决定是否允许实例覆盖 ​

在已弃用的旧版压缩模式中，每个压缩字段旁的 可配置 决定创建智能体实例时能否修改该值：

  • 不勾选：所有智能体实例使用智能体模板保存的值。
  • 勾选：从智能体模板创建实例时，可以为该实例覆盖该值。

只有不同环境、客户或模型凭证确实需要不同压缩策略时才开放实例覆盖。生产实例应记录最终使用的压缩模型和参数；修改模板后，还需要更新已有实例才能采用新配置。

根据长会话症状调整 ​

使用固定长会话输入重现问题，再根据观察结果选择优先调整项。

观察到的结果优先测试的调整
在压缩发挥作用前出现上下文超限降低压缩模型最大长度或压缩阈值
较新的指令或工具结果丢失适度提高保留阈值
压缩后释放的空间不足降低保留阈值，并减少不必要的大段工具返回
较早事实被错误改写选用更可靠的压缩模型，保持低温度，并把稳定规则移入系统提示词
延迟或模型用量明显增加在上下文余量测试通过后，逐步提高压缩阈值
中文、工具密集型或多模态会话仍在接近上限时失败降低最大长度或压缩阈值，为估算误差和额外输入留出更多空间

不要同时改变多个值。否则无法判断哪一项改善或破坏了结果。

迁移或排查旧版压缩时，把当前配置加入固定长会话对照，记录压缩模型、最大长度、阈值、事实保留、延迟、Token 用量和工具连续性。每次只修改一个旧版参数。切换到新版压缩后，先同步或更新测试智能体实例，必要时重启实例，再验证生产实例。

通过实例参数区分环境 ​

只有表单中被标记为可配置的字段才会在创建智能体实例时出现。把环境差异集中在少量参数中，并为生产实例记录最终值。修改智能体模板后，已有智能体实例不会自动采用新配置，需要处理配置同步状态。

参见更新智能体模板并验证现有实例。