AgentScope 实战指南：三步把带工具调用的多智能体应用推进生产

AgentScope 实战指南：三步把带工具调用的多智能体应用推进生产

【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscope

凌晨，Agent 把一句幻觉命令真打进了生产目录；长对话一撑爆上下文，前半程的结论全丢。病根不在模型，在缺工程管控。AgentScope 是面向生产的多智能体框架，工具调用、权限、沙箱工作区都是现成积木。

🚀 快速安装验证：Python 3.11 环境下的第一次对话

环境要求只有一条：Python 3.11 及以上。

安装：

uv pip install agentscope # 或 pip install agentscope

验证是否就绪：

python -c "import agentscope; print(agentscope.__version__)"

能打印版本号就说明装好了。想改源码做二次开发，先 clone 仓库（https://gitcode.com/GitHub_Trending/ag/agentscope）再uv pip install -e .即可。

核心机制：权限引擎、上下文压缩、沙箱工作区

权限引擎：工具调用先过审再执行 ⚠️

解决什么问题：模型幻觉没法根除，与其在 prompt 里求它别生成危险命令，不如在执行层硬拦。AgentScope 让每次工具调用先过权限引擎（agentscope/permission/），产出允许、拒绝、询问三种判定，人随时能介入（HITL）。机制怎么工作：引擎按 PermissionMode 分层放行——DEFAULT 默认逐次确认（ls、git status这类内置只读命令可自动放行），ACCEPT_EDITS 在工作目录内自动放行文件读写，EXPLORE 纯只读，适合让 Agent 先摸代码库再动手，BYPASS 跳过全部检查。什么情况要当心：记住，BYPASS 连危险命令的安全询问都一并跳过，只能在容器、虚拟机这类隔离环境里开，并用 deny 规则钉死关键路径；无人值守又想保安全，用 DONT_ASK 更稳，它会把所有询问直接转成拒绝，默认安全。

上下文压缩机制：长对话压成可续跑的摘要

解决什么问题：长对话必然撞上模型窗口上限，硬截断会丢掉前半程的发现，Agent 等于失忆重跑。机制怎么工作：ContextConfig（agentscope/agent/_config.py）持续盯 token 占用，默认到模型窗口的 80%（trigger_ratio=0.8）触发压缩，把旧对话重写进五段式摘要——任务概述、当前状态、关键发现、下一步计划、需保留的上下文。模板强制把"这个文件""刚才那个方案"这类相对指代换成绝对路径和绝对时间，换窗口也能直接续跑；超大工具结果还能交给 offloader 外移到文件，不挤占正文。什么情况要当心：想让摘要保住你的领域黑话，改compression_prompt和summary_template这两个字段就够了，别去动系统提示词。

沙箱工作区：工具执行面与宿主隔离

解决什么问题：Bash、Write 这类工具直接挂在宿主机上，Agent 一跑偏就是真删真写。机制怎么工作：内置工具不直接落系统，而是绑定到 Workspace（agentscope/workspace/），本地、Docker、E2B、K8s 后端随意切换；工具清单由工作区自己提供（await workspace.list_tools()），说白了，换后端等于换一整套受控的文件系统和命令环境。什么情况要当心：上一条说的 BYPASS 这类激进权限，只在沙箱里谈才有意义；反过来，接上AgenticMemoryMiddleware后，工作区目录还能跨会话持久化长期记忆，属于免费的额外收益。

最小可运行示例：20 行带工具的对话 Agent

import asyncio, os from agentscope.agent import Agent from agentscope.console import launch_console from agentscope.credential import DashScopeCredential from agentscope.model import DashScopeChatModel from agentscope.tool import Toolkit from agentscope.workspace import LocalWorkspace async def main(): async with LocalWorkspace(workdir="./workspace") as workspace: agent = Agent( name="Friday", system_prompt="A helpful assistant. " + await workspace.get_instructions(), model=DashScopeChatModel( credential=DashScopeCredential(api_key=os.environ["DASHSCOPE_API_KEY"]), model="qwen3.7-max", stream=True, ), toolkit=Toolkit(tools=await workspace.list_tools()), offloader=workspace, ) await launch_console(agent) asyncio.run(main())

一句话，Agent是统一入口，内部就是 ReAct 推理-行动循环，工具调用支持批量顺序或并发执行；Toolkit的工具清单来自工作区，所以换沙箱后端时工具一行不用动；launch_console把流式输出、工具确认、Ctrl+C 中断全接好了。换模型厂商只改model这一处，OpenAI、Anthropic、Gemini 的 ChatModel 同构替换，凭据换成对应的 Credential 就行。

🛠 落地用法：长跑任务、多智能体分工、执行-验证互审

长跑任务执行者：让 Agent 连续处理一个跨文件的改造需求。上下文压缩自动兜底，配合 TaskCreate/TaskList 这类内置任务工具，它会把活儿拆成带状态的计划并实时更新，中途不会因上下文溢出丢掉前半程的发现。

多智能体团队分工：一个复杂需求要并行推进多个子任务时，Agent Service 的 team 工具让 leader 动态生成 worker、派活、验收。为什么行得通：分工、消息流转和验收状态都在 Web UI 上全程可见，出问题能定位到具体是哪个 worker 哪一步。

执行者-验证者互审：生成的代码要过独立验证才交付，GoalPipeline 里 executor 负责写、verifier 读同一工作区独立检查，不达标就循环返工。容器沙箱里配 BYPASS 跑全程免确认，产出比单次生成稳。

延伸资源

• docs/NEWS.md：最新更新公告，跟进新特性看这里。
• docs/changelog.md：逐版本变更记录，升级前查行为差异。
• docs/roadmap.md：项目路线图，判断某个能力是否已经稳定。
• examples/：全部可运行示例，含终端对话、Agent Service + Web UI、执行者-验证者流水线。
• README_zh.md：中文 README，快速过一遍框架全貌。
• CONTRIBUTING_zh.md：贡献指南，要改源码先读它。

现在就打开 examples/console/main.py，把默认模型名改成自己的，export DASHSCOPE_API_KEY=...再跑python main.py，一个带工具的 Agent 就在你终端里跑起来了。

【免费下载链接】agentscopeBuild and run agents you can see, understand and trust.项目地址: https://gitcode.com/GitHub_Trending/ag/agentscope