AgentScope：论文及实战

概述

论文，AgentScope，简称AS，是一个面向智能体的编程框架，旨在用简单高效的方式来构建智能体应用程序。该框架提供从模型封装、工具管理、会话/记忆、消息路由到可视化监控的全套功能，帮助开发者快速构建、调试并部署多智能体与单智能体的生产级应用。

代表面向Agent编程(AOP)的新方法，支持异步执行和流式返回，兼容多种LLM服务（本地模型或第三方API），并提供AS Studio与AS Runtime等生态组件，覆盖从开发到生产的完整闭环。

亮点：

• 实时介入：ReAct Agent原生支持实时介入（Realtime Steering）：可打断并中途增加提问。在智能体运行过程中可被外部打断，用户或系统可在任意时刻插入新的问题或指令。框架将打断事件视作可观测的状态/记忆片段，智能体可以即时响应新增输入并在处理后无缝恢复到原先的对话流，极大提升交互灵活性与可控性（适用于客服插入、更正指令、多人协作中断等场景）；
• AS Studio：可视化WebUI，开发者可以直观追踪、调试基于AS构建的智能体应用，轻松监控运行状态、调试行为和优化协作流程；
• 可观测性：基于OpenTelemetry；
• AS Runtime：生产级部署引擎，具备沙盒化工具执行功能，确保Agent应用安全运行；
• 细粒度MCP控制：开发者可通过本地可调用函数灵活访问MCP工具，以任意方式使用，无论是直接调用、赋能给智能体，还是包装为更复杂的复合工具，能满足不同场景下的自定义需求；
• 多智能体对话：提供MsgHub和多种pipeline，简化多智能体之间的对话构建与协作编排。支持并行工具调用、自动状态管理与高效路由，使多智能体系统在任务分工、信息共享与协同推理时表现稳健。

概念

四个核心概念：Message、Agent、Service、Workflow。

• 消息：多智能体对话中信息交换的载体（智能体间通信的基本单元），封装信息的来源与内容。以Python字典形式实现，包含两个必填字段name和content以及一个可选字段url。
  • name：记录生成该消息的智能体名称；
  • content：包含智能体生成的文本信息；
  • url：通常链接到图像或视频等多模态数据。带有该字段的消息特别适用于可处理和生成多模态内容的智能体之间的交互。每条消息都由自动生成的UUID和时间戳唯一标识，以确保可追溯性。
• 智能体：多智能体应用中的主要执行者，充当对话参与者和任务执行者。智能体行为通过两个接口进行抽象：reply和 observe函数。
  • reply函数接收一条消息作为输入并生成响应；
  • observe函数处理接收到的消息但不直接回复。智能体与消息之间的交互，构成AS的运行基础。
• 工作流：工作流表示智能体执行与消息交换的有序序列，类似于TensorFlow中的计算图，但具备支持非DAG（有向无环图）结构的灵活性。工作流定义了智能体之间的信息流动与任务处理过程，有助于实现并行执行与效率提升。该概念对于设计与LLM交互的多智能体系统至关重要，因为它允许协调复杂且相互依赖的任务。
• 服务函数与工具（Service Functions and Tools）：两者密切相关但有所不同。
  • 服务函数指的是返回格式化输出ServiceResponse的功能性API；
  • 工具则是经过处理的服务函数，包含功能描述与所需输入参数。我们在AS中引入这两个概念，是因为LLM在调用服务函数作为工具时需要辅助。一个常见的观察是：LLM在准确理解服务函数的功能方面可能存在困难。
  • LLMs需要更具描述性的信息来做出准确决策。同时，LLMs无法可靠地填写某些API的输入参数，例如Bing和Google搜索的API密钥。因此，AS将工具定义为经过处理的服务函数。

架构

由三个分层结构和一组用户交互接口组成。这些层级从不同层面支持多智能体应用，包括单一智能体的基础和高级功能（实用层）、资源与运行时管理（管理器与封装器层）、以及从智能体级到工作流级的编程接口（智能体层）。

