# machine-core：支持 MCP 协议的灵活 AI Agent 框架

> machine-core 是一个用于构建 AI Agent 的灵活框架，支持 MCP（Model Context Protocol）集成、动态 OpenAPI 工具生成、基于向量的 RAG 工具过滤，以及多种 LLM 和 Embedding 提供商。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-09T19:50:33.000Z
- 最近活动: 2026-04-09T20:22:50.348Z
- 热度: 159.5
- 关键词: AI Agent, MCP, LLM, Embedding, RAG, OpenAPI, Python, 框架
- 页面链接: https://www.zingnex.cn/forum/thread/machine-core-mcp-ai-agent
- Canonical: https://www.zingnex.cn/forum/thread/machine-core-mcp-ai-agent
- Markdown 来源: ingested_event

---

# machine-core：支持 MCP 协议的灵活 AI Agent 框架

## 什么是 machine-core？

machine-core 是一个专为构建 AI Agent 设计的灵活框架。它的核心定位是提供一套清晰、可扩展的基础设施，让开发者能够快速搭建具备工具调用、知识检索、多模型支持能力的智能代理系统。

与传统的 Agent 框架不同，machine-core 强调**架构的清晰分离**：基础设施层（`AgentCore`）与执行模式层（`BaseAgent`）解耦，使得开发者可以根据具体场景选择合适的 Agent 类型，而不必被框架的预设结构所限制。

## 核心特性解析

### 1. 多提供商 LLM + Embedding 支持

machine-core 内置了对 7 个 LLM 提供商和 3 个 Embedding 提供商的支持：

**LLM 提供商**：
- Ollama（本地/云端，默认：`qwen3-vl:32b`）
- Azure（Azure OpenAI，默认：`gpt-4o-2`）
- Grok（x.ai，默认：`grok-2-latest`）
- Groq（Groq Cloud，默认：`llama-3.3-70b-versatile`）
- Google Gemini
- Vertex Gemini
- Vertex Claude

**Embedding 提供商**：
- Ollama（默认：`nomic-embed-text`）
- Azure（默认：`text-embedding-3-large`）
- Google Cloud

这种多提供商架构允许开发者通过环境变量或配置轻松切换模型，实现灵活的模型路由和降级策略。

### 2. MCP（Model Context Protocol）集成

MCP 是 Anthropic 提出的开放协议，旨在标准化 AI 模型与外部工具、数据源之间的交互方式。machine-core 原生支持 MCP：

- 从 JSON 配置加载和验证 MCP 工具集
- 动态工具发现和调用
- 与现有 Agent 工作流无缝集成

这意味着你可以将任何符合 MCP 规范的工具（如文件系统访问、数据库查询、API 调用等）快速接入你的 Agent。

### 3. 动态 OpenAPI 工具生成

这是一个非常实用的特性：machine-core 能够根据 OpenAPI 规范动态生成 pydantic-ai 工具。工作流程如下：

1. 获取 OpenAPI 规范（`fetch_openapi_spec`）
2. 使用 `ToolFilterManager` 索引和过滤工具
3. 根据任务相关性选择工具
4. 动态生成工具并重建 Agent（`rebuild_agent`）

这种设计使得 Agent 能够根据当前任务需求，动态调整可用工具集，避免一次性加载过多无关工具导致的上下文膨胀。

### 4. RAG 工具过滤

machine-core 内置了基于向量的工具过滤机制：

- `ToolFilterManager` 使用向量相似度对工具进行索引和过滤
- 根据任务描述自动选择最相关的工具
- 支持 `essential_tools` 强制包含特定工具

这种机制显著提高了 Agent 的工具选择效率，特别是在工具数量较多的场景下。

### 5. 文件处理能力

框架内置了多种文件处理功能：
- PDF 文本提取
- 图片 OCR
- VLM（视觉语言模型）预处理
- 批量上传处理

这些能力使得 Agent 能够处理多模态输入，扩展了应用场景。

### 6. 向量存储

基于 LanceDB 的向量存储实现：
- 跨表搜索
- `DocumentStore` 门面模式
- 与 Embedding 提供商集成

这为 RAG（检索增强生成）应用提供了坚实的基础设施。

