AgentScope 2.0 完全实战：3 步让编码智能体跑通隔离、权限与多租户上线

AgentScope 2.0 完全实战：3 步让编码智能体跑通隔离、权限与多租户上线

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

AgentScope 2.0 是通义实验室开源的生产级多智能体框架，用终端对话到在线服务的方式组装 ReAct 智能体。这篇文章带你先 3 步在终端跑起一个能读写文件的编码智能体，再讲清权限引擎、沙箱后端怎么选，最后把同一个智能体变成多租户、带 Web UI 的 Agent Service。照着做，每一步都有具体命令、目录和规则示例。

3 步跑通第一个终端编码智能体 🚀

最快上手的入口是终端控制台，不需要部署任何服务。

第 1 步：安装核心包（要求 Python ≥ 3.11，这是硬门槛）：

uv pip install agentscope

第 2 步：拿到源码并进入 console 示例：

git clone https://gitcode.com/GitHub_Trending/ag/agentscope cd agentscope/examples/console

第 3 步：配好模型 Key 并运行（示例默认用 DashScope）：

export DASHSCOPE_API_KEY=sk-... python main.py

打开的就是一个完整的聊天界面：流式输出、工具调用的人机确认、Ctrl+C 中断以及中断后的恢复，都由launch_console接管。示例脚本 main.py 里能看到智能体的组装方式——Bash、Read、Write、Edit、Grep、Glob 这些工具全部来自LocalWorkspace.list_tools()，AgenticMemoryMiddleware把长期记忆写进工作区目录下的 Markdown 文件，下次启动还在。复杂任务会被拆成可跟踪的计划，边执行边更新进度：

到这里，智能体已经能改你当前目录里的文件了。接下来要回答的问题是：哪些动作必须先问你，哪些可以直接执行？

它会不会乱改我的文件：权限引擎与 5 种模式对照 🔐

权限引擎在"工具 + 规则"两层做控制，源码在 src/agentscope/permission/。

规则层：每条规则由tool_name、rule_content、behavior（allow / deny / ask）三个字段组成，匹配方式随工具类型变化——Bash 按命令子串匹配，读写工具按文件路径 glob 匹配。也就是说一条Bash + "rm -rf" + deny就能拦住所有带这个子串的命令，一条Write + "secrets/**" + deny就能锁住整个敏感目录。

全局层：规则之上叠加 5 种模式，从"人在场"一路覆盖到"完全无人值守"：

一条必须记住的结论：BYPASS 连工具自带的安全询问也会跳过——rm -rf、改写 shell 配置这类动作它不再拦。所以用 BYPASS 时，deny 规则就是唯一护栏，一定要写够。想让无人值守仍保留安全底线，用 DONT_ASK 代替：该问的全变成拒。

模式解决"问不问"，沙箱解决"在哪跑"——下一节看 8 个执行后端怎么选。

代码到底在哪执行：8 种沙箱后端对照

"代码在哪里跑"由 workspace 后端决定。同一套工具箱绑定不同后端时，工具代码一行不用改。

SDK 侧各后端实现在 src/agentscope/workspace/；服务侧由 workspace_manager 按会话和租户分配工作区。依赖按后端拆成了独立 extras（workspace-docker、workspace-e2b、workspace-k8s等，见 pyproject.toml），只用 Docker 隔离就只装这一个。tests/目录下每个后端都有独立测试文件，接入前先跑一遍对应用例最稳。

单智能体至此闭环。但"你自己能用"和"别人也能用"之间还差一层服务化。

从单智能体到多租户在线服务：Agent Service 怎么拼

服务层把同一个智能体变成多租户、多会话的在线应用。完整入口看 examples/agent_service/main.py——一次create_app(...)把所有零件拼在一起：

• 存储：示例用RedisStorage（状态可持久化到 Redis 或 SQL，SQL 后端自带 Alembic 迁移），会话与智能体状态落库后重启不丢进度；
• 消息总线：单进程用InMemoryMessageBus，多进程部署换成RedisMessageBus；
• IM 频道：DingTalkChannel、FeishuChannel、DiscordChannel直接注册，消息路由在服务层完成，智能体接知识库后就是一个能查资料的客服入口；
• 智能体团队：主智能体按需创建子智能体，用内置团队工具协调分工，源码在 src/agentscope/app/_tool/；示例还注册了一个SubAgentTemplate自定义的只读 explorer（EXPLORE 模式），专门负责探索代码库而绝不改动文件；
• 后台任务卸载：长耗时工具调用自动转入后台，结果出来后唤醒智能体继续对话，前端全程可感知，实现见 _tool_offload_middleware.py；
• RAG 与定时任务：内置多租户知识库与调度器，examples/rag/ 有完整的索引与接入示例。

观测方面不用额外接入：OpenTelemetry SDK 与 OTLP 导出器就在基础依赖里，追踪和指标直接汇入你现有的监控体系。

对输出质量要求高的场景，examples/pipeline/goal/ 演示了"执行者 + 验证者"流水线：一个写代码，另一个用结构化输出给出通过/不通过及理由，不通过就把反馈带回重做。两者共享同一个工作区，验证者检查的是真实产物而不是口头汇报——这正是 GoalPipeline 值得单独跑一遍的原因。

在最短路径上再走两步就能上线：

python main.py # 在 examples/agent_service 下，需先启动 Redis

cd examples/web_ui && pnpm install && pnpm dev

Web UI 页面里把 API 地址指向http://localhost:8000，权限确认、定时任务、工具调用就能在网页上完整体验。

功能都齐了，剩下的是真正会咬人的地方。

权衡与避坑：上线前必须定的 6 件事 ⚠️

1. 无人值守首选"容器 + BYPASS + deny"，而不是"DEFAULT + 人工逐条点"。原因：DEFAULT 下每个未放行动作都会挂起等人确认，长任务会卡死在确认上；而容器隔离已经把爆炸半径圈住了。做法：Docker 工作区 + BYPASS 模式 + 明确的 deny 规则。想保留安全底线就用 DONT_ASK，把所有询问转成拒绝。
2. deny 规则要写到命令与路径粒度。Bash 规则按子串匹配，rm -rf、sudo各配一条；读写规则按 glob 匹配，secrets/**、.env各配一条。规则挂在 deny_rules 里，BYPASS 下依然生效。
3. 生产环境别装[full]，按功能挑 extras。full 打包了 20 多个功能组；只跑对话服务的话，service+storage-redis+channel+workspace-docker足够，依赖面小、升级风险低。
4. 长对话必须接压缩与卸载。上下文只写不擦会越来越乱，模型会先失忆再出错。框架内置自动压缩与工具结果卸载，用法就是把 workspace 传成offloader，长任务再挂上上下文类中间件（示例见 examples/console/main.py 里的AgenticMemoryMiddleware）。
5. InMemory 消息总线不能跨进程。示例默认InMemoryMessageBus，一上 uvicorn 多进程或多机部署，任务状态就丢了。多进程前换RedisMessageBus，示例 main.py 里注释已给出写法。
6. 两个环境坑提前查掉。Windows 上 uvicorn 的reload会强制 SelectorEventLoop，无法启动内置工具依赖的子进程，Windows 部署请关掉 reload（示例已按平台处理）；Web UI 需要 Node.js ≥ 20。

延伸阅读索引

• 更新日志：docs/NEWS.md
• 路线图：docs/roadmap.md
• 权限引擎源码：src/agentscope/permission/
• 沙箱工作区各后端实现：src/agentscope/workspace/

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