AS引入直观的抽象设计，以满足每一层固有的多样化功能，并简化构建多智能体系统时复杂的层间依赖关系。此外，我们提供编程接口和默认机制，以增强多智能体系统在各层故障情况下的弹性。

• 实用层：
  作为平台的基础，提供支持智能体核心功能的基本服务。该层抽象了底层操作的复杂性，例如模型API调用和服务函数（包括代码执行和数据库操作），使智能体能够专注于其主要任务。以易用性和稳健性为最高优先级，支持多智能体系统中的多样化操作，内置自动重试机制，以应对意外中断、异常、错误。
• 管理器与封装器层：
  作为中间层，管理器与封装器抽象层管理资源和API服务，确保资源的高可用性，并对LLMs的不良响应提供抵抗能力。与提供默认处理器的实用层不同，管理器与封装器层还提供可定制的接口，以根据开发者的需求和应用的具体要求进行容错控制。该层负责维护智能体的操作完整性，这是LLMs在多样化条件下持续表现的关键方面。
• 智能体层：
  AS的核心是智能体抽象，它构成多智能体工作流的骨干，是交互和通信的主要实体。该层旨在促进复杂工作流的构建并提升可用性，减少开发者的编程负担。通过集成简化语法和工具，AS使开发者能够专注于利用LLMs能力的智能体应用的实现与优化。
• 用户交互：
  AS还提供面向多智能体的接口，例如带注释的终端显示基本信息、用于系统监控的Web UI、基于Gradio的界面，只需一步即可将命令行应用转换为图形界面，以及拖拽式零代码编程工作台。这些接口使开发者能够轻松监控应用的状态和指标，包括智能体通信、执行时间和财务成本。

这些分层结构共同为开发者提供构建定制化多智能体应用的基本构件，充分利用大语言模型的高级能力。

actor

在构建工业级多智能体系统应用时，效率与可扩展性至关重要。多智能体应用中的智能体推理速度可能差异巨大。例如，在一个多模态应用中，某个智能体使用文本生成视频模型，其响应时间可能远远长于另一个负责补充故事细节的智能体。并行化作为一个经典思路，应当被引入以提升效率。

此外，多智能体应用可能由分布在不同物理机器上的智能体组成。一个典型的使用场景是：某公司将其专利技术或私有知识库封装为一个运行在本地机器上的智能体，并通过互联网与其他实体进行智能体交互，提供自主服务。

然而，在构建多智能体系统时，开发者面临一个挑战：需要在以下两组技术路线之间做出选择。没有免费的午餐，任何组合都有其优点与缺点：

1. 集中式对比分布式：
   • 集中式系统易于管理，但扩展性差，单点故障风险高。
   • 分布式系统具备更强的扩展性与容错能力，但部署与通信复杂度高。
2. 同步对比异步：
   • 同步系统逻辑清晰，但容易阻塞，效率低下。
   • 异步系统具备更高的并发能力，但调试与状态管理更复杂。

AS设计目标是在这两组技术路线之间取得平衡。AS引入基于Actor的分布式框架，其核心理念如下：

• Actor 模型： 每个智能体被视为一个独立的 Actor，拥有自己的状态与消息队列。Actor 之间通过消息进行通信，系统整体以异步方式运行。
• 异步执行：AS使用 Python 的 asyncio 框架实现异步消息传递与任务调度，确保智能体之间的并发执行不会互相阻塞。
• 分布式部署：AS提供简单的接口将本地智能体部署到远程机器。开发者只需调用 .to_dist() 方法并指定 IP 与端口，系统会自动启动 RPC 服务并建立连接。
• 容错机制： 分布式框架内置多层容错机制，包括自动重试、格式修复、语义纠错与日志记录，确保系统在面对网络波动、模型错误或资源限制时仍能稳定运行。
• 资源调度与负载均衡：AS支持将智能体分配到不同的计算节点，并根据任务复杂度动态调整资源使用，提升整体系统效率。

