Stirrup 是一个轻量级的 Python 构建 AI Agent 框架，而 Agent 的运行行为——跑多少轮、何时压缩上下文、能用哪些工具、何时结束任务——几乎全部由Agent构造函数的 12 个关键配置参数决定。本文结合源码逐个拆解这些 Stirrup Agent 参数，帮你用最少的配置调出最稳的 Agent。

Agent 参数总览：12个配置项一览表

所有参数都定义在Agent.__init__中，源码见 src/stirrup/core/agent.py#L345-L365，默认值集中在 src/stirrup/constants.py#L20-L23。先看全景表：

💡 除client和name两个必填项外，这 12 个参数全部有合理默认值，意味着你可以零配置直接跑通，再按需微调。

控制执行节奏的参数

1.max_turns：Agent 运行的硬性天花板

每轮 = 一次「LLM 生成 → 工具执行 → 消息累积」。到达max_turns后即使任务没完成也会强制停止，并记录Maximum number of turns reached错误日志。默认 30 轮（AGENT_MAX_TURNS）。

• 简单问答类任务：设小一点（如 10），省 Token 又省时
• 多文件、多步骤的重任务：适当调大，避免 Agent 做到一半被掐断

2.turns_remaining_warning_threshold：剩余额度的预警线

当剩余轮数 ≤ 该阈值时，Stirrup 会自动向对话注入一条警告消息（"你还有 N 轮"），最后一轮甚至会提示"请立即调用 finish 工具"。这样模型会主动收束任务，而不是被突然"断电"。

⚠️ 注意它必须小于max_turns才有意义。默认组合（30 / 20）表示从第 10 轮开始每轮都会收到提醒。

3.run_sync_in_thread：同步工具不阻塞事件循环

工具执行器可以是异步函数，也可以是同步函数。若为同步函数且此参数为True（默认），Stirrup 会将其放到独立线程中运行（基于anyio.to_thread），避免长时间命令卡死整个异步循环。高并发布会话场景下这个默认值非常重要，一般无需改动。

控制上下文管理的参数

4.context_summarization_cutoff：自动摘要的触发比例

这是 Stirrup 上下文管理的核心。每轮结束后，框架会计算「本条消息总 Token ÷ 模型的context_window_tokens」，一旦达到该比例（默认 0.7，即 70%），就把较早的历史消息交给摘要器压缩成一条SummaryMessage，保留任务上下文的同时腾出窗口空间。

• 调低（如 0.5）：更早压缩，适合窗口小或长任务
• 调高（如 0.85）：压缩更少，历史细节保留更久，但溢出风险上升

5.recover_from_context_overflow：溢出了还能救吗

如果模型直接报上下文溢出（ContextOverflowError），开启此参数（默认True）时，Stirrup 会丢弃最近一轮未完成的内容、对剩余历史做摘要，然后自动重试——对用户来说任务看起来只是"多花了一点时间"。关闭它则错误直接抛出。对生产环境建议保持开启。

控制行为的参数

6.system_prompt：在基础提示词之上加规则

Stirrup 会先拼装一段基础系统提示词（包含任务目标、max_turns、输入文件清单、技能清单），然后把你提供的system_prompt作为"用户指令"追加在末尾。适合写入角色设定、输出格式要求、领域约束等。

7.tools：决定 Agent 的能力边界

不传则使用 src/stirrup/tools/init.py 中的default_tools()，包含本地代码执行（code_exec）与网页工具（web_fetch、web_search）。常见用法是tools=[*default_tools(), 自定义工具]。两点提醒：

• 工具名不能与 finish 工具重名，否则构造时直接抛错
• 框架会在运行前做配置体检，例如使用LocalCodeExecToolProvider会提示"可访问本地文件系统，建议换成 Docker/E2B 沙箱"

8.finish_tool：任务如何算"完成"

默认使用内置的finish工具（定义见 src/stirrup/tools/finish.py），模型调用它并返回reason时，run()返回结果、运行结束。你也可以传入自定义工具或一个工具列表——调用列表中任意一个即视为完成，适合"成功/失败/需人工接管"多出口的场景。注意同一轮内调用多个 finish 工具会被整体拒绝，迫使模型改用单次调用。

9.block_successive_assistant_messages：防止模型"空聊"

有些模型会连续输出文字而不调用任何工具，导致任务原地打转。开启（默认）时，Stirrup 检测到某轮没有工具调用，会自动注入一条 "Please continue the task" 用户消息，把 Agent 重新推回执行轨道。

10.text_only_tool_responses：纯文本模型的图片处理

工具结果可能包含图片块，但部分模型只接受纯文本。开启（默认）时，Stirrup 会把图片块从工具消息中抽出、转成独立的用户消息，并在原位置留下文字占位说明，保证多模态与纯文本模型都能正确消费工具结果。

子Agent与可观测性参数

11.share_parent_exec_env：子 Agent 要不要共享执行环境

通过to_tool()把 Agent 包装成子 Agent 后，默认每个子 Agent 有独立的代码执行环境（需要文件拷贝）。设为True时，子 Agent 直接借用父 Agent 的执行环境：无需文件复制、性能更好，且能看到父环境中的全部文件；环境生命周期也由父 Agent 统一管理。适合子 Agent 之间大量交换中间文件的流水线场景。

12.logger：定制 Agent 的可观测性

传入自定义的AgentLoggerBase子类（基类见 src/stirrup/utils/logging.py）即可接管任务开始、每轮助手消息、工具结果、上下文压缩等全部事件输出；不传则使用内置AgentLogger()。对接自己的监控面板或 UI 时这是唯一的入口。

实战速查：常见场景怎么配

小结

Stirrup 的 Agent 参数设计遵循"默认即可用、按需再调优"：

1. 执行节奏三件套（max_turns/turns_remaining_warning_threshold/run_sync_in_thread）决定跑得久不久、稳不稳；
2. 上下文管理两件套（context_summarization_cutoff/recover_from_context_overflow）是长任务不翻车的关键；
3. 行为控制四件套（system_prompt/tools/finish_tool/block_successive_assistant_messages）定义 Agent 能做什么、怎么做、何时停；
4. 进阶参数（share_parent_exec_env/logger/text_only_tool_responses）分别服务多 Agent 协作、可观测性与模型兼容性。

更多细节可查阅 docs/api/core/agent.md 与完整示例 examples/getting_started.py。