Demo 演示指南

0.8.x 增量(已可演示):多模态附件理解、联网搜索 web_search、MCP 连接器、自动化定时任务(均纯标准库零依赖)。 最近一次现场核验:2026-08-28(服务以 --demo 离线模式启动,SSE 全链路跑通,270 项 smoke + 38 项 e2e 测试全过)。

0. 先确认项目状态(给演示者的速查)

项当前状态
端口默认 8765(config.json → server.port)
代码位置E:\Project\trueagt
入口Web 服务 web.py;CLI 对话 main.py
测试test_smoke.py 270 通过 / 0 失败;e2e 38 通过 / 0 失败
授权(License)默认 关闭,演示不会被 402 拦截
鉴权有注册用户才启用;全新库(0 用户)直接进入,无登录摩擦
模型默认指向本地 http://192.168.0.80:9000/v1(qwen3.8-27b-llamacpp),仅真实模式需要;演示用 --demo 离线 Mock,无需任何 API Key

一句话结论:直接 TrueAGT.exe --demo 就能把整套能力演示出来,不依赖外网、不依赖模型服务、不弹登录框。


1. 启动演示服务(第一步,必做)

用 离线演示模式 启动(推荐,稳定、可复现、无需模型端点):

cd E:\Project\trueagt
TrueAGT.exe --demo            # 默认监听 0.0.0.0:8765
# 或显式指定: TrueAGT.exe --demo --host 127.0.0.1 --port 8765

启动成功后日志里有这行关键标志(说明已进入 Mock 模式):

服务启动 http://0.0.0.0:8765 [离线演示(mock)] [鉴权未启用] [单进程] [工具 7 个]

健康自检(任选其一,确认服务活着):

curl http://127.0.0.1:8765/healthz     # → {"ok": true, "version": "0.9.233"}
curl http://127.0.0.1:8765/api/status   # → 其中 "demo": true, "model": "mock-1"
只要 api/status 返回 "demo": true 且 "model": "mock-1",就说明 Mock 模式真正生效了(详见第 7 节排错:端口被旧进程占用的坑)。

2. 四大能力 · 逐步演示脚本(穿插讲解)

下面这条主线问题一次就把"SSE 流式 + 工具调用 + 长期记忆"全点亮,适合作为开场 demo:

用户问:「帮我算一下 12345 乘以 67 是多少,并把结论记到长期记忆里。」

能力①:Web 服务 + 前端界面(基础门面)

能力②:SSE 流式输出(核心亮点)

能力③:工具调用(Tool Calling)

能力④:长期记忆(Long-term Memory)

附加亮点:计划确认(Plan-First)

  curl -s -X POST http://127.0.0.1:8765/api/plan \
    -H "Content-Type: application/json" \
    -d '{"session_id":"<会话ID>","message":"调研一下本地部署智能体的优缺点"}'
  # → {"steps":["用计算器算出结果","把结论写入长期记忆","汇报答案"]}

3. 三种演示入口(按场景选)

A. 浏览器前端(最省事,推荐给大多数观众)

  1. TrueAGT.exe --demo 启动;
  2. 打开 http://127.0.0.1:8765/;
  3. 直接聊天,观众看到流式回答与工具调用过程。

B. curl 看 SSE 原始事件(最"硬核",适合技术评审)

能直观展示每一个事件帧:user_input → plan → llm_delta(流式) → llm_response(含 tool_calls) → tool_result → final_answer → done。

# 1) 建一个会话,拿到会话 ID
SID=$(curl -s -X POST http://127.0.0.1:8765/api/sessions \
  -H "Content-Type: application/json" -d '{"title":"demo"}' \
  | python -c "import sys,json;print(json.load(sys.stdin)['id'])")

# 2) 发消息,用 -N 保持 SSE 流
curl -N -X POST http://127.0.0.1:8765/api/chat \
  -H "Content-Type: application/json" \
  -d "{\"session_id\":\"$SID\",\"message\":\"帮我算一下 12345 乘以 67 是多少,并把结论记到长期记忆里。\"}"

下面是本次现场实际跑出来的 SSE 输出(节选,证明链路真实可用):