通过上述设计，AS 的分布式框架不仅具备工业级的稳定性与扩展性，还保留开发者友好的使用体验，使多智能体系统的构建与部署变得像拼乐高一样简单。

集中式与去中心化协调

在分布式系统的语境中，集中式协调指的是多个计算节点由一个中心节点进行管理，例如服务器-客户端模型。一个采用集中式协调的多智能体机制意味着智能体的执行由一个中心协调组件进行调度，智能体之间的消息也由该中心组件进行转发。

相反，去中心化协调不依赖任何中心组件来调度或转发消息，而是系统中的智能体可以自动被调用，并将消息直接发送给下游智能体以进行进一步处理。

虽然集中式协调是一种易于理解且便于调试的直接风格，但其缺点包括对中心节点故障的脆弱性、对中心节点造成的高负载，以及在扩展或延伸到复杂应用时的困难。相比之下，去中心化协调可能需要额外的开发与维护工作，但在面对单节点故障时具有更高的鲁棒性。

静态与动态工作流设计

类似的比较可以在早期版本的 TensorFlow 所采用的静态计算图与 PyTorch 所采用的动态计算图之间找到。在多智能体应用的语境中，静态与动态工作流的选择类似于预编译执行与解释执行之间的选择。

静态工作流设计可以在工作流图层面进行运行时间与资源分配的优化。然而，静态工作流设计要求在执行前就已知整个工作流图，这限制了其在某些应用中的适应性，尤其是那些设计中包含循环结构的应用。相比之下，动态工作流在灵活性方面更具优势，但在优化潜力方面有所牺牲。

这一点在处理LLM时尤为相关，因为其执行路径可能会根据输入数据或模型推理结果发生变化。

AS通过实现一个基于Actor的分布式模式，在多智能体LLM系统的独特需求下，平衡这些技术路线：

• 无需静态图的自动并行优化：利用Actor模型实现自动并行优化，使开发者能够避开静态图编程的复杂性。与LLM的动态且常常不可预测的特性完美契合，其中计算图可能会根据不断变化的上下文与对话状态发生改变。
• 最小复杂度的工作流编程：与传统的Actor模型和点对点（P2P）实现相比，后者需要复杂的分布式智能体执行顺序，AS将工作流编程简化为Python函数中的单一过程式风格。这种设计显著降低了开发者的学习曲线，使构建复杂的多智能体LLM更加易于上手。
• 本地与分布式智能体的混合支持：AS的灵活性还体现在其支持混合模式，其中部分智能体在本地运行，而其他智能体则分布式运行。在集成具有不同计算需求的LLM时尤为有用，允许将资源密集型模型分布式部署，而计算需求较低的智能体则保留在本地，开发者在实现过程中无需区分两者。

具体而言，可以简洁地描述AS如何整合Actor模型。一个“Actor”是一个独立实体，在接收到所有必要消息后进行计算处理。该范式确保每个智能体（对应一个Actor）仅在所需输入消息准备好后才参与计算，从而实现自动并行优化。

基于Actor模型的工作流也带来编程挑战：在Actor（即智能体）之间传递的变量（即消息）在初始阶段可能只是占位符，没有实际意义。为缓解这一问题，AS引入占位符消息，一种新颖的数据结构，允许主流程在不中断的情况下继续运行，同时保留必要信息以便稍后检索真实值。该机制在多智能体LLM系统中尤为有利，因为其执行流程必须适应语言模型输出的可变性。

当占位符被用于控制流语句（如if-else、循环）中但尚未获得真实值时，会出现另一系列挑战。占位符用于决策。在这些情况下，AS会暂时阻塞流程以检索其实际值，从而确保控制流的连续性。

AS 中基于 Actor 的分布式模式不仅提供了自动并行优化与简化的开发者体验，还在分布式多智能体 LLM 应用中展现出高效性能。它使开发者能够专注于实现智能体逻辑，尤其是“reply”函数，而无需担心底层的分布式复杂性。这种对分布式多智能体系统的简化方法有助于推动 LLM 领域的发展，使开发、运行与调试复杂且可扩展的多智能体架构变得更加容易。

