feat: 支持 MCP

Author: wangtao2001

docs/tutorials/agent/agent.md

@@ -38,12 +38,12 @@ controller = Controller(max_turns=10)
 ## 启动智能体
 
 ```python
-_, resp = controller.run(agent=translator, message="请帮我翻译蛋白质。")
+_, resp = controller.run_sync(agent=translator, message="请帮我翻译蛋白质。")
 ```
 
 其中 `message` 参数代表用户的具体指令或者是用户与智能体对话的开始。
 
-`controller.run` 方法返回两个值, 其中第一个值代表最后响应的 `Agent` 对象 (暂时还用不到), 第二个值代表智能体最后的相应内容。在这个例子中, `resp` 的值应该是智能体翻译的结果 (不排除其中包含一些提示语)。
+`controller.run_sync` 方法返回两个值, 其中第一个值代表最后响应的 `Agent` 对象 (暂时还用不到), 第二个值代表智能体最后的相应内容。在这个例子中, `resp` 的值应该是智能体翻译的结果 (不排除其中包含一些提示语)。
 
 ## 使用外部工具
 
@@ -253,22 +253,111 @@ from course_graph.agent import Result
 result = Result(context_variables={'current_time': '2024/09/02'})
 ```
 
+## MCP 支持
+
+> [!NOTE]
+> 目前 MCP 协议是通过 function call 功能实现的。
+
+### 获取一个 MCP Server
+
+你可以通过 [Model Context Protocol servers](https://github.com/modelcontextprotocol/servers) 等项目获取到大量的 MCP Server 资源。
+
+这里我们使用 Python SDK 实现一个简单的 MCP Server:
+
+```python
+from mcp.server.fastmcp import FastMCP
+import json
+
+mcp = FastMCP('weather')
+
+@mcp.tool()
+def get_weather(city: str) -> str:
+    """ 获取指定城市当天的天气
+    
+    Args:
+        city: 城市名称
+
+    Returns:
+        dict: 天气信息
+    """
+    resp = {
+        'city': city,
+        'temperature_high': 20,
+        'temperature_low': 18,
+        'temperature_unit': 'C',
+        'weather': 'sunny'
+    }
+    return json.dumps(resp, ensure_ascii=False)
+
+if __name__ == '__main__':
+    mcp.run(transport='stdio')
+```
+
+项目创建以及环境配置可以参考 [官方文档](https://modelcontextprotocol.io/quickstart/server)。 该 Server 可以通过以下命令启动:
+
+```bash
+uv --directory examples/agent run mcp_server.py
+```
+
+### 为智能体添加 MCP Server 并启动
+
+```python
+from course_graph.agent import Agent, Controller, MCPServer
+from course_graph.llm import Qwen
+import asyncio
+
+qwen = Qwen()
+
+async def main():
+    async with MCPServer(
+        type='stdio',
+        command='uv',
+        args=['--directory', 'examples/agent', 'run', 'mcp_server.py'],
+    ) as mcp_server:
+
+        agent = Agent(
+            llm=qwen,
+            mcp_server=[mcp_server]
+        )
+        await agent.initialize()
+        controller = Controller()
+        _, resp = await controller.run(agent, "帮我查询南京今天的天气")
+        print(resp)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+这里有三需要注意:
+
+- MCP Server 必须使用 `async with` 语句块来启动。
+
+- 如果给 `Agent` 传递了 `mcp_server` 参数, 必须调用 `await agent.initialize()` 方法等待初始化完成。
+
+- `Controller` 必须使用异步的 `run` 方法来启动。不能使用同步的 `run_sync` 方法, 因为本质上 `run_sync` 只是 `asyncio.run(controller.run(...))` 的包装。
+
+### MCP Server 与外部工具的比较
+
+这里 MCP 协议虽然是通过 function call 功能实现的, 但是缺失了自动注入上下文变量和当前 Agent 的功能。并且本地外部工具的优先级更高，如果遇到同名的工具函数，会优先调用本地函数。
+
 ## Trace
 
 Trace 功能, 可以记录智能体的对话、工具调用、上下文变量变化等历史。 `Controller` 的 `trace_callback` 参数可以传递一个回调函数, 当 trace 事件发生时, 会调用该回调函数。
 
 ```python
+from pprint import pprint
+
 controller = Controller(trace_callback=pprint)
 ```
 
-该回调函数需要接受一个 `TraceEvent` 类型的参数, 具体来说包含以下几种类型:
+该回调函数需要接受一个 `TraceEvent` 类型的参数, 其中事件类型包括:
 
-- `TraceEventUserMessage`:   用户消息
-- `TraceEventAgentMessage`:  智能体消息
-- `TraceEventAgentSwitch`: 智能体切换
-- `TraceEventToolCall`: 工具调用
-- `TraceEventToolResult`: 工具调用结果
-- `TraceEventContextUpdate`: 上下文变量更新
+- `USER_MESSAGE`:   用户消息
+- `AGENT_MESSAGE`:  智能体消息
+- `AGENT_SWITCH`: 智能体切换
+- `TOOL_CALL`: 工具调用
+- `TOOL_RESULT`: 工具调用结果
+- `CONTEXT_UPDATE`: 上下文变量更新
 
 ## 多智能体编排
 

examples/agent/agents.py

@@ -84,7 +84,7 @@ def transfer_to_alarm_clock_agent():
 
 if __name__ == '__main__':
     controller = Controller()