## 内置 Agent 类型

machine-core 提供了 6 种开箱即用的 Agent 实现：

| Agent | 描述 | 适用场景 |
|-------|------|---------|
| `ChatAgent` | 流式聊天 | Streamlit UI、Web 聊天 |
| `CLIAgent` | 非流式 | 终端、定时任务 |
| `ReceiptProcessorAgent` | 视觉 + 队列 | 文档分析 |
| `TwitterBotAgent` | 定时发布 | 社交媒体自动化 |
| `RAGChatAgent` | 知识图谱 | Q&A、客户支持 |
| `MemoryMasterAgent` | 知识提取 | 图谱维护 |

## 快速开始

### 安装

```bash
# 作为依赖添加
uv add git+https://github.com/samletnorge/machine-core.git

# 本地开发
git clone https://github.com/samletnorge/machine-core.git
cd machine-core
uv sync
```

### MCP 工具集模式（推荐）

```python
from machine_core.core.agent_base import BaseAgent

class MyAgent(BaseAgent):
    def __init__(self):
        super().__init__(
            system_prompt="You are a helpful assistant.",
            mcp_config_path="mcp.json",
        )

    async def run(self, query: str):
        async for event in self.run_query_stream(query):
            yield event
```

### 动态工具模式（高级）

```python
from machine_core import (
    AgentCore, AgentConfig,
    generate_tools_from_openapi, fetch_openapi_spec,
    Embedder, VectorStore, ToolFilterManager,
)

# 创建核心
core = AgentCore(tools=[], system_prompt="...", agent_config=AgentConfig())

# 每次请求：RAG 过滤 + 重建
spec = await fetch_openapi_spec("https://api.example.com")
manager = ToolFilterManager(embedder=embedder, vector_store=vs)
await manager.index_openapi(spec)
result = await manager.filter("find all invoices", essential_tools={"search"})
tools = generate_tools_from_openapi(spec, base_url, tool_filter=result.names)
core.rebuild_agent(tools=tools)
```

## 配置说明

### 环境变量

```bash
# LLM 配置
LLM_PROVIDER=google           # ollama|azure|grok|groq|google|vertex-gemini|vertex-claude
LLM_MODEL=gemini-2.5-flash

# Embedding 配置
EMBEDDING_PROVIDER=google
EMBEDDING_MODEL=gemini-embedding-001

# Agent 行为
AGENT_MAX_ITERATIONS=10
AGENT_TIMEOUT=604800.0
```

### Azure 特定配置

```bash
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-08-01-preview
AZURE_OPENAI_DEPLOYMENT=gpt-4o-2
AZURE_USE_TOKEN_AUTH=true  # 使用 az login，或设为 false 使用 API key
```

## 服务化部署

machine-core 可以很容易地部署为服务：

```bash
# Docker
export GITHUB_TOKEN=your_token
docker-compose up -d

# 本地
uvicorn src.main:app --host 0.0.0.0 --port 8000
```

服务提供以下端点：
- `/`：前端界面
- `/docs`：Swagger API 文档
- `/health`：健康检查
- `/api/info`：API 信息
- `/metrics`：Prometheus 指标

## 架构优势

machine-core 的架构设计有几个显著优势：

1. **清晰的关注点分离**：基础设施与执行模式解耦
2. **灵活的提供商切换**：通过环境变量即可更换 LLM/Embedding 提供商
3. **动态工具管理**：避免静态工具列表的局限性
4. **类型安全**：基于 Pydantic 的配置和工具定义
5. **可观测性**：内置 Prometheus 指标和结构化日志

## 适用场景

- 需要快速原型验证的 AI 应用
- 需要多模型备份/路由的生产系统
- 工具数量较多且需要动态选择的复杂 Agent
- 需要 MCP 生态集成的项目
- 需要多模态处理能力的文档分析系统

## 结语

machine-core 代表了一种务实的 Agent 框架设计理念：不追求大而全，而是提供清晰、可组合的基础设施，让开发者能够根据实际需求灵活组装。对于正在评估 Agent 框架的团队来说，这是一个值得关注的选项，特别是当你需要 MCP 支持或多提供商灵活性时。