AgentScope 终端控制台(agentscope.console)实战指南:无需 UI 即可交互调试完整 Agent
AgentScope 终端控制台(agentscope.console)实战指南:无需 UI 即可交互调试完整 Agent
本篇技术指南以 AgentScope 仓库中的 examples/console/README.md 为核心,讲解如何借助 agentscope.console 模块在终端里直接试跑、调试一个功能完整的 Agent——包含流式模型输出、工作区文件系统工具、长期记忆中间件、工具调用人工确认与 Ctrl+C 中断等能力,全程无需启动 Web 服务、无需编写任何 UI 代码。读完本文,你将掌握 launch_console 的交互用法、三种 verbosity 输出级别,并能将被动渲染器 ConsoleRenderer 嵌入自己的 Agent 循环。
为什么需要终端控制台
AgentScope 的 Agent 天然以事件流(AgentEvent)驱动:文本、思考过程、工具调用与结果、提示块、token 消耗等都会以结构化事件的形式流式产出。要让一个 Agent 跑起来“看得到、能理解、可信任”,最直接的调试入口就是终端。
agentscope/console 模块 对外只暴露两个公开入口,分别服务两种使用场景:
launch_console:一个绑定到单个 Agent 的交互式聊天循环,输入、工具调用确认、Ctrl+C 中断一应俱全,适合“不写任何 UI 代码就把 Agent 跑起来试玩/调试”;ConsoleRenderer:一个被动事件渲染器,把Agent.reply_stream产出的事件流渲染成行式终端输出,适合在你自己掌控循环的脚本、Agent 流水线或测试中嵌入。
演示 Agent 的完整组装(main.py 逐段解析)
examples/console/main.py 演示了如何用 AgentScope 的各组件拼装出一个全功能 Agent,然后交给 launch_console 运行。其核心结构如下:
1. 命令行参数
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--model", default="qwen3.7-max")
parser.add_argument(
"--verbosity",
choices=["quiet", "default", "debug"],
default="default",
)
parser.add_argument(
"--workdir",
default=os.path.join(
os.path.dirname(os.path.abspath(__file__)),
"workspace",
),
help="The workspace root directory.",
)
--model:默认qwen3.7-max(DashScope 通义千问系列),可替换为其他 DashScope 模型名;--verbosity:quiet/default/debug三档,对应渲染器的输出详尽度;--workdir:工作区根目录,默认位于示例目录下的workspace/。
2. 凭证与模型
api_key = os.environ.get("DASHSCOPE_API_KEY")
if not api_key:
raise RuntimeError(
"Set the DASHSCOPE_API_KEY environment variable before "
"running this demo.",
)
必须先通过环境变量 DASHSCOPE_API_KEY 提供 DashScope 的 API Key,否则直接抛出 RuntimeError。模型使用流式模式构建:
model=DashScopeChatModel(
credential=DashScopeCredential(api_key=api_key),
model=args.model,
stream=True,
),
stream=True 是终端实时渲染的前提:文本、思考、工具调用的增量事件会随生成过程逐个到达。
3. 工作区:文件系统工具与技能的来源
async with LocalWorkspace(workdir=args.workdir) as workspace:
agent = Agent(
name="Friday",
system_prompt=(
"You are a helpful assistant named Friday. Use the "
"provided tools whenever they help answering the "
"question.\n\n" + await workspace.get_instructions()
),
...
toolkit=Toolkit(
tools=await workspace.list_tools(),
skills_or_loaders=await workspace.list_skills(),
),
...
offloader=workspace,
)
await launch_console(agent, verbosity=args.verbosity)
LocalWorkspace 以 ./workspace 为根目录,其目录布局(见 src/agentscope/workspace/_local_workspace.py)为:
{workdir}/
├── .mcp # 声明的 MCP 配置(按 agent/session 存放)
├── data/ # 卸载(offload)的多模态文件
├── skills/ # .seed 模板,以及每个 agent 一个分区
└── sessions/ # 每会话的上下文与工具结果文件
关键点:内置文件系统工具与 Agent 技能都来自工作区。
workspace.list_tools()返回绑定到工作区后端的工具集。在 Linux/macOS 上是Bash,在 Windows 上自动替换为PowerShell,其余为Edit、Glob、Grep、Read、Write(见 list_tools 实现)。这些工具的 shell 工作目录即cwd=self.workdir,所有文件操作被约束在工作区目录内。workspace.list_skills()从工作区的 skills 分区读取技能(每个 agent 一个 partition,用.index记录 agent 可见的名称)。SKILL.md 必须包含name与description的 frontmatter 字段,技能目录名冲突时自动追加数字后缀。workspace.get_instructions()返回一段系统提示模板,包含{workdir}占位符,注入到 agent 的 system prompt 中,告诉模型工作区的位置与约定。- 把
workspace作为offloader传入,压缩后的上下文与超长的工具结果会被卸载(offload)进工作区目录,避免撑爆上下文。
4. 长期记忆:AgenticMemoryMiddleware
middlewares=[
AgenticMemoryMiddleware(
workdir=workspace.workdir,
backend=workspace.get_backend(),
),
],
AgenticMemoryMiddleware(src/agentscope/middleware/_longterm_memory/_agentic_memory/_middleware.py)是一个基于文件系统的长期记忆中间件:
- 在工作区目录内维护一个 Markdown 记忆库,将持久化的事实(如用户角色、偏好、反馈)写成带 frontmatter 的 Markdown 文件;
- 会在系统提示中注入一个有界的
MEMORY.md索引,让模型知道自己记住了什么; - 推理循环过程中可以异步地把相关的主题文件以 hint 块(hint block)形式呈现给模型。
记忆文件按 user / feedback / project / reference 等类型分类,具备 mtime 记录;跨运行存活——重启 demo 后,上一轮“记住”的事实依然存在。
快速上手
环境准备与运行
export DASHSCOPE_API_KEY=sk-...
python main.py # 交互式聊天
python main.py --verbosity debug # 额外显示生命周期事件
python main.py --verbosity quiet # 只显示回复文本
启动后终端会出现 user> 提示符,输入内容回车即向 Agent 发送消息。注意对话存在于 agent.state 中,不包含会话管理与持久化,进程结束对话即消失(长期记忆除外)。
值得一试的三个场景
README 提供了三个能直观感受控制台能力的实测建议:
-
只读工具免确认:输入
List the python files in this directory。Glob/Grep/Read等只读工具默认直接执行,无需人工确认,可以立刻看到工具调用与结果的流式渲染。 -
写操作触发确认,
a一劳永逸:输入Create a note.md summarizing our conversation。Write属于会修改文件系统的工具,Agent 会发出RequireUserConfirmEvent停在人工确认环节,终端提示Allow 'Write'? [y]es / [N]o;此时回答a(always)会同时接受建议的权限规则,后续匹配的调用不再二次询问——你可以继续观察“后续写入跳过确认”的效果。 -
长期记忆跨运行存活:输入
Please remember that I prefer concise Chinese answers,记忆中间件会把它持久化到workspace/下的 Markdown 文件;重启 demo 后问What do you remember about me?,Agent 会基于记忆作答。
退出与中断
- 输入
exit或quit退出; - 按 Ctrl+D(EOF)退出;
- Ctrl+C 中断当前回复:
launch_console会把 Ctrl+C 转换成对当前流式回复的任务取消(见 src/agentscope/console/_console.py 中_run_reply的loop.add_signal_handler(signal.SIGINT, task.cancel)实现)。Agent 自身会处理取消清理(关闭工具调用、发出中断事件),只要react_config.interruption_raise_cancelled_error保持默认的False。在 Windows 等不支持add_signal_handler的事件循环上,会回退到KeyboardInterrupt处理。
交互循环内部实现:事件驱动与人工确认
launch_console 的主循环(src/agentscope/console/_console.py)核心逻辑是:
- 从 stdin 读取用户输入,包装成
UserMsg; - 调用
agent.reply_stream(inputs),逐事件渲染; - 若事件流中出现
RequireUserConfirmEvent(工具调用等待人工确认),循环暂停,逐条询问用户; - 用户确认结果以
UserConfirmResultEvent回传给 agent,恢复推理; - 若用户在确认环节按 Ctrl+C / EOF,则发送
UserInterruptEvent中止停驻的回复,保证下一次输入从干净状态开始。
确认逻辑(_confirm 函数)对每个待确认工具调用生成提示:
Allow 'Write'? [y]es / [N]o / [a]lways
只有当工具调用带有 suggested_rules 时才出现 [a]lways 选项;回答 a 会把建议权限规则(PermissionRule)一并接受,写入 ConfirmResult.rules 字段,匹配的后续调用不再询问。回答 y 仅放行本次。
这一交互建立在 AgentScope 完整的事件模型之上(见 src/agentscope/event/_event.py):ReplyStartEvent/ReplyEndEvent 标记一次回复的起止,TextBlock*/ThinkingBlock*/DataBlock* 承载流式内容,ToolCall*/ToolResult* 承载工具生命周期,RequireUserConfirmEvent/RequireExternalExecutionEvent 表达人工参与点,UserConfirmResultEvent/UserInterruptEvent 由外部回传。Agent.reply_stream(src/agentscope/agent/_agent.py)会把这一整套事件异步地 yield 出来。
三档 verbosity 详解
ConsoleRenderer 的 verbosity 参数取值(类型见 src/agentscope/console/_renderer.py 的 Verbosity = Literal["quiet", "default", "debug"]),内部映射为 0/1/2 三个级别:
| 级别 | 展示内容 |
|---|---|
quiet |
仅流式回复文本与错误 |
default |
在 quiet 基础上增加:思考过程(✻ Thinking…)、工具调用与结果、hint 提示块、token 用量(tokens: N in / M out)、人工确认(HITL)通知 |
debug |
在 default 基础上增加:生命周期事件(如 · model call → qwen3.7-max、· reply end · completed)、工具结果元数据等默认不可见的事件;未知事件类型也会以 dim 样式打印一行,保证渲染器在新增事件类型时仍能工作 |
其他渲染细节:
- 工具调用的 JSON 参数在流式过程中被缓冲,结束后才整块打印(短参数单行展示,长参数按 2 空格缩进多行展示);
- 并发工具的结果增量交错到达时,会被分别缓冲、以完整块输出,不会互相穿插;
- 工具结果默认最多打印 20 行(
max_tool_result_lines=20),超出部分折叠为… (+N more lines),None表示不截断; - 工具结果状态带图标与颜色:
✓(green,成功)、✗(red,错误)、⊘(yellow,拒绝)、⚠(yellow,中断)、…(dim,运行中); - 二进制数据(如图片)不打印原始 base64,而是显示占位行
[data: image/png, ~1.2MB]。
将 ConsoleRenderer 嵌入你自己的循环
对于你自己掌控循环的场景——Agent 流水线、脚本或测试——使用被动渲染器而非 launch_console:
from agentscope.console import ConsoleRenderer
renderer = ConsoleRenderer()
async for event in agent.reply_stream(msg):
renderer.render(event)
final_msg = renderer.last_msg
要点:
renderer.render(event)按事件类型分发渲染:文本/思考增量实时输出,工具调用与结果在对应 end 事件上整块打印;- 渲染的同时会累积完整回复消息,结束后可从
renderer.last_msg取到(其id与finished_reason等属性可读); - 输入、工具调用确认与中断此时是调用方的责任——渲染器只负责打印,不读 stdin。
这一用法在 tests/console_renderer_test.py 中有完整的测试支撑:文本流式渲染、quiet 隐藏非文本内容、工具参数整块打印、并发工具结果不交错、超长结果截断、hint 块与建议权限规则的展示、中断通知与 last_msg 状态累积等行为均有对应用例验证。
小结
agentscope.console 为 AgentScope 提供了“零 UI”的 Agent 调试路径:launch_console 把输入、渲染、工具确认、中断打包成一个开箱即用的交互循环,适合快速试玩与调试;ConsoleRenderer 则把事件流渲染能力开放给任何自定义循环。配合 LocalWorkspace 的文件系统工具/技能供应与 AgenticMemoryMiddleware 的文件型长期记忆,你可以仅凭一个终端就完成对 Agent 行为、工具安全确认与记忆能力的完整验证——这正是项目“Build and run agents you can see, understand and trust”理念的最小可运行体现。