-    _, resp = controller.run(
+    _, resp = controller.run_sync(
         agent=core_agent,
         message='帮我查询一下我这里的天气, 并查询一下我的日程信息。如果日程中有考试的话, 请帮我定一个闹钟, 时间是考试开始前的一个小时。')
     pprint(resp)

examples/agent/mcp_server.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+# Create Date: 2025/03/29
+# Author: wangtao <wangtao.cpu@gmail.com>
+# File Name: examples/agent/mcp_server.py
+# Description: 一个简单的 MCP Server 示例
+
+from mcp.server.fastmcp import FastMCP
+import json
+
+mcp = FastMCP('weather')
+
+
+@mcp.tool()
+def get_weather(city: str) -> str:
+    """ 获取指定城市当天的天气
+    
+    Args:
+        city: 城市名称
+
+    Returns:
+        dict: 天气信息
+    """
+    resp = {
+        'city': city,
+        'temperature_high': 20,
+        'temperature_low': 18,
+        'temperature_unit': 'C',
+        'weather': 'sunny'
+    }
+    return json.dumps(resp, ensure_ascii=False)
+
+
+if __name__ == '__main__':
+    mcp.run(transport='stdio')

examples/agent/use_mcp.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+# Create Date: 2025/03/29
+# Author: wangtao <wangtao.cpu@gmail.com>
+# File Name: examples/agent/use_mcp.py
+# Description: 使用 MCP 工具
+
+from course_graph.agent import Agent, Controller, MCPServer, TraceEvent
+from course_graph.llm import Qwen
+import asyncio
+qwen = Qwen()
+
+
+async def main():
+    async with MCPServer(
+        type='stdio',
+        command='uv',
+        args=['--directory', 'examples/agent', 'run', 'mcp_server.py'],
+    ) as mcp_server:
+
+        agent = Agent(
+            llm=qwen,
+            mcp_server=[mcp_server]
+        )
+        await agent.initialize()
+        controller = Controller()
+        _, resp = await controller.run(agent, "帮我查询今天南京的天气")
+        print(resp)
+
+if __name__ == '__main__':
+    asyncio.run(main())

examples/agent/workflow.py

@@ -46,14 +46,14 @@ def get_english_news_editor_instruction(context_variables: ContextVariables):
 
 
 def chinese_news_write(controller: Controller) -> str:
-    _, trans = controller.run(agent=translator)
+    _, trans = controller.run_sync(agent=translator)
     controller.context_variables['trans'] = trans
-    _, res = controller.run(agent=chinese_news_editor)
+    _, res = controller.run_sync(agent=chinese_news_editor)
     return res
 
 
 def english_news_write(controller: Controller) -> str:
-    _, res = controller.run(agent=english_news_editor)
+    _, res = controller.run_sync(agent=english_news_editor)
     return res
 
 

src/course_graph/agent/agent.py

@@ -10,7 +10,7 @@
 from openai.types.chat import *
 import inspect
 import docstring_parser
-from typing import Callable
+from typing import Callable, Awaitable
 from typing import Literal
 from openai import NOT_GIVEN, NotGiven
 from .mcp import MCPServer
@@ -23,7 +23,7 @@ def __init__(
             self,
             llm: LLMBase,
             name: str = 'Assistant',
-            functions: list[Callable] = None,
+            functions: list[Callable | Awaitable] = None,
             tool_choice: str | NotGiven | Literal['required', 'auto', 'none'] = NOT_GIVEN,
             parallel_tool_calls: bool | NotGiven = NOT_GIVEN,
             instruction: str | Callable[[ContextVariables], str] | Callable[[], str] = 'You are a helpful assistant.',
@@ -35,7 +35,7 @@ def __init__(
         Args: 
             llm (LLMBase): 大模型 
             name (str, optional): 名称. Defaults to 'Assistant'.
-            functions: (list[Callable], optional): 工具函数. Defaults to None.
+            functions: (list[Callable | Awaitable], optional): 工具函数. Defaults to None.
             parallel_tool_calls: (bool, optional): 允许工具并行调用. Defaults to False.
             tool_choice: (Literal['required', 'auto', 'none'] | NotGiven, optional). 强制使用工具函数, 选择模式或提供函数名称. Defaults to NOT_GIVEN.
             instruction (str | Callable[[ContextVariables], str] | Callable[[], str], optional): 指令. Defaults to 'You are a helpful assistant.'.
@@ -48,7 +48,7 @@ def __init__(
 
         self.tools: list[ChatCompletionToolParam] = []  # for LLM
 
-        self.tool_functions: dict[str, Callable] = {}  # for local function call
+        self.tool_functions: dict[str, Callable | Awaitable] = {}  # for local function call
         self.mcp_functions: dict[str, MCPServer] = {}  # for remote function call
 
         self.parallel_tool_calls = parallel_tool_calls
@@ -150,10 +150,10 @@ def add_tool_call_message(self, tool_content: str, tool_call_id: str) -> None:
         }
         self.messages.append(message)
 
-    def tool(self) -> Callable:
+    def tool(self) -> Callable | Awaitable:
         """ 标记一个外部工具函数
         """
-        def wrapper(function: Callable) -> Callable:
+        def wrapper(function: Callable | Awaitable) -> Callable | Awaitable:
             self.add_tool_functions(function)
             return function
         return wrapper
@@ -180,7 +180,7 @@ def add_tools(self, *tools: 'Tool') -> 'Agent':
                 self.use_agent_variables[function_name] = r
         return self
 
-    def add_tool_functions(self, *functions: Callable) -> 'Agent':
+    def add_tool_functions(self, *functions: Callable | Awaitable) -> 'Agent':
         """ 添加外部工具函数，并从自动解析函数描述、参数类型、以及参数描述等信息 \n
         若使用了不支持的文档风格或使用复杂参数，请调用 add_tools 方法手动编写函数描述