A programming framework for agentic AI
Introduce workbench (#6340)
Eric Zhu8fcba01704f2
diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/llamaindex-agent.ipynb b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/llamaindex-agent.ipynbindex 08a322403..03894e686 100644--- a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/llamaindex-agent.ipynb+++ b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/llamaindex-agent.ipynb@@ -38,7 +38,6 @@"outputs": [],"source": ["import os\n",- "from pydantic import BaseModel\n","from typing import List, Optional\n","\n","from autogen_core import AgentId, MessageContext, RoutedAgent, SingleThreadedAgentRuntime, message_handler\n",@@ -57,7 +56,8 @@"from llama_index.embeddings.openai import OpenAIEmbedding\n","from llama_index.llms.azure_openai import AzureOpenAI\n","from llama_index.llms.openai import OpenAI\n",- "from llama_index.tools.wikipedia import WikipediaToolSpec"+ "from llama_index.tools.wikipedia import WikipediaToolSpec\n",+ "from pydantic import BaseModel"]},{diff --git a/python/packages/autogen-core/src/autogen_core/_component_config.py b/python/packages/autogen-core/src/autogen_core/_component_config.pyindex ce768ddaf..bb603a839 100644--- a/python/packages/autogen-core/src/autogen_core/_component_config.py+++ b/python/packages/autogen-core/src/autogen_core/_component_config.py@@ -7,7 +7,7 @@ from typing import Any, ClassVar, Dict, Generic, Literal, Type, TypeGuard, cast,from pydantic import BaseModelfrom typing_extensions import Self, TypeVar-ComponentType = Literal["model", "agent", "tool", "termination", "token_provider"] | str+ComponentType = Literal["model", "agent", "tool", "termination", "token_provider", "workbench"] | strConfigT = TypeVar("ConfigT", bound=BaseModel)FromConfigT = TypeVar("FromConfigT", bound=BaseModel, contravariant=True)ToConfigT = TypeVar("ToConfigT", bound=BaseModel, covariant=True)diff --git a/python/packages/autogen-core/src/autogen_core/tools/__init__.py b/python/packages/autogen-core/src/autogen_core/tools/__init__.pyindex 52a9d725f..4f48463a0 100644--- a/python/packages/autogen-core/src/autogen_core/tools/__init__.py+++ b/python/packages/autogen-core/src/autogen_core/tools/__init__.py@@ -1,5 +1,7 @@from ._base import BaseTool, BaseToolWithState, ParametersSchema, Tool, ToolSchemafrom ._function_tool import FunctionTool+from ._static_workbench import StaticWorkbench+from ._workbench import ImageResultContent, TextResultContent, ToolResult, Workbench__all__ = ["Tool",@@ -8,4 +10,9 @@ __all__ = ["BaseTool","BaseToolWithState","FunctionTool",+ "Workbench",+ "ToolResult",+ "TextResultContent",+ "ImageResultContent",+ "StaticWorkbench",]diff --git a/python/packages/autogen-core/src/autogen_core/tools/_function_tool.py b/python/packages/autogen-core/src/autogen_core/tools/_function_tool.pyindex 048b26525..985d7d1d1 100644--- a/python/packages/autogen-core/src/autogen_core/tools/_function_tool.py+++ b/python/packages/autogen-core/src/autogen_core/tools/_function_tool.py@@ -178,4 +178,4 @@ class FunctionTool(BaseTool[BaseModel, BaseModel], Component[FunctionToolConfig]if not callable(func):raise TypeError(f"Expected function but got {type(func)}")- return cls(func, "", None)+ return cls(func, name=config.name, description=config.description, global_imports=config.global_imports)diff --git a/python/packages/autogen-core/src/autogen_core/tools/_static_workbench.py b/python/packages/autogen-core/src/autogen_core/tools/_static_workbench.pynew file mode 100644index 000000000..5a997defa--- /dev/null+++ b/python/packages/autogen-core/src/autogen_core/tools/_static_workbench.py@@ -0,0 +1,88 @@+import asyncio+from typing import Any, Dict, List, Literal, Mapping++from pydantic import BaseModel+from typing_extensions import Self++from .._cancellation_token import CancellationToken+from .._component_config import Component, ComponentModel+from ._base import BaseTool, ToolSchema+from ._workbench import TextResultContent, ToolResult, Workbench+++class StaticWorkbenchConfig(BaseModel):+ tools: List[ComponentModel] = []+++class StateicWorkbenchState(BaseModel):+ type: Literal["StaticWorkbenchState"] = "StaticWorkbenchState"+ tools: Dict[str, Mapping[str, Any]] = {}+++class StaticWorkbench(Workbench, Component[StaticWorkbenchConfig]):+ """+ A workbench that provides a static set of tools that do not change after+ each tool execution.++ Args:+ tools (List[BaseTool[Any, Any]]): A list of tools to be included in the workbench.+ The tools should be subclasses of :class:`~autogen_core.tools.BaseTool`.+ """++ component_provider_override = "autogen_core.tools.StaticWorkbench"+ component_config_schema = StaticWorkbenchConfig++ def __init__(self, tools: List[BaseTool[Any, Any]]) -> None:+ self._tools = tools++ async def list_tools(self) -> List[ToolSchema]:+ return [tool.schema for tool in self._tools]++ async def call_tool(+ self, name: str, arguments: Mapping[str, Any] | None = None, cancellation_token: CancellationToken | None = None+ ) -> ToolResult:+ tool = next((tool for tool in self._tools if tool.name == name), None)+ if tool is None:+ raise ValueError(f"Tool {name} not found in workbench.")+ if not cancellation_token:+ cancellation_token = CancellationToken()+ if not arguments:+ arguments = {}+ try:+ result_future = asyncio.ensure_future(tool.run_json(arguments, cancellation_token))+ cancellation_token.link_future(result_future)+ result = await result_future+ is_error = False+ except Exception as e:+ result = str(e)+ is_error = True+ result_str = tool.return_value_as_string(result)+ return ToolResult(name=tool.name, result=[TextResultContent(content=result_str)], is_error=is_error)++ async def start(self) -> None:+ return None++ async def stop(self) -> None:+ return None++ async def reset(self) -> None:+ return None++ async def save_state(self) -> Mapping[str, Any]:+ tool_states = StateicWorkbenchState()+ for tool in self._tools:+ tool_states.tools[tool.name] = await tool.save_state_json()+ return tool_states.model_dump()++ async def load_state(self, state: Mapping[str, Any]) -> None:+ parsed_state = StateicWorkbenchState.model_validate(state)+ for tool in self._tools:+ if tool.name in parsed_state.tools:+ await tool.load_state_json(parsed_state.tools[tool.name])++ def _to_config(self) -> StaticWorkbenchConfig:+ return StaticWorkbenchConfig(tools=[tool.dump_component() for tool in self._tools])++ @classmethod+ def _from_config(cls, config: StaticWorkbenchConfig) -> Self:+ return cls(tools=[BaseTool.load_component(tool) for tool in config.tools])diff --git a/python/packages/autogen-core/src/autogen_core/tools/_workbench.py b/python/packages/autogen-core/src/autogen_core/tools/_workbench.pynew file mode 100644index 000000000..23f1b4769--- /dev/null+++ b/python/packages/autogen-core/src/autogen_core/tools/_workbench.py@@ -0,0 +1,164 @@+from abc import ABC, abstractmethod+from types import TracebackType+from typing import Any, List, Literal, Mapping, Optional, Type++from pydantic import BaseModel, Field+from typing_extensions import Annotated, Self++from .._cancellation_token import CancellationToken+from .._component_config import ComponentBase+from .._image import Image+from ._base import ToolSchema+++class TextResultContent(BaseModel):+ """+ Text result content of a tool execution.+ """++ type: Literal["TextResultContent"] = "TextResultContent"++ content: str+ """The text content of the result."""+++class ImageResultContent(BaseModel):+ """+ Image result content of a tool execution.+ """++ type: Literal["ImageResultContent"] = "ImageResultContent"++ content: Image+ """The image content of the result."""+++ResultContent = Annotated[TextResultContent | ImageResultContent, Field(discriminator="type")]+++class ToolResult(BaseModel):+ """+ A result of a tool execution by a workbench.+ """++ type: Literal["ToolResult"] = "ToolResult"++ name: str+ """The name of the tool that was executed."""++ result: List[ResultContent]+ """The result of the tool execution."""++ is_error: bool = False+ """Whether the tool execution resulted in an error."""+++class Workbench(ABC, ComponentBase[BaseModel]):+ """+ A workbench is a component that provides a set of tools that may share+ resources and state.++ A workbench is responsible for managing the lifecycle of the tools and+ providing a single interface to call them. The tools provided by the workbench+ may be dynamic and their availabilities may change after each tool execution.++ A workbench can be started by calling the :meth:`~autogen_core.tools.Workbench.start` method+ and stopped by calling the :meth:`~autogen_core.tools.Workbench.stop` method.+ It can also be used as an asynchronous context manager, which will automatically+ start and stop the workbench when entering and exiting the context.+ """++ component_type = "workbench"++ @abstractmethod+ async def list_tools(self) -> List[ToolSchema]:+ """+ List the currently available tools in the workbench as :class:`ToolSchema`+ objects.++ The list of tools may be dynamic, and their content may change after+ tool execution.+ """+ ...++ @abstractmethod+ async def call_tool(+ self, name: str, arguments: Mapping[str, Any] | None = None, cancellation_token: CancellationToken | None = None+ ) -> ToolResult:+ """+ Call a tool in the workbench.++ Args:+ name (str): The name of the tool to call.+ arguments (Mapping[str, Any] | None): The arguments to pass to the tool.+ If None, the tool will be called with no arguments.+ cancellation_token (CancellationToken | None): An optional cancellation token+ to cancel the tool execution.+ Returns:+ ToolResult: The result of the tool execution.+ """+ ...++ @abstractmethod+ async def start(self) -> None:+ """+ Start the workbench and initialize any resources.++ This method should be called before using the workbench.+ """+ ...++ @abstractmethod+ async def stop(self) -> None:+ """+ Stop the workbench and release any resources.++ This method should be called when the workbench is no longer needed.+ """+ ...++ @abstractmethod+ async def reset(self) -> None:+ """+ Reset the workbench to its initialized, started state.+ """+ ...++ @abstractmethod+ async def save_state(self) -> Mapping[str, Any]:+ """+ Save the state of the workbench.++ This method should be called to persist the state of the workbench.+ """+ ...++ @abstractmethod+ async def load_state(self, state: Mapping[str, Any]) -> None:+ """+ Load the state of the workbench.++ Args:+ state (Mapping[str, Any]): The state to load into the workbench.+ """+ ...++ async def __aenter__(self) -> Self:+ """+ Enter the workbench context manager.++ This method is called when the workbench is used in a `with` statement.+ It calls the :meth:`~autogen_core.tools.WorkBench.start` method to start the workbench.+ """+ await self.start()+ return self++ async def __aexit__(+ self, exc_type: Optional[Type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]+ ) -> None:+ """+ Exit the workbench context manager.+ This method is called when the workbench is used in a `with` statement.+ It calls the :meth:`~autogen_core.tools.WorkBench.stop` method to stop the workbench.+ """+ await self.stop()diff --git a/python/packages/autogen-core/tests/test_workbench.py b/python/packages/autogen-core/tests/test_workbench.pynew file mode 100644index 000000000..0de372c45--- /dev/null+++ b/python/packages/autogen-core/tests/test_workbench.py@@ -0,0 +1,119 @@+from typing import Annotated++import pytest+from autogen_core.code_executor import ImportFromModule+from autogen_core.tools import FunctionTool, StaticWorkbench, Workbench+++async def test_static_workbench() -> None:+ def test_tool_func_1(x: Annotated[int, "The number to double."]) -> int:+ return x * 2++ def test_tool_func_2(x: Annotated[int, "The number to add 2."]) -> int:+ raise ValueError("This is a test error") # Simulate an error++ test_tool_1 = FunctionTool(+ test_tool_func_1,+ name="test_tool_1",+ description="A test tool that doubles a number.",+ global_imports=[ImportFromModule(module="typing_extensions", imports=["Annotated"])],+ )+ test_tool_2 = FunctionTool(+ test_tool_func_2,+ name="test_tool_2",+ description="A test tool that adds 2 to a number.",+ global_imports=[ImportFromModule(module="typing_extensions", imports=["Annotated"])],+ )++ # Create a StaticWorkbench instance with the test tools.+ async with StaticWorkbench(tools=[test_tool_1, test_tool_2]) as workbench:+ # List tools+ tools = await workbench.list_tools()+ assert len(tools) == 2+ assert "description" in tools[0]+ assert "parameters" in tools[0]+ assert tools[0]["name"] == "test_tool_1"+ assert tools[0]["description"] == "A test tool that doubles a number."+ assert tools[0]["parameters"] == {+ "type": "object",+ "properties": {"x": {"type": "integer", "title": "X", "description": "The number to double."}},+ "required": ["x"],+ "additionalProperties": False,+ }+ assert "description" in tools[1]+ assert "parameters" in tools[1]+ assert tools[1]["name"] == "test_tool_2"+ assert tools[1]["description"] == "A test tool that adds 2 to a number."+ assert tools[1]["parameters"] == {+ "type": "object",+ "properties": {"x": {"type": "integer", "title": "X", "description": "The number to add 2."}},+ "required": ["x"],+ "additionalProperties": False,+ }++ # Call tools+ result_1 = await workbench.call_tool("test_tool_1", {"x": 5})+ assert result_1.name == "test_tool_1"+ assert result_1.result[0].type == "TextResultContent"+ assert result_1.result[0].content == "10"+ assert result_1.is_error is False++ # Call tool with error+ result_2 = await workbench.call_tool("test_tool_2", {"x": 5})+ assert result_2.name == "test_tool_2"+ assert result_2.result[0].type == "TextResultContent"+ assert result_2.result[0].content == "This is a test error"+ assert result_2.is_error is True++ # Save state.+ state = await workbench.save_state()+ assert state["type"] == "StaticWorkbenchState"+ assert "tools" in state+ assert len(state["tools"]) == 2++ # Dump config.+ config = workbench.dump_component()++ # Load the workbench from the config.+ async with Workbench.load_component(config) as new_workbench:+ # Load state.+ await new_workbench.load_state(state)++ # Verify that the tools are still available after loading the state.+ tools = await new_workbench.list_tools()+ assert len(tools) == 2+ assert "description" in tools[0]+ assert "parameters" in tools[0]+ assert tools[0]["name"] == "test_tool_1"+ assert tools[0]["description"] == "A test tool that doubles a number."+ assert tools[0]["parameters"] == {+ "type": "object",+ "properties": {"x": {"type": "integer", "title": "X", "description": "The number to double."}},+ "required": ["x"],+ "additionalProperties": False,+ }+ assert "description" in tools[1]+ assert "parameters" in tools[1]+ assert tools[1]["name"] == "test_tool_2"+ assert tools[1]["description"] == "A test tool that adds 2 to a number."+ assert tools[1]["parameters"] == {+ "type": "object",+ "properties": {"x": {"type": "integer", "title": "X", "description": "The number to add 2."}},+ "required": ["x"],+ "additionalProperties": False,+ }++ # Call tools+ result_1 = await new_workbench.call_tool("test_tool_1", {"x": 5})+ assert result_1.name == "test_tool_1"+ assert result_1.result[0].type == "TextResultContent"+ assert result_1.result[0].content == "10"+ assert result_1.is_error is False++ # Call tool with error+ result_2 = await new_workbench.call_tool("test_tool_2", {"x": 5})+ assert result_2.name == "test_tool_2"+ assert result_2.result[0].type == "TextResultContent"+ assert result_2.result[0].content == "This is a test error"+ assert result_2.is_error is Truediff --git a/python/packages/autogen-ext/src/autogen_ext/tools/mcp/__init__.py b/python/packages/autogen-ext/src/autogen_ext/tools/mcp/__init__.pyindex eeae32f1c..bde36794c 100644--- a/python/packages/autogen-ext/src/autogen_ext/tools/mcp/__init__.py+++ b/python/packages/autogen-ext/src/autogen_ext/tools/mcp/__init__.py@@ -1,15 +1,19 @@+from ._actor import McpSessionActorfrom ._config import McpServerParams, SseServerParams, StdioServerParamsfrom ._factory import mcp_server_toolsfrom ._session import create_mcp_server_sessionfrom ._sse import SseMcpToolAdapterfrom ._stdio import StdioMcpToolAdapter+from ._workbench import McpWorkbench__all__ = ["create_mcp_server_session",+ "McpSessionActor","StdioMcpToolAdapter","StdioServerParams","SseMcpToolAdapter","SseServerParams","McpServerParams","mcp_server_tools",+ "McpWorkbench",]diff --git a/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_actor.py b/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_actor.pynew file mode 100644index 000000000..7e84e24b5--- /dev/null+++ b/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_actor.py@@ -0,0 +1,147 @@+import asyncio+import atexit+from typing import Any, Coroutine, Dict, Mapping, TypedDict++from autogen_core import Component, ComponentBase+from mcp.types import CallToolResult, ListToolsResult+from pydantic import BaseModel+from typing_extensions import Self++from ._config import McpServerParams+from ._session import create_mcp_server_session++McpResult = Coroutine[Any, Any, ListToolsResult] | Coroutine[Any, Any, CallToolResult]+McpFuture = asyncio.Future[McpResult]+++class McpActorArgs(TypedDict):+ name: str | None+ kargs: Mapping[str, Any]+++class McpSessionActorConfig(BaseModel):+ server_params: McpServerParams+++class McpSessionActor(ComponentBase[BaseModel], Component[McpSessionActorConfig]):+ component_type = "mcp_session_actor"+ component_config_schema = McpSessionActorConfig+ component_provider_override = "autogen_ext.tools.mcp.McpSessionActor"++ server_params: McpServerParams++ # model_config = ConfigDict(arbitrary_types_allowed=True)++ def __init__(self, server_params: McpServerParams) -> None:+ self.server_params: McpServerParams = server_params+ self.name = "mcp_session_actor"+ self.description = "MCP session actor"+ self._command_queue: asyncio.Queue[Dict[str, Any]] = asyncio.Queue()+ self._actor_task: asyncio.Task[Any] | None = None+ self._shutdown_future: asyncio.Future[Any] | None = None+ self._active = False+ atexit.register(self._sync_shutdown)++ async def initialize(self) -> None:+ if not self._active:+ self._active = True+ self._actor_task = asyncio.create_task(self._run_actor())++ async def call(self, type: str, args: McpActorArgs | None = None) -> McpFuture:+ if not self._active:+ raise RuntimeError("MCP Actor not running, call initialize() first")+ if self._actor_task and self._actor_task.done():+ raise RuntimeError("MCP actor task crashed", self._actor_task.exception())+ fut: asyncio.Future[McpFuture] = asyncio.Future()+ if type in {"list_tools", "shutdown"}:+ await self._command_queue.put({"type": type, "future": fut})+ res = await fut+ elif type == "call_tool":+ if args is None:+ raise ValueError("args is required for call_tool")+ name = args.get("name", None)+ kwargs = args.get("kargs", {})+ if name is None:+ raise ValueError("name is required for call_tool")+ await self._command_queue.put({"type": type, "name": name, "args": kwargs, "future": fut})+ res = await fut+ else:+ raise ValueError(f"Unknown command type: {type}")+ return res++ async def close(self) -> None:+ if not self._active or self._actor_task is None:+ return+ self._shutdown_future = asyncio.Future()+ await self._command_queue.put({"type": "shutdown", "future": self._shutdown_future})+ await self._shutdown_future+ await self._actor_task+ self._active = False++ async def _run_actor(self) -> None:+ result: McpResult+ try:+ async with create_mcp_server_session(self.server_params) as session:+ await session.initialize()+ while True:+ cmd = await self._command_queue.get()+ if cmd["type"] == "shutdown":+ cmd["future"].set_result("ok")+ break+ elif cmd["type"] == "call_tool":+ try:+ result = session.call_tool(name=cmd["name"], arguments=cmd["args"])+ cmd["future"].set_result(result)+ except Exception as e:+ cmd["future"].set_exception(e)+ elif cmd["type"] == "list_tools":+ try:+ result = session.list_tools()+ cmd["future"].set_result(result)+ except Exception as e:+ cmd["future"].set_exception(e)+ except Exception as e:+ if self._shutdown_future and not self._shutdown_future.done():+ self._shutdown_future.set_exception(e)+ finally:+ self._active = False+ self._actor_task = None++ def _sync_shutdown(self) -> None:+ if not self._active or self._actor_task is None:+ return+ try:+ loop = asyncio.get_event_loop()+ except RuntimeError:+ # No loop available — interpreter is likely shutting down+ return++ if loop.is_closed():+ return++ if loop.is_running():+ loop.create_task(self.close())+ else:+ loop.run_until_complete(self.close())++ def _to_config(self) -> McpSessionActorConfig:+ """+ Convert the adapter to its configuration representation.++ Returns:+ McpSessionConfig: The configuration of the adapter.+ """+ return McpSessionActorConfig(server_params=self.server_params)++ @classmethod+ def _from_config(cls, config: McpSessionActorConfig) -> Self:+ """+ Create an instance of McpSessionActor from its configuration.++ Args:+ config (McpSessionConfig): The configuration of the adapter.++ Returns:+ McpSessionActor: An instance of SseMcpToolAdapter.+ """+ return cls(server_params=config.server_params)diff --git a/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_config.py b/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_config.pyindex 236ff6892..215102c5e 100644--- a/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_config.py+++ b/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_config.py@@ -1,22 +1,27 @@-from typing import Any, TypeAlias+from typing import Any, Literalfrom mcp import StdioServerParameters-from pydantic import BaseModel+from pydantic import BaseModel, Field+from typing_extensions import Annotatedclass StdioServerParams(StdioServerParameters):"""Parameters for connecting to an MCP server over STDIO."""+ type: Literal["StdioServerParams"] = "StdioServerParams"+read_timeout_seconds: float = 5class SseServerParams(BaseModel):"""Parameters for connecting to an MCP server over SSE."""+ type: Literal["SseServerParams"] = "SseServerParams"+url: strheaders: dict[str, Any] | None = Nonetimeout: float = 5sse_read_timeout: float = 60 * 5-McpServerParams: TypeAlias = StdioServerParams | SseServerParams+McpServerParams = Annotated[StdioServerParams | SseServerParams, Field(discriminator="type")]diff --git a/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_workbench.py b/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_workbench.pynew file mode 100644index 000000000..3272a86ee--- /dev/null+++ b/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_workbench.py@@ -0,0 +1,200 @@+import builtins+import warnings+from typing import Any, List, Literal, Mapping++from autogen_core import CancellationToken, Component, Image+from autogen_core.tools import (+ ImageResultContent,+ ParametersSchema,+ TextResultContent,+ ToolResult,+ ToolSchema,+ Workbench,+)+from mcp.types import CallToolResult, EmbeddedResource, ImageContent, ListToolsResult, TextContent+from pydantic import BaseModel+from typing_extensions import Self++from ._actor import McpSessionActor+from ._config import McpServerParams, SseServerParams, StdioServerParams+++class McpWorkbenchConfig(BaseModel):+ server_params: McpServerParams+++class McpWorkbenchState(BaseModel):+ type: Literal["McpWorkBenchState"] = "McpWorkBenchState"+++class McpWorkbench(Workbench, Component[McpWorkbenchConfig]):+ """+ A workbench that wraps an MCP server and provides an interface+ to list and call tools provided by the server.++ Args:+ server_params (McpServerParams): The parameters to connect to the MCP server.+ This can be either a :class:`StdioServerParams` or :class:`SseServerParams`.++ Example:++ .. code-block:: python++ import asyncio++ from autogen_ext.tools.mcp import McpWorkbench, StdioServerParams+++ async def main() -> None:+ params = StdioServerParams(+ command="uvx",+ args=["mcp-server-fetch"],+ read_timeout_seconds=60,+ )++ # You can also use `start()` and `stop()` to manage the session.+ async with McpWorkbench(server_params=params) as workbench:+ tools = await workbench.list_tools()+ print(tools)+ result = await workbench.call_tool(tools[0]["name"], {"url": "https://github.com/"})+ print(result)+++ asyncio.run(main())++ """++ component_provider_override = "autogen_ext.tools.mcp.McpWorkbench"+ component_config_schema = McpWorkbenchConfig++ def __init__(self, server_params: McpServerParams) -> None:+ self._server_params = server_params+ # self._session: ClientSession | None = None+ self._actor: McpSessionActor | None = None+ self._read = None+ self._write = None++ @property+ def server_params(self) -> McpServerParams:+ return self._server_params++ async def list_tools(self) -> List[ToolSchema]:+ if not self._actor:+ await self.start() # fallback to start the actor if not initialized instead of raising an error+ # Why? Because when deserializing the workbench, the actor might not be initialized yet.+ # raise RuntimeError("Actor is not initialized. Call start() first.")+ if self._actor is None:+ raise RuntimeError("Actor is not initialized. Please check the server connection.")+ result_future = await self._actor.call("list_tools", None)+ list_tool_result = await result_future+ assert isinstance(+ list_tool_result, ListToolsResult+ ), f"list_tools must return a CallToolResult, instead of : {str(type(list_tool_result))}"+ schema: List[ToolSchema] = []+ for tool in list_tool_result.tools:+ name = tool.name+ description = tool.description or ""+ parameters = ParametersSchema(+ type="object",+ properties=tool.inputSchema["properties"],+ required=tool.inputSchema.get("required", []),+ additionalProperties=tool.inputSchema.get("additionalProperties", False),+ )+ tool_schema = ToolSchema(+ name=name,+ description=description,+ parameters=parameters,+ )+ schema.append(tool_schema)+ return schema++ async def call_tool(+ self, name: str, arguments: Mapping[str, Any] | None = None, cancellation_token: CancellationToken | None = None+ ) -> ToolResult:+ if not self._actor:+ await self.start() # fallback to start the actor if not initialized instead of raising an error+ # Why? Because when deserializing the workbench, the actor might not be initialized yet.+ # raise RuntimeError("Actor is not initialized. Call start() first.")+ if self._actor is None:+ raise RuntimeError("Actor is not initialized. Please check the server connection.")+ if not cancellation_token:+ cancellation_token = CancellationToken()+ if not arguments:+ arguments = {}+ try:+ result_future = await self._actor.call("call_tool", {"name": name, "kargs": arguments})+ cancellation_token.link_future(result_future)+ result = await result_future+ assert isinstance(+ result, CallToolResult+ ), f"call_tool must return a CallToolResult, instead of : {str(type(result))}"+ result_parts: List[TextResultContent | ImageResultContent] = []+ is_error = result.isError+ for content in result.content:+ if isinstance(content, TextContent):+ result_parts.append(TextResultContent(content=content.text))+ elif isinstance(content, ImageContent):+ result_parts.append(ImageResultContent(content=Image.from_base64(content.data)))+ elif isinstance(content, EmbeddedResource):+ # TODO: how to handle embedded resources?+ # For now we just use text representation.+ result_parts.append(TextResultContent(content=content.model_dump_json()))+ else:+ raise ValueError(f"Unknown content type from server: {type(content)}")+ except Exception as e:+ error_message = self._format_errors(e)+ is_error = True+ result_parts = [TextResultContent(content=error_message)]+ return ToolResult(name=name, result=result_parts, is_error=is_error)++ def _format_errors(self, error: Exception) -> str:+ """Recursively format errors into a string."""++ error_message = ""+ if hasattr(builtins, "ExceptionGroup") and isinstance(error, builtins.ExceptionGroup):+ # ExceptionGroup is available in Python 3.11+.+ # TODO: how to make this compatible with Python 3.10?+ for sub_exception in error.exceptions: # type: ignore+ error_message += self._format_errors(sub_exception) # type: ignore+ else:+ error_message += f"{str(error)}\n"+ return error_message++ async def start(self) -> None:+ if self._actor:+ warnings.warn(+ "McpWorkbench is already started. No need to start again.",+ UserWarning,+ stacklevel=2,+ )+ return # Already initialized, no need to start again++ if isinstance(self._server_params, (StdioServerParams, SseServerParams)):+ self._actor = McpSessionActor(self._server_params)+ await self._actor.initialize()+ else:+ raise ValueError(f"Unsupported server params type: {type(self._server_params)}")++ async def stop(self) -> None:+ if self._actor:+ # Close the actor+ await self._actor.close()+ self._actor = None+ else:+ raise RuntimeError("McpWorkbench is not started. Call start() first.")++ async def reset(self) -> None:+ pass++ async def save_state(self) -> Mapping[str, Any]:+ return McpWorkbenchState().model_dump()++ async def load_state(self, state: Mapping[str, Any]) -> None:+ pass++ def _to_config(self) -> McpWorkbenchConfig:+ return McpWorkbenchConfig(server_params=self._server_params)++ @classmethod+ def _from_config(cls, config: McpWorkbenchConfig) -> Self:+ return cls(server_params=config.server_params)diff --git a/python/packages/autogen-ext/tests/tools/test_mcp_tools.py b/python/packages/autogen-ext/tests/tools/test_mcp_tools.pyindex 998d678ab..10f17c2c3 100644--- a/python/packages/autogen-ext/tests/tools/test_mcp_tools.py+++ b/python/packages/autogen-ext/tests/tools/test_mcp_tools.py@@ -4,8 +4,10 @@ from unittest.mock import AsyncMock, MagicMockimport pytestfrom autogen_core import CancellationToken+from autogen_core.tools import Workbenchfrom autogen_core.utils import schema_to_pydantic_modelfrom autogen_ext.tools.mcp import (+ McpWorkbench,SseMcpToolAdapter,SseServerParams,StdioMcpToolAdapter,@@ -422,3 +424,80 @@ async def test_mcp_server_github() -> None:{"owner": "microsoft", "repo": "autogen", "path": "python", "branch": "main"}, CancellationToken())assert result is not None+++async def test_mcp_workbench_start_stop() -> None:+ params = StdioServerParams(+ command="uvx",+ args=["mcp-server-fetch"],+ read_timeout_seconds=60,+ )++ workbench = McpWorkbench(params)+ assert workbench is not None+ assert workbench.server_params == params+ await workbench.start()+ assert workbench._actor is not None # type: ignore[reportPrivateUsage]+ await workbench.stop()+ assert workbench._actor is None # type: ignore[reportPrivateUsage]+++async def test_mcp_workbench_server_fetch() -> None:+ params = StdioServerParams(+ command="uvx",+ args=["mcp-server-fetch"],+ read_timeout_seconds=60,+ )++ workbench = McpWorkbench(server_params=params)+ await workbench.start()++ tools = await workbench.list_tools()+ assert tools is not None+ assert tools[0]["name"] == "fetch"++ result = await workbench.call_tool(tools[0]["name"], {"url": "https://github.com/"}, CancellationToken())+ assert result is not None++ await workbench.stop()+++async def test_mcp_workbench_server_filesystem() -> None:+ params = StdioServerParams(+ command="npx",+ args=[+ "-y",+ "@modelcontextprotocol/server-filesystem",+ ".",+ ],+ read_timeout_seconds=60,+ )++ workbench = McpWorkbench(server_params=params)+ await workbench.start()++ tools = await workbench.list_tools()+ assert tools is not None+ tools = [tool for tool in tools if tool["name"] == "read_file"]+ assert len(tools) == 1+ tool = tools[0]+ result = await workbench.call_tool(tool["name"], {"path": "README.md"}, CancellationToken())+ assert result is not None++ await workbench.stop()++ # Serialize the workbench.+ config = workbench.dump_component()++ # Deserialize the workbench.+ async with Workbench.load_component(config) as new_workbench:+ tools = await new_workbench.list_tools()+ assert tools is not None+ tools = [tool for tool in tools if tool["name"] == "read_file"]+ assert len(tools) == 1+ tool = tools[0]+ result = await new_workbench.call_tool(tool["name"], {"path": "README.md"}, CancellationToken())+ assert result is not None