ag2 0.10.2__py3-none-any.whl

autogen/tools/tool.py

@@ -0,0 +1,188 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import inspect
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Union
+
+from ..doc_utils import export_module
+from ..tools.function_utils import get_function_schema
+from .dependency_injection import ChatContext, get_context_params, inject_params
+
+if TYPE_CHECKING:
+    from ..agentchat.conversable_agent import ConversableAgent
+
+__all__ = ["Tool", "tool"]
+
+
+@export_module("autogen.tools")
+class Tool:
+    """A class representing a Tool that can be used by an agent for various tasks.
+
+    This class encapsulates a tool with a name, description, and an executable function.
+    The tool can be registered with a ConversableAgent for use either with an LLM or for direct execution.
+
+    Attributes:
+        name (str): The name of the tool.
+        description (str): The description of the tool.
+        func_or_tool (Union[Tool, Callable[..., Any]]): The function or Tool instance to create a Tool from.
+        parameters_json_schema (Optional[ict[str, Any]]): A schema describing the parameters that the function accepts. If None, the schema will be generated from the function signature.
+    """
+
+    def __init__(
+        self,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        func_or_tool: Union["Tool", Callable[..., Any]],
+        parameters_json_schema: dict[str, Any] | None = None,
+    ) -> None:
+        """Create a new Tool object.
+
+        Args:
+            name (str): The name of the tool.
+            description (str): The description of the tool.
+            func_or_tool (Union[Tool, Callable[..., Any]]): The function or Tool instance to create a Tool from.
+            parameters_json_schema (Optional[dict[str, Any]]): A schema describing the parameters that the function accepts. If None, the schema will be generated from the function signature.
+        """
+        if isinstance(func_or_tool, Tool):
+            self._name: str = name or func_or_tool.name
+            self._description: str = description or func_or_tool.description
+            self._func: Callable[..., Any] = func_or_tool.func
+            self._chat_context_param_names: list[str] = func_or_tool._chat_context_param_names
+        elif inspect.isfunction(func_or_tool) or inspect.ismethod(func_or_tool):
+            self._chat_context_param_names = get_context_params(func_or_tool, subclass=ChatContext)
+            self._func = inject_params(func_or_tool)
+            self._name = name or func_or_tool.__name__
+            self._description = description or func_or_tool.__doc__ or ""
+        else:
+            raise ValueError(
+                f"Parameter 'func_or_tool' must be a function, method or a Tool instance, it is '{type(func_or_tool)}' instead."
+            )
+
+        self._func_schema = (
+            {
+                "type": "function",
+                "function": {
+                    "name": name,
+                    "description": description,
+                    "parameters": parameters_json_schema,
+                },
+            }
+            if parameters_json_schema
+            else None
+        )
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def description(self) -> str:
+        return self._description
+
+    @property
+    def func(self) -> Callable[..., Any]:
+        return self._func
+
+    def register_for_llm(self, agent: "ConversableAgent") -> None:
+        """Registers the tool for use with a ConversableAgent's language model (LLM).
+
+        This method registers the tool so that it can be invoked by the agent during
+        interactions with the language model.
+
+        Args:
+            agent (ConversableAgent): The agent to which the tool will be registered.
+        """
+        if self._func_schema:
+            agent.update_tool_signature(self._func_schema, is_remove=False)
+        else:
+            agent.register_for_llm()(self)
+
+    def register_for_execution(self, agent: "ConversableAgent") -> None:
+        """Registers the tool for direct execution by a ConversableAgent.
+
+        This method registers the tool so that it can be executed by the agent,
+        typically outside of the context of an LLM interaction.
+
+        Args:
+            agent (ConversableAgent): The agent to which the tool will be registered.
+        """
+        agent.register_for_execution()(self)
+
+    def register_tool(self, agent: "ConversableAgent") -> None:
+        """Register a tool to be both proposed and executed by an agent.
+
+        Equivalent to calling both `register_for_llm` and `register_for_execution` with the same agent.
+
+        Note: This will not make the agent recommend and execute the call in the one step. If the agent
+        recommends the tool, it will need to be the next agent to speak in order to execute the tool.
+
+        Args:
+            agent (ConversableAgent): The agent to which the tool will be registered.
+        """
+        self.register_for_llm(agent)
+        self.register_for_execution(agent)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute the tool by calling its underlying function with the provided arguments.
+
+        Args:
+            *args: Positional arguments to pass to the tool
+            **kwargs: Keyword arguments to pass to the tool
+
+        Returns:
+            The result of executing the tool's function.
+        """
+        return self._func(*args, **kwargs)
+
+    @property
+    def tool_schema(self) -> dict[str, Any]:
+        """Get the schema for the tool.
+
+        This is the preferred way of handling function calls with OpeaAI and compatible frameworks.
+
+        """
+        return get_function_schema(self.func, name=self.name, description=self.description)
+
+    @property
+    def function_schema(self) -> dict[str, Any]:
+        """Get the schema for the function.
+
+        This is the old way of handling function calls with OpenAI and compatible frameworks.
+        It is provided for backward compatibility.
+
+        """
+        schema = get_function_schema(self.func, name=self.name, description=self.description)
+        return schema["function"]  # type: ignore[no-any-return]
+
+    @property
+    def realtime_tool_schema(self) -> dict[str, Any]:
+        """Get the schema for the tool.
+
+        This is the preferred way of handling function calls with OpeaAI and compatible frameworks.
+
+        """
+        schema = get_function_schema(self.func, name=self.name, description=self.description)
+        schema = {"type": schema["type"], **schema["function"]}
+
+        return schema
+
+
+@export_module("autogen.tools")
+def tool(name: str | None = None, description: str | None = None) -> Callable[[Callable[..., Any]], Tool]:
+    """Decorator to create a Tool from a function.
+
+    Args:
+        name (str): The name of the tool.
+        description (str): The description of the tool.
+
+    Returns:
+        Callable[[Callable[..., Any]], Tool]: A decorator that creates a Tool from a function.
+    """
+
+    def decorator(func: Callable[..., Any]) -> Tool:
+        return Tool(name=name, description=description, func_or_tool=func)
+
+    return decorator

autogen/tools/toolkit.py

@@ -0,0 +1,86 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import TYPE_CHECKING
+
+from ..doc_utils import export_module
+from .tool import Tool
+
+if TYPE_CHECKING:
+    from ..agentchat.conversable_agent import ConversableAgent
+
+__all__ = ["Toolkit"]
+
+
+@export_module("autogen.tools")
+class Toolkit:
+    """A class representing a set of tools that can be used by an agent for various tasks."""
+
+    def __init__(self, tools: list[Tool]) -> None:
+        """Create a new Toolkit object.
+
+        Args:
+            tools (list[Tool]): The list of tools in the
+        """
+        self.toolkit = {tool.name: tool for tool in tools}
+
+    @property
+    def tools(self) -> list[Tool]:
+        """Get the list of tools in the set."""
+        return list(self.toolkit.values())
+
+    def register_for_llm(self, agent: "ConversableAgent") -> None:
+        """Register the tools in the set with an LLM agent.
+
+        Args:
+            agent (ConversableAgent): The LLM agent to register the tools with.
+        """
+        for tool in self.toolkit.values():
+            tool.register_for_llm(agent)
+
+    def register_for_execution(self, agent: "ConversableAgent") -> None:
+        """Register the tools in the set with an agent for
+
+        Args:
+            agent (ConversableAgent): The agent to register the tools with.
+        """
+        for tool in self.toolkit.values():
+            tool.register_for_execution(agent)
+
+    def get_tool(self, tool_name: str) -> Tool:
+        """Get a tool from the set by name.
+
+        Args:
+            tool_name (str): The name of the tool to get.
+
+        Returns:
+            Tool: The tool with the given name.
+        """
+        if tool_name in self.toolkit:
+            return self.toolkit[tool_name]
+
+        raise ValueError(f"Tool '{tool_name}' not found in Toolkit.")
+
+    def set_tool(self, tool: Tool) -> None:
+        """Set a tool in the set.
+
+        Args:
+            tool (Tool): The tool to set.
+        """
+        self.toolkit[tool.name] = tool
+
+    def remove_tool(self, tool_name: str) -> None:
+        """Remove a tool from the set by name.
+
+        Args:
+            tool_name (str): The name of the tool to remove.
+        """
+        if tool_name in self.toolkit:
+            del self.toolkit[tool_name]
+        else:
+            raise ValueError(f"Tool '{tool_name}' not found in Toolkit.")
+
+    def __len__(self) -> int:
+        """Get the number of tools in the map."""
+        return len(self.toolkit)

autogen/types.py

@@ -0,0 +1,29 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Portions derived from  https://github.com/microsoft/autogen are under the MIT License.
+# SPDX-License-Identifier: MIT
+
+from typing import Any, Literal, TypedDict
+
+MessageContentType = str | list[dict[str, Any] | str] | None
+
+
+class UserMessageTextContentPart(TypedDict):
+    """Represents a text content part of a user message"""
+
+    type: Literal["text"]
+    """The type of the content part. Always "text" for text content parts."""
+    text: str
+    """The text content of the part."""
+
+
+class UserMessageImageContentPart(TypedDict):
+    """Represents an image content part of a user message"""
+
+    type: Literal["image_url"]
+    """The type of the content part. Always "image_url" for image content parts."""
+    # Ignoring the other "detail param for now"
+    image_url: dict[Literal["url"], str]
+    """The URL of the image."""

autogen/version.py

@@ -0,0 +1,7 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+__all__ = ["__version__"]
+
+__version__ = "0.10.2"

templates/client_template/main.jinja2

@@ -0,0 +1,72 @@
+{{imports}}
+
+import argparse
+import json
+import os
+from typing import *
+
+from autogen.mcp.mcp_proxy import MCPProxy
+from autogen.mcp.mcp_proxy.security import BaseSecurity
+from autogen.mcp.mcp_proxy.security import {% for i in security_classes %}{{i}}{% if not loop.last %}, {% endif %}{% endfor %}
+
+app = MCPProxy(
+    {% if info %}
+    {% for key,value in info.items() %}
+    {% set info_value= value.__repr__() %}
+    {% if not key.startswith('x-') %}
+    {{ key }} = {{info_value}},
+    {% endif %}
+    {% endfor %}
+    {% endif %}
+    )
+
+
+{% for operation in operations %}
+@app.{{operation.type}}('{{operation.path}}'
+    {% if operation.description %}
+    , description=""" {{operation.description}} """
+    {% endif %}
+    {% if operation.tags %}
+    , tags={{operation.tags}}
+    {% endif %}
+    {% if operation.security %}
+    , security=[{% for security in operation.security %}
+    {% for key, value in security.items() %}
+    {{security_parameters[key]}},
+    {% endfor %}
+    {% endfor %}]
+    {% endif %}
+    )
+def {{operation.function_name}}({{operation.snake_case_arguments}}
+    ):
+    {%- if operation.summary %}
+    """
+    {{ operation.summary }}
+    """
+    {%- endif %}
+    raise RuntimeError("Should be patched by MCPProxy and never executed")
+{% endfor %}
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Math Server")
+    parser.add_argument("transport", choices=["stdio", "sse", "streamable-http"], help="Transport mode (stdio, sse or streamable-http)")
+    args = parser.parse_args()
+
+    if "CONFIG_PATH" in os.environ:
+        config_path = os.environ["CONFIG_PATH"]
+        app.load_configuration(config_path)
+
+    if "CONFIG" in os.environ:
+        config = os.environ["CONFIG"]
+        app.load_configuration_from_string(config)
+
+    if "SECURITY" in os.environ:
+        security_params = BaseSecurity.parse_security_parameters_from_env(
+            os.environ,
+        )
+
+        app.set_security_params(security_params)
+
+    mcp_settings = json.loads(os.environ.get("MCP_SETTINGS", "{}"))
+
+    app.get_mcp(**mcp_settings).run(transport=args.transport)

templates/config_template/config.jinja2

@@ -0,0 +1,7 @@
+{
+  "server": {
+    "url": "{{ server_url }}"
+  },
+  "authentication": {{ authentications | tojson(indent=2) }},
+  "operations": {{ operations | tojson(indent=2) }}
+}

templates/main.jinja2

@@ -0,0 +1,61 @@
+{{imports}}
+
+import argparse
+import os
+from typing import *
+
+from autogen.mcp.mcp_proxy import MCPProxy
+from autogen.mcp.mcp_proxy.security import BaseSecurity
+from autogen.mcp.mcp_proxy.security import {% for i in security_classes %}{{i}}{% if not loop.last %}, {% endif %}{% endfor %}
+
+app = MCPProxy(
+    {% if info %}
+    {% for key,value in info.items() %}
+    {% set info_value= value.__repr__() %}
+    {% if not key.startswith('x-') %}
+    {{ key }} = {{info_value}},
+    {% endif %}
+    {% endfor %}
+    {% endif %}
+    )
+
+
+{% for operation in operations %}
+@app.{{operation.type}}('{{operation.path}}'
+    {% if operation.description %}
+    , description=""" {{operation.description}} """
+    {% endif %}
+    {% if operation.tags %}
+    , tags={{operation.tags}}
+    {% endif %}
+    {% if operation.security %}
+    , security=[{% for security in operation.security %}
+    {% for key, value in security.items() %}
+    {{security_parameters[key]}},
+    {% endfor %}
+    {% endfor %}]
+    {% endif %}
+    )
+def {{operation.function_name}}({{operation.snake_case_arguments}}
+    ):
+    {%- if operation.summary %}
+    """
+    {{ operation.summary }}
+    """
+    {%- endif %}
+    raise RuntimeError("Should be patched by MCPProxy and never executed")
+{% endfor %}
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Math Server")
+    parser.add_argument("transport", choices=["stdio", "sse", "streamable-http"], help="Transport mode (stdio, sse or streamable-http)")
+    args = parser.parse_args()
+
+    if "SECURITY" in os.environ:
+        security_params = BaseSecurity.parse_security_parameters_from_env(
+            os.environ,
+        )
+
+        app.set_security_params(security_params)
+
+    app._mcp.run(transport=args.transport)