AI导哈

混合规划决策代理

一个结合感知、规划、执行和持久记忆的推理驱动工具使用代理，支持多服务器工具调用和本地RAG检索。

  • by SHMISHRA666
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 shmishra666/agentic_ai_hybrid_planning_decision_making

使用说明

Agent混合规划与决策（Cortex-R）

推理驱动的、使用工具的代理，在多个MCP服务器上计划和执行操作。它结合了感知（意图/工具选择）、计划（单步或多步）、执行（工具调用+沙盒代码）和持久内存。包括您的本地RAG管道 documents/ 文件夹、网络搜索/获取工具和数学/实用工具。

特性

  • 混合规划模式：保守型（单函数调用）和探索型（并行或顺序回退）
  • 多MCP编排：每个任务从多个MCP服务器中发现和调用工具
  • 持久存储器：每个会话运行元数据、工具I/O和最终答案 memory/YYYY/MM/DD/
  • 本地RAG：FAISS指数建立于 documents/ 语义组块和图像字幕
  • Web工具：DuckDuckGo搜索和原始网页内容提取
  • 数学和实用程序：算术、三角函数、ASCII变换、斐波那契、缩略图等。

需求

  • Python>=3.11
  • 推荐： uv （快速Python包管理器）。退路： pip
  • 对于默认文本模型（Gemini）：设置 GEMINI_API_KEY 在环境或 .env
  • 对于RAG和中的一些图像操作 mcp_server_2.py （可选但推荐）：正在运行的Ollama服务器提供
    • 嵌入端点(/api/embeddings)对于模型 nomic-embed-text
    • 聊天/生成端点(/api/chat 或 /api/generate)对于服务器中引用的模型

Ollama设置示例（可选）：

ollama serve
ollama pull nomic-embed-text
ollama pull phi4
ollama pull gemma3:12b
ollama pull qwen2.5:32b-instruct-q4_0

快速启动

  1. 克隆并进入项目目录。

  2. 安装依赖项

  • 使用紫外线（推荐）：
uv sync
  • 使用pip（Windows PowerShell）：
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
  • 使用pip（macOS/Linux）：
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .
  1. 配置环境
  • 创建一个 .env 文件或导出 GEMINI_API_KEY 如果您使用Gemini进行计划/文本（默认）：
GEMINI_API_KEY=your_api_key_here
  1. 验证/调整配置路径
  • 打开 config/profiles.yaml 并更新每个 mcp_servers[*].cwd 如果需要，请访问您的本地repo路径。
  • 确保 strategy 和 llm 设置是您想要的（见下文）。
  1. 运行代理
python agent.py

您将看到： 🧑 What do you want to solve today? →.

  • 键入任务，然后按Enter键。
  • 类型 new 开始新的会议。
  • 类型 exit 退出。

配置

  • config/profiles.yaml

    • agent：名称/id/描述
    • strategy：规划模式和限制
      • planning_mode: conservative 或 exploratory
      • exploration_mode: parallel 或 sequential （仅适用于 exploratory)
      • max_steps, max_lifelines_per_step：控制重试
    • memory：存储选项；会话数据落在 memory/
    • llm.text_generation：选择 gemini （默认）或Ollama模型密钥（例如。， phi4, gemma3:12b, qwen2.5:32b-instruct-q4_0)
    • mcp_servers：MCP服务器列表 id, script, cwd，以及说明

  • config/models.json

    • 选择并配置文本生成和嵌入的支持模型
    • 对于 gemini：阅读 GEMINI_API_KEY 来自env
    • 对于 ollama 条目：URL指向 http://localhost:11434

运作原理

  1. 感知 (modules/perception.py)

    • 提取意图/实体，提示可能的工具，并选择相关的MCP服务器

  2. 规划 (modules/decision.py, core/strategy.py)

    • 构建异步 solve() 在下使用所选提示模板的函数 prompts/
    • 模式：保守（一次工具调用）、探索性并行、探索性顺序

  3. 执行 (modules/action.py)

    • 运行生成的 solve() 在受限的沙箱中，通过调度器调用工具
    • 将每个计划限制为5次工具调用

  4. 记忆 (modules/memory.py)

    • 在每个会话下持久运行元数据和工具I/O memory/YYYY/MM/DD/

  5. 通过MCP加工 (core/session.py)

    • 从配置的服务器中发现工具，并通过stdio路由工具调用

  6. 对话历史索引 (history_index/)

    • 从您过去的会话中构建一个轻量级的向量索引 memory/
    • 检索前N个相似的问答对，并在规划过程中将其作为少镜头上下文注入

