Minimal Python Agent

这是一个从零实现的最小可用 Python CLI Agent。

核心 Agent Runtime 由本项目自行实现，不依赖 LangGraph、OpenHands、OpenClaw 或其他 Agent 框架完成主流程。

功能特性

• 真实 OpenAI-compatible LLM 适配器，可配置千问兼容 API
• 解析 LLM 输出中的 thought、tool_call、final_answer
• 基于 Schema 的工具注册机制
• 内置工具：calculator、search、weather、todo
• 基于 user_id + session_id 的 session 隔离
• 轻量 context folding：session_facts、rolling_summary、短期消息窗口
• Loop 安全预算：最大循环次数、解析重试、工具错误重试、重复工具调用、无进展停止
• 结构化 trace 事件
• 本地 JSON 运行记录：data/session_runs.json

系统设计

Runtime 围绕一个明确的 Agent loop 组织：

用户输入
  -> 写入 session
  -> 构建 context
  -> 调用 LLM
  -> 解析 decision
  -> final answer 或 tool call
  -> 执行工具
  -> 写入 tool observation
  -> 继续 loop，直到最终回答或安全停止

主要模块：

• minimal_agent/runtime.py：Agent loop、循环预算、工具执行、trace 事件、最终结果处理。
• minimal_agent/llm.py：OpenAI-compatible chat completion 客户端。
• minimal_agent/parser.py：解析 LLM 输出为 thought、tool_call 或 final_answer，支持 fenced JSON。
• minimal_agent/tools.py：工具元数据、Schema 校验、注册与执行。
• minimal_agent/builtin_tools.py：内置 calculator、search、weather、todo 工具。
• minimal_agent/session.py：基于 user_id + session_id 的内存 session store。
• minimal_agent/context.py：prompt 构建和轻量 context folding。
• minimal_agent/storage.py：本地 JSON run recorder，用于记录最近原始运行结果。
• minimal_agent/trace.py：结构化 trace event 创建。

重复的相同工具调用会在执行前被拦截，避免重复副作用，例如同一个 todo 被添加两次。

Memory 与 Context

运行时 session 状态保存在内存中。每个活跃 session 独立保存：

• 最近对话消息
• 最近工具 observation
• session facts
• rolling summary
• todo list
• trace events

每次 LLM decision 前都会召回 context。prompt 的组装顺序是：

1. System instruction 与可用工具 Schema
2. session_facts
3. rolling_summary
4. 最近工具结果
5. 短期消息窗口

Memory 的放置方式：

• short_term_window：保存最近消息，用于支持即时追问。
• session_facts：保存稳定事实，例如最近查询的天气城市、todo 数量、最近工具名、最近工具结果。
• rolling_summary：当消息超过 max_history_messages 后，折叠较早消息。
• tool_results：保存最近工具 observation，让 LLM 可以基于已有结果回答，避免重复调用工具。

本地 JSON 记录与运行时 memory 分离。data/session_runs.json 只保存最近 run 的原始输出，方便检查真实 LLM 测试结果；Agent 不把它作为检索记忆或数据库使用。

运行方式

安装依赖：

pip install -e ".[dev]"

配置千问兼容 API：

set LLM_API_KEY=your-key
set LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
set LLM_MODEL=qwen-plus
set SESSION_RUNS_PATH=data/session_runs.json

启动 CLI：

python -m minimal_agent chat --user user_a --session window_1

CLI 内可用命令：

/switch user_a window_2
/sessions
/exit

活跃 session 状态在进程退出后会消失。最近 run 的原始输出默认仍会写入 data/session_runs.json。

真实 LLM Smoke Test

配置 LLM_API_KEY、LLM_BASE_URL、LLM_MODEL 后运行：

python scripts/run_real_llm_smoke.py

脚本会运行两个真实场景，并将原始结果写入 data/session_runs.json：

• user_a / window_1：查天气并记录 todo
• user_a / window_2：写周报并记录 todo

查看 JSON：

python -m json.tool data/session_runs.json

测试

pytest -v

当前验证结果：

29 passed