深入解析mcp-agent框架中的智能代理(Agent)系统

什么是智能代理？

在mcp-agent框架中，**智能代理(Agent)**是构建智能应用程序的核心接口。它结合了大型语言模型(LLM)与专用能力，使其能够使用工具、访问数据并与外部系统交互完成任务。

可以将代理视为一个智能助手，具备以下能力：

• 理解自然语言请求
• 决定使用哪些工具
• 执行复杂的多步骤工作流
• 维护对话历史和上下文
• 在需要时请求人工输入

核心概念：代理是一个配置好的LLM，通过工具、记忆系统增强，能够在环境中执行操作。

代理的核心组件

mcp-agent中的代理由多个关键组件协同工作：

1. 代理核心：管理工作流并协调交互
2. LLM集成：连接各种语言模型提供商
3. 工具访问：通过MCP服务器为LLM提供能力
4. 记忆系统：维护对话历史和上下文
5. 人工输入：支持需要用户输入的交互式工作流

这些组件的工作流程可以表示为：

用户请求 → 代理核心 → LLM提供者 → 判断是否需要工具 → 是则调用工具 → 工具响应 → 返回LLM
                                 → 否则直接生成响应 → 存储记忆 → 返回用户响应

创建第一个代理

创建代理最简单的方式是通过Agent类。以下是一个基础示例：

from mcp_agent.agents.agent import Agent
from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM

# 创建具有特定工具访问权限的代理
finder_agent = Agent(
    name="finder",
    instruction="""你是一个可以访问文件系统和网络获取能力的代理。
    你的工作是根据用户请求查找和检索信息。""",
    server_names=["fetch", "filesystem"],
)

# 在异步上下文中使用代理
async with finder_agent:
    # 为代理附加LLM
    llm = await finder_agent.attach_llm(OpenAIAugmentedLLM)

    # 生成响应
    result = await llm.generate_str(
        message="查找并显示README文件的内容"
    )
    print(result)

代理配置方法

代理可以通过编程方式或配置文件进行配置：

配置文件方式

创建mcp_agent.config.yaml文件定义代理环境：

# mcp_agent.config.yaml
$schema: ../../schema/mcp-agent.config.schema.json

execution_engine: asyncio

# 日志配置
logger:
  transports: [console, file]
  level: debug
  progress_display: true

# 定义可用的MCP服务器(工具)
mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem"]

# LLM提供商配置
openai:
  default_model: "gpt-4o-mini"

编程配置方式

直接在代码中配置代理：

from mcp_agent.config import Settings, MCPSettings, MCPServerSettings

settings = Settings(
    execution_engine="asyncio",
    mcp=MCPSettings(
        servers={
            "fetch": MCPServerSettings(
                command="uvx",
                args=["mcp-server-fetch"],
            ),
            "filesystem": MCPServerSettings(
                command="npx",
                args=["-y", "@modelcontextprotocol/server-filesystem"],
            ),
        }
    ),
    openai=OpenAISettings(
        default_model="gpt-4o-mini",
    ),
)

代理的核心能力

mcp-agent中的代理具备多项强大内置能力：

多LLM提供商支持

无缝切换不同LLM提供商：

from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
from mcp_agent.workflows.llm.augmented_llm_anthropic import AnthropicAugmentedLLM

async with agent:
    # 使用OpenAI开始
    llm = await agent.attach_llm(OpenAIAugmentedLLM)
    result1 = await llm.generate_str("分析这些数据...")

    # 为下一个任务切换到Anthropic
    llm = await agent.attach_llm(AnthropicAugmentedLLM)
    result2 = await llm.generate_str("总结分析结果...")

高级模型选择

通过偏好控制模型选择：

from mcp_agent.workflows.llm.augmented_llm import RequestParams
from mcp_agent.workflows.llm.llm_selector import ModelPreferences

result = await llm.generate_str(
    message="复杂推理任务",
    request_params=RequestParams(
        modelPreferences=ModelPreferences(
            costPriority=0.1,        # 低成本优先级
            speedPriority=0.2,       # 低速度优先级
            intelligencePriority=0.7  # 高智能优先级
        ),
        temperature=0.3,
        maxTokens=1000,
    )
)

人工输入集成

代理可以在执行过程中请求人工输入：

# 代理可以在需要时自动请求人工输入
# 这通过human_input_callback机制处理
# 并作为LLM可以调用的工具出现
from mcp_agent.human_input.handler import console_input_callback

app = MCPApp(name="my_application", human_input_callback=console_input_callback)

# ...其余代码

result = await llm.generate_str(
    "请审查此分析并询问你需要澄清的任何问题。"
)

记忆与上下文管理

代理自动维护对话历史：

# 多轮对话保持上下文
result1 = await llm.generate_str("天气怎么样？")
result2 = await llm.generate_str("明天呢？")  # 记住上下文

代理生命周期管理

代理遵循可预测的生命周期：

1. 初始化：加载配置、连接MCP服务器、发现可用工具
2. 使用：处理请求、协调工具调用、维护历史、处理错误
3. 清理：关闭连接、释放资源、保存持久状态

# 显式生命周期管理
agent = Agent(name="my_agent", server_names=["fetch"])

# 初始化
await agent.initialize()

# 使用
llm = await agent.attach_llm(OpenAIAugmentedLLM)
result = await llm.generate_str("你好！")

# 清理
await agent.shutdown()

# 或使用上下文管理器(推荐)
async with Agent(name="my_agent", server_names=["fetch"]) as agent:
    llm = await agent.attach_llm(OpenAIAugmentedLLM)
    result = await llm.generate_str("你好！")
    # 退出上下文时自动清理

常见使用模式

应用集成

使用MCPApp类进行完整应用设置：

from mcp_agent.app import MCPApp

app = MCPApp(name="my_application")

async def main():
    async with app.run() as agent_app:
        logger = agent_app.logger
        context = agent_app.context

        # 在应用上下文中创建和使用代理
        agent = Agent(
            name="assistant",
            instruction="你是一个有帮助的助手。",
            server_names=["filesystem", "fetch"]
        )

        async with agent:
            llm = await agent.attach_llm(OpenAIAugmentedLLM)
            result = await llm.generate_str("帮我整理文件")
            logger.info("任务完成", data={"result": result})

工具发现

探索代理可用的工具：

async with agent:
    # 列出所有可用工具
    tools = await agent.list_tools()
    print(f"可用工具: {[tool.name for tool in tools.tools]}")

    # 获取详细工具信息
    for tool in tools.tools:
        print(f"工具: {tool.name}")
        print(f"描述: {tool.description}")
        print(f"输入模式: {tool.inputSchema}")

通过以上内容，开发者可以全面理解mcp-agent框架中智能代理的概念、配置和使用方法，从而构建强大的智能应用程序。