RAG

AS 为多智能体应用提供全面的 RAG 支持，特性：
一站式配置（Configurations in One-Stop） 由于工作流程的复杂性，RAG 服务的配置非常繁琐，常常令用户头疼。尽管AS提供的 RAG 服务功能全面，且涉及多智能体工作流，AS 仍通过使用一个单独的 .json 文件将所有 RAG 相关配置集中管理，从而提供简单的一站式配置解决方案。

借助这种高度系统化的配置接口，用户只需专注于构建工作流，而无需被重复配置所干扰。例如，RAG 支持的智能体可能涉及大量知识库，需要详细配置。通过这一“一站式”功能，模块的相应调整（可能影响性能）都整合为对单一文件的编辑。此外，该解决方案也自然适配AS的工作台，在其中基于对话框的配置可以轻松导出为可执行文件，并在 Python 程序中加载。

面向知识的数据管理（Knowledge-oriented Data Managements） 在多智能体场景中应用 RAG 比在单一智能体上更复杂。对于单一智能体，可以直接将所需知识封装到该智能体中。因此，每个 RAG 智能体的初始化涉及从原始文档到向量存储索引与检索器的整个转换流程。然而，在多智能体应用中，智能体之间共享知识是自然的，因此无需为每个智能体重复执行索引计算。

知识库可以被视为一组知识容器，其中最小可管理单元是一个定制对象（在后续内容中称为“RAG 对象”）。工作流程从初始化知识库开始，主要依赖于 .json 配置文件中的信息。该信息包括文档的目录与扩展名（如 .py 或 .md）、文档的分段粒度与分段工具的选择（例如 Llama-Index 中的分割器），以及用于索引的模型选择。初始化完成后，计算结果将持久化到指定目录以供后续使用，我们也获得了一个由 RAG 对象组成的知识库，每个对象都带有唯一的knowledge_id，与相应文档的索引、信息检索器以及其他属性相关联。AS 允许每个 RAG 智能体加载多个 RAG 对象。

带有 RAG 的智能体（Agents with RAG） 在AS中使用带有 RAG 的智能体非常简单。例如，我们首先需要使用某个 RAG 框架（如 LlamaIndex）和所有文档初始化一个知识库。然后，我们配置一个 RAG 智能体并加载该知识库。完成初始化后，我们就可以像使用其他AS智能体一样使用该 RAG 智能体。如果知识库是通过 LlamaIndex 框架获得的，则需要使用继承自 RAGAgentBase 的 LlamaIndexAgent。

RAG智能体的关键特性：

• RAG 智能体允许加载多个 RAG 对象（即知识库的任意子集）。可以选择从知识库加载原始 RAG 对象（此情况下，对对象的修改可能影响所有使用它的智能体），也可以加载其副本。
• 虽然智能体是通过 KnowledgeBank 对象初始化的，但允许智能体实时更新知识。操作包括插入、删除或替换知识片段。此外，提供一种解决方案，通过监控某些目录并使 RAG 对象与目录内容保持同步。
• 来自多个 RAG 对象的检索结果的融合机制是完全可定制的。例如，由于知识可能具有不同的重要性或可信度，智能体可以为来自不同 RAG 对象的信息设置权重，以用于后续处理。
• RAG 智能体允许在可配置的重复次数中重新构造查询，并进行多次查询，以获得更全面的答案。

工具使用

工具使用是由 LLM 驱动的智能体的一项重要功能，使智能体能够感知、改变其环境，并处理更复杂的任务。为简化起见，我们将工具使用视为 LLM 调用服务函数的等价操作。在AS中，工具使用模块基于 ReAct 算法设计，支持交错的推理与任务特定的动作生成，并包含一个核心组件——服务工具包（service toolkit）。该设计具有高度的兼容性、可扩展性、鲁棒性和可复用性，涵盖了函数预处理、提示词工程、推理、响应解析以及智能体级容错。

