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. 克隆并进入项目目录。

1. 安装依赖项

• 使用紫外线（推荐）：

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服务器

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

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

1. 执行 (modules/action.py)

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

1. 记忆 (modules/memory.py)

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

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

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

1. 对话历史索引 (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/ 改变计划/感知行为

______________________________________________________________________