前言¶

在 Python 里接 AgentScope，常见卡点不是「能不能 import」，而是版本混用：文档指向 2.x，仓库里仍是 ReActAgent、register_tool_function 等 1.x 写法；模型、工具、会话状态各有一套入口，改一处容易牵一片。自己翻官方文档可以解决问题，但 Agent 往往缺少按任务拆分的核对清单和可复制的最小工程。

下面介绍 SkillHub 社区 Skill agentscope-builder（坐标 @user_ea778c49/agentscope-builder）。它把 AgentScope 官方文档与目标版本源码对齐，引导 Agent 做搭建、调试、扩展或迁移，默认面向 AgentScope 2.x，并附带参考文档、最小单智能体模板和本地校验脚本。

这是什么¶

agentscope-builder 是一份基于通用 SKILL.md 格式的 Agent 技能包，简介为「AgentScope 框架搭建指南」。发布者为社区用户 user_ea778c49，来源为 community，SkillHub 分类为 ai-agent，当前商店版本为 1.0.2（技能包内 SKILL 正文标注的技能版本为 2.0.0，示例核验基线为 AgentScope 2.0.10、Python 3.11+，资料核查日期 2026-10-16）。

官方入口：

• API 坐标页：https://api.skillhub.cn/user_ea778c49/agentscope-builder
• SkillHub 展示页：https://www.skillhub.cn/skills/user_ea778c49/agentscope-builder

页面标签包含 requires_api_key=true：按包内最小模板跑通时，需要配置模型厂商密钥（示例使用 DashScope 的 DASHSCOPE_API_KEY）。

核心功能¶

以下内容均来自已安装技能包内的 SKILL.md 与配套文件，能力按任务类型组织。

版本边界与迁移¶

1. 从项目依赖、锁文件和入口判断实际使用的 AgentScope 版本（含 importlib.metadata 查询命令）。
2. 新项目默认按 2.x 核对公开 API；1.x 项目先走维护与迁移参考，仅在用户明确要求时再升主版本。
3. 资料冲突时以目标版本公开 API、源码与文档为准；不把 QwenPaw 等应用层约定写成框架硬性要求。

2.x 开发约定¶

技能内整理了 2.x 的推荐用法，并明确列出应避免的 1.x 模板写法，例如：

• 使用 agentscope.agent.Agent、await agent.reply(message) / reply_stream。
• 工具通过 Toolkit(tools=[FunctionTool(fn)])；技能目录与 MCP 通过 Toolkit 的 skills_or_loaders、mcps 接入。
• 会话与上下文：AgentState、ContextConfig；扩展侧 ReActConfig、ModelConfig、InjectionConfig 与 middleware。
• 不要在 2.x 模板中使用 ReActAgent、memory=InMemoryMemory()、register_tool_function 等旧 API。

分主题参考文档¶

技能包 references/ 下按任务索引，Agent 按需读取：

最小可运行模板¶

assets/minimal-agent/ 提供完整单智能体示例（main.py、requirements.txt）：DashScope 模型、一个执行计算的 Python 工具、官方 console；遵循默认权限策略，纯计算工具声明为只读。

本地校验脚本¶

包内 scripts/ 提供三类脚本（不替代真实联调，但便于 Agent 自检）：

• inspect_environment.py：报告已安装版本与公开签名，不联网、不读凭据。
• validate_skill.py：检查 front matter、引用路径与 Python 示例语法。
• smoke_test.py：在已安装 AgentScope 2.0.10 的环境中用假模型验证消息、工具确认、技能加载与状态恢复。

安装与启用¶

安装 SkillHub CLI¶

若本机尚未安装 skillhub，可按 SkillHub 安装说明执行（完整安装含 CLI 与默认 Skill）：

command -v skillhub && skillhub --version

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

仅安装 CLI 时：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安装 agentscope-builder¶

安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别。

skillhub install agentscope-builder --namespace user_ea778c49 --dir <skills 目录>

SkillHub 页面也支持让 AI 按说明安装：

请根据 https://skillhub.cn/install/skillhub.md，安装 `@user_ea778c49/agentscope-builder`。

常见客户端 skills 路径（摘自 SkillHub 安装文档）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/

安装后通常需要重启或刷新 Agent，使新技能被加载。包内 agents/openai.yaml 提供默认提示示例：使用 $agentscope-builder 按当前项目版本搭建可运行智能体并核验工具与状态。

典型用法¶

1. 让 Agent 启用技能后的工作流¶

启用技能后，Agent 应先确定项目 AgentScope 版本，再按上表读取对应 reference。对新项目，技能建议顺序为：单 Agent + 一种模型 → 注册工具 → 按需加载技能目录与 MCP → 会话/长期记忆 → 多智能体或服务部署。

版本检查示例（在项目 Python 环境中）：

python -c "from importlib.metadata import version; print(version('agentscope'))"

2. 从最小模板启动¶

复制 assets/minimal-agent/ 到新项目目录后：

python -m venv .venv
# 激活虚拟环境后：
python -m pip install -r requirements.txt
python main.py

通过当前 shell 设置 DASHSCOPE_API_KEY；可选 DASHSCOPE_MODEL。技能明确要求不要将真实凭据写入源码或版本库。

3. 环境自检¶

将路径替换为本机技能安装目录下的 scripts：

python /path/to/agentscope-builder/scripts/inspect_environment.py
python /path/to/agentscope-builder/scripts/inspect_environment.py --module agentscope.agent.Agent

修改技能或模板后：

python /path/to/agentscope-builder/scripts/validate_skill.py
python /path/to/agentscope-builder/scripts/smoke_test.py

适用场景与注意¶

适合谁

• 用 Python 基于 AgentScope 2.x 新建智能体，希望 Agent 按官方 API 写入口、工具和状态，而不是混用 1.x 片段。
• 维护 1.x 代码库，需要按技能内迁移文档评估升级范围。
• 需要模型接入、MCP、多智能体流水线或服务部署时，希望 Agent 按索引读配套 reference，而不是一次性塞满上下文。

限制与注意

• 标签 requires_api_key=true：跑通官方示例模型需自备 API Key；技能强调凭据只通过环境变量注入。
• 技能正文中的 AgentScope 2.0.10 与 Python 3.11+ 是编写时的核验快照，上线前应在目标环境重新确认版本与文档（stable 与 latest 可能不一致）。
• smoke_test.py 依赖已安装的 AgentScope 2.0.10，不能代替真实厂商 API 或生产部署验证。
• SkillHub 页面统计（截至资料抓取）：评分 100000，下载 1126，安装 2；社区来源，使用前应自行评估维护节奏与合规要求。

结尾¶

agentscope-builder 把 AgentScope 2.x 的约定、分主题参考、最小模板和校验脚本收进一个 Skill，适合交给 coding Agent 做「按版本搭架子、少踩 1.x/2.x 混写」类任务。安装与坐标以 SkillHub 为准：

• https://www.skillhub.cn/skills/user_ea778c49/agentscope-builder
• https://api.skillhub.cn/user_ea778c49/agentscope-builder