ag2 0.10.2__py3-none-any.whl

autogen/tools/dependency_injection.py

@@ -0,0 +1,249 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import functools
+import inspect
+import sys
+from abc import ABC
+from collections.abc import Callable, Iterable
+from functools import wraps
+from typing import TYPE_CHECKING, Any, TypeVar, get_type_hints
+
+from ..agentchat import Agent
+from ..doc_utils import export_module
+from ..fast_depends import Depends as FastDepends
+from ..fast_depends import inject
+from ..fast_depends.dependencies import model
+from ..fast_depends.utils import is_coroutine_callable
+
+if TYPE_CHECKING:
+    from ..agentchat.conversable_agent import ConversableAgent
+
+__all__ = [
+    "BaseContext",
+    "ChatContext",
+    "Depends",
+    "Field",
+    "get_context_params",
+    "inject_params",
+    "on",
+    "remove_params",
+]
+
+
+@export_module("autogen.tools")
+class BaseContext(ABC):
+    """Base class for context classes.
+
+    This is the base class for defining various context types that may be used
+    throughout the application. It serves as a parent for specific context classes.
+    """
+
+    pass
+
+
+@export_module("autogen.tools")
+class ChatContext(BaseContext):
+    """ChatContext class that extends BaseContext.
+
+    This class is used to represent a chat context that holds a list of messages.
+    It inherits from `BaseContext` and adds the `messages` attribute.
+    """
+
+    def __init__(self, agent: "ConversableAgent") -> None:
+        """Initializes the ChatContext with an agent.
+
+        Args:
+            agent: The agent to use for retrieving chat messages.
+        """
+        self._agent = agent
+
+    @property
+    def chat_messages(self) -> dict[Agent, list[dict[Any, Any]]]:
+        """The messages in the chat.
+
+        Returns:
+            A dictionary of agents and their messages.
+        """
+        return self._agent.chat_messages
+
+    @property
+    def last_message(self) -> dict[str, Any] | None:
+        """The last message in the chat.
+
+        Returns:
+            The last message in the chat.
+        """
+        return self._agent.last_message()
+
+
+T = TypeVar("T")
+
+
+def on(x: T) -> Callable[[], T]:
+    def inner(ag2_x: T = x) -> T:
+        return ag2_x
+
+    return inner
+
+
+@export_module("autogen.tools")
+def Depends(x: Any) -> Any:  # noqa: N802
+    """Creates a dependency for injection based on the provided context or type.
+
+    Args:
+        x: The context or dependency to be injected.
+
+    Returns:
+        A FastDepends object that will resolve the dependency for injection.
+    """
+    if isinstance(x, BaseContext):
+        return FastDepends(lambda: x)
+
+    return FastDepends(x)
+
+
+def get_context_params(func: Callable[..., Any], subclass: type[BaseContext] | type[ChatContext]) -> list[str]:
+    """Gets the names of the context parameters in a function signature.
+
+    Args:
+        func: The function to inspect for context parameters.
+        subclass: The subclass to search for.
+
+    Returns:
+        A list of parameter names that are instances of the specified subclass.
+    """
+    sig = inspect.signature(func)
+    return [p.name for p in sig.parameters.values() if _is_context_param(p, subclass=subclass)]
+
+
+def _is_context_param(param: inspect.Parameter, subclass: type[BaseContext] | type[ChatContext] = BaseContext) -> bool:
+    # param.annotation.__args__[0] is used to handle Annotated[MyContext, Depends(MyContext(b=2))]
+    param_annotation = param.annotation.__args__[0] if hasattr(param.annotation, "__args__") else param.annotation
+    try:
+        return isinstance(param_annotation, type) and issubclass(param_annotation, subclass)
+    except TypeError:
+        return False
+
+
+def _is_depends_param(param: inspect.Parameter) -> bool:
+    return isinstance(param.default, model.Depends) or (
+        hasattr(param.annotation, "__metadata__")
+        and type(param.annotation.__metadata__) == tuple
+        and isinstance(param.annotation.__metadata__[0], model.Depends)
+    )
+
+
+def remove_params(func: Callable[..., Any], sig: inspect.Signature, params: Iterable[str]) -> None:
+    new_signature = sig.replace(parameters=[p for p in sig.parameters.values() if p.name not in params])
+    func.__signature__ = new_signature  # type: ignore[attr-defined]
+
+
+def _remove_injected_params_from_signature(func: Callable[..., Any]) -> Callable[..., Any]:
+    func = _fix_staticmethod(func)
+    sig = inspect.signature(func)
+    params_to_remove = [p.name for p in sig.parameters.values() if _is_context_param(p) or _is_depends_param(p)]
+    remove_params(func, sig, params_to_remove)
+    return func
+
+
+class Field:
+    """Represents a description field for use in type annotations.
+
+    This class is used to store a description for an annotated field, often used for
+    documenting or validating fields in a context or data model.
+    """
+
+    def __init__(self, description: str) -> None:
+        """Initializes the Field with a description.
+
+        Args:
+            description: The description text for the field.
+        """
+        self._description = description
+
+    @property
+    def description(self) -> str:
+        return self._description
+
+
+def _string_metadata_to_description_field(func: Callable[..., Any]) -> Callable[..., Any]:
+    type_hints = get_type_hints(func, include_extras=True)
+
+    for _, annotation in type_hints.items():
+        # Check if the annotation itself has metadata (using __metadata__)
+        if hasattr(annotation, "__metadata__"):
+            metadata = annotation.__metadata__
+            if metadata and isinstance(metadata[0], str):
+                # Replace string metadata with Field
+                annotation.__metadata__ = (Field(description=metadata[0]),)
+        # For Python < 3.11, annotations like `Optional` are stored as `Union`, so metadata
+        # would be in the first element of __args__ (e.g., `__args__[0]` for `int` in `Optional[int]`)
+        elif hasattr(annotation, "__args__") and hasattr(annotation.__args__[0], "__metadata__"):
+            metadata = annotation.__args__[0].__metadata__
+            if metadata and isinstance(metadata[0], str):
+                # Replace string metadata with Field
+                annotation.__args__[0].__metadata__ = (Field(description=metadata[0]),)
+    return func
+
+
+def _fix_staticmethod(f: Callable[..., Any]) -> Callable[..., Any]:
+    # This is a workaround for Python 3.9+ where staticmethod.__func__ is accessible
+    if sys.version_info >= (3, 9) and isinstance(f, staticmethod) and hasattr(f, "__func__"):
+
+        @wraps(f.__func__)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            return f.__func__(*args, **kwargs)  # type: ignore[attr-defined]
+
+        wrapper.__name__ = f.__func__.__name__
+
+        f = wrapper
+    return f
+
+
+def _set_return_annotation_to_any(f: Callable[..., Any]) -> Callable[..., Any]:
+    if is_coroutine_callable(f):
+
+        @functools.wraps(f)
+        async def _a_wrapped_func(*args: Any, **kwargs: Any) -> Any:
+            return await f(*args, **kwargs)
+
+        wrapped_func = _a_wrapped_func
+
+    else:
+
+        @functools.wraps(f)
+        def _wrapped_func(*args: Any, **kwargs: Any) -> Any:
+            return f(*args, **kwargs)
+
+        wrapped_func = _wrapped_func
+
+    sig = inspect.signature(f)
+
+    # Change the return annotation directly on the signature of the wrapper
+    wrapped_func.__signature__ = sig.replace(return_annotation=Any)  # type: ignore[attr-defined]
+
+    return wrapped_func
+
+
+def inject_params(f: Callable[..., Any]) -> Callable[..., Any]:
+    """Injects parameters into a function, removing injected dependencies from its signature.
+
+    This function is used to modify a function by injecting dependencies and removing
+    injected parameters from the function's signature.
+
+    Args:
+        f: The function to modify with dependency injection.
+
+    Returns:
+        The modified function with injected dependencies and updated signature.
+    """
+    # This is a workaround for Python 3.9+ where staticmethod.__func__ is accessible
+    f = _fix_staticmethod(f)
+    f = _string_metadata_to_description_field(f)
+    f = _set_return_annotation_to_any(f)
+    f = inject(f)
+    f = _remove_injected_params_from_signature(f)
+
+    return f