构建索引：

uv run -m history_index.indexer

程序化使用：

from history_index.indexer import HistoryIndexer
HistoryIndexer().build()

from history_index.retriever import HistoryRetriever
retriever = HistoryRetriever()
shots = retriever.retrieve("Your new query", top_k=3)

可用MCP服务器（默认）

  • math → mcp_server_1.py

    • 算术： add, subtract, multiply, divide, power, remainder
    • 功能： cbrt, factorial, sin, cos, tan, fibonacci_numbers
    • 转换： strings_to_chars_to_int, int_list_to_exponential_sum
    • 图像： create_thumbnail

  • documents → mcp_server_2.py

    • 抹布： search_stored_documents 基于FAISS指数构建 documents/
    • 提取： convert_webpage_url_into_markdown, extract_pdf
    • 首次运行时，服务器会构建/更新 faiss_index/ 语义组块和图像字幕

  • websearch → mcp_server_3.py

    • 搜索： duckduckgo_search_results
    • 提取： download_raw_html_from_url

您可以独立运行服务器进行开发：

python mcp_server_1.py dev
python mcp_server_2.py dev
python mcp_server_3.py dev

当代理启动时，服务器会自动在stdio上运行，无需手动启动。

处理文档（RAG）

  1. 将文件放入 documents/ （PDF、DOCX、MD、HTML等）
  2. 启动代理；这 documents 服务器将在以下位置构建或更新FAISS索引 faiss_index/
  3. 提出以下问题：“在存储的文档中搜索DLF Capbridge付款”

要强制完全重建，请删除 faiss_index/ 然后重新运行。

查询示例

  • 数学链：“找到INDIA的ASCII值，并返回它们的指数之和。”
  • 网站摘要：“总结此页面：https://theschoolof.ai/”
  • 文件问答：“通过Capbridge支付的DLF公寓费用是多少？”
  • 公司关系：“Gensol和Go Auto之间的关系是什么？”

在运行过程中，代理返回以下任一结果：

  • FINAL_ANSWER: ... 完成后，或
  • FURTHER_PROCESSING_REQUIRED: ... 当上一步产生的内容应该被下一步总结/使用时

类型 new 开始新的会议；类型 exit 退出。

项目结构

agent.py                     # CLI entrypoint
config/                      # Agent profile, models
core/                        # Context, loop, strategy, MultiMCP session
modules/                     # Perception, planning, action, memory, modeling utils
mcp_server_1.py              # Math & utility tools
mcp_server_2.py              # RAG + webpage/PDF extraction
mcp_server_3.py              # Web search + raw content fetch
prompts/                     # Prompt templates for planning and perception
documents/                   # Your local corpus (indexed into faiss_index/)
faiss_index/                 # Auto-generated vector index + metadata
memory/                      # Persisted session traces
pyproject.toml               # Project metadata and dependencies
uv.lock                      # uv lockfile (optional)

提示和故障排除

  • 缺失 GEMINI_API_KEY：设置它 .env 或环境，或开关 llm.text_generation 到Ollama模型 config/profiles.yaml
  • RAG故障：确保Ollama正在运行，并且所需的模型已被拉取；删除 faiss_index/ 重建
  • Windows上的路径：更新 config/profiles.yaml cwd 进入您的本地路径
  • 沙盒限制：生成 solve() 使用有限的内置程序运行，最多可调用5个工具；如果违反了工具合同，它仍然可能失败

延伸

  • 添加工具：在现有工具中实现 mcp_server_*.py 随着 @mcp.tool()
  • 添加新服务器：创建 mcp_server_X.py 并将其注册在 config/profiles.yaml > mcp_servers
  • 修改提示：在中编辑文件 prompts/ 改变计划/感知行为

相关 MCP