AgentScope 框架应用项目技术解析:Agent 工作流程与 Plan 触发机制
该项目基于 AgentScope 框架构建,采用清晰的三层架构设计,将 Web 服务、Agent 执行与工具模型层有效解耦。系统以 FastAPI 作为 Web 服务入口,基于 Python 异步编程模型实现高并发处理;核心执行层通过 ReActAgent 负责智能推理与行动循环;工具与模型层则通过集成阿里云 DashScope 与自定义插件机制,提供外部交互能力。此外,系统设计了精细的会话管理与 Plan 触发机制,以支持从标准对话到深度研究的多模式切换。
01系统架构分层设计
- Web 服务层(接入网关)
基于 FastAPI 框架构建,利用 Python 异步特性处理 HTTP 请求。该层定义了 /chat 核心端点,采用 SSE 流式响应提供实时交互体验。系统启动时,lifespan 上下文管理器负责初始化全局会话管理器、定时任务管理器及技能目录。针对高并发场景,代码中实现了三重重试机制与 0.5 秒退避策略,专门处理会话过期瞬间的竞态条件,显著提升边界情况下的成功率。 - Agent 执行层(智能核心)
负责 ReActAgent 的生命周期管理与运行调度。该层采用无限循环的事件驱动模式(agent_runner),持续从会话请求队列中获取任务。架构上实现了精细化钩子机制(pre_reasoning、post_acting 等),用于注入时间信息、激活会话保活及防止任务中断。异步协程架构使得单个进程能高效管理多个 Agent 实例,显著提升资源利用率。 - 工具与模型层(交互边界)
遵循 AgentScope 的 Toolkit 设计模式,支持同步/异步工具函数、流式响应及并行工具调用。该层通过 FLAGS 字典管理运行时配置,包括系统提示词(AGENT_SYS_PROMPT)和子 Agent 提示词(SUBAGENT_PROMPT)的动态组装。工具注册采用条件编译模式,支持会话级别的灵活配置。
02核心并发与会话机制
- 单消费者事件模型
每个用户会话对应独立的 Session 实例,内部维护异步请求队列(asyncio.Queue)。系统采用单消费者模型,每个 Session 绑定唯一的 agent_runner 协程,确保请求按顺序处理,维护对话上下文的因果一致性。协程在无请求时通过 await 挂起,不占用 CPU 资源。 - 会话保活与状态管理
GlobalSessionManager 统一管理会话生命周期,设置 expires=60 的过期时间。对于长时任务,会话保活机制在 Agent 执行的关键节点持续重置计时器,防止任务被强制终止。会话状态包括 ACTIVE(活跃)和 INACTIVE(待清理),agent_runner 在检测到 INACTIVE 状态时会完成当前迭代后优雅退出。 - 数据契约与透传
ChatRequest 是交互的核心数据契约,包含 session_id、content 和 deepresearch 字段。Web 层将其转换为 AgentRequest 并透传给执行层,deepresearch 参数作为功能开关,决定是否激活 Plan 机制,实现 A/B 测试与降级能力。
03Plan 触发与执行逻辑
该项目的深度研究模式依赖于显式的 Plan 触发机制,通过 deepresearch 参数控制 Agent 的行为模式切换。
Agent 执行模式对比
deepresearch = False
依赖模型内在推理能力,通过 ReAct 循环逐步解决问题
plan_notebook 为 None,无全局计划结构
每轮迭代基于当前上下文决定下一步行动
适用于日常问答与简单交互


deepresearch = True
实例化 PlanNotebook,启动时生成完整或部分任务计划
每轮迭代参考计划确定当前子任务,并持续更新状态
支持任务的持久化、恢复与并行分解
适用于需要多步骤推理与信息检索的复杂场景
04模型配置与关键参数
| 配置参数 | 设置值/描述 | 设计意图与影响 |
|---|---|---|
| 基座模型 | qwen3.5-plus | 利用阿里云 DashScope 平台,针对中文场景深度优化,平衡工具调用能力与成本效益。 |
| API 兼容 | compatible-mode | 使用 OpenAI API 格式兼容层,直接通过 OpenAIChatModel 接入,简化适配逻辑,支持响应缓存。 |
| 搜索策略 | forced_search=True | 强制调用搜索工具,确保获取最新信息,适用于深度研究任务,但会增加延迟和成本。 |
| 迭代限制 | max_iters=sys.maxsize | 实际上无限制迭代,依赖 Session 过期或用户中断作为终止机制,支持长时任务。 |
| 记忆压缩 | 60万 tokens 阈值 | 行业领先水平,约相当于 45-60 万汉字,配合 keep_recent=5 策略,支持超长对话上下文。 |
| 并行调用 | parallel_tool_calls=True | 允许单轮迭代中同时调用多个独立工具,显著提升多源信息查询与并发处理的效率。 |
当前文章无评论,是时候发表评论了