autogen/tools/experimental/__init__.py

@@ -0,0 +1,54 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .browser_use import BrowserUseTool
+from .code_execution import PythonCodeExecutionTool
+from .crawl4ai import Crawl4AITool
+from .deep_research import DeepResearchTool
+from .duckduckgo import DuckDuckGoSearchTool
+from .firecrawl import FirecrawlTool
+from .google_search import GoogleSearchTool, YoutubeSearchTool
+from .messageplatform import (
+    DiscordRetrieveTool,
+    DiscordSendTool,
+    SlackRetrieveRepliesTool,
+    SlackRetrieveTool,
+    SlackSendTool,
+    TelegramRetrieveTool,
+    TelegramSendTool,
+)
+from .perplexity import PerplexitySearchTool
+from .reliable import ReliableTool, ReliableToolError, SuccessfulExecutionParameters, ToolExecutionDetails
+from .searxng import SearxngSearchTool
+from .tavily import TavilySearchTool
+from .web_search_preview import WebSearchPreviewTool
+from .wikipedia import WikipediaPageLoadTool, WikipediaQueryRunTool
+
+__all__ = [
+    "BrowserUseTool",
+    "Crawl4AITool",
+    "DeepResearchTool",
+    "DiscordRetrieveTool",
+    "DiscordSendTool",
+    "DuckDuckGoSearchTool",
+    "FirecrawlTool",
+    "GoogleSearchTool",
+    "PerplexitySearchTool",
+    "PythonCodeExecutionTool",
+    "ReliableTool",
+    "ReliableToolError",
+    "SearxngSearchTool",
+    "SlackRetrieveRepliesTool",
+    "SlackRetrieveTool",
+    "SlackSendTool",
+    "SuccessfulExecutionParameters",
+    "TavilySearchTool",
+    "TelegramRetrieveTool",
+    "TelegramSendTool",
+    "ToolExecutionDetails",
+    "WebSearchPreviewTool",
+    "WikipediaPageLoadTool",
+    "WikipediaQueryRunTool",
+    "YoutubeSearchTool",
+]

