AgentScope 终端控制台(agentscope.console)实战指南:无需 UI 即可交互调试完整 Agent

原创2026-09-09 13:44:052,186 阅读
文章标签:人工智能AI AgentAgent 框架多智能体工具调用MCP 服务MCP ClientsRAGAgent 记忆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 提供了三个能直观感受控制台能力的实测建议:

  1. 只读工具免确认:输入 List the python files in this directory。Glob/Grep/Read 等只读工具默认直接执行,无需人工确认,可以立刻看到工具调用与结果的流式渲染。

  2. 写操作触发确认,a 一劳永逸:输入 Create a note.md summarizing our conversation。Write 属于会修改文件系统的工具,Agent 会发出 RequireUserConfirmEvent 停在人工确认环节,终端提示 Allow 'Write'? [y]es / [N]o;此时回答 a(always)会同时接受建议的权限规则,后续匹配的调用不再二次询问——你可以继续观察“后续写入跳过确认”的效果。

  3. 长期记忆跨运行存活:输入 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)核心逻辑是:

  1. 从 stdin 读取用户输入,包装成 UserMsg;
  2. 调用 agent.reply_stream(inputs),逐事件渲染;
  3. 若事件流中出现 RequireUserConfirmEvent(工具调用等待人工确认),循环暂停,逐条询问用户;
  4. 用户确认结果以 UserConfirmResultEvent 回传给 agent,恢复推理;
  5. 若用户在确认环节按 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”理念的最小可运行体现。

登录后查看全文
agentscope