FastGPT Agent Loop 模型循环协议解析统一架构、暂停恢复与用量计费【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT本文以 FastGPT 仓库中.agents/design/core/ai/agent-loop/index.md设计文档为骨架结合packages/service/core/ai/llm/agentLoop与packages/service/core/workflow/dispatch/ai/agentLoopCore的实际源码系统讲解 FastGPT 中 Agent Loop 的分层架构、Input/Runtime/Result/Event 公共协议、系统工具模型、Checkpoint 上下文压缩、ask/子工具交互的暂停恢复机制以及单次上报的用量计费链路。读完本文你将掌握runAgentLoop这一唯一公共入口背后的设计取舍理解 Workflow Agent 与 ToolCall 节点如何共用同一套模型循环协议并能基于源码定位各关键能力的实现与测试位置。Agent Loop 是什么为模型循环提供稳定协议Agent Loop 是 FastGPT 为不同 Agent provider 和上层业务提供的一个稳定的模型循环协议层。它统一了以下语义模型请求、工具调用、计划plan、询问ask与上下文压缩流式事件、完整消息、暂停状态与 provider 恢复状态模型、工具与压缩用量的单次上报fastAgent与piAgent两个 provider 的业务可见行为。同时Agent Loop 明确不负责Workflow 节点输出、数据库写入、SSE 协议、权限鉴定或具体工具业务——这些职责由上层 adapter 承担。协议边界的清晰划分保证了底层循环逻辑可以被 Workflow Agent、ToolCall 等不同节点形态复用而不被某一种业务耦合。分层架构从 Workflow 节点到 Provider 的三层边界设计文档给出了完整的分层结构结合仓库目录可对应如下Workflow Agent / ToolCall -- packages/service/core/workflow/dispatch/ai/agentLoopCore |-- context and runtime adapters |-- assistantResponses / nodeResponse collectors |-- interactive and usage adapters -- packages/service/core/ai/llm/agentLoop/interface |-- application: provider selection and usage collection |-- domain: input/runtime/result/event/tool contracts -- provider |-- fastAgent -- piAgentagentLoop与 provider 无关的协议核心目录为packages/service/core/ai/llm/agentLoop职责包括暴露唯一公共入口runAgentLoop实现在 interface/run.ts。调用方只依赖稳定协议不感知具体 provider 的目录与实现细节维护与 provider 无关的 Input、Runtime、Result、Event、Tool 与 Usage 协议全部集中在domain目录通过 registry 选择 provider。默认 provider 为fastAgent未知 provider 直接抛出Unknown agent loop provider错误避免业务层静默回退到错误的 loop见 provider/registry.ts把 provider 抛出的未处理异常收敛为status: error的标准结果收集实际通过usagePush上报的用量并随结果返回不二次触发计费。顶层入口runAgentLoopApplication见 application/run.ts在组合根中完成了 provider 选择与 usage 收集它包装runtime.usagePush把 provider/工具/压缩模块上报的 usage 规范化后同时转发给调用方与本地收集器最后作为只读 result 返回避免业务层为了补汇总再次计费。agentLoopCoreWorkflow 侧的适配层目录为packages/service/core/workflow/dispatch/ai/agentLoopCore职责包括把 Workflow 运行信息转换为通用 Agent Loop 的 Input 和 Runtime执行 workflow 工具、子 workflow 与交互工具消费标准事件生成assistantResponses、nodeResponse与 SSE 所需数据将底层paused状态转换为 Workflow 的interactive汇总节点使用的 token、积分、最终文本、错误与恢复状态。核心入口runAgentLoopCore见 application/run.ts包装底层的runAgentLoop它注入一个事件采集器将标准事件同时转发给assistantResponsescollector 与调用方的emitEvent运行结束后统一压缩重复的计划快照并在paused时把结果转成interactive状态。配套的runAgentLoopCoreWithSummary进一步返回 Workflow 节点常用的输出摘要requestIds、token/points、assistantResponses、interactive、error/finalText避免外层重复了解 Result 的内部结构。节点外壳共享 core、保留各自语义Workflow Agent 与 ToolCall 都调用agentLoopCore但保留各自节点语义Workflow Agentpackages/service/core/workflow/dispatch/ai/agent负责 Agent 配置、系统工具、历史上下文与 Sandbox/Skill 准备ToolCallpackages/service/core/workflow/dispatch/ai/toolcall是简化 Agent只装配传入的工具节点与模型参数两者自行决定节点输出字段与外层错误处理不复制Agent Loop 内部实现。公共协议Input / Runtime / ResultInput只包含模型循环可理解的数据AgentLoopInput见 domain/input.ts字段包括字段说明messages对话消息列表ChatCompletionMessageParam[]systemPrompt可选系统提示词activePlan当前计划AgentPlanTypeproviderStateprovider 私有但可持久化的状态userAnswerask 恢复时用户回答childrenInteractiveParams子工具恢复时的参数Runtime由调用方注入运行能力AgentLoopRuntime见 domain/runtime.ts是调用方向循环注入能力的唯一通道包含teamId与llmParams模型、reasoningEffort、temperature、maxTokens、topP、responseFormat、useVision/useAudio/useVideo 等systemTools启用的系统工具及所需 executor/clienttoolCatalogruntime tool catalogruntimeTools与可选batchToolSize统一executeTool与可选的executeInteractiveToolcheckIsStopping停止检查、usagePush用量回调、emitEvent事件回调。设计上底层不能从 Workflow 闭包读取额外状态新增业务能力时应先判断它属于通用协议、系统工具还是 Workflow adapter避免协议层与业务层互相穿透。Result四种状态的判别联合AgentLoopResult见 domain/result.ts使用判别联合表达四种状态done正常完成paused等待 ask 回答pause.type: ask或子工具继续执行pause.type: tool_childaborted用户停止或 provider 控制结束error执行失败同时尽量保留已产生的消息、requestId 与 usage。稳定返回字段AgentLoopResultBase包括completeMessages完整消息、assistantMessages当前轮 assistant 消息、requestIds、usages、activePlan、providerState、contextCheckpoint与finishReason。底层结果不包含 Workflow interactive schema暂停态统一通过pause承载再由 Workflow adapter 转成业务交互结构。工具模型系统工具与 Runtime 工具系统工具系统工具由 Agent Loop 维护统一语义目前包括工具语义plan创建和更新当前计划ask暂停本轮并等待用户回答sandbox使用准备好的 Sandbox client 执行系统工具readFile读取对话上传的文档datasetSearch查询当前可用知识库是否启用以及所需 executor/client 由 Runtime 显式传入见 domain/tool.ts。例如sandbox需要enabled clientreadFile需要enabled maxFileAmount executedatasetSearch需要enabled execute currentInputFiles。对应实现位于 domain/systemTool 目录其中ask含parser.ts参数解析与tool.tsplan含state.ts、reviser.ts与updateTool.ts。Runtime 工具业务工具通过toolCatalog.runtimeTools暴露由统一executeTool执行。执行结果AgentLoopToolExecutionResult见 domain/tool.ts包含response返回给模型的文本assistantMessages需要持久化的标准 assistant 消息usages工具产生的用量可选interactive子工具交互、stop、errorMessage、skipResponseCompress与metadata。Agent Loop不解释 metadata 的业务结构Workflow collector 在边界外消费它。事件与输出双消费者模型Provider 通过AgentLoopEvent见 domain/event.ts报告模型生命周期中的各类事件包括llm_request_start/llm_request_end模型请求开始与结束携带 modelName、requestId、finishReason、answerText、reasoningText、toolCalls、usages 与耗时reasoning_delta/answer_delta流式推理文本与回答增量tool_call/tool_params工具调用声明与参数流式增量tool_run_start/tool_run_end工具运行开始与结束tool_run_end携带 rawResponse、response、标准 assistantMessages、usages、toolResponseCompress 与 opaque metadataafter_message_compress消息压缩完成携带 usages、requestIds 与 contextCheckpointplan_status/plan_operation计划生成/更新状态与操作结果set_plan、add_steps、update_stepsask_start/ask/ask_resume询问生命周期。事件有两个独立消费者Workflow 事件流负责 SSEagentLoopCorecollector 负责assistantResponses与nodeResponse。assistantResponses的写入原则是单一来源调用方传入额外业务响应extraResponsescollector 只根据标准事件追加 Agent 响应最终统一压缩重复计划快照compactAgentLoopCorePlanSnapshots节点外壳不得再根据最终 messages 重复补写同一批工具结果。相关 collector 位于 adapter/assistantResponses 与 adapter/nodeResponse。上下文当前轮 reminder 与 Checkpoint 压缩当前轮 reminderagentLoopCore/application/context/reminder.ts见 reminder.ts统一构造当前用户消息中的动态上下文已部署 Skill 的名称、描述与SKILL.md路径buildAgentLoopCoreSkillsPrompt提示模型先用 sandbox read_file 读取完整技能文件再执行Sandbox 用户产物写入边界本轮文件的 id、名称、类型与 URLbuildAgentLoopCoreInputFilesPrompt文档可通过read_files协议读取多模态文件保留 URL 供模型引用当前可用知识库dataset列表含 id/name/description当前时间与 Sandbox 工作目录buildAgentLoopCoreEnvPrompt。这些内容放在 user message 的system-reminder标签中buildAgentLoopCoreUserReminderInput属于当前轮动态上下文历史消息只注入稳定文件片段。所有动态字段都会做 XML 转义escapeXml避免模型输出或文件内容破坏标签结构。文档文件通过read_files的{ ids }协议读取Sandbox 文件操作使用独立的 Sandbox 工具。Checkpoint 压缩历史上下文超过阈值时压缩模块packages/service/core/ai/llm/compress生成一个context_checkpoint字符串保留目标、约束、关键事实、工具结果、资源与下一步。其约束包括Checkpoint 是上下文不是可见回答也不能恢复成伪造的运行时计划当前 active plan 以确定性结构拼接避免模型摘要改变计划状态后续裁剪必须保留 leading CheckpointCheckpoint 作为隐藏 AI value 持久化恢复时从最新值开始重建消息模型与工具响应压缩产生的 usage 走同一用量协议。实现层面compress/index.ts 中的normalizeContextCheckpointContent会对 LLM 输出做规整去掉可能的 markdown 代码块围栏若模型已返回CONTEXT_CHECKPOINT_START_TAG/END_TAG则只保留第一段完整 checkpoint否则自动补齐标签。压缩阈值通过calculateCompressionThresholds与getCompressionTokenLimitconstants.ts计算包含CHECKPOINT_OUTPUT_TARGET_RATIO、FINAL_HEAD_RATIO、MERGED_COMPRESSION_MAX_ROUNDS等可调参数。Agent provider 只消费其标准结果不感知压缩内部实现。暂停与恢复ask 与子工具交互ask 流程ask 工具产生标准ask事件ask_start→askProvider 把暂停点 messages、ask call id 与计划写入providerState.pendingMainContextAgent Loop 返回status: paused与pause.type: askAgentLoopPause中携带ask载荷与askId见 domain/result.tsagentLoopCore将其转换为 Workflow interactiverunAgentLoopCore在paused时返回status: interactive用户回答后调用方通过userAnswer与providerState传回provider 在原工具调用后追加 tool response 并继续。子工具交互流程工具执行返回 interactive children responseAgent Loop 返回pause.type: tool_child与toolCallId恢复时调用方通过childrenInteractiveParams回传子流程结果Provider 把结果补到原工具调用上下文后继续。旧 interactive 快照的兼容读取集中在 adapter/memoryproviderState.ts与 provider 恢复边界新写入只使用标准结构。agentLoopCore侧的 interactive 转换见 adapter/interactiveask.ts与child.ts。用量与计费单次上报不重复计费设计文档明确了用量链路的四条原则Provider、工具与压缩模块只通过runtime.usagePush上报真实 usageapplication 层在转发回调时收集同一批 usage不能为了汇总再次计费agentLoopCore将通用 usage 转换为 Workflow 账单类型父 Agent 节点的inputTokens、outputTokens与llmTotalPoints只汇总agentCall项工具与压缩积分保留在各自的 nodeResponse/tool detail避免父节点重复计分。统一用量记录AgentLoopUsage见 domain/usage.ts包含inputTokens、outputTokens、pages、totalPoints、moduleName与modelId不依赖 workflow/chat node 的账单类型由调用方在 adapter 边界转换。稳定计费项展示名称AgentUsageModuleName定义了agentCall、contextCompress与toolResponseCompress三个模块。normalizeAgentLoopUsages负责过滤空 usage保证内部数组处理一致。主要代码入口能力路径公共入口interface/run.ts领域协议domainProvider 注册provider/registry.tsWorkflow CoreagentLoopCoreWorkflow AgentagentToolCalltoolcall历史压缩compress两个 provider 的循环实现分别在 provider/fastAgent含 loop/base.ts、message.ts、type.ts 与 tools与 provider/piAgent含 modelBridge.ts、payload.ts、run.ts、message.ts 与 tool/catalog.ts。验证范围协议改动的测试基线相关测试主要位于packages/service/test/core/ai/llm/agentLoopprovider contract 与公共协议测试packages/service/test/core/ai/llm/compressCheckpoint 压缩与 usage 上报测试packages/service/test/core/workflow/dispatch/ai/agentLoopCoreWorkflow 侧 adapter/collector 测试Workflow Agent 与 ToolCall 的节点测试目录。协议改动至少需要覆盖provider contract、collector、ask/child 恢复、Checkpoint 传播与 usage 单次上报五个方面。这套测试基线保证了不同 provider 与不同节点形态在协议变更后仍能保持一致的可观察行为。小结FastGPT 的 Agent Loop 通过领域协议 provider registry workflow adapter三层结构把模型循环中最高频、最容易失控的环节工具调用、暂停恢复、上下文压缩、用量计费收敛为一份稳定协议runAgentLoop是唯一公共入口agentLoopCore是 Workflow 侧的统一适配层fastAgent与piAgent通过 registry 可插拔替换。对于想要扩展新 provider 或新工具类型的开发者建议从 domain 的契约出发遵循先判断属于通用协议、系统工具还是 Workflow adapter的边界原则并以验证范围中的五类测试作为改动通过的底线。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考