autogen/tools/experimental/browser_use/__init__.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
+
+from .browser_use import BrowserUseResult, BrowserUseTool, ExtractedContent
+
+__all__ = ["BrowserUseResult", "BrowserUseTool", "ExtractedContent"]

autogen/tools/experimental/browser_use/browser_use.py

@@ -0,0 +1,154 @@
+# Copyright (c) 2023 - 2025, AG2ai, Inc., AG2ai open-source projects maintainers and core contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Annotated, Any, Optional
+
+from pydantic import BaseModel, field_validator
+
+from ....doc_utils import export_module
+from ....import_utils import optional_import_block, require_optional_import
+from ....llm_config import LLMConfig
+from ... import Depends, Tool
+from ...dependency_injection import on
+
+with optional_import_block():
+    from browser_use import Agent, Controller
+    from browser_use.browser.browser import Browser, BrowserConfig
+
+    from ....interop.langchain.langchain_chat_model_factory import LangChainChatModelFactory
+
+
+__all__ = ["BrowserUseResult", "BrowserUseTool", "ExtractedContent"]
+
+
+@export_module("autogen.tools.experimental.browser_use")
+class ExtractedContent(BaseModel):
+    """Extracted content from the browser.
+
+    Attributes:
+        content: The extracted content.
+        url: The URL of the extracted content
+    """
+
+    content: str
+    url: str | None
+
+    @field_validator("url")
+    @classmethod
+    def check_url(cls, v: str) -> str | None:
+        """Check if the URL is about:blank and return None if it is.
+
+        Args:
+            v: The URL to check.
+        """
+        if v == "about:blank":
+            return None
+        return v
+
+
+@export_module("autogen.tools.experimental.browser_use")
+class BrowserUseResult(BaseModel):
+    """The result of using the browser to perform a task.
+
+    Attributes:
+        extracted_content: List of extracted content.
+        final_result: The final result.
+    """
+
+    extracted_content: list[ExtractedContent]
+    final_result: str | None
+
+
+@require_optional_import(
+    [
+        "langchain_anthropic",
+        "langchain_google_genai",
+        "langchain_ollama",
+        "langchain_openai",
+        "langchain_core",
+        "browser_use",
+    ],
+    "browser-use",
+)
+@export_module("autogen.tools.experimental")
+class BrowserUseTool(Tool):
+    """BrowserUseTool is a tool that uses the browser to perform a task."""
+
+    def __init__(  # type: ignore[no-any-unimported]
+        self,
+        *,
+        llm_config: LLMConfig | dict[str, Any] | None = None,
+        browser: Optional["Browser"] = None,
+        agent_kwargs: dict[str, Any] | None = None,
+        browser_config: dict[str, Any] | None = None,
+    ):
+        """Use the browser to perform a task.
+
+        Args:
+            llm_config: The LLM configuration. If None, the current LLMConfig from context is used.
+            browser: The browser to use. If defined, browser_config must be None
+            agent_kwargs: Additional keyword arguments to pass to the Agent
+            browser_config: The browser configuration to use. If defined, browser must be None
+        """
+        if llm_config is None:
+            llm_config = LLMConfig.current
+        if agent_kwargs is None:
+            agent_kwargs = {}
+        if browser_config is None:
+            browser_config = {}
+        if browser is not None and browser_config:
+            raise ValueError(
+                f"Cannot provide both browser and additional keyword parameters: {browser=}, {browser_config=}"
+            )
+
+        async def browser_use(  # type: ignore[no-any-unimported]
+            task: Annotated[str, "The task to perform."],
+            llm_config: Annotated[LLMConfig | dict[str, Any], Depends(on(llm_config))],
+            browser: Annotated[Browser | None, Depends(on(browser))],
+            agent_kwargs: Annotated[dict[str, Any], Depends(on(agent_kwargs))],
+            browser_config: Annotated[dict[str, Any], Depends(on(browser_config))],
+        ) -> BrowserUseResult:
+            agent_kwargs = agent_kwargs.copy()
+            browser_config = browser_config.copy()
+            if browser is None:
+                # set default value for headless
+                headless = browser_config.pop("headless", True)
+                browser_config = BrowserConfig(headless=headless, **browser_config)
+                browser = Browser(config=browser_config)
+            # set default value for generate_gif
+            if "generate_gif" not in agent_kwargs:
+                agent_kwargs["generate_gif"] = False
+            llm = LangChainChatModelFactory.create_base_chat_model(llm_config)
+            max_steps = agent_kwargs.pop("max_steps", 100)
+            agent = Agent(
+                task=task,
+                llm=llm,
+                browser=browser,
+                controller=BrowserUseTool._get_controller(llm_config),
+                **agent_kwargs,
+            )
+            result = await agent.run(max_steps=max_steps)
+            extracted_content = [
+                ExtractedContent(content=content, url=url)
+                for content, url in zip(result.extracted_content(), result.urls())
+            ]
+            return BrowserUseResult(
+                extracted_content=extracted_content,
+                final_result=result.final_result(),
+            )
+
+        super().__init__(
+            name="browser_use",
+            description="Use the browser to perform a task.",
+            func_or_tool=browser_use,
+        )
+
+    @staticmethod
+    def _get_controller(llm_config: LLMConfig | dict[str, Any]) -> Any:
+        response_format = (
+            llm_config["config_list"][0].get("response_format", None)
+            if "config_list" in llm_config
+            else llm_config.get("response_format")
+        )
+        return Controller(output_model=response_format)