data: {"type": "user_input", "text": "帮我算一下 12345 乘以 67 是多少,并把结论记到长期记忆里。"}
data: {"type": "plan", "steps": ["用计算器算出结果", "把结论写入长期记忆", "汇报答案"]}
data: {"type": "llm_delta", "iteration": 1, "delta": "我先用计算器"}
data: {"type": "llm_delta", "iteration": 1, "delta": "算一下。"}
data: {"type": "usage", "prompt_tokens": 100, "completion_tokens": 50}
data: {"type": "llm_response", "iteration": 1, "content": "我先用计算器算一下。", "tool_calls": [["calculate", {"expression": "12345 * 67"}]]}
data: {"type": "tool_result", "name": "calculate", "arguments": {"expression": "12345 * 67"}, "result": "827115"}
data: {"type": "llm_response", "iteration": 2, "content": "结果出来了,我把这个结论记下来。", "tool_calls": [["note", {"content": "演示任务结论:12345×67=827115", "tag": "task"}]]}
data: {"type": "tool_result", "name": "note", "arguments": {"content": "演示任务结论:12345×67=827115", "tag": "task"}, "result": "已记入长期记忆 #778"}
data: {"type": "final_answer", "text": "计算完成:12345 × 67 = 827115。我已把这条结论写入长期记忆,之后可以随时 recall 查到它。"}
data: {"type": "done"}

C. 纯 CLI(无界面,适合终端演示)

TrueAGT.exe --demo
# 自动问:"帮我算一下 12345 乘以 67 是多少,并把结论记到长期记忆里。"
# 跑完直接打印最终回答 + 长期记忆库内容

4. 演示话术模板(照着讲就行)

"我们现在看的是TrueAGT——一个跑在本地、端口 8765 的私有化智能体。 第一,它对外是一个 Web 服务,浏览器直接访问就能用(指界面)。 第二,它的回答是 SSE 流式推出来的,你看字是一个一个出来的(指流式)。 第三,遇到计算它自己调了计算器工具,遇到要记的事自己调了笔记工具,这是 Agent 的工具调用能力(指工具调用)。 第四,它把结论写进了长期记忆,之后换一个会话还能 recall 回来(指记忆编号 #778)。 而且全程不联网、不依赖任何外部大模型 API——刚才用的是内置离线 Mock,所以演示永远稳定可复现。"

5. 接入真实模型(可选,演示"真智能"时用)

--demo 的 Mock 是脚本化的:它固定走"calculate → note → 总结",不会根据问题内容变化,因此无法演示 recall 真正检索历史记忆(Mock 不读你的输入)。

要演示"真实理解 + 真实记忆检索",改用真实模型:

  1. 准备一个 OpenAI 兼容的模型端点(本地 llama-cpp / vLLM,或云端);
  2. 改 config.json:
   "llm": {
     "provider": "openai",
     "model": "你的模型名",
     "api_key": "你的Key或占位",
     "base_url": "http://模型服务地址/v1"
   }
  1. 不加 --demo 启动:TrueAGT.exe(此时走真实 LLM);
  2. 问"我之前记了什么关于乘法结论的内容?用 recall 查一下"——真实模型会调用 recall 把历史记忆检索回来。
注意:真实模式下若 data/trueagt.db 已有注册用户,会启用登录;首次启动且库为空则免登录。

6. 常用接口速查(贴给技术观众)

方法路径说明
GET/healthz健康检查
GET/api/version版本号
GET/api/status当前模型/工具/记忆/加密状态
GET/api/sessions会话列表
POST/api/sessions新建会话(返回 12 位 ID)
POST/api/plan只生成计划不执行
POST/api/chatSSE 对话主接口(支持 attachments 附件数组)
POST/api/stop取消当前生成
GET/api/automations自动化任务列表(管理员)
POST/api/automations新建自动化任务(管理员,返回 201)
POST/api/automations/{id}/run立即运行一次(管理员)
DELETE/api/automations/{id}删除自动化任务(管理员)
GET/api/auth/config当前鉴权/注册模式

完整协议见同目录 API参考.md。


7. 排错(演示前必看,都是踩过的坑)

  1. /api/status 显示 "demo": false、model 是真实模型名,且对话卡住/报错

→ 8765 端口上有上一轮残留的旧服务进程在应答,新起的 --demo 没抢到流量。 解决:清掉 8765 上的所有 python 进程再重启:

   netstat -ano | findstr 8765      # 看占用 PID
   taskkill /PID <PID> /F           # 逐个杀掉
   # 确认端口空闲后重新 TrueAGT.exe --demo

重新启动后务必再 curl /api/status 确认 "demo": true。

  1. 打开网页却要先登录

→ data/trueagt.db 里已有注册用户(鉴权"有用户才启用")。演示可二选一:

  1. 新对话被 402 拒绝

→ 授权(License)被开启且已过期。config.json 里删掉/置 license.enabled: false 即可;默认就是关闭的。

  1. 界面图标(logo)加载 404

→ 构建期静态资源路径小瑕疵,仅影响图标显示,不影响任何功能,可忽略。

  1. 真实模式连不上模型

→ 检查 config.json 的 base_url / api_key 与网络;本地 llama-cpp 需先把它跑起来。

本文档随 TrueAGT 安装包一同发布;如与软件实际行为不一致,以软件当前版本为准。