agno 0.1.2__py3-none-any.whl → 2.3.13__py3-none-any.whl

agno/tools/whatsapp.py

@@ -0,0 +1,286 @@
+from os import getenv
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from agno.tools import Toolkit
+from agno.utils.log import logger
+
+
+class WhatsAppTools(Toolkit):
+    """WhatsApp Business API toolkit for sending messages."""
+
+    base_url = "https://graph.facebook.com"
+
+    def __init__(
+        self,
+        access_token: Optional[str] = None,
+        phone_number_id: Optional[str] = None,
+        version: Optional[str] = None,
+        recipient_waid: Optional[str] = None,
+        async_mode: bool = False,
+    ):
+        """Initialize WhatsApp toolkit.
+
+        Args:
+            access_token: WhatsApp Business API access token
+            phone_number_id: WhatsApp Business Account phone number ID
+            version: API version to use
+            recipient_waid: Default recipient WhatsApp ID (optional)
+            async_mode: Whether to use async methods (default: False)
+        """
+        # Core credentials
+        self.access_token = access_token or getenv("WHATSAPP_ACCESS_TOKEN")
+        if not self.access_token:
+            logger.error("WHATSAPP_ACCESS_TOKEN not set. Please set the WHATSAPP_ACCESS_TOKEN environment variable.")
+
+        self.phone_number_id = phone_number_id or getenv("WHATSAPP_PHONE_NUMBER_ID")
+        if not self.phone_number_id:
+            logger.error(
+                "WHATSAPP_PHONE_NUMBER_ID not set. Please set the WHATSAPP_PHONE_NUMBER_ID environment variable."
+            )
+
+        # Optional default recipient
+        self.default_recipient = recipient_waid or getenv("WHATSAPP_RECIPIENT_WAID")
+
+        # API version and mode
+        self.version = version or getenv("WHATSAPP_VERSION", "v22.0")
+        self.async_mode = async_mode
+
+        tools: List[Any] = []
+        if self.async_mode:
+            tools.append(self.send_text_message_async)
+            tools.append(self.send_template_message_async)
+        else:
+            tools.append(self.send_text_message_sync)
+            tools.append(self.send_template_message_sync)
+
+        super().__init__(name="whatsapp", tools=tools)
+
+    def _get_headers(self) -> Dict[str, str]:
+        """Get headers for API requests."""
+        return {"Authorization": f"Bearer {self.access_token}", "Content-Type": "application/json"}
+
+    def _get_messages_url(self) -> str:
+        """Get the messages endpoint URL."""
+        return f"{self.base_url}/{self.version}/{self.phone_number_id}/messages"
+
+    async def _send_message_async(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Send a message asynchronously using the WhatsApp API.
+
+        Args:
+            data: Message data to send
+
+        Returns:
+            API response as dictionary
+        """
+        url = self._get_messages_url()
+        headers = self._get_headers()
+
+        logger.debug(f"Sending WhatsApp request to URL: {url}")
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(url, headers=headers, json=data)
+
+            response.raise_for_status()
+            return response.json()
+
+    def _send_message_sync(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Send a message synchronously using the WhatsApp API.
+
+        Args:
+            data: Message data to send
+
+        Returns:
+            API response as dictionary
+        """
+        url = self._get_messages_url()
+        headers = self._get_headers()
+
+        logger.debug(f"Sending WhatsApp request to URL: {url}")
+        response = httpx.post(url, headers=headers, json=data)
+
+        response.raise_for_status()
+        return response.json()
+
+    def send_text_message_sync(
+        self,
+        text: str = "",
+        recipient: Optional[str] = None,
+        preview_url: bool = False,
+        recipient_type: str = "individual",
+    ) -> str:
+        """Send a text message to a WhatsApp user (synchronous version).
+
+        Args:
+            text: The text message to send
+            recipient: Recipient's WhatsApp ID or phone number (e.g., "+1234567890"). If not provided, uses default_recipient
+            preview_url: Whether to generate previews for links in the message
+
+        Returns:
+            Success message with message ID
+        """
+        # Use default recipient if none provided
+        if recipient is None:
+            if not self.default_recipient:
+                raise ValueError("No recipient provided and no default recipient set")
+            recipient = self.default_recipient
+            logger.debug(f"Using default recipient: {recipient}")
+
+        logger.debug(f"Sending WhatsApp message to {recipient}: {text}")
+        logger.debug(f"Current config - Phone Number ID: {self.phone_number_id}, Version: {self.version}")
+
+        data = {
+            "messaging_product": "whatsapp",
+            "recipient_type": recipient_type,
+            "to": recipient,
+            "type": "text",
+            "text": {"preview_url": preview_url, "body": text},
+        }
+
+        try:
+            response = self._send_message_sync(data)
+            message_id = response.get("messages", [{}])[0].get("id", "unknown")
+            return f"Message sent successfully! Message ID: {message_id}"
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Failed to send WhatsApp message: {e}")
+            logger.error(f"Error response: {e.response.text if hasattr(e, 'response') else 'No response text'}")
+            raise
+        except Exception as e:
+            logger.error(f"Unexpected error sending WhatsApp message: {str(e)}")
+            raise
+
+    def send_template_message_sync(
+        self,
+        recipient: Optional[str] = None,
+        template_name: str = "",
+        language_code: str = "en_US",
+        components: Optional[List[Dict[str, Any]]] = None,
+    ) -> str:
+        """Send a template message to a WhatsApp user (synchronous version).
+
+        Args:
+            recipient: Recipient's WhatsApp ID or phone number (e.g., "+1234567890"). If not provided, uses default_recipient
+            template_name: Name of the template to use
+            language_code: Language code for the template (e.g., "en_US")
+            components: Optional list of template components (header, body, buttons)
+
+        Returns:
+            Success message with message ID
+        """
+        # Use default recipient if none provided
+        if recipient is None:
+            if not self.default_recipient:
+                raise ValueError("No recipient provided and no default recipient set")
+            recipient = self.default_recipient
+
+        logger.debug(f"Sending WhatsApp template message to {recipient}: {template_name}")
+
+        data = {
+            "messaging_product": "whatsapp",
+            "to": recipient,
+            "type": "template",
+            "template": {"name": template_name, "language": {"code": language_code}},
+        }
+
+        if components:
+            data["template"]["components"] = components  # type: ignore[index]
+
+        try:
+            response = self._send_message_sync(data)
+            message_id = response.get("messages", [{}])[0].get("id", "unknown")
+            return f"Template message sent successfully! Message ID: {message_id}"
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Failed to send WhatsApp template message: {e}")
+            raise
+
+    async def send_text_message_async(
+        self,
+        text: str = "",
+        recipient: Optional[str] = None,
+        preview_url: bool = False,
+        recipient_type: str = "individual",
+    ) -> str:
+        """Send a text message to a WhatsApp user (asynchronous version).
+
+        Args:
+            text: The text message to send
+            recipient: Recipient's WhatsApp ID or phone number (e.g., "+1234567890"). If not provided, uses default_recipient
+            preview_url: Whether to generate previews for links in the message
+
+        Returns:
+            Success message with message ID
+        """
+        # Use default recipient if none provided
+        if recipient is None:
+            if not self.default_recipient:
+                raise ValueError("No recipient provided and no default recipient set")
+            recipient = self.default_recipient
+            logger.debug(f"Using default recipient: {recipient}")
+
+        logger.debug(f"Sending WhatsApp message to {recipient}: {text}")
+        logger.debug(f"Current config - Phone Number ID: {self.phone_number_id}, Version: {self.version}")
+
+        data = {
+            "messaging_product": "whatsapp",
+            "recipient_type": recipient_type,
+            "to": recipient,
+            "type": "text",
+            "text": {"preview_url": preview_url, "body": text},
+        }
+
+        try:
+            response = await self._send_message_async(data)
+            message_id = response.get("messages", [{}])[0].get("id", "unknown")
+            return f"Message sent successfully! Message ID: {message_id}"
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Failed to send WhatsApp message: {e}")
+            logger.error(f"Error response: {e.response.text if hasattr(e, 'response') else 'No response text'}")
+            raise
+        except Exception as e:
+            logger.error(f"Unexpected error sending WhatsApp message: {str(e)}")
+            raise
+
+    async def send_template_message_async(
+        self,
+        recipient: Optional[str] = None,
+        template_name: str = "",
+        language_code: str = "en_US",
+        components: Optional[List[Dict[str, Any]]] = None,
+    ) -> str:
+        """Send a template message to a WhatsApp user (asynchronous version).
+
+        Args:
+            recipient: Recipient's WhatsApp ID or phone number (e.g., "+1234567890"). If not provided, uses default_recipient
+            template_name: Name of the template to use
+            language_code: Language code for the template (e.g., "en_US")
+            components: Optional list of template components (header, body, buttons)
+
+        Returns:
+            Success message with message ID
+        """
+        # Use default recipient if none provided
+        if recipient is None:
+            if not self.default_recipient:
+                raise ValueError("No recipient provided and no default recipient set")
+            recipient = self.default_recipient
+
+        logger.debug(f"Sending WhatsApp template message to {recipient}: {template_name}")
+
+        data = {
+            "messaging_product": "whatsapp",
+            "to": recipient,
+            "type": "template",
+            "template": {"name": template_name, "language": {"code": language_code}},
+        }
+
+        if components:
+            data["template"]["components"] = components  # type: ignore[index]
+
+        try:
+            response = await self._send_message_async(data)
+            message_id = response.get("messages", [{}])[0].get("id", "unknown")
+            return f"Template message sent successfully! Message ID: {message_id}"
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Failed to send WhatsApp template message: {e}")
+            raise

agno/tools/wikipedia.py

@@ -1,21 +1,29 @@
 import json
 from typing import List, Optional
 
-from agno.document import Document
-from agno.knowledge.wikipedia import WikipediaKnowledgeBase
+from agno.knowledge.document import Document
+from agno.knowledge.knowledge import Knowledge
+from agno.knowledge.reader.wikipedia_reader import WikipediaReader
 from agno.tools import Toolkit
-from agno.utils.log import logger
+from agno.utils.log import log_debug, log_info
 
 
 class WikipediaTools(Toolkit):
-    def __init__(self, knowledge_base: Optional[WikipediaKnowledgeBase] = None):
-        super().__init__(name="wikipedia_tools")
-        self.knowledge_base: Optional[WikipediaKnowledgeBase] = knowledge_base
-
-        if self.knowledge_base is not None and isinstance(self.knowledge_base, WikipediaKnowledgeBase):
-            self.register(self.search_wikipedia_and_update_knowledge_base)
+    def __init__(
+        self,
+        knowledge: Optional[Knowledge] = None,
+        all: bool = False,
+        **kwargs,
+    ):
+        tools = []
+
+        self.knowledge: Optional[Knowledge] = knowledge
+        if self.knowledge is not None and isinstance(self.knowledge, Knowledge):
+            tools.append(self.search_wikipedia_and_update_knowledge_base)
         else:
-            self.register(self.search_wikipedia)
+            tools.append(self.search_wikipedia)  # type: ignore
+
+        super().__init__(name="wikipedia_tools", tools=tools, **kwargs)
 
     def search_wikipedia_and_update_knowledge_base(self, topic: str) -> str:
         """This function searches wikipedia for a topic, adds the results to the knowledge base and returns them.
@@ -26,15 +34,16 @@ class WikipediaTools(Toolkit):
         :return: Relevant documents from Wikipedia knowledge base.
         """
 
-        if self.knowledge_base is None:
-            return "Knowledge base not provided"
+        if self.knowledge is None:
+            return "Knowledge not provided"
 
-        logger.debug(f"Adding to knowledge base: {topic}")
-        self.knowledge_base.topics.append(topic)
-        logger.debug("Loading knowledge base.")
-        self.knowledge_base.load(recreate=False)
-        logger.debug(f"Searching knowledge base: {topic}")
-        relevant_docs: List[Document] = self.knowledge_base.search(query=topic)
+        log_debug(f"Adding to knowledge: {topic}")
+        self.knowledge.add_content(
+            topics=[topic],
+            reader=WikipediaReader(),
+        )
+        log_debug(f"Searching knowledge: {topic}")
+        relevant_docs: List[Document] = self.knowledge.search(query=topic)
         return json.dumps([doc.to_dict() for doc in relevant_docs])
 
     def search_wikipedia(self, query: str) -> str:
@@ -50,5 +59,5 @@ class WikipediaTools(Toolkit):
                 "The `wikipedia` package is not installed. Please install it via `pip install wikipedia`."
             )
 