autogen/tools/experimental/code_execution/__init__.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
+
+from .python_code_execution import PythonCodeExecutionTool
+
+__all__ = ["PythonCodeExecutionTool"]

autogen/tools/experimental/code_execution/python_code_execution.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
+
+import os
+import tempfile
+from typing import Annotated, Any
+
+from pydantic import BaseModel, Field
+
+from ....doc_utils import export_module
+from ....environments import WorkingDirectory
+from ....environments.python_environment import PythonEnvironment
+from ... import Tool
+
+__all__ = ["PythonCodeExecutionTool"]
+
+
+@export_module("autogen.tools.experimental")
+class PythonCodeExecutionTool(Tool):
+    """Executes Python code in a given environment and returns the result."""
+
+    def __init__(
+        self,
+        *,
+        timeout: int = 30,
+        working_directory: WorkingDirectory | None = None,
+        python_environment: PythonEnvironment | None = None,
+    ) -> None:
+        """Initialize the PythonCodeExecutionTool.
+
+        **CAUTION**: If provided a local environment, this tool will execute code in your local environment, which can be dangerous if the code is untrusted.
+
+        Args:
+            timeout: Maximum execution time allowed in seconds, will raise a TimeoutError exception if exceeded.
+            working_directory: Optional WorkingDirectory context manager to use.
+            python_environment: Optional PythonEnvironment to use. If None, will auto-detect or create based on other parameters.
+        """
+        # Store configuration parameters
+        self.timeout = timeout
+        self.working_directory = WorkingDirectory.get_current_working_directory(working_directory)
+        tool_python_environment = PythonEnvironment.get_current_python_environment(python_environment)
+
+        assert self.working_directory, "No Working directory found"
+        assert tool_python_environment, "No Python environment found"
+
+        self.python_environment = tool_python_environment
+
+        # Pydantic model to contain the code and list of libraries to execute
+        class CodeExecutionRequest(BaseModel):
+            code: Annotated[str, Field(description="Python code to execute")]
+            libraries: Annotated[list[str], Field(description="List of libraries to install before execution")]
+
+        # The tool function, this is what goes to the LLM
+        async def execute_python_code(
+            code_execution_request: Annotated[CodeExecutionRequest, "Python code and the libraries required"],
+        ) -> dict[str, Any]:
+            """Executes Python code in the attached environment and returns the result.
+
+            Args:
+                code_execution_request (CodeExecutionRequest): The Python code and libraries to execute
+            """
+            code = code_execution_request.code
+
+            # NOTE: Libraries are not installed (something to consider for future versions)
+
+            # Prepare a script file path
+            script_dir = self._get_script_directory()
+            script_path = os.path.join(script_dir, "script.py")
+
+            # Execute the code
+            return await self.python_environment.execute_code(code=code, script_path=script_path, timeout=self.timeout)
+
+        super().__init__(
+            name="python_execute_code",
+            description="Executes Python code and returns the result.",
+            func_or_tool=execute_python_code,
+        )
+
+    def _get_script_directory(self) -> str:
+        """Get the directory to use for scripts."""
+        if self.working_directory and hasattr(self.working_directory, "path") and self.working_directory.path:
+            path = self.working_directory.path
+            os.makedirs(path, exist_ok=True)
+            return path
+        return tempfile.mkdtemp(prefix="ag2_script_dir_")

autogen/tools/experimental/crawl4ai/__init__.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
+
+from .crawl4ai import Crawl4AITool
+
+__all__ = ["Crawl4AITool"]