最近在研究一个阿里的开源框架 AgentScope一般来说学习框架做好的方法就是实践了我就想要不要用这个框架整一个agent出来。之前我用python开发了一个Agent有基础的模型配置工具管理技能配置记忆管理会话压缩等功能我用AgentScope把这些功能都实现了基本也就了解这个框架要怎么使用了。正好这段时间我又在折腾 workbuddy研究他的一些实现机制那我就用AgentScope这个框架来实现一个mini版本的workbuddy。那不又学习了框架还搞懂了workbuddy的一些工作机制顺便写文章记录下。AgentScope 是什么AgentScope 是一个面向大模型 Agent 应用开发的开源框架由阿里巴巴团队发起目前托管在AgentScope-AI开源组织下。它主要帮助开发者构建具备模型推理、工具调用、上下文管理、记忆管理以及多 Agent 协作能力的智能体应用。在没有 Agent 框架的情况下我们通常需要自己处理模型调用、消息格式、工具执行、历史上下文、Agent Loop、多智能体通信等问题。AgentScope 对这些常用能力进行了封装开发者可以在框架提供的基础组件上配置模型、提示词、工具和记忆而不需要从头实现一套完整的 Agent 运行逻辑。AgentScope 提供的核心能力包括可以对接不同的厂商的模型工具调用和 MCP 工具接入以及skill的执行消息和上下文管理支持短期记忆与长期记忆标准的ReAct Agent实现多 Agent 对话、路由和任务交接Agent 运行追踪与调试AgentScope 既可以用于开发简单的对话助手也可以构建代码处理、数据分析、文档生成等类型的 Agent还可以通过多个 Agent 的协作完成更复杂的任务。它解决的核心问题是如何把大模型、提示词、工具、记忆和执行流程组合起来形成一个能够持续推理并执行任务的完整 Agent。AgentScope 的 GitHub 地址https://github.com/agentscope-ai/agentscopeAgentScope-AI 是什么在 GitHub 上我们会看到一个名为AgentScope-AI的组织。它并不是某一个具体框架而是 AgentScope 相关开源项目所在的 GitHub 组织也可以将它理解为整个 AgentScope 开源生态的代码仓库集合。https://github.com/agentscope-ai除了核心的 AgentScope 框架这个组织下面还有 AgentScope Runtime、AgentScope Java、AgentScope Studio、AgentScope Samples 等多个项目分别覆盖 Agent 开发、运行、部署、调试和示例应用等不同环节。AgentScope RuntimeAgentScope Runtime 是 AgentScope 生态中的 Agent 运行时项目。如果说 AgentScope 主要解决的是“如何开发 Agent”那么 AgentScope Runtime 主要解决的是“如何让 Agent 安全、稳定地运行和对外提供服务”。AgentScope JavaAgentScope 最早主要面向 Python 开发者而 AgentScope Java 则是面向 Java 和 JVM 技术栈提供的 Agent 开发框架。它同样提供了 Agent 开发所需要的基础能力AgentScope Java 更适合已经采用 Java、Spring Boot 或其他 JVM 技术栈的企业项目。Java 开发者不需要为了构建 Agent 单独维护一套 Python 服务可以直接在现有 Java 系统中集成 Agent 能力。它与 Python 版本的 AgentScope 定位相近只是面向的语言和应用环境不同本文接下来主要介绍的是 Python 版本的AgentScope。AgentScope Runtime 和 AgentScope Java 属于同一开源生态中的相关项目这里只做简单说明不作为本文重点。如何使用AgentScope来开发一个mini-workbuddy在开发之前我们需要先想一下开发一个mini-workbudy需要哪些功能我们知道正常开发一个Agent需要配置模型配置工具MCP和skills是按需使用一般来说skills都是需要的会话压缩记忆管理这些上下文工程。复杂一点的任务还需要多Agent来完成。这些构成了一个Agent的基本元素。workbuddy和其他Agent没有什么不同其底层都是一样的但是它内置了很多的技能专家和专家团。大部分用户无需关心这些是怎么配置的开箱即可用包括新建skills专家和专家团都是通过技能来引导用户完成。对于大部分用户而言这个是非常友好的。他不关心你的技能是怎么写的专家的提示词是怎么描述它需要的是一个可以帮助干活的助手。下面我们就来逐步拆解这些功能模型配置开发Agent的第一件事情肯定是配置模型不同模型能力边界并不相同我们需要提供配置不同厂商模型的能力。AgentScope 的模型层由 API 凭证Credential和模型族组成。Credential 负责存储调用某个 API 所需的认证参数比如 api_key 和 base_url。系统可以根据这个凭证按模型族model family分组列出该提供商所有可用的模型。下面代码是一个模型接入的标准用法可以获取到一个qwen-plus的模型并且采用流式输出上面的代码适合直接在程序中创建一个固定模型但是 mini-WorkBuddy 是一个面向用户的产品用户需要在模型管理页面中添加多个模型并在聊天时选择使用哪一个模型。因此我们需要在 AgentScope 模型层的外面加一层模型配置管理。AgentScope 只负责根据 Credential 和模型参数创建可以调用的模型对象并不负责保存我们在页面中填写的模型配置。模型配置保存、默认模型切换读需要在项目中自己实现。整个模型管理的流程如下模型管理页面需要保存以下几个主要字段provider模型厂商例如 DashScope、DeepSeek、Moonshot、Ollama 或 OpenAI 兼容服务model具体的模型名称例如qwen-plus、deepseek-chatapi_key模型服务的 API Keybase_url模型服务地址自定义 OpenAI 兼容接口时会用到thinking是否开启模型的思考模式max_context模型支持的上下文长度我们把这些配置保存在workspace/models.json中并使用active_model_id记录默认模型。workspace是我们自己定义的一个配置保存目录没有使用数据库来保存后续所有的配置数据都保存到这个目录并且使用json文件的形式来保存。下面是一个简化后的配置结构新增模型时,我们把数据写入配置文件设置默认模型时更新active_model_id。前端读取模型列表时后端会主动移除api_key避免把密钥重新返回给浏览器。在聊天页面发送消息时我们会把用户选择的模型通过model_profile这个参数会穿给聊天API。如果传入auto后端就使用当前默认模型。后端再根据model_profile再workspace/models.json 中找到完整配置再把数据转换成 AgentScope 的模型对象。我们在项目中做了一个适配器方法create_model_client上诉代码我们只判断了dashscope的模型项目里面可以根据不同的的模型厂商做不同的适配如果需要DeepSeek、Moonshot、Ollama 以及 OpenAI 兼容模型也是一样的处理方式只是使用的 Credential 和 ChatModel 不同。模型管理页面只需要维护一套统一字段真正创建模型时再根据provider选择 AgentScope 对应的实现。聊天服务先读取用户选择的模型配置根据选择的模型创建模型客户端最后把模型对象传给 Agent。这里有一个问题同一个会话中用户可能会切换模型。已经创建的 Agent 内部绑定了原来的模型客户端用户手动切换后还需修改AgentScope的模型配置我们在开发中把模型配置 ID 放进 Agent 的缓存 key 中用户切换模型以后之前的key就无法命中系统就会创建一个使用新模型的 Agent避免页面显示已经切换后端实际还在使用旧模型在回复。通过上述的处理我们就把 mini-WorkBuddy 页面上的添加模型、设置默认模型和聊天时切换模型与 AgentScope 的 Credential、ChatModel 和 Agent 连接起来了。工具管理和权限控制模型接入以后Agent 已经可以完成普通问答但是还不能读取项目文件、搜索代码或者执行命令。我们开发的mini-WorkBuddy 是一个工作助手只能聊天显然不够它需要通过工具操作用户的工作目录。mini-WorkBuddy 接入工具后很多问题就自然而然的来了哪些工具可以交给模型模型从哪里知道工具参数工具结果怎么返回删除文件是否需要用户确认Agent 又能访问哪些目录这些都需要一套完整的管理机制。AgentScope 中负责管理工具的是Toolkit负责判断工具能不能执行的是 Permission 系统。我们需要使用它们来实现 mini-WorkBuddy 的工具列表、工作空间和权限管理。AgentScope 的 Toolkit 是什么Toolkit不是某一个具体工具它是 AgentScope 的工具容器和调用入口。模型在一轮任务中能看到哪些工具、工具以什么 JSON Schema 提供给模型、调用哪个 Python 对象、如何返回流式结果都由 Toolkit 处理。从 AgentScope 2.0.4 的实现来看Toolkit 主要管理四类内容。普通 Tool例如Read、Write和BashMCP Client 提供的远程工具Agent Skills 以及 Skill LoaderTool Group用于按组启用或停用工具Toolkit 的构造参数也对应这四类内容。toolkit Toolkit( tools[...], skills_or_loaders[...], mcps[...], tool_groups[...],)这里面的tools、skills_or_loaders和mcps都属于basic基础工具组basic工作组的工具始终可用。额外传入的tool_groups可以动态启用和停用适合工具很多、又不希望一次把所有工具 Schema 都塞给模型的场景。Toolkit 如何把工具交给模型每个 AgentScope Tool 都有名称、说明和输入 Schema。以Read为例它的名称是Read输入参数包括绝对文件路径、起始行和最大行数。Agent 执行前会调用 Toolkit 的get_tool_schemas()把当前可用工具转换成模型 Function Calling 使用的 JSON Schema。模型返回 ToolCall 后Toolkit 会使用call_tool()方法来处理工具调用逻辑:检查工具是否存在以及所属工具组是否已经激活解析模型生成的 JSON 参数在需要时注入当前AgentState调用同步函数、异步函数或者生成器将增量结果统一转换成ToolChunk最后汇总为完整的ToolResponseToolkit 不只是一个工具数组用来管理系统内置的工具。它同时处理工具发现、分组、MCP的接入、以及Skill的加载和使用最后还统一做了工具的执行。AgentScope 自带了一批工具类包括Read、Write、Bash等 但创建一个空的Toolkit()不会自动把 全部注册进去我们需要根据自己的产品边界显式选择需要哪些工具然后传入给Toolkit()。Toolkit 内部还有两个特殊工具。注册了 Skill 时会提供 Skill 查看工具让模型按需读取完整的SKILL.md配置了额外 Tool Group 时会提供ResetTools元工具让 Agent 动态切换工具组这两个工具由 Toolkit 根据当前配置加入。文件工具和 Bash等工具必须由项目明确注册。我们开发的 mini-WorkBuddy 项目时显式的选择了六个通用工具。这组工具对于 mini-WorkBuddy 主要使用场景我觉得是完全够用了。Agent 可以查看项目、搜索文件、修改文件和执行bash命令。任务相关的工具主要用于后面专家团的管理MCP 和 Skills 也通过 Toolkit 的其他参数接入。创建 Agent 时把这一个 Toolkit 传进去。agent Agent( nameWorkBuddy, system_promptSYSTEM_PROMPT, modelmodel, toolkittoolkit,)模型在 ReAct 循环中决定是否调用工具。工具结果返回以后模型可以继续调用下一个工具也可以整理最终答案。mini-WorkBuddy 的工作目录WorkBuddy还有一个重要的处理就是选择工作目录让Agent在这个目录下工作。我们在设计的时候系统配置了一个默认的工作空间当然也允许用户把本地文件夹添加成新的工作空间。这个配置的话我们也保存到了workspace/workspace.json文件中然后给每一个工作空间分配一个workspace_id和workspace_dir。用户和mini-WorkBuddy交互的时候都会在一个工作空间中每一轮聊天请求接口都会将workspace_id和workspace_dir传入后端会根据workspace_id从workspace.json中获取到配置的工作目录。WorkspaceStore.validate_workdir()还会检查路径是否存在、是否为目录以及是否可写。拿到工作目录后项目做了两层配置。第一层是Bash(cwdworkdir)它决定 Bash 启动时的当前目录。模型执行pwd、git status或相对路径命令时都以这里为起点。Bash(cwdworkdir)第二层是PermissionContext.working_directories。这个是 AgentScope 的权限引擎它告诉Agent 哪些目录属于本轮任务允许工作的范围。cwd只决定命令从哪里开始执行它本身没有任何安全属性也做不了一点安全限制。PermissionContext中保存的工作目录会在agent调用Write、Edit和文件类 Bash 命令的时候做权限判断。项目除了当前工作目录还会按需登记长期记忆目录和 Skill 目录因为Agent执行任务的时候可能需要读取skill和长期记忆需要开放这些目录权限给他Agent。所以工作目录主要承担三个作用。它给工具提供默认执行位置为写入和文件命令提供自动放行范围也帮助项目选择当前会话操作的仓库。不同 WorkBuddy 工作空间的聊天数据由项目存储层隔离文件系统的强隔离则需要另外实现。AgentScope 原始权限系统有哪些模式我们目前使用的是 AgentScope 2.0.4 一共有五种PermissionModeclass PermissionMode(Enum): DEFAULT default ACCEPT_EDITS accept_edits EXPLORE explore BYPASS bypass DONT_ASK dont_ask权限引擎会给出四种行为结果。ALLOW允许执行DENY拒绝执行ASK暂停并询问用户PASSTHROUGH工具不直接决定继续交给权限规则和当前模式判断DEFAULTDEFAULT是最保守的交互模式。权限引擎依次检查 DENY 规则、ASK 规则、工具自己的安全判断和 ALLOW 规则。如果都没有明确允许最终结果是ASK。Read、Glob和Grep虽然是只读工具但它们自己的权限检查返回PASSTHROUGH。在DEFAULT模式中如果没有额外 ALLOW 规则它们仍会落到默认询问。Bash 对ls、git status这类能够识别的只读命令可以直接返回ALLOW。ACCEPT_EDITSACCEPT_EDITS会先放行只读调用再让工具判断写入目标是否位于working_directories中。Write和Edit修改工作目录内文件可以直接执行工作目录外的写入不会因为选了这个模式就自动放行。它也不是所有命令自动同意。普通网络命令、不能确认目标路径的命令以及工具判断为安全风险的调用仍可能进入ASK或DENY。EXPLOREEXPLORE是严格只读模式。Read、Glob、Grep和只读 Bash 命令允许执行Write、Edit以及修改文件的命令直接拒绝。它很适合先让 Agent 阅读仓库并给方案但不希望它改任何文件的场景。即使用户配置了 ALLOW 规则也不能破坏 EXPLORE 的只读保证。BYPASSBYPASS用于明确选择跳过确认的场景。工具产生的安全 ASK 也会被跳过包括危险删除、写入 shell 配置文件和部分命令注入风险。它不是绝对无规则。用户显式配置的 DENY 或 ASK 规则仍然生效工具直接返回 DENY 也会保留。但是不能把它理解为普通的自动确认最好只在沙箱、容器或用户完全清楚风险时使用。DONT_ASKDONT_ASK与 BYPASS 的方向相反。它同样不会弹确认框但凡是需要询问用户的操作都会转成拒绝。后台定时任务没有用户守在页面前使用DEFAULT会永远停在确认事件使用BYPASS又过于宽松。DONT_ASK就是给这种无人值守任务准备的。mini-WorkBuddy 只保留三种权限workbuddy的权限只有两种一个默认一个完全放行。但是AgentScope的权限分的比较细默认就有5种我最开始弄的时候把他们都放出来了看了这几个模式我自己都有点晕直接提供给用户不太友好最后我们在 mini-WorkBuddy 聊天页提供下面三档权限。默认自动审批完全放行映射代码如下。这里的auto-approve是当前项目前后端使用的字段名实际映射的是AgentScope的ACCEPT_EDITS这个不是表示所有工具都自动同意。只能在当前工作目录下先是自动放行如果模型请求其他路径还是需要用户审批虽然我们在聊天页面保留了3中模式但是在使用过程中我们更多的是使用自动审批这个权限档位如果使用默认 Agent在执行任务的时候就需要不停的点击同意这个挺烦人的。完全放行的风险太高基本也不会使用。PermissionRuleAgentScope的PermissionMode 解决的是怎么处理权限。它定义了一些默认的规则但是如果我们有一些自定义的规则要怎么办呢这个时候就需要使用PermissionRule 来处理例如其他 Bash 命令使用默认策略但uv run pytest始终允许执行npm install时始终询问所有以rm开头的命令直接拒绝禁止Read读取项目的.env只允许Write写入docs目录这些自定义的配置不是定义在 Toolkit 里需要保存在当前 Agent 的PermissionContext中。context agent.state.permission_contextprint(context.mode)print(context.allow_rules)print(context.deny_rules)print(context.ask_rules)PermissionRule 由下面几个字段组成字段含义tool_name规则作用于哪个工具名称必须与 Tool 的name一致例如Bash、Read、Writerule_content要匹配的命令或路径填写None表示匹配该工具的所有调用behavior命中后执行ALLOW、DENY或ASKsource规则来自哪里例如userSettings、projectSettings配置规则最直接的方法是创建PermissionEngine再调用add_rule()。PermissionEngine.add_rule()会根据 behavior把规则放进context.allow_rules、context.deny_rules或context.ask_rules。执行工具时AgentScope 就会使用这个 PermissionContext。工具审批如何继续执行当权限结果为 ASK 时AgentScope 会先把待确认工具调用记录到 AgentState并将其状态标记为 ASKING随后产生 RequireUserConfirmEvent。收到用户确认后必须向同一个 Agent或者向从该 AgentState 完整恢复出的 Agent传入匹配的 UserConfirmResultEvent才能继续原来的 ReAct 流程。AgentScope 会将待确认工具记录在 AgentState 中并通过 RequireUserConfirmEvent 通知调用方暂停执行。然后mini-WorkBuddy会将这个审批的动作显示到用户的界面上等待用户确认后,才能继续执行mini-WorkBuddy 需要自行保存恢复审批流程所需的应用层信息。所以我们在项目中定义了 PendingApproval用于记录如何定位原 Agent、待确认的工具调用、原请求配置以及已经产生的流式内容。它不是 AgentScope 提供的类型。用户确认后后端根据这份记录构造 UserConfirmResultEvent交给原 Agent 继续执行。当前 PendingApproval 只保存在后端进程内存中因此服务重启后尚未处理的审批无法继续。我们现在是把 Agent key、reply ID、待确认工具、原始请求和已经产生的流式内容保存为PendingApproval然后向页面发送approval_required。用户确认后后端构造UserConfirmResultEvent交回原来的 Agent。模型可能一次发出多个并行工具调用。项目按 reply ID 保存一个ConfirmationBatch用户确认一次以后把这一批ConfirmResult一起返回给 AgentScope。拒绝也不是简单关闭弹窗。拒绝结果需要回到 Agent模型可以改用其他安全方法也可以向用户说明任务因为权限不足没有完成。工具执行过程如何显示工具执行结果需要显示吗对于我们开发者而言展示出来更容易观察agent是否按照预期执行但是对于用户他们对这个无感只需要显示一些思考过程表示Agent正在努力干活就行。AgentScope 通过 ToolCallStartEvent、ToolCallDeltaEvent 和 ToolCallEndEvent 流式输出工具名称与调用参数。后端按照 tool call ID 聚合参数片段在参数完整后发送 tool_call_end工具执行结果也以相同方式聚合并在结束时发送 tool_result。前端根据 tool call ID 创建或更新同一张工具卡片显示工具名称、格式化后的参数、执行状态和结果。对于需要审批的工具后端则从 RequireUserConfirmEvent 中取出完整的 ToolCallBlock放入 approval_required 事件供审批卡片展示。mini-workbuddy的工具可以分成四层。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】