Mini Agent

基于 LangGraph 和 LangChain middleware 的通用 Agent 学习项目，在标准 ReAct agent loop 上叠加上下文工程、工具能力、长期记忆和中间件治理。

上图示意 Agent 在可视化环境中的执行过程（可配合 LangGraph API、CLI 等使用；当前仓库不附带独立 Web 前端）。

核心特性

最小可扩展的 Agent Loop - 基于 create_agent(...) 的统一基座
显式运行时上下文 - user_id / thread_id / user_role 隔离
统一记忆系统 - OpenViking session + OpenViking user memories
丰富的工具集 - 网页搜索、数学计算、文件管理、记忆召回、技能等
技能注册表 - 按需 load_skill 加载领域专用能力
澄清中断机制 - ask_clarification 工具 + middleware 中断式确认
子代理能力 - DeepAgents SubAgentMiddleware 提供 task 隔离
LangSmith 监控 - 运行时链路上报与可视化

架构图

flowchart TD
    userInput[UserInput] --> cli[CLIOrServiceRuntime]
    cli --> runtimeContext[MiniAgentContext]
    runtimeContext --> agentInvoke[MiniAgentRuntime.invoke]
    agentInvoke --> agentCore[create_agent]

    subgraph middlewareStack [Middleware Stack]
        contextMw[上下文工程中间件]
        fileSearchMw[文件搜索中间件]
        selectorMw[工具选择中间件]
        subagentMw[子代理中间件]
        summaryMw[摘要中间件]
        todoMw[待办中间件]
        retryMw[重试机制]
        limitMw[调用限制]
        safetyMw[循环检测]
        errorMw[错误处理]
        memoryMw[记忆中间件]
        clarificationMw[澄清中间件]
    end

    agentCore --> middlewareStack
    middlewareStack --> modelCall[模型调用]
    modelCall --> decision{需要工具?}
    decision -->|否| finalAnswer[最终回答]
    decision -->|是| toolExec[工具执行]

    toolExec --> normalTools[搜索/计算/文件/技能]
    toolExec --> taskTool[Task 子代理]
    toolExec --> clarificationTool[澄清提问]
    clarificationTool --> clarificationMw
    taskTool --> subagents[通用/研究子代理]
    subagents --> modelCall
    normalTools --> modelCall
    clarificationMw --> finalAnswer

    runtimeContext --> openViking[OpenVikingEmbedded]
    openViking --> ovSession[SessionHistory]
    openViking --> ovMemory[UserMemories]

    contextMw --> promptContext[动态系统提示]
    promptContext --> modelCall

项目结构

mini_agent/
├── backend/                    # 核心后端代码
│   ├── agent.py               # Agent 创建与配置
│   ├── runtime.py             # 运行时封装
│   ├── context.py             # 上下文管理
│   ├── config.py              # 配置加载
│   ├── openviking/            # OpenViking 适配层
│   │   ├── client.py          # per-user client 与运行时 ov.conf 生成
│   │   ├── session_store.py   # session 持久化与历史回灌
│   │   ├── memory_store.py    # 用户记忆概览读写与召回
│   │   └── retrieval.py       # prompt 分层召回组装
│   ├── middlewares/           # 中间件集合
│   │   ├── context_engineering_middleware.py
│   │   ├── clarification_middleware.py
│   │   └── ...
│   └── tools/                 # 工具集合
│       ├── web_search.py
│       ├── calculator.py
│       ├── file_manager.py
│       └── skills.py
├── skills/                     # 技能定义
│   └── data-query-interpretation/
├── scripts/                    # 启动脚本
├── data/                       # 数据目录
│   ├── openviking/           # OpenViking embedded workspace 与运行时配置
│   └── workspace/            # 用户工作区
├── config.yaml                 # 主配置
├── main.py                     # CLI 入口
└── pyproject.toml              # 依赖管理

快速开始

1. 环境准备

确保已安装 Python 3.13+ 和 uv。

2. 配置环境变量

复制示例文件并填写 API 密钥：

cp .env_example .env

编辑 .env：

KIMI_API_KEY=your_kimi_api_key_here
DOUBAO_EMBEDDING_API_KEY=your_doubao_embedding_key_here
TAVILY_API_KEY=your_tavily_api_key_here  # 可选，用于搜索
LANGCHAIN_API_KEY=your_langsmith_key_here  # 可选，用于监控

3. 安装依赖

uv sync

运行方式

CLI 交互模式

uv run python main.py

启动后输入 user_id，即可开始对话：

输入 new 开始新会话
输入 help 查看帮助
输入 exit 退出

启动 LangGraph API 服务

bash scripts/start_langgraph.sh
# 或
uv run langgraph dev --allow-blocking

服务默认运行在 http://127.0.0.1:2024。

启动记忆编辑 API

bash scripts/start_memory_api.sh

服务运行在 http://127.0.0.1:8001。

API 调用示例

通过 HTTP 直接调用 LangGraph API：

curl -X POST http://127.0.0.1:2024/runs/wait \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "mini_agent",
    "input": {
      "messages": [
        {"role": "user", "content": "你好"}
      ],
      "user_id": "demo-user",
      "thread_id": "demo-thread"
    }
  }'

注意：必须显式传入 user_id 和 thread_id，前者用于隔离 OpenViking 用户空间，后者用于绑定可恢复 session。

配置说明

config.yaml 支持以下配置：

配置项	说明
`models`	LLM 模型配置，支持多模型
`tools`	工具开关与参数（搜索、计算、文件、技能、记忆召回等）
`sandbox`	工作区目录配置
`skills`	技能目录配置
`openviking`	OpenViking embedded、session 与记忆配置
`middleware`	中间件开关与阈值
`langsmith`	链路追踪配置

技术栈

Agent 框架: LangGraph / LangChain
模型: Kimi (Moonshot AI)
搜索: Tavily / DuckDuckGo
子代理: DeepAgents
监控: LangSmith
后端: FastAPI + OpenViking embedded
包管理: uv

用户数据隔离

每个 user_id 拥有独立的数据空间：

长期记忆与会话: data/openviking/
- OpenViking session 目录维护历史会话与归档摘要
- OpenViking user namespace 维护用户画像与长期记忆
工作区: data/workspace/<user_id>/ - 文件操作沙箱

用户画像（OpenViking 单轨）：画像由 OpenViking 写入用户空间概览（如 .overview.md），经 build_user_memory_context 注入对话，不在应用层另建画像库。若需稳定栏目，可在该概览中采用 Markdown 小标题自行组织，例如：偏好、角色或职责、长期目标、常用任务类型；具体文风仍以系统提示中的使用规则为准。

开发状态

✅ runtime、middleware、长期记忆
✅ Clarification 澄清流程
✅ DeepAgents 子代理集成（general-purpose / skills-research）
✅ LangSmith 运行时监控

License

MIT

FilesExpand file tree

readme.md

Latest commit

History