Local Agent
Local Agent 是 LangBot 官方的进程内运行器。它在 LangBot 插件进程中完成提示词组装、模型调用、工具循环、知识库检索、上下文压缩和技能调用，适合使用 LangBot 托管模型与工具的通用 Agent 场景。
运行器 ID
plugin:langbot-team/LocalAgent/default
SDK 兼容性
LocalAgent 0.2.3 使用 langbot-plugin>=0.7.18,<0.8.0，允许同一 0.7 系列的稳定补丁更新，不再精确锁定单个 SDK 版本。测试环境的 uv.lock 仍固定已验证版本以保证可复现；插件包的 requirements.txt 与项目声明使用相同的兼容范围。跨 0.8 系列升级需要单独验证。
主要能力
- 支持主模型与 fallback 模型切换。
- 支持流式与非流式模型调用。
- 支持 LangBot 工具调用，并可选择同批工具并行或串行执行。
- 支持多知识库检索、重排和 Top-K 控制。
- 支持文本、图片、音频和文件等结构化输入。
- 支持基于模型上下文窗口的 token 预算与自动压缩。
- 支持 Host 管理的技能发现、激活和注册工具。
- 支持运行中断和同一会话内的 steering 跟进消息。
工作方式
LangBot 负责运行信封、资源授权与结果投递；Local Agent 负责 Agent 循环。每次运行会收到当前事件、输入、会话句柄、授权资源和运行时信息。需要历史、模型、工具、知识库或状态时，插件通过 RunnerAPIProxy 调用 Host API，不直接访问 LangBot 内部管理器。
典型流程如下：
- 获取预处理后的有效提示词和授权的历史记录。
- 组装当前输入、历史、RAG 结果、技能提示和工具定义。
- 使用 Host token 计数 API计算上下文预算。
- 必要时生成或复用会话级压缩摘要。
- 调用模型并处理工具调用，直到得到最终回复或达到迭代上限。
- 将流式增量、工具事件、状态更新和最终结果交给 LangBot 投递。
配置
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
model |
model-fallback-selector |
是 | 主模型为空，fallback 为空，reasoning 为 {} | 选择主模型及备用模型 |
timeout |
integer |
否 | 300 |
整次运行超时秒数；0 或 null 仅关闭插件本地超时，Host 截止时间仍有效 |
prompt |
prompt-editor |
是 | You are a helpful assistant. |
默认系统提示词；Host 提供有效提示词 API 时优先使用预处理后的结果 |
remove-think |
boolean |
否 | false |
请求模型适配器移除思考内容 |
knowledge-bases |
knowledge-base-multi-selector |
否 | [] |
用于 RAG 的知识库 |
box-enabled |
boolean |
否 | true |
启用沙箱执行和文件工具 |
box-session-id-template |
string |
是 | {launcher_type}_{launcher_id} |
预设下拉选择共享范围，支持自定义插值模板 |
advanced-settings |
boolean |
否 | false |
展开检索、工具、超时和上下文管理的高级参数；仅影响表单显示 |
date-grounding |
boolean |
否 | true |
注入当前 UTC 日期，并提醒核实时效信息 |
retrieval-top-k |
integer |
否 | 5 |
每个知识库请求的检索条数 |
rerank-model |
rerank-model-selector |
否 | 空 | 可选重排模型 |
rerank-top-k |
integer |
否 | 5 |
重排后保留的结果数 |
max-tool-iterations |
integer |
否 | 100 |
最大工具跟进轮数 |
tool-execution-mode |
select |
否 | parallel |
同批工具调用使用 parallel 或 serial |
max-tool-result-chars |
integer |
否 | 20000 |
注入下一次模型请求的工具结果字符上限 |
context-history-fetch-limit |
integer |
否 | 50 |
从 Host 历史 API 拉取的消息数 |
context-window-tokens |
integer |
否 | 200000 |
上下文窗口 fallback，同时作为 Host 模型元数据的上限 |
context-reserve-tokens |
integer |
否 | 16384 |
为模型输出和 provider 开销预留的 token |
context-keep-recent-tokens |
integer |
否 | 20000 |
压缩时保留的近期历史 token |
context-summary-tokens |
integer |
否 | 8000 |
压缩摘要的最大 token |
上下文管理
Local Agent 不按固定对话轮数截断历史，而是按最终 provider 消息和工具 schema 的 token 数进行预算。超过输入预算时，会通过授权模型生成结构化摘要，并保留近期历史。Host 支持状态 API 时，摘要会以会话级 checkpoint 持久化；下次运行可从 checkpoint 游标之后继续拉取历史。
如果 provider 在尚未输出内容前返回上下文溢出错误，Local Agent 会使用更激进的预算再压缩一次，并重试当前模型调用一次。Host 不提供 token 计数能力时，运行会失败关闭，不使用不可靠的字符估算替代。
工具与大结果
工具调用通过 Host 授权列表执行。过大的工具结果只向模型提供有界预览；工具明确返回的路径、URL 或其他外部引用会被保留。工具可返回顶层 terminate: true，当同批所有工具结果都请求终止时，Local Agent 会跳过额外模型调用并结束当前运行。
技能支持
当 Host 提供技能资源并允许 activate 或 register_skill 工具时，Local Agent 会将可见技能事实加入模型上下文。技能包、挂载路径和可见性策略由 LangBot 与 Box 管理，Local Agent 只负责把授权能力呈现给模型并转发工具调用。
权限与安全边界
插件声明并使用以下 Host 权限：
- 模型：
count_tokens、invoke、stream、rerank - 工具：
detail、call - 知识库：
list、retrieve - 历史：
page
“Local”表示 Agent 循环运行在本地插件进程中，并不表示模型可以访问运行机器的任意文件。文件和沙箱操作必须通过本次运行授权的 Host 或 Box 工具完成。
开发与测试
uv sync --dev
uv run --no-sync pytest -q
uv run --no-sync ruff check .
本地联调需要使用包含 Runner Protocol v1 的 LangBot Plugin SDK。若 LangBot 固定的 PyPI 版本缺少新实体，请先安装工作区中的本地 SDK，并使用 uv run --no-sync 启动，避免同步过程覆盖 editable 安装。
文件交付
文件写入 sandbox 后不会自动交付。模型需要显式调用 export_box_files(paths)，传入要交付的绝对路径；建议把生成物放在本次 run 的 outbox 中。Core 会先完整校验所选文件，成功后登记附件并仅清理所选文件，其他文件保持不变。导出错误通过对应的工具结果返回同一上下文，重试沿用原来的工具、上下文和时间预算，没有独立的两次自动修复循环。
清理警告不代表导出失败，不应因此重复交付。Core 接收后的平台发送失败会终止运行，避免重新生成或重发可能已经送达的文件。流式文字已发出时不会被撤回。
此分支配合 LangBot #2641 和 SDK #180，开发与 CI 用 uv.lock 固定 SDK 提交 b300830b0e5339e7989be237efa811bedf761d55。已发布的 SDK 0.7.4/0.7.13 不包含新的路径参数；Core 和 Plugin Runtime 必须使用配套版本，插件会在旧 SDK 上明确拒绝准备文件工具。待对应 SDK 发布后，由维护者统一更新发布版本依赖。
当前边界
- 不负责 EventGateway、事件订阅、调度器或事件广播。
- 不绕过
ctx.resources访问未授权模型、工具、知识库或平台 API。 - 不在插件实例上保存可变的跨会话状态；需要持久化时使用 Host 管理的状态或存储接口。
原生运行器迁移说明
以上字段属于每条流水线的 Runner 绑定配置（ai.runner_config[plugin:langbot-team/LocalAgent/default] / 解析后的
binding.runner_config），不是插件全局配置。model.reasoning 默认 {}，按模型 UUID
保存 provider-neutral 等级：provider_default、disabled、enabled、minimal、low、
medium、high、xhigh、max。Host 必须从描述符声明的模型选择器读取配置，在运行开始时
冻结到授权快照，并对主模型、fallback、工具跟进与摘要请求使用请求级模型副本。插件不生成
供应商参数，也不扩展 SDK/wire；需要支持该桥接的 Host，单纯保存配置不代表推理等级已生效。
remove-think 只控制思考输出过滤，不代表推理强度。
date-grounding=true 默认在 token 预算计算前注入当前 UTC 日期与时效信息核实提示，
并保留静态或 Host 有效提示词。UTC 不等于推测用户时区；已有独立日期提示时可设为 false。
SDK 支持的结构化提示词内容与消息元数据会保留；无效内容显式报错，不再静默丢弃。
迁移采用新默认：token 预算与 checkpoint 压缩替代 max-round，不做轮数到 token 的伪换算；
工具结果上限 20000 字符、总运行超时 300 秒、工具跟进上限 100 轮；保留有界且独立的 RAG 上下文。
timeout=0/null 只关闭插件本地超时，不能取消 Host 截止时间。retrieval-top-k=5 为每个知识库
请求 5 条，无重排时合并后也最多保留 5 条；有重排时使用 rerank-top-k=5。
保留 tool-execution-mode=parallel 默认以并发执行独立工具，结果仍按源顺序返回。
结果排列不代表执行顺序，有副作用或依赖顺序的操作可能竞争，应选择 serial；
两种模式均不能扩大 Host 授权范围。工具、MCP 附件/可见性、技能授权由 Host 管理，Box 复用由运行器配置控制，
不可移到插件全局配置。旧 knowledge-base 和字符串 model 分别需要显式迁移为
knowledge-bases 与模型选择器；旧历史与 Box 文件共享范围必须另行分析，压缩不等于数据导入。
Box 沙箱
沙箱开关和复用范围在运行器配置中设置。默认 {launcher_type}_{launcher_id} 按聊天复用；
{global} 在当前工作区共享，也可用 {sender_id}、{bot_id}、{run_id}、{event_type}
和当前请求变量组合模板。变量不存在时会明确报错，不会悄悄把不同会话合并。
托管环境要求固定共享范围时，运行器采用 Host 返回的范围限制。
LocalAgent 在执行前获取并绑定 Box，再导入当前附件。生成的文件须放到提示词指定的 本次运行 outbox 中。成功完成后，流水线把导出的文件作为回复附件发送；Agent 通过 当前事件的回复 API 发送，仍遵守该事件允许调用的工具范围。关闭沙箱后不提供原生文件和执行工具。
Box 复用不等于文件发送范围复用：每次运行的收件与发件目录独立。Box 空闲回收后会重新创建， 工作区文件保留，容器内部进程不会保留。