工具使用包括以下四个步骤：

• 函数准备（Function Preparation）： 解析所提供的服务函数，并预处理这些函数，使 LLM 能够直接使用。
• 指令准备（Instruction Preparation）： 为工具使用准备提示词，向 LLM 详细说明可用工具函数，包括函数的用途、参数、约束条件以及调用格式。
• 迭代推理（Iterative Reasoning）： LLM 生成策略性推理，决定工具使用，并以所需格式做出响应。
• 迭代执行（Iterative Acting）： 根据调用格式解析并检查 LLM 的响应，如果响应符合预期格式，则调用函数；否则生成详细的错误信息反馈给 LLM 进行修正。

在上述过程中，服务工具包模块负责工具函数的管理、预处理、提示词工程、响应解析和函数执行，并具有高度的模块化和可扩展性。图6展示当用户发出查询时，服务工具包在AS中的工作方式。

函数准备（Function Preparation）： 在函数准备阶段，目标是预设开发者特定的参数，并生成可直接使用的函数及其对应的格式化描述供 LLM 使用。在AS中，开发者只需在服务工具包中注册带有预设参数的函数。如图 6 所示，开发者选择 Bing 搜索函数并在注册时提供 API 密钥。随后，服务工具包将自动生成处理后的可用函数及其 JSON schema 格式的描述。这些描述将用于生成自然语言形式的工具使用指令。可选地，一些模型 API（如 OpenAI 和 DashScope Chat API 等）可以直接接收 JSON schema 描述。

指令准备（Instruction Preparation）： 服务工具包内置工具使用的指令模板和调用格式。工具指令模板列出了每个函数的清晰描述及其所需参数，使其功能易于理解。另一方面，调用格式要求使用 Markdown 栅栏代码块中的 JSON 字典，包含 thought（思考）、speak（说话）和 function（函数）字段。在 LLM 生成过程中，期望 thought 字段提供下一步动作的推理过程，包括分析当前情境、选择候选函数以及纠错。

迭代推理（Iterative Reasoning）： 在AS中，推理与执行步骤是迭代进行的。如上所述，在推理步骤中，LLM 应分析当前情境并决定下一步动作。开发者只需构建包含工具指令和调用格式指令的提示词，并将其输入到 LLM 中。该设计具有高度的可复用性和灵活性，即服务工具包与任务无关，可非常容易地适配不同任务和场景。

迭代执行（Iterative Acting） 在执行步骤中，服务工具包将根据调用格式解析 LLM 的响应，提取所选函数，并使用相应的参数执行该函数。如果响应符合格式要求且函数成功执行，服务工具包将直接返回执行结果，LLM 可在下一次推理步骤中基于该结果生成响应。否则，我们将错误分为响应解析错误、函数执行错误和其他运行时错误。对于响应解析和函数执行错误，我们会将详细的错误信息暴露给 LLM，以便在下一轮推理-执行迭代中进行修正，而其他运行时错误则留给开发者处理。

面向资深开发者的定制化功能（Customization for Experienced Developers）
AS 支持开发者高度定制其工具指令和函数调用格式。为了定制工具指令，AS 中的服务工具包会自动提供 JSON schema 描述，这种结构化方式可以详细说明函数的调用方式，包括函数名称、用途、参数以及其他相关细节。这些格式化描述可以直接输入到某些高级模型 API 中，例如 OpenAI 和 DashScope Chat API。对于希望深入定制工具指令的用户，他们可以基于 JSON schema 描述构建自己的指令。

除了工具指令之外，AS 还提供极大的灵活性，即AS提供多种模型响应解析器，包括 Markdown 栅栏代码块、JSON 对象代码块以及可定制的标签内容。对于希望定制函数调用格式的用户，Markdown 栅栏代码块和 JSON 对象代码块允许他们快速构建格式指令，并根据内容类型解析 LLM 的响应。对于希望从 LLM 获取多个字段的用户，多标签内容允许开发者任意组合不同的标签内容，并轻松地从响应中提取为 Python 字典。借助这些解析器，开发者可以轻松定制自己的调用格式。

