\---
name: agentscope-builder
description: 严格依据 AgentScope 官方文档与 CoPaw 工程实现模式，指导基于 AgentScope v1.0 搭建单智能体、多智能体、工具、记忆、计划与技能系统。
tags:
\---
当用户要求你基于 AgentScope 框架搭建、改造或扩展智能体时，你必须：
ReActAgent 封装、动态技能加载、工作区提示词拼装、内存/钩子扩展、按目录组织能力。\---
ReActAgent。model 与 formatter 必须匹配，不能混搭。Toolkit 注册。SKILL.md 表达，并通过 Toolkit.register\\\_agent\\\_skill() 注册。InMemoryMemory() 起步；确有持久化需要时，再升级到 SQLAlchemy / Redis / Tablestore 等实现。PlanNotebook，多智能体编排优先考虑官方 pipeline。async / await。import。OpenAIChatModel，并通过 client\\\_kwargs={"base\\\_url": ...} 指定兼容端点。生成方案时，默认采用如下分层：
Toolkit 统一注册工具ReActAgent 或其封装类SKILL.md\---
在 AgentScope 中，智能体、记忆、长期记忆和工具模块本身都是有状态对象。因此，设计时要把“对象初始化”和“状态恢复/迁移”分开考虑。消息 Msg 是统一数据结构，贯穿用户输入、智能体对话、工具调用、记忆存储与多智能体协作。
建议按以下顺序搭建：
MsgToolkitReActAgentmemoryPlanNotebookpipelineregister\\\_agent\\\_skill\---
pip install agentscope
# 如需额外模型/工具能力：
# Windows
pip install agentscope\\\[full]
# macOS / Linux
pip install agentscope\\\\\\\[full\\\\]
\---
Msg 的核心字段是：
namerolecontentmetadata其中：
role 只能是 system / assistant / usercontent 可以是纯字符串，也可以是内容块列表metadata 适合承载结构化输出，不参与常规提示拼接from agentscope.message import Msg
user\\\_msg = Msg(
name="user",
role="user",
content="请先分析需求，再给出 AgentScope 工程结构。",
)
\---
ReActAgent 创建时，model 与 formatter 必须一起确定。OpenAIChatModel。generate\\\_kwargs 传入。import os
from agentscope.model import DashScopeChatModel
from agentscope.formatter import DashScopeChatFormatter
model = DashScopeChatModel(
model\\\_name="qwen-max",
api\\\_key=os.environ\\\["DASHSCOPE\\\_API\\\_KEY"],
stream=True,
enable\\\_thinking=False,
)
formatter = DashScopeChatFormatter()
如果用户使用 OpenAI 兼容服务（例如 vLLM、自建网关等），按下面的思路写：
from agentscope.model import OpenAIChatModel
from agentscope.formatter import OpenAIChatFormatter
model = OpenAIChatModel(
client\\\_kwargs={"base\\\_url": "http://localhost:8000/v1"},
generate\\\_kwargs={"temperature": 0.2, "max\\\_tokens": 1200},
)
formatter = OpenAIChatFormatter()
> 注意：这里展示的是官方文档明确提到的 client\\\_kwargs 与 generate\\\_kwargs 用法；若用户有既定 provider 配置，再按其环境补足 model\\\_name、api\\\_key 等参数。
\---
AgentScope 中工具函数应满足两点：
ToolResponse，或返回 ToolResponse 的生成器from agentscope.message import TextBlock
from agentscope.tool import ToolResponse
def project\\\_search(query: str) -> ToolResponse:
"""在项目知识中搜索信息。
Args:
query (str): 搜索关键词。
"""
return ToolResponse(
content=\\\[
TextBlock(
type="text",
text=f"已收到搜索请求：{query}",
),
],
)
from agentscope.tool import Toolkit
toolkit = Toolkit()
toolkit.register\\\_tool\\\_function(project\\\_search)
如果一个能力域下有多组工具（例如浏览器工具、数据库工具、文件系统工具），再使用 Toolkit.create\\\_tool\\\_group() 做显式管理；否则直接注册到默认组即可。
\---
官方文档里，ReActAgent 常用参数包括：
namesys\\\_promptmodelformattertoolkitmemorylong\\\_term\\\_memorylong\\\_term\\\_memory\\\_modeenable\\\_meta\\\_toolparallel\\\_tool\\\_callsmax\\\_itersplan\\\_notebookimport asyncio
import os
from agentscope.agent import ReActAgent
from agentscope.formatter import DashScopeChatFormatter
from agentscope.memory import InMemoryMemory
from agentscope.model import DashScopeChatModel
from agentscope.tool import Toolkit
from agentscope.message import TextBlock, Msg
from agentscope.tool import ToolResponse
def execute\\\_plan(topic: str) -> ToolResponse:
"""根据主题返回一个简要执行计划。
Args:
topic (str): 任务主题。
"""
return ToolResponse(
content=\\\[
TextBlock(
type="text",
text=f"建议先拆解任务，再检索资料，最后生成结果：{topic}",
),
],
)
async def main() -> None:
toolkit = Toolkit()
toolkit.register\\\_tool\\\_function(execute\\\_plan)
agent = ReActAgent(
name="Jarvis",
sys\\\_prompt="你是一个严格遵循 AgentScope 官方用法的开发助手。",
model=DashScopeChatModel(
model\\\_name="qwen-max",
api\\\_key=os.environ\\\["DASHSCOPE\\\_API\\\_KEY"],
stream=True,
enable\\\_thinking=False,
),
formatter=DashScopeChatFormatter(),
toolkit=toolkit,
memory=InMemoryMemory(),
max\\\_iters=10,
)
reply = await agent(
Msg(name="user", role="user", content="帮我设计一个智能客服 Agent。")
)
print(reply)
if \\\_\\\_name\\\_\\\_ == "\\\_\\\_main\\\_\\\_":
asyncio.run(main())
\---
默认从 InMemoryMemory() 起步。它简单、官方示例使用频繁，并且适合先跑通功能。
AgentScope 的记忆支持给消息打 mark，这对于：
都很有帮助。
如果用户明确需要长期记忆，优先解释三种模式：
agent\\\_control：让智能体借助工具主动管理长期记忆static\\\_control：在回复前后自动做检索/写入both：两者同时启用InMemoryMemory() 即可\---
只要任务具有明显的“拆解—执行—回收”结构，就考虑启用 PlanNotebook。
适合场景：
不适合场景：
from agentscope.plan import PlanNotebook
plan\\\_notebook = PlanNotebook(max\\\_subtasks=8)
agent = ReActAgent(
name="Planner",
sys\\\_prompt="你需要先拆解任务，再逐步完成。",
model=model,
formatter=formatter,
toolkit=toolkit,
memory=InMemoryMemory(),
plan\\\_notebook=plan\\\_notebook,
)
> 官方文档强调：当前计划模块默认是\\\\\\顺序执行子任务\\\\\\，不是任意 DAG 调度器。因此不要先假设并行子任务编排。
\---
当用户要多智能体时，优先从官方 pipeline 起步，而不是先写自定义 orchestrator。
适合：
from agentscope.pipeline import sequential\\\_pipeline
msg = await sequential\\\_pipeline(
agents=\\\[analyst\\\_agent, builder\\\_agent, reviewer\\\_agent],
msg=None,
)
适合：
如果用户只是要“多个角色协作”，默认先给顺序管道方案；只有明确要并发多视角时，再给 fanout。
\---
AgentScope 原生支持把“技能目录”挂到 Toolkit 上。技能本质上是目录 + SKILL.md，然后由 Toolkit.register\\\_agent\\\_skill() 注册。
from agentscope.tool import Toolkit
toolkit = Toolkit()
toolkit.register\\\_agent\\\_skill("sample\\\_skill")
agent\\\_skill\\\_prompt = toolkit.get\\\_agent\\\_skill\\\_prompt()
print(agent\\\_skill\\\_prompt)
my\\\_skill/
└── SKILL.md
SKILL.md 最小模板---
name: my\\\_skill
description: 用于指导 Agent 按固定流程完成某类任务。
---
# 使用说明
当用户要求你处理某类任务时，先阅读本文件，再按约定流程执行。
\---
CoPaw 不是在 AgentScope 之上“另起炉灶”，而是把 AgentScope 的核心抽象进一步工程化。搭建你自己的系统时，优先借鉴以下几点。
ReActAgentCoPaw 的主 Agent 继承自 ReActAgent，初始化顺序非常值得参考：
Toolkitsuper().\\\_\\\_init\\\_\\\_(...)from agentscope.agent import ReActAgent
from agentscope.memory import InMemoryMemory
from agentscope.tool import Toolkit
class ProjectAgent(ReActAgent):
def \\\_\\\_init\\\_\\\_(self, model, formatter, sys\\\_prompt: str):
toolkit = Toolkit()
toolkit.register\\\_tool\\\_function(project\\\_search)
toolkit.register\\\_agent\\\_skill("./skills/agentscope\\\_builder")
super().\\\_\\\_init\\\_\\\_(
name="ProjectAgent",
model=model,
formatter=formatter,
sys\\\_prompt=sys\\\_prompt,
toolkit=toolkit,
memory=InMemoryMemory(),
max\\\_iters=12,
)
这比把所有逻辑直接塞进 main.py 更适合后续扩展。
\---
CoPaw 会从工作区中的多个 Markdown 文件拼装系统提示，核心思路是：
可借鉴的文件分层：
AGENTS.md：职责、行为边界、执行原则SOUL.md：语气、风格、人格偏好PROFILE.md：业务背景、常量、领域知识\---
CoPaw 的技能实践说明了两件事：
建议你采用以下目录：
project/
├── app/
│ ├── main.py
│ ├── agent\\\_factory.py
│ ├── prompts/
│ │ ├── AGENTS.md
│ │ ├── SOUL.md
│ │ └── PROFILE.md
│ ├── tools/
│ │ ├── search.py
│ │ └── file\\\_ops.py
│ └── workflows/
│ ├── single\\\_agent.py
│ └── multi\\\_agent.py
├── skills/
│ ├── agentscope\\\_builder/
│ │ └── SKILL.md
│ └── report\\\_writer/
│ └── SKILL.md
└── data/
如果你要做“多技能启停”，可以再加一个 manifest 文件维护：
\---
CoPaw 的文档与实现都表明，SKILL.md 最少要包含 front matter 中的：
namedescription因此，当你帮用户创建技能文档时，默认带上 YAML front matter，不要只写正文。
---
name: skill\\\_name
description: 这个技能解决什么问题、在什么场景下启用。
---
# 任务边界
# 操作步骤
# 输出要求
# 禁止事项
\---
参考 CoPaw，建议这样分工：
不要把三者混成一个超长 system prompt。
\---
CoPaw 会在 Agent 初始化后追加 hook，用于：
当用户要求以下能力时，你应优先建议 hook：
如果只是普通工具调用，不需要引入 hook。
\---
当用户要求“帮我搭一个 AgentScope 智能体”时，优先按下面格式输出：
main.pyagent\\\_factory.pytools/skills/prompts/asyncio.run(main())InMemoryMemory 升级到持久化 memory\---
你应该：
ReActAgentToolkitInMemoryMemory()你应该：
PlanNotebook你应该：
sequential\\\_pipeline你应该：
SKILL.mdname 与 description\---
AgentScope.init() 之类官方文档没有的入口\---
agentscope\\\_project/
├── main.py
├── requirements.txt
├── app/
│ ├── agent\\\_factory.py
│ ├── prompts/
│ │ ├── AGENTS.md
│ │ ├── SOUL.md
│ │ └── PROFILE.md
│ ├── tools/
│ │ ├── project\\\_search.py
│ │ ├── file\\\_tool.py
│ │ └── web\\\_tool.py
│ ├── skills/
│ │ └── agentscope\\\_builder/
│ │ └── SKILL.md
│ ├── memory/
│ │ └── memory\\\_factory.py
│ └── workflows/
│ ├── single\\\_agent.py
│ ├── planner\\\_agent.py
│ └── multi\\\_agent\\\_pipeline.py
└── data/
\---
当用户给出需求后，你应按下面流程执行：
ReActAgent / Toolkit / InMemoryMemory / PlanNotebook / pipeline / register\\\_agent\\\_skill。\---
src/copaw/agents/react\\\_agent.pysrc/copaw/agents/model\\\_factory.pysrc/copaw/agents/skills\\\_manager.pysrc/copaw/agents/prompt.pysrc/copaw/agents/skills/共 2 个版本