AgentScope深入分析-扩展机制-编程实验室

扩展的智慧：框架扩展机制深度解析

请关注公众号【碳硅化合物AI】

摘要

AgentScope 的强大之处在于它的可扩展性。你可以添加新的模型、新的工具、新的智能体，甚至新的记忆系统。本文将深入分析框架的扩展机制，包括如何添加新模型、如何创建自定义工具、如何扩展智能体，以及扩展的最佳实践。通过阅读本文，你会理解框架的扩展点在哪里，如何正确实现扩展，以及如何避免常见的陷阱。无论你是想要集成新的模型提供商，还是想要创建领域特定的智能体，这篇文章都会为你提供清晰的指导。

扩展入口与架构

扩展点概览

AgentScope 提供了多个扩展点：

关键代码：扩展基类接口

所有扩展点都基于抽象基类：

class ChatModelBase: """Base class for chat models.""" model_name: str stream: bool def __init__( self, model_name: str, stream: bool, ) -> None: self.model_name = model_name self.stream = stream @abstractmethod async def __call__( self, *args: Any, **kwargs: Any, ) -> ChatResponse | AsyncGenerator[ChatResponse, None]: pass

class FormatterBase: """The base class for formatters.""" @abstractmethod async def format(self, *args: Any, **kwargs: Any) -> list[dict[str, Any]]: """Format the Msg objects to a list of dictionaries that satisfy the API requirements."""

关键流程分析

添加新模型的完整流程

添加新模型需要实现三个组件：

工具注册和执行流程

工具扩展的流程：

关键技术点

1. 如何添加新模型

根据贡献指南，添加新模型需要实现三个组件：

第一步：实现 ChatModelBase

fromagentscope.modelimportChatModelBase,ChatResponseclassYourChatModel(ChatModelBase):def__init__(self,model_name:str,api_key:str,stream:bool=True):super().__init__(model_name,stream)# 初始化你的 API 客户端self.client=YourAPIClient(api_key=api_key)asyncdef__call__(self,messages:list[dict],tools:list[dict]|None=None,tool_choice:str|None=None,**kwargs:Any,)->ChatResponse|AsyncGenerator[ChatResponse,None]:# 实现模型调用逻辑# 支持流式和非流式返回# 支持 tools APIifself.stream:asyncforchunkinself.client.stream(messages,tools):yieldChatResponse(...)else:response=awaitself.client.create(messages,tools)returnChatResponse(...)

关键点：

必须支持流式和非流式两种模式
必须支持 tools API（如果模型支持）
必须返回ChatResponse对象

第二步：实现 FormatterBase

fromagentscope.formatterimportFormatterBaseclassYourModelFormatter(FormatterBase):asyncdefformat(self,msgs:list[Msg],**kwargs:Any,)->list[dict[str,Any]]:# 将 Msg 对象转换为你的 API 所需格式formatted=[]formsginmsgs:formatted.append({"role":msg.role,"name":msg.name,# 如果 API 支持"content":self._convert_content(msg.content),})returnformatted

关键点：

如果 API 不支持多智能体（name 字段），需要为单智能体和多智能体场景分别实现两个格式化器
需要处理多模态内容（图像、音频等）

第三步：实现 TokenCounterBase（可选）

fromagentscope.tokenimportTokenCounterBaseclassYourTokenCounter(TokenCounterBase):defcount(self,text:str)->int:# 实现 token 计数逻辑returnyour_tokenizer.count(text)

2. 如何添加新工具

添加工具非常简单，只需要注册函数：

fromagentscope.toolimportToolkit toolkit=Toolkit()# 注册普通函数defmy_tool_function(query:str)->str:"""Tool function description. Args: query: The query string. Returns: The result string. """# 实现工具逻辑returnresult toolkit.register_tool_function(my_tool_function)# 注册异步函数asyncdefmy_async_tool(query:str)->str:"""Async tool function."""# 实现异步逻辑returnresult toolkit.register_tool_function(my_async_tool)# 注册流式函数asyncdefmy_streaming_tool(query:str)->AsyncGenerator[str,None]:"""Streaming tool function."""asyncforchunkinprocess_streaming(query):yieldchunk toolkit.register_tool_function(my_streaming_tool)

Toolkit 会自动：

从 docstring 解析函数签名和描述
生成 JSON Schema
包装同步函数为异步
处理流式返回

3. 如何创建自定义智能体

创建自定义智能体有两种方式：

方式一：继承 AgentBase

fromagentscope.agentimportAgentBasefromagentscope.messageimportMsgclassMyCustomAgent(AgentBase):asyncdefreply(self,msg:Msg|None=None)->Msg:"""实现自定义的回复逻辑"""# 你的自定义逻辑returnMsg(self.name,response,"assistant")

方式二：继承 ReActAgentBase

fromagentscope.agentimportReActAgentBaseclassMyReActAgent(ReActAgentBase):asyncdef_reasoning(self,*args,**kwargs)->Msg:"""实现推理逻辑"""# 你的推理实现passasyncdef_acting(self,tool_call,*args,**kwargs):"""实现行动逻辑"""# 你的行动实现pass

4. 如何扩展记忆系统

扩展记忆系统也很直接：

fromagentscope.memoryimportMemoryBasefromagentscope.messageimportMsgclassMyCustomMemory(MemoryBase):def__init__(self):super().__init__()# 你的存储实现（如数据库、文件等）self.storage=YourStorage()asyncdefadd(self,memories:Msg|list[Msg]|None)->None:"""实现添加记忆的逻辑"""# 你的实现passasyncdefget_memory(self)->list[Msg]:"""实现获取记忆的逻辑"""# 你的实现returnself.storage.get_all()

扩展最佳实践

1. 遵循接口契约

扩展时，必须严格遵循基类的接口：

方法签名必须匹配
返回类型必须正确
异常处理要合理

2. 保持模块化

扩展应该：

独立于其他模块
可以单独测试
不破坏现有功能

3. 文档和测试

扩展应该：

提供完整的文档字符串
包含使用示例
有单元测试覆盖

4. 懒加载原则

遵循框架的懒加载原则：

第三方库在函数内部导入
避免在模块级别导入重型依赖

总结

AgentScope 的扩展机制设计得非常灵活：

模型扩展：通过实现 ChatModelBase、FormatterBase 和 TokenCounterBase，可以集成任何模型提供商
工具扩展：通过 Toolkit.register_tool_function，可以轻松添加任何可调用对象作为工具
智能体扩展：通过继承 AgentBase 或 ReActAgentBase，可以创建自定义智能体
记忆扩展：通过继承 MemoryBase，可以实现自定义的记忆系统

这些扩展点都遵循统一的接口设计，让扩展变得简单而强大。在下一篇文章中，我们会分析框架中使用的设计模式和架构决策，这些是理解框架设计精髓的关键。

AgentScope深入分析-扩展机制