-        logger.info(f"Searching wikipedia for: {query}")
+        log_info(f"Searching wikipedia for: {query}")
         return json.dumps(Document(name=query, content=wikipedia.summary(query)).to_dict())

agno/tools/workflow.py

@@ -0,0 +1,285 @@
+import json
+from textwrap import dedent
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, log_error
+from agno.workflow.workflow import Workflow, WorkflowRunOutput
+
+
+class RunWorkflowInput(BaseModel):
+    input_data: str = Field(..., description="The input data for the workflow.")
+    additional_data: Optional[Dict[str, Any]] = Field(default=None, description="The additional data for the workflow.")
+
+
+class WorkflowTools(Toolkit):
+    def __init__(
+        self,
+        workflow: Workflow,
+        enable_run_workflow: bool = True,
+        enable_think: bool = False,
+        enable_analyze: bool = False,
+        all: bool = False,
+        instructions: Optional[str] = None,
+        add_instructions: bool = True,
+        add_few_shot: bool = False,
+        few_shot_examples: Optional[str] = None,
+        async_mode: bool = False,
+        **kwargs,
+    ):
+        # Add instructions for using this toolkit
+        if instructions is None:
+            self.instructions = self.DEFAULT_INSTRUCTIONS
+            if add_few_shot:
+                if few_shot_examples is not None:
+                    self.instructions += "\n" + few_shot_examples
+        else:
+            self.instructions = instructions
+
+        # The workflow to execute
+        self.workflow: Workflow = workflow
+
+        super().__init__(
+            name="workflow_tools",
+            instructions=self.instructions,
+            add_instructions=add_instructions,
+            auto_register=False,
+            **kwargs,
+        )
+
+        if enable_think or all:
+            if async_mode:
+                self.register(self.async_think, name="think")
+            else:
+                self.register(self.think, name="think")
+        if enable_run_workflow or all:
+            if async_mode:
+                self.register(self.async_run_workflow, name="run_workflow")
+            else:
+                self.register(self.run_workflow, name="run_workflow")
+        if enable_analyze or all:
+            if async_mode:
+                self.register(self.async_analyze, name="analyze")
+            else:
+                self.register(self.analyze, name="analyze")
+
+    def think(self, session_state: Dict[str, Any], thought: str) -> str:
+        """Use this tool as a scratchpad to reason about the workflow execution, refine your approach, brainstorm workflow inputs, or revise your plan.
+        Call `Think` whenever you need to figure out what to do next, analyze the user's requirements, plan workflow inputs, or decide on execution strategy.
+        You should use this tool as frequently as needed.
+        Args:
+            thought: Your thought process and reasoning about workflow execution.
+        """
+        try:
+            log_debug(f"Workflow Thought: {thought}")
+
+            # Add the thought to the session state
+            if session_state is None:
+                session_state = {}
+            if "workflow_thoughts" not in session_state:
+                session_state["workflow_thoughts"] = []
+            session_state["workflow_thoughts"].append(thought)
+
+            # Return the full log of thoughts and the new thought
+            thoughts = "\n".join([f"- {t}" for t in session_state["workflow_thoughts"]])
+            formatted_thoughts = dedent(
+                f"""Workflow Thoughts:
+                {thoughts}
+                """
+            ).strip()
+            return formatted_thoughts
+        except Exception as e:
+            log_error(f"Error recording workflow thought: {e}")
+            return f"Error recording workflow thought: {e}"
+
+    async def async_think(self, session_state: Dict[str, Any], thought: str) -> str:
+        """Use this tool as a scratchpad to reason about the workflow execution, refine your approach, brainstorm workflow inputs, or revise your plan.
+        Call `Think` whenever you need to figure out what to do next, analyze the user's requirements, plan workflow inputs, or decide on execution strategy.
+        You should use this tool as frequently as needed.
+        Args:
+            thought: Your thought process and reasoning about workflow execution.
+        """
+        try:
+            log_debug(f"Workflow Thought: {thought}")
+
+            # Add the thought to the session state
+            if session_state is None:
+                session_state = {}
+            if "workflow_thoughts" not in session_state:
+                session_state["workflow_thoughts"] = []
+            session_state["workflow_thoughts"].append(thought)
+
+            # Return the full log of thoughts and the new thought
+            thoughts = "\n".join([f"- {t}" for t in session_state["workflow_thoughts"]])
+            formatted_thoughts = dedent(
+                f"""Workflow Thoughts:
+                {thoughts}
+                """
+            ).strip()
+            return formatted_thoughts
+        except Exception as e:
+            log_error(f"Error recording workflow thought: {e}")
+            return f"Error recording workflow thought: {e}"
+
+    def run_workflow(
+        self,
+        session_state: Dict[str, Any],
+        input: RunWorkflowInput,
+    ) -> str:
+        """Use this tool to execute the workflow with the specified inputs and parameters.
+        After thinking through the requirements, use this tool to run the workflow with appropriate inputs.
+
+        Args:
+            input: The input data for the workflow.
+        """
+        if isinstance(input, dict):
+            input = RunWorkflowInput.model_validate(input)
+
+        try:
+            log_debug(f"Running workflow with input: {input.input_data}")
+
+            user_id = session_state.get("current_user_id")
+            session_id = session_state.get("current_session_id")
+
+            # Execute the workflow
+            result: WorkflowRunOutput = self.workflow.run(
+                input=input.input_data,
+                user_id=user_id,
+                session_id=session_id,
+                session_state=session_state,
+                additional_data=input.additional_data,
+            )
+
+            if "workflow_results" not in session_state:
+                session_state["workflow_results"] = []
+
+            session_state["workflow_results"].append(result.to_dict())
+
+            return json.dumps(result.to_dict(), indent=2)
+
+        except Exception as e:
+            log_error(f"Error running workflow: {e}")
+            return f"Error running workflow: {e}"
+
+    async def async_run_workflow(
+        self,
+        session_state: Dict[str, Any],
+        input: RunWorkflowInput,
+    ) -> str:
+        """Use this tool to execute the workflow with the specified inputs and parameters.
+        After thinking through the requirements, use this tool to run the workflow with appropriate inputs.
+        Args:
+            input_data: The input data for the workflow (use a `str` for a simple input)
+            additional_data: The additional data for the workflow. This is a dictionary of key-value pairs that will be passed to the workflow. E.g. {"topic": "food", "style": "Humour"}
+        """
+        if isinstance(input, dict):
+            input = RunWorkflowInput.model_validate(input)
+
+        try:
+            log_debug(f"Running workflow with input: {input.input_data}")
+
+            user_id = session_state.get("current_user_id")
+            session_id = session_state.get("current_session_id")
+
+            # Execute the workflow
+            result: WorkflowRunOutput = await self.workflow.arun(
+                input=input.input_data,
+                user_id=user_id,
+                session_id=session_id,
+                session_state=session_state,
+                additional_data=input.additional_data,
+            )
+
+            if "workflow_results" not in session_state:
+                session_state["workflow_results"] = []
+
+            session_state["workflow_results"].append(result.to_dict())
+
+            return json.dumps(result.to_dict(), indent=2)
+
+        except Exception as e:
+            log_error(f"Error running workflow: {e}")
+            return f"Error running workflow: {e}"
+
+    def analyze(self, session_state: Dict[str, Any], analysis: str) -> str:
+        """Use this tool to evaluate whether the workflow execution results are correct and sufficient.
+        If not, go back to "Think" or "Run" with refined inputs or parameters.
+        Args:
+            analysis: Your analysis of the workflow execution results.
+        """
+        try:
+            log_debug(f"Workflow Analysis: {analysis}")
+
+            # Add the analysis to the session state
+            if session_state is None:
+                session_state = {}
+            if "workflow_analysis" not in session_state:
+                session_state["workflow_analysis"] = []
+            session_state["workflow_analysis"].append(analysis)
+
+            # Return the full log of analysis and the new analysis
+            analysis_log = "\n".join([f"- {a}" for a in session_state["workflow_analysis"]])
+            formatted_analysis = dedent(
+                f"""Workflow Analysis:
+                {analysis_log}
+                """
+            ).strip()
+            return formatted_analysis
+        except Exception as e:
+            log_error(f"Error recording workflow analysis: {e}")
+            return f"Error recording workflow analysis: {e}"
+
+    async def async_analyze(self, session_state: Dict[str, Any], analysis: str) -> str:
+        """Use this tool to evaluate whether the workflow execution results are correct and sufficient.
+        If not, go back to "Think" or "Run" with refined inputs or parameters.
+        Args:
+            analysis: Your analysis of the workflow execution results.
+        """
+        try:
+            log_debug(f"Workflow Analysis: {analysis}")
+
+            # Add the analysis to the session state
+            if session_state is None:
+                session_state = {}
+            if "workflow_analysis" not in session_state:
+                session_state["workflow_analysis"] = []
+            session_state["workflow_analysis"].append(analysis)
+
+            # Return the full log of analysis and the new analysis
+            analysis_log = "\n".join([f"- {a}" for a in session_state["workflow_analysis"]])
+            formatted_analysis = dedent(
+                f"""Workflow Analysis:
+                {analysis_log}
+                """
+            ).strip()
+            return formatted_analysis
+        except Exception as e:
+            log_error(f"Error recording workflow analysis: {e}")
+            return f"Error recording workflow analysis: {e}"
+
+    DEFAULT_INSTRUCTIONS = dedent("""\
+        You have access to the Think, Run Workflow, and Analyze tools that will help you execute workflows and analyze their results. Use these tools as frequently as needed to successfully complete workflow-based tasks.
+        ## How to use the Think, Run Workflow, and Analyze tools:
+        
+        1. **Think**
+        - Purpose: A scratchpad for planning workflow execution, brainstorming inputs, and refining your approach. You never reveal your "Think" content to the user.
+        - Usage: Call `think` whenever you need to figure out what workflow inputs to use, analyze requirements, or decide on execution strategy before (or after) you run the workflow.
+        2. **Run Workflow**
+        - Purpose: Executes the workflow with specified inputs and parameters.
+        - Usage: Call `run_workflow` with appropriate input data whenever you want to execute the workflow.
+            - For all workflows, start with simple inputs and gradually increase complexity
+        3. **Analyze**
+        - Purpose: Evaluate whether the workflow execution results are correct and sufficient. If not, go back to "Think" or "Run Workflow" with refined inputs.
+        - Usage: Call `analyze` after getting workflow results to verify the quality and correctness of the execution. Consider:
+            - Completeness: Did the workflow complete all expected steps?
+            - Quality: Are the results accurate and meet the requirements?
+            - Errors: Were there any failures or unexpected behaviors?
+        **Important Guidelines**:
+        - Do not include your internal chain-of-thought in direct user responses.
+        - Use "Think" to reason internally. These notes are never exposed to the user.
+        - When you provide a final answer to the user, be clear, concise, and based on the workflow results.
+        - If workflow execution fails or produces unexpected results, acknowledge limitations and explain what went wrong.
+        - Synthesize information from multiple workflow runs if you execute the workflow several times with different inputs.\
+    """)