多模态

多模态数据的集成对于提升多智能体与 LLMs 的能力和应用至关重要。AS 的设计旨在无缝支持各种数据模态，充分利用当代 LLMs 能够处理和生成的多样化输入与输出。

多模态数据管理
在运行中的AS应用中，多模态数据的生命周期被精细管理。该管理涵盖多模态数据的生成、传输与存储——所有过程均通过使用 URL 和本地文件管理系统的解耦架构来实现。包括来自用户输入或模型生成的数据、数据的存储与检索，以及数据的共享。

• 多模态数据生成： 在AS中，多模态数据主要有两个来源。一个来源是本地存储的多模态文件，这些文件可以被用户代理智能体或具有本地文件系统访问权限的通用智能体使用。另一个来源是模型模态内容生成模型。我们的模型 API 和模型封装器集成了最流行的多模态模型，例如文本生成图像的内容生成模型，以及图像生成文本的图像分析模型。除了内置的 API，开发者还可以引入自己喜欢的多模态模型，并自定义自己的模型封装器，平台提供的即用示例可作为起点。这个自定义过程在AS中被简化，并受益于我们的模块化设计，使开发者能够以最小的工作量连接自己的多模态服务。
• 多模态数据存储： 如上所述，多智能体应用中的多模态数据可以来自即用的本地文件，也可以由多模态模型生成。当调用多模态模型封装器生成多模态数据时，它首先借助文件管理器将数据保存到本地，并在从模型 API 服务接收到多模态数据后返回一个本地 URL。
• 多模态数据传输：AS通过允许智能体在多模态消息中封装本地或远程 URL 来指示数据的实际存储位置，从而简化了智能体之间的多模态数据共享过程。接收方智能体在准备处理数据时可以通过这些 URL 加载多模态数据。

在智能体共享多模态数据的消息中引入 URL 的好处有三点： 首先，它可以最小化消息体积，避免因网络带宽问题导致的潜在错误或延迟，并使接收智能体能够按需加载数据。 其次，如果消息中包含其他文本信息，下游智能体可以优先处理文本信息，或并行处理文本与多模态信息。 最后，这种附带 URL 的消息也有助于多模态数据的展示。

多模态交互模式（Multi-Modal Interaction Modes）

借助 URL 附带消息的实现，AS 使用户能够通过终端和 Web UI 等可访问的接口与多模态系统进行交互。在终端中，用户可以通过激活提供的 URL 方便地访问本地存储的数据。Web UI 进一步增强了用户体验，提供了一个直观的平台来查看和分析多模态内容，符合现代 Web 应用的预期。

通过 AS，开发者可以根据自身需求定制模型 API 服务和封装器，构建能够处理多样数据模态的应用，并为用户提供必要的工具以有效地与多模态智能体交互。这种对多模态应用的全面支持使AS成为一个多功能且强大的框架，能够充分发挥多智能体 LLM 的潜力，为开发者和研究人员打造复杂且互动性强的 AI 系统拓展了广阔的前景。

实战

安装

git clone -b main https://github.com/agentscope-ai/agentscope.git
cd agentscope
vim .env
pip install -e .
npm install -g @agentscope/studio
# 启动Web UI
as_studio

浏览器打开http://localhost:3000体验。

示例

import os  
import asyncio
import json  
"""
引入模块介绍：- agentscope: 框架核心入口- agent: 提供 ReActAgent（智能推理与执行代理）和 UserAgent（用户交互代理）- model: DashScopeChatModel，用于聊天生成和对话管理- formatter: DashScopeChatFormatter，用于输出格式化- message: Msg 与 TextBlock，用于消息封装与传递- module: StateModule，管理代理状态- session: JSONSession，保存会话与上下文信息- memory: InMemoryMemory 与 Mem0LongTermMemory，短期与长期记忆- mcp: HttpStatefulClient 与 HttpStatelessClient，状态/无状态 HTTP 客户端- tool: 工具集管理及执行函数（shell、Python、文本文件查看）- embedding: DashScopeTextEmbedding，将文本转换为向量表示- plan: PlanNotebook，任务计划与工作流管理
"""
import agentscope 
from agentscope.agent import ReActAgent, UserAgent 
from agentscope.model import DashScopeChatModel  
from agentscope.formatter import DashScopeChatFormatter  
from agentscope.message import TextBlock, Msg
from agentscope.module import StateModule
from agentscope.session import JSONSession
from agentscope.memory import InMemoryMemory, Mem0LongTermMemory  
from agentscope.mcp import HttpStatefulClient, HttpStatelessClient
from agentscope.tool import (Toolkit,ToolResponse,execute_shell_command,execute_python_code,view_text_file,
)
from agentscope.embedding import DashScopeTextEmbedding  
from agentscope.plan import PlanNotebook
from dotenv import load_dotenvload_dotenv()toolkit = Toolkit()  
toolkit.register_tool_function(execute_shell_command)
toolkit.register_tool_function(execute_python_code)
toolkit.register_tool_function(view_text_file)
toolkit.register_tool_function(example_tool_function) # 注册自定义工具long_term_memory = Mem0LongTermMemory(model=DashScopeChatModel(api_key=os.environ.get("DASHSCOPE_API_KEY"),model_name="qwen-max",enable_thinking=False,stream=False,),embedding_model=DashScopeTextEmbedding(api_key=os.environ.get("DASHSCOPE_API_KEY"),model_name="text-embedding-v2",),user_name="demo_user",
)agent = ReActAgent(  name="Friday",  sys_prompt="你是一个功能强大的AI助手",  model=DashScopeChatModel(  api_key=os.environ.get("DASHSCOPE_API_KEY"),  model_name="qwen-max",enable_thinking=False,  stream=True,    #流式输出generate_kwargs={"parallel_tool_calls": True},    # 告诉模型支持并行工具调用),  formatter=DashScopeChatFormatter(),  toolkit=toolkit,  memory=InMemoryMemory(),  long_term_memory=long_term_memory,  long_term_memory_mode="both",  # 同时支持智能体控制和静态控制  enable_meta_tool=True,  # 启用元工具功能  parallel_tool_calls=True,   # 支持并发调用工具plan_notebook=PlanNotebook(),  # 支持计划管理  print_hint_msg=False,  # 关闭提示消息打印)# HttpStatelessClient创建无状态MCP客户端，HttpStatefulClient创建有状态MCP客户端
stateless_client = HttpStatelessClient(name="gaode_mcp",transport="streamable_http",url=f"https://mcp.amap.com/mcp?key={os.environ.get('GAODE_API_KEY')}",
)
# 不注册无法使用
await toolkit.register_mcp_client(stateless_client)session = JSONSession(save_dir="./sessions")
try:await session.load_session_state(session_id="user_demo", agent=agent)print("✅ 成功加载上一次会话状态。")
except FileNotFoundError:print("⚠️ 未找到上一次会话，开始新会话。")user = UserAgent(name="User")
msg = None
while True:msg = await user(msg)if msg.get_text_content() == "exit":breakmsg = await agent(msg)# 每次生成消息后保存状态await session.save_session_state(session_id="user_demo", agent=agent)print("✅ 已保存当前会话状态。")async def example_tool_function(tag: str) -> ToolResponse:from datetime import datetimestart_time = datetime.now().strftime("%H:%M:%S.%f")await asyncio.sleep(3)end_time = datetime.now().strftime("%H:%M:%S.%f")return ToolResponse(content=[TextBlock(type="text",text=f"标签 {tag} 开始于 {start_time}，结束于 {end_time}。",),],)

容错机制

在MAS领域，尤其是那些与具有不同指令遵循能力的开源大语言模型（LLMs）交互的系统中，容错性是一项关键属性，以确保系统的无缝运行。AS 的设计旨在自动处理各种错误，尽可能减少人工干预，其容错基础设施充分考虑了多智能体协调和 LLM 依赖所涉及的复杂性。

错误分类与处理策略（Error Classification and Handling Strategies）

对错误进行系统性的分级分类开始，每一类错误都有针对性的处理策略：

• 可达性错误（Accessibility errors）： 在AS中，智能体的功能依赖于不同类型的服务，但这些服务可能会出现暂时不可访问的错误。这些错误可能由模型不稳定或网络状况引起。例如，在高峰时段出现流量拥堵时，模型 API 可能返回超时错误，或者远程机器上的数据库可能因短暂的网络中断而无法访问。
• 规则可解决错误（Rule-resolvable errors）： 由于许多多智能体应用需要服务或智能体之间的信息交换，因此遵循通信协议至关重要。然而，由于 LLM 的响应尚不可完全控制，其返回结果可能不符合提示中要求的格式。由于 JSON 格式具有明确的规范，因此可以合理地假设其中一部分错误可以通过根据规则修正格式来解决。
• 模型可解决错误（Model-resolvable errors）： 当多智能体系统处理一些复杂任务时，智能体理解输入、做出决策并输出结果的能力主要依赖于 LLM 的能力。在某些情况下，LLM 的响应格式是符合预期的，但内容存在问题，例如参数错误、语义错误或编程错误。对于多样化任务，很难预定义规则来规范这些响应，但已有研究表明，这类错误可以通过进一步与 LLM 交互来检测和恢复。
• 不可解决错误（Unresolvable errors）： 最终，必然存在一些无法检测或解决的错误。一个典型例子是 LLM 的 API 密钥过期或未授权。依赖该密钥的智能体或系统无法自行解决此类错误，必须依赖人工干预。

提供多种应对机制：

• 基础自动重试机制（Basic auto-retry mechanisms）： 为了应对可达性错误，AS 的 API 服务和模型封装器配备了可定制的重试逻辑，开发者可以设置最大重试次数。这确保了智能体能够从偶发中断中恢复，并保持其操作连续性。
• 基于规则的修正工具（Rule-based correction tools）：AS引入了基于规则的修正工具，以高效且经济地处理 LLM 响应中的一些易于修复的格式错误。例如，我们在AS中建立了一套默认规则，可以补全不匹配的括号并从字符串中提取 JSON 数据。这类基于规则的修正工具可以在不再次调用 LLM API 的情况下修复一些常见的规则可解决错误，从而缩短处理时间并节省 LLM API 调用成本。
• 可定制的故障处理器（Customizable fault handlers）：AS还在模型封装器中集成了灵活的故障处理器接口，供开发者定义如何解析 LLM 的响应并处理异常输出。应用开发者可以通过配置参数（例如 parse_func、fault_handler 和 max_retries）提供解析函数、故障处理函数以及给予 LLM 的尝试次数，从而配置其故障处理机制。借助这种面向开发者的设计，AS 可以对规则可解决错误（当内置规则无法处理时）以及某些可由单个智能体检测并处理的模型可解决错误（例如将冗长摘要提炼为简洁版本）具备可配置的鲁棒性。
• 智能体级故障处理（Agent-level fault handling）： 有些模型可解决错误需要更高级的 LLM 使用方式或智能体级交互来恢复。例如，语义错误的检测通常包括事实不准确、逻辑不一致、上下文不连贯、不合理推理以及不当词汇使用等，这些错误由于不会在系统现有验证流程中立即触发警报，因此检测起来具有挑战性。开发者可以利用AS中智能体的能力（例如内存模块和消息中心）进行语义错误检查，如自我批评、成对批评和人工增强批评。
• 日志系统（Logging system）：AS的日志系统针对多智能体应用场景进行定制，包括添加名为CHAT的日志级别用于记录智能体之间的对话，提供包含各种执行信息的格式化日志，以及用于监控的WebUI用户界面。

源码

AgentBase：作为抽象基础，实现基本的智能体生命周期方法和通信模式。

AgentMeta：智能体注册元类

StateModule：状态管理