agno 2.0.1__py3-none-any.whl → 2.3.0__py3-none-any.whl

agno/tools/googlecalendar.py

@@ -4,7 +4,7 @@ import uuid
 from functools import wraps
 from os import getenv
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, cast
 
 from agno.tools import Toolkit
 from agno.utils.log import log_debug, log_error, log_info
@@ -164,8 +164,10 @@ class GoogleCalendarTools(Toolkit):
                 )
 
         try:
+            service = cast(Resource, self.service)
+
             events_result = (
-                self.service.events()  # type: ignore
+                service.events()
                 .list(
                     calendarId=self.calendar_id,
                     timeMin=start_date,
@@ -194,6 +196,7 @@ class GoogleCalendarTools(Toolkit):
         timezone: Optional[str] = "UTC",
         attendees: Optional[List[str]] = None,
         add_google_meet_link: Optional[bool] = False,
+        notify_attendees: Optional[bool] = False,
     ) -> str:
         """
         Create a new event in the Google Calendar.
@@ -207,6 +210,7 @@ class GoogleCalendarTools(Toolkit):
             timezone (Optional[str]): Timezone for the event (default: UTC)
             attendees (Optional[List[str]]): List of email addresses of the attendees
             add_google_meet_link (Optional[bool]): Whether to add a Google Meet video link to the event
+            notify_attendees (Optional[bool]): Whether to send email notifications to attendees (default: False)
 
         Returns:
             str: JSON string containing the created Google Calendar event or error message
@@ -241,12 +245,18 @@ class GoogleCalendarTools(Toolkit):
             # Remove None values
             event = {k: v for k, v in event.items() if v is not None}
 
+            # Determine sendUpdates value based on notify_attendees parameter
+            send_updates = "all" if notify_attendees and attendees else "none"
+
+            service = cast(Resource, self.service)
+
             event_result = (
-                self.service.events()  # type: ignore
+                service.events()
                 .insert(
                     calendarId=self.calendar_id,
                     body=event,
                     conferenceDataVersion=1 if add_google_meet_link else 0,
+                    sendUpdates=send_updates,
                 )
                 .execute()
             )
@@ -267,6 +277,7 @@ class GoogleCalendarTools(Toolkit):
         end_date: Optional[str] = None,
         timezone: Optional[str] = None,
         attendees: Optional[List[str]] = None,
+        notify_attendees: Optional[bool] = False,
     ) -> str:
         """
         Update an existing event in the Google Calendar.
@@ -280,13 +291,16 @@ class GoogleCalendarTools(Toolkit):
             end_date (Optional[str]): New end date and time in ISO format (YYYY-MM-DDTHH:MM:SS)
             timezone (Optional[str]): New timezone for the event
             attendees (Optional[List[str]]): Updated list of attendee email addresses
+            notify_attendees (Optional[bool]): Whether to send email notifications to attendees (default: False)
 
         Returns:
             str: JSON string containing the updated Google Calendar event or error message
         """
         try:
+            service = cast(Resource, self.service)
+
             # First get the existing event to preserve its structure
-            event = self.service.events().get(calendarId=self.calendar_id, eventId=event_id).execute()  # type: ignore
+            event = service.events().get(calendarId=self.calendar_id, eventId=event_id).execute()
 
             # Update only the fields that are provided
             if title is not None:
@@ -317,9 +331,15 @@ class GoogleCalendarTools(Toolkit):
                 except ValueError:
                     return json.dumps({"error": f"Invalid end datetime format: {end_date}. Use ISO format."})
 
+            # Determine sendUpdates value based on notify_attendees parameter
+            send_updates = "all" if notify_attendees and attendees else "none"
+
             # Update the event
+
             updated_event = (
-                self.service.events().update(calendarId=self.calendar_id, eventId=event_id, body=event).execute()  # type: ignore
+                service.events()
+                .update(calendarId=self.calendar_id, eventId=event_id, body=event, sendUpdates=send_updates)
+                .execute()
             )
 
             log_debug(f"Event {event_id} updated successfully.")
@@ -329,18 +349,24 @@ class GoogleCalendarTools(Toolkit):
             return json.dumps({"error": f"An error occurred: {error}"})
 
     @authenticate
-    def delete_event(self, event_id: str) -> str:
+    def delete_event(self, event_id: str, notify_attendees: Optional[bool] = True) -> str:
         """
         Delete an event from the Google Calendar.
 
         Args:
             event_id (str): ID of the event to delete
+            notify_attendees (Optional[bool]): Whether to send email notifications to attendees (default: False)
 
         Returns:
             str: JSON string containing success message or error message
         """
         try:
-            self.service.events().delete(calendarId=self.calendar_id, eventId=event_id).execute()  # type: ignore
+            # Determine sendUpdates value based on notify_attendees parameter
+            send_updates = "all" if notify_attendees else "none"
+
+            service = cast(Resource, self.service)
+
+            service.events().delete(calendarId=self.calendar_id, eventId=event_id, sendUpdates=send_updates).execute()
 
             log_debug(f"Event {event_id} deleted successfully.")
             return json.dumps({"success": True, "message": f"Event {event_id} deleted successfully."})
@@ -366,6 +392,8 @@ class GoogleCalendarTools(Toolkit):
             str: JSON string containing all Google Calendar events or error message
         """
         try:
+            service = cast(Resource, self.service)
+
             params = {
                 "calendarId": self.calendar_id,
                 "maxResults": min(max_results, 100),
@@ -412,7 +440,7 @@ class GoogleCalendarTools(Toolkit):
                 if page_token:
                     params["pageToken"] = page_token
 
-                events_result = self.service.events().list(**params).execute()  # type: ignore
+                events_result = service.events().list(**params).execute()
                 all_events.extend(events_result.get("items", []))
 
                 page_token = events_result.get("nextPageToken")

agno/tools/googlesheets.py

@@ -48,13 +48,14 @@ import json
 from functools import wraps
 from os import getenv
 from pathlib import Path
-from typing import Any, List, Optional
+from typing import Any, List, Optional, Union
 
 from agno.tools import Toolkit
 
 try:
     from google.auth.transport.requests import Request
     from google.oauth2.credentials import Credentials
+    from google.oauth2.service_account import Credentials as ServiceAccountCredentials
     from google_auth_oauthlib.flow import InstalledAppFlow
     from googleapiclient.discovery import Resource, build
 except ImportError:
@@ -91,9 +92,10 @@ class GoogleSheetsTools(Toolkit):
         scopes: Optional[List[str]] = None,
         spreadsheet_id: Optional[str] = None,
         spreadsheet_range: Optional[str] = None,
-        creds: Optional[Credentials] = None,
+        creds: Optional[Union[Credentials, ServiceAccountCredentials]] = None,
         creds_path: Optional[str] = None,
         token_path: Optional[str] = None,
+        service_account_path: Optional[str] = None,
         oauth_port: int = 0,
         enable_read_sheet: bool = True,
         enable_create_sheet: bool = False,
@@ -108,9 +110,10 @@ class GoogleSheetsTools(Toolkit):
             scopes (Optional[List[str]]): Custom OAuth scopes. If None, uses write scope by default.
             spreadsheet_id (Optional[str]): ID of the target spreadsheet.
             spreadsheet_range (Optional[str]): Range within the spreadsheet.
-            creds (Optional[Credentials]): Pre-existing credentials.
+            creds (Optional[Credentials | ServiceAccountCredentials]): Pre-existing credentials.
             creds_path (Optional[str]): Path to credentials file.
             token_path (Optional[str]): Path to token file.
+            service_account_path (Optional[str]): Path to a service account file.
             oauth_port (int): Port to use for OAuth authentication. Defaults to 0.
             enable_read_sheet (bool): Enable reading from a sheet.
             enable_create_sheet (bool): Enable creating a sheet.
@@ -126,6 +129,7 @@ class GoogleSheetsTools(Toolkit):
         self.token_path = token_path
         self.oauth_port = oauth_port
         self.service: Optional[Resource] = None
+        self.service_account_path = service_account_path
 
         # Determine required scopes based on operations if no custom scopes provided
         if scopes is None:
@@ -171,6 +175,17 @@ class GoogleSheetsTools(Toolkit):
         if self.creds and self.creds.valid:
             return
 
+        service_account_path = self.service_account_path or getenv("GOOGLE_SERVICE_ACCOUNT_FILE")
+
+        if service_account_path:
+            self.creds = ServiceAccountCredentials.from_service_account_file(
+                service_account_path,
+                scopes=self.scopes,
+            )
+            if self.creds and self.creds.expired:
+                self.creds.refresh(Request())
+            return
+
         token_file = Path(self.token_path or "token.json")
         creds_file = Path(self.credentials_path or "credentials.json")
 
@@ -178,7 +193,7 @@ class GoogleSheetsTools(Toolkit):
             self.creds = Credentials.from_authorized_user_file(str(token_file), self.scopes)
 
         if not self.creds or not self.creds.valid:
-            if self.creds and self.creds.expired and self.creds.refresh_token:
+            if self.creds and self.creds.expired and self.creds.refresh_token:  # type: ignore
                 self.creds.refresh(Request())
             else:
                 client_config = {
@@ -199,7 +214,7 @@ class GoogleSheetsTools(Toolkit):
                     flow = InstalledAppFlow.from_client_config(client_config, self.scopes)
                 # Opens up a browser window for OAuth authentication
                 self.creds = flow.run_local_server(port=self.oauth_port)
-            token_file.write_text(self.creds.to_json()) if self.creds else None
+            token_file.write_text(self.creds.to_json()) if self.creds else None  # type: ignore
 
     @authenticate
     def read_sheet(self, spreadsheet_id: Optional[str] = None, spreadsheet_range: Optional[str] = None) -> str:

agno/tools/jira.py

@@ -22,6 +22,7 @@ class JiraTools(Toolkit):
         enable_create_issue: bool = True,
         enable_search_issues: bool = True,
         enable_add_comment: bool = True,
+        enable_add_worklog: bool = True,
         all: bool = False,
         **kwargs,
     ):
@@ -55,6 +56,8 @@ class JiraTools(Toolkit):
             tools.append(self.search_issues)
         if enable_add_comment or all:
             tools.append(self.add_comment)
+        if enable_add_worklog or all:
+            tools.append(self.add_worklog)
 
         super().__init__(name="jira_tools", tools=tools, **kwargs)
 
@@ -148,3 +151,20 @@ class JiraTools(Toolkit):
         except Exception as e:
             logger.error(f"Error adding comment to issue {issue_key}: {e}")
             return json.dumps({"error": str(e)})
+
+    def add_worklog(self, issue_key: str, time_spent: str, comment: Optional[str] = None) -> str:
+        """
+        Adds a worklog entry to log time spent on a specific Jira issue.
+
+        :param issue_key: The key of the issue to log work against (e.g., 'PROJ-123').
+        :param time_spent: The amount of time spent. Use Jira's format, e.g., '2h', '30m', '1d 4h'.
+        :param comment: An optional comment describing the work done.
+        :return: A JSON string indicating success or containing an error message.
+        """
+        try:
+            self.jira.add_worklog(issue=issue_key, timeSpent=time_spent, comment=comment)
+            log_debug(f"Worklog of '{time_spent}' added to issue {issue_key}")
+            return json.dumps({"status": "success", "issue_key": issue_key, "time_spent": time_spent})
+        except Exception as e:
+            logger.error(f"Error adding worklog to issue {issue_key}: {e}")
+            return json.dumps({"error": str(e)})

agno/tools/knowledge.py

@@ -43,15 +43,15 @@ class KnowledgeTools(Toolkit):
         if enable_think or all:
             tools.append(self.think)
         if enable_search or all:
-            tools.append(self.search)
+            tools.append(self.search_knowledge)
         if enable_analyze or all:
             tools.append(self.analyze)
 
         super().__init__(
             name="knowledge_tools",
+            tools=tools,
             instructions=self.instructions,
             add_instructions=add_instructions,
-            tools=tools,
             **kwargs,
         )
 
@@ -89,7 +89,7 @@ class KnowledgeTools(Toolkit):
             log_error(f"Error recording thought: {e}")
             return f"Error recording thought: {e}"
 
-    def search(self, session_state: Dict[str, Any], query: str) -> str:
+    def search_knowledge(self, session_state: Dict[str, Any], query: str) -> str:
         """Use this tool to search the knowledge base for relevant information.
         After thinking through the question, use this tool as many times as needed to search for relevant information.
 

agno/tools/mcp/__init__.py

@@ -0,0 +1,10 @@
+from agno.tools.mcp.mcp import MCPTools
+from agno.tools.mcp.multi_mcp import MultiMCPTools
+from agno.tools.mcp.params import SSEClientParams, StreamableHTTPClientParams
+
+__all__ = [
+    "MCPTools",
+    "MultiMCPTools",
+    "StreamableHTTPClientParams",
+    "SSEClientParams",
+]

agno/tools/mcp/mcp.py

@@ -0,0 +1,331 @@
+import weakref
+from dataclasses import asdict
+from datetime import timedelta
+from typing import Any, Literal, Optional, Union
+
+from agno.tools import Toolkit
+from agno.tools.function import Function
+from agno.tools.mcp.params import SSEClientParams, StreamableHTTPClientParams
+from agno.utils.log import log_debug, log_error, log_info
+from agno.utils.mcp import get_entrypoint_for_tool, prepare_command
+
+try:
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.sse import sse_client
+    from mcp.client.stdio import get_default_environment, stdio_client
+    from mcp.client.streamable_http import streamablehttp_client
+except (ImportError, ModuleNotFoundError):
+    raise ImportError("`mcp` not installed. Please install using `pip install mcp`")
+
+
+class MCPTools(Toolkit):
+    """
+    A toolkit for integrating Model Context Protocol (MCP) servers with Agno agents.
+    This allows agents to access tools, resources, and prompts exposed by MCP servers.
+
+    Can be used in three ways:
+    1. Direct initialization with a ClientSession
+    2. As an async context manager with StdioServerParameters
+    3. As an async context manager with SSE or Streamable HTTP client parameters
+    """
+
+    def __init__(
+        self,
+        command: Optional[str] = None,
+        *,
+        url: Optional[str] = None,
+        env: Optional[dict[str, str]] = None,
+        transport: Literal["stdio", "sse", "streamable-http"] = "stdio",
+        server_params: Optional[Union[StdioServerParameters, SSEClientParams, StreamableHTTPClientParams]] = None,
+        session: Optional[ClientSession] = None,
+        timeout_seconds: int = 10,
+        client=None,
+        include_tools: Optional[list[str]] = None,
+        exclude_tools: Optional[list[str]] = None,
+        refresh_connection: bool = False,
+        tool_name_prefix: Optional[str] = "",
+        **kwargs,
+    ):
+        """
+        Initialize the MCP toolkit.
+
+        Args:
+            session: An initialized MCP ClientSession connected to an MCP server
+            server_params: Parameters for creating a new session
+            command: The command to run to start the server. Should be used in conjunction with env.
+            url: The URL endpoint for SSE or Streamable HTTP connection when transport is "sse" or "streamable-http".
+            env: The environment variables to pass to the server. Should be used in conjunction with command.
+            client: The underlying MCP client (optional, used to prevent garbage collection)
+            timeout_seconds: Read timeout in seconds for the MCP client
+            include_tools: Optional list of tool names to include (if None, includes all)
+            exclude_tools: Optional list of tool names to exclude (if None, excludes none)
+            transport: The transport protocol to use, either "stdio" or "sse" or "streamable-http"
+            refresh_connection: If True, the connection and tools will be refreshed on each run
+        """
+        super().__init__(name="MCPTools", **kwargs)
+
+        if transport == "sse":
+            log_info("SSE as a standalone transport is deprecated. Please use Streamable HTTP instead.")
+
+        # Set these after `__init__` to bypass the `_check_tools_filters`
+        # because tools are not available until `initialize()` is called.
+        self.include_tools = include_tools
+        self.exclude_tools = exclude_tools
+        self.refresh_connection = refresh_connection
+        self.tool_name_prefix = tool_name_prefix
+
+        if session is None and server_params is None:
+            if transport == "sse" and url is None:
+                raise ValueError("One of 'url' or 'server_params' parameters must be provided when using SSE transport")
+            if transport == "stdio" and command is None:
+                raise ValueError(
+                    "One of 'command' or 'server_params' parameters must be provided when using stdio transport"
+                )
+            if transport == "streamable-http" and url is None:
+                raise ValueError(
+                    "One of 'url' or 'server_params' parameters must be provided when using Streamable HTTP transport"
+                )
+
+        # Ensure the received server_params are valid for the given transport
+        if server_params is not None:
+            if transport == "sse":
+                if not isinstance(server_params, SSEClientParams):
+                    raise ValueError(
+                        "If using the SSE transport, server_params must be an instance of SSEClientParams."
+                    )
+            elif transport == "stdio":
+                if not isinstance(server_params, StdioServerParameters):
+                    raise ValueError(
+                        "If using the stdio transport, server_params must be an instance of StdioServerParameters."
+                    )
+            elif transport == "streamable-http":
+                if not isinstance(server_params, StreamableHTTPClientParams):
+                    raise ValueError(
+                        "If using the streamable-http transport, server_params must be an instance of StreamableHTTPClientParams."
+                    )
+
+        self.timeout_seconds = timeout_seconds
+        self.session: Optional[ClientSession] = session
+        self.server_params: Optional[Union[StdioServerParameters, SSEClientParams, StreamableHTTPClientParams]] = (
+            server_params
+        )
+        self.transport = transport
+        self.url = url
+
+        # Merge provided env with system env
+        if env is not None:
+            env = {
+                **get_default_environment(),
+                **env,
+            }
+        else:
+            env = get_default_environment()
+
+        if command is not None and transport not in ["sse", "streamable-http"]:
+            parts = prepare_command(command)
+            cmd = parts[0]
+            arguments = parts[1:] if len(parts) > 1 else []
+            self.server_params = StdioServerParameters(command=cmd, args=arguments, env=env)
+
+        self._client = client
+
+        self._initialized = False
+        self._connection_task = None
+        self._active_contexts: list[Any] = []
+        self._context = None
+        self._session_context = None
+
+        def cleanup():
+            """Cancel active connections"""
+            if self._connection_task and not self._connection_task.done():
+                self._connection_task.cancel()
+
+        # Setup cleanup logic before the instance is garbage collected
+        self._cleanup_finalizer = weakref.finalize(self, cleanup)
+
+    @property
+    def initialized(self) -> bool:
+        return self._initialized
+
+    async def is_alive(self) -> bool:
+        if self.session is None:
+            return False
+        try:
+            await self.session.send_ping()
+            return True
+        except (RuntimeError, BaseException):
+            return False
+
+    async def connect(self, force: bool = False):
+        """Initialize a MCPTools instance and connect to the contextual MCP server"""
+
+        if force:
+            # Clean up the session and context so we force a new connection
+            self.session = None
+            self._context = None
+            self._session_context = None
+            self._initialized = False
+            self._connection_task = None
+            self._active_contexts = []
+
+        if self._initialized:
+            return
+
+        try:
+            await self._connect()
+        except (RuntimeError, BaseException) as e:
+            log_error(f"Failed to connect to {str(self)}: {e}")
+
+    async def _connect(self) -> None:
+        """Connects to the MCP server and initializes the tools"""
+
+        if self._initialized:
+            return
+
+        if self.session is not None:
+            await self.initialize()
+            return
+
+        # Create a new studio session
+        if self.transport == "sse":
+            sse_params = asdict(self.server_params) if self.server_params is not None else {}  # type: ignore
+            if "url" not in sse_params:
+                sse_params["url"] = self.url
+            self._context = sse_client(**sse_params)  # type: ignore
+            client_timeout = min(self.timeout_seconds, sse_params.get("timeout", self.timeout_seconds))
+
+        # Create a new streamable HTTP session
+        elif self.transport == "streamable-http":
+            streamable_http_params = asdict(self.server_params) if self.server_params is not None else {}  # type: ignore
+            if "url" not in streamable_http_params:
+                streamable_http_params["url"] = self.url
+            self._context = streamablehttp_client(**streamable_http_params)  # type: ignore
+            params_timeout = streamable_http_params.get("timeout", self.timeout_seconds)
+            if isinstance(params_timeout, timedelta):
+                params_timeout = int(params_timeout.total_seconds())
+            client_timeout = min(self.timeout_seconds, params_timeout)
+
+        else:
+            if self.server_params is None:
+                raise ValueError("server_params must be provided when using stdio transport.")
+            self._context = stdio_client(self.server_params)  # type: ignore
+            client_timeout = self.timeout_seconds
+
+        session_params = await self._context.__aenter__()  # type: ignore
+        self._active_contexts.append(self._context)
+        read, write = session_params[0:2]
+
+        self._session_context = ClientSession(read, write, read_timeout_seconds=timedelta(seconds=client_timeout))  # type: ignore
+        self.session = await self._session_context.__aenter__()  # type: ignore
+        self._active_contexts.append(self._session_context)
+
+        # Initialize with the new session
+        await self.initialize()
+
+    async def close(self) -> None:
+        """Close the MCP connection and clean up resources"""
+        if not self._initialized:
+            return
+
+        try:
+            if self._session_context is not None:
+                await self._session_context.__aexit__(None, None, None)
+                self.session = None
+                self._session_context = None
+
+            if self._context is not None:
+                await self._context.__aexit__(None, None, None)
+                self._context = None
+        except (RuntimeError, BaseException) as e:
+            log_error(f"Failed to close MCP connection: {e}")
+
+        self._initialized = False
+
+    async def __aenter__(self) -> "MCPTools":
+        await self._connect()
+        return self
+
+    async def __aexit__(self, _exc_type, _exc_val, _exc_tb):
+        """Exit the async context manager."""
+        if self._session_context is not None:
+            await self._session_context.__aexit__(_exc_type, _exc_val, _exc_tb)
+            self.session = None
+            self._session_context = None
+
+        if self._context is not None:
+            await self._context.__aexit__(_exc_type, _exc_val, _exc_tb)
+            self._context = None
+
+        self._initialized = False
+
+    async def build_tools(self) -> None:
+        """Build the tools for the MCP toolkit"""
+        if self.session is None:
+            raise ValueError("Session is not initialized")
+
+        try:
+            # Get the list of tools from the MCP server
+            available_tools = await self.session.list_tools()  # type: ignore
+
+            self._check_tools_filters(
+                available_tools=[tool.name for tool in available_tools.tools],
+                include_tools=self.include_tools,
+                exclude_tools=self.exclude_tools,
+            )
+
+            # Filter tools based on include/exclude lists
+            filtered_tools = []
+            for tool in available_tools.tools:
+                if self.exclude_tools and tool.name in self.exclude_tools:
+                    continue
+                if self.include_tools is None or tool.name in self.include_tools:
+                    filtered_tools.append(tool)
+
+            # Get tool name prefix if available
+            tool_name_prefix = ""
+            if self.tool_name_prefix is not None:
+                tool_name_prefix = self.tool_name_prefix + "_"
+
+            # Register the tools with the toolkit
+            for tool in filtered_tools:
+                try:
+                    # Get an entrypoint for the tool
+                    entrypoint = get_entrypoint_for_tool(tool, self.session)  # type: ignore
+                    # Create a Function for the tool
+                    f = Function(
+                        name=tool_name_prefix + tool.name,
+                        description=tool.description,
+                        parameters=tool.inputSchema,
+                        entrypoint=entrypoint,
+                        # Set skip_entrypoint_processing to True to avoid processing the entrypoint
+                        skip_entrypoint_processing=True,
+                    )
+
+                    # Register the Function with the toolkit
+                    self.functions[f.name] = f
+                    log_debug(f"Function: {f.name} registered with {self.name}")
+                except Exception as e:
+                    log_error(f"Failed to register tool {tool.name}: {e}")
+
+        except (RuntimeError, BaseException) as e:
+            log_error(f"Failed to get tools for {str(self)}: {e}")
+            raise
+
+    async def initialize(self) -> None:
+        """Initialize the MCP toolkit by getting available tools from the MCP server"""
+        if self._initialized:
+            return
+
+        try:
+            if self.session is None:
+                raise ValueError("Session is not initialized")
+
+            # Initialize the session if not already initialized
+            await self.session.initialize()
+
+            await self.build_tools()
+
+            self._initialized = True
+
+        except (RuntimeError, BaseException) as e:
+            log_error(f"Failed to initialize MCP toolkit: {e}")