agno 2.4.2__py3-none-any.whl → 2.4.4__py3-none-any.whl

agno/tools/function.py

@@ -121,6 +121,9 @@ class Function(BaseModel):
     # If True, the function will be executed outside the agent's control.
     external_execution: Optional[bool] = None
 
+    # If True (and external_execution=True), the function will not produce verbose paused messages (e.g., "I have tools to execute...")
+    external_execution_silent: Optional[bool] = None
+
     # Caching configuration
     cache_results: bool = False
     cache_dir: Optional[str] = None

agno/tools/unsplash.py

@@ -0,0 +1,341 @@
+"""Unsplash Tools for searching and retrieving high-quality, royalty-free images.
+
+This toolkit provides AI agents with the ability to search for and retrieve images
+from Unsplash, a popular platform with over 4.3 million high-quality photos.
+
+Get your free API key at: https://unsplash.com/developers
+"""
+
+import json
+from os import getenv
+from typing import Any, Dict, List, Optional
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from agno.tools import Toolkit
+from agno.utils.log import log_debug, logger
+
+
+class UnsplashTools(Toolkit):
+    """A toolkit for searching and retrieving images from Unsplash.
+
+    Unsplash provides access to over 4.3 million high-quality, royalty-free images
+    that can be used for various purposes. This toolkit enables AI agents to:
+    - Search for photos by keywords
+    - Get detailed information about specific photos
+    - Retrieve random photos with optional filters
+    - Track downloads (required by Unsplash API guidelines)
+
+    Example:
+        ```python
+        from agno.agent import Agent
+        from agno.models.openai import OpenAIChat
+        from agno.tools.unsplash import UnsplashTools
+
+        agent = Agent(
+            model=OpenAIChat(id="gpt-4o"),
+            tools=[UnsplashTools()],
+        )
+        agent.print_response("Find me 3 photos of mountains at sunset")
+        ```
+    """
+
+    def __init__(
+        self,
+        access_key: Optional[str] = None,
+        enable_search_photos: bool = True,
+        enable_get_photo: bool = True,
+        enable_get_random_photo: bool = True,
+        enable_download_photo: bool = False,
+        all: bool = False,
+        **kwargs: Any,
+    ):
+        """Initialize the Unsplash toolkit.
+
+        Args:
+            access_key: Unsplash API access key. If not provided, will look for
+                UNSPLASH_ACCESS_KEY environment variable.
+            enable_search_photos: Enable the search_photos tool. Default: True.
+            enable_get_photo: Enable the get_photo tool. Default: True.
+            enable_get_random_photo: Enable the get_random_photo tool. Default: True.
+            enable_download_photo: Enable the download_photo tool. Default: False.
+            all: Enable all tools. Default: False.
+            **kwargs: Additional arguments passed to the Toolkit base class.
+        """
+        self.access_key = access_key or getenv("UNSPLASH_ACCESS_KEY")
+        if not self.access_key:
+            logger.warning("No Unsplash API key provided. Set UNSPLASH_ACCESS_KEY environment variable.")
+
+        self.base_url = "https://api.unsplash.com"
+
+        tools: List[Any] = []
+        if all or enable_search_photos:
+            tools.append(self.search_photos)
+        if all or enable_get_photo:
+            tools.append(self.get_photo)
+        if all or enable_get_random_photo:
+            tools.append(self.get_random_photo)
+        if all or enable_download_photo:
+            tools.append(self.download_photo)
+
+        super().__init__(name="unsplash_tools", tools=tools, **kwargs)
+
+    def _make_request(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Make an authenticated request to the Unsplash API.
+
+        Args:
+            endpoint: API endpoint path (e.g., "/search/photos").
+            params: Optional query parameters.
+
+        Returns:
+            JSON response as a dictionary.
+
+        Raises:
+            Exception: If the API request fails.
+        """
+        url = f"{self.base_url}{endpoint}"
+        if params:
+            url = f"{url}?{urlencode(params)}"
+
+        headers = {
+            "Authorization": f"Client-ID {self.access_key}",
+            "Accept-Version": "v1",
+        }
+
+        request = Request(url, headers=headers)
+        with urlopen(request) as response:
+            return json.loads(response.read().decode())
+
+    def _format_photo(self, photo: Dict[str, Any]) -> Dict[str, Any]:
+        """Format photo data into a clean, consistent structure.
+
+        Args:
+            photo: Raw photo data from Unsplash API.
+
+        Returns:
+            Formatted photo dictionary with essential fields.
+        """
+        return {
+            "id": photo.get("id"),
+            "description": photo.get("description") or photo.get("alt_description"),
+            "width": photo.get("width"),
+            "height": photo.get("height"),
+            "color": photo.get("color"),
+            "created_at": photo.get("created_at"),
+            "urls": {
+                "raw": photo.get("urls", {}).get("raw"),
+                "full": photo.get("urls", {}).get("full"),
+                "regular": photo.get("urls", {}).get("regular"),
+                "small": photo.get("urls", {}).get("small"),
+                "thumb": photo.get("urls", {}).get("thumb"),
+            },
+            "author": {
+                "name": photo.get("user", {}).get("name"),
+                "username": photo.get("user", {}).get("username"),
+                "profile_url": photo.get("user", {}).get("links", {}).get("html"),
+            },
+            "links": {
+                "html": photo.get("links", {}).get("html"),
+                "download": photo.get("links", {}).get("download"),
+            },
+            "likes": photo.get("likes"),
+            "tags": [tag.get("title") for tag in photo.get("tags", [])[:5] if tag.get("title")],
+        }
+
+    def search_photos(
+        self,
+        query: str,
+        per_page: int = 10,
+        page: int = 1,
+        orientation: Optional[str] = None,
+        color: Optional[str] = None,
+    ) -> str:
+        """Search for photos on Unsplash by keyword.
+
+        Args:
+            query: The search query string (e.g., "mountain sunset", "office workspace").
+            per_page: Number of results per page (1-30). Default: 10.
+            page: Page number to retrieve. Default: 1.
+            orientation: Filter by orientation: "landscape", "portrait", or "squarish".
+            color: Filter by color: "black_and_white", "black", "white", "yellow",
+                "orange", "red", "purple", "magenta", "green", "teal", "blue".
+
+        Returns:
+            JSON string containing search results with photo details including
+            URLs, author information, and metadata.
+        """
+        if not self.access_key:
+            return "Error: No Unsplash API key provided. Set UNSPLASH_ACCESS_KEY environment variable."
+
+        if not query:
+            return "Error: Please provide a search query."
+
+        log_debug(f"Searching Unsplash for: {query}")
+
+        try:
+            params: Dict[str, Any] = {
+                "query": query,
+                "per_page": min(max(1, per_page), 30),
+                "page": max(1, page),
+            }
+
+            if orientation and orientation in ["landscape", "portrait", "squarish"]:
+                params["orientation"] = orientation
+
+            if color:
+                valid_colors = [
+                    "black_and_white",
+                    "black",
+                    "white",
+                    "yellow",
+                    "orange",
+                    "red",
+                    "purple",
+                    "magenta",
+                    "green",
+                    "teal",
+                    "blue",
+                ]
+                if color in valid_colors:
+                    params["color"] = color
+
+            response = self._make_request("/search/photos", params)
+
+            results = {
+                "total": response.get("total", 0),
+                "total_pages": response.get("total_pages", 0),
+                "photos": [self._format_photo(photo) for photo in response.get("results", [])],
+            }
+
+            return json.dumps(results, indent=2)
+
+        except Exception as e:
+            return f"Error searching Unsplash: {e}"
+
+    def get_photo(self, photo_id: str) -> str:
+        """Get detailed information about a specific photo.
+
+        Args:
+            photo_id: The unique identifier of the photo.
+
+        Returns:
+            JSON string containing detailed photo information including
+            URLs, author, metadata, EXIF data, and location if available.
+        """
+        if not self.access_key:
+            return "Error: No Unsplash API key provided. Set UNSPLASH_ACCESS_KEY environment variable."
+
+        if not photo_id:
+            return "Error: Please provide a photo ID."
+
+        log_debug(f"Getting Unsplash photo: {photo_id}")
+
+        try:
+            photo = self._make_request(f"/photos/{photo_id}")
+
+            result = self._format_photo(photo)
+
+            # Add extra details available for single photo requests
+            if photo.get("exif"):
+                result["exif"] = {
+                    "make": photo["exif"].get("make"),
+                    "model": photo["exif"].get("model"),
+                    "aperture": photo["exif"].get("aperture"),
+                    "exposure_time": photo["exif"].get("exposure_time"),
+                    "focal_length": photo["exif"].get("focal_length"),
+                    "iso": photo["exif"].get("iso"),
+                }
+
+            if photo.get("location"):
+                result["location"] = {
+                    "name": photo["location"].get("name"),
+                    "city": photo["location"].get("city"),
+                    "country": photo["location"].get("country"),
+                }
+
+            result["views"] = photo.get("views")
+            result["downloads"] = photo.get("downloads")
+
+            return json.dumps(result, indent=2)
+
+        except Exception as e:
+            return f"Error getting photo: {e}"
+
+    def get_random_photo(
+        self,
+        query: Optional[str] = None,
+        orientation: Optional[str] = None,
+        count: int = 1,
+    ) -> str:
+        """Get random photo(s) from Unsplash.
+
+        Args:
+            query: Optional search query to filter random photos.
+            orientation: Filter by orientation: "landscape", "portrait", or "squarish".
+            count: Number of random photos to return (1-30). Default: 1.
+
+        Returns:
+            JSON string containing random photo(s) data.
+        """
+        if not self.access_key:
+            return "Error: No Unsplash API key provided. Set UNSPLASH_ACCESS_KEY environment variable."
+
+        log_debug(f"Getting random Unsplash photo (query={query})")
+
+        try:
+            params: Dict[str, Any] = {
+                "count": min(max(1, count), 30),
+            }
+
+            if query:
+                params["query"] = query
+
+            if orientation and orientation in ["landscape", "portrait", "squarish"]:
+                params["orientation"] = orientation
+
+            response = self._make_request("/photos/random", params)
+
+            # Response is a list when count > 1, single object when count = 1
+            if isinstance(response, list):
+                photos = [self._format_photo(photo) for photo in response]
+            else:
+                photos = [self._format_photo(response)]
+
+            return json.dumps({"photos": photos}, indent=2)
+
+        except Exception as e:
+            return f"Error getting random photo: {e}"
+
+    def download_photo(self, photo_id: str) -> str:
+        """Trigger a download event for a photo.
+
+        This is required by the Unsplash API guidelines when a photo is downloaded
+        or used. It helps photographers track the usage of their work.
+
+        Args:
+            photo_id: The unique identifier of the photo being downloaded.
+
+        Returns:
+            JSON string with the download URL.
+        """
+        if not self.access_key:
+            return "Error: No Unsplash API key provided. Set UNSPLASH_ACCESS_KEY environment variable."
+
+        if not photo_id:
+            return "Error: Please provide a photo ID."
+
+        log_debug(f"Tracking download for Unsplash photo: {photo_id}")
+
+        try:
+            response = self._make_request(f"/photos/{photo_id}/download")
+
+            return json.dumps(
+                {
+                    "photo_id": photo_id,
+                    "download_url": response.get("url"),
+                },
+                indent=2,
+            )
+
+        except Exception as e:
+            return f"Error tracking download: {e}"

agno/utils/print_response/agent.py

@@ -105,8 +105,9 @@ def print_response_stream(
                 if response_event.is_paused:  # type: ignore
                     response_event = cast(RunPausedEvent, response_event)  # type: ignore
                     response_panel = create_paused_run_output_panel(response_event)  # type: ignore
-                    panels.append(response_panel)
-                    live_log.update(Group(*panels))
+                    if response_panel is not None:
+                        panels.append(response_panel)
+                        live_log.update(Group(*panels))
                     return
 
                 if response_event.event == RunEvent.pre_hook_completed:  # type: ignore
@@ -310,8 +311,9 @@ async def aprint_response_stream(
             if isinstance(resp, tuple(get_args(RunOutputEvent))):
                 if resp.is_paused:
                     response_panel = create_paused_run_output_panel(resp)  # type: ignore
-                    panels.append(response_panel)
-                    live_log.update(Group(*panels))
+                    if response_panel is not None:
+                        panels.append(response_panel)
+                        live_log.update(Group(*panels))
                     break
 
                 if (
@@ -798,7 +800,8 @@ def build_panels(
 
     if isinstance(run_response, RunOutput) and run_response.is_paused:
         response_panel = create_paused_run_output_panel(run_response)
-        panels.append(response_panel)
+        if response_panel is not None:
+            panels.append(response_panel)
         return panels
 
     if isinstance(run_response, RunOutput) and run_response.reasoning_steps is not None:

agno/utils/response.py

@@ -80,35 +80,41 @@ def format_tool_calls(tool_calls: List[ToolExecution]) -> List[str]:
 def create_paused_run_output_panel(run_output: Union[RunPausedEvent, RunOutput]):
     from rich.text import Text
 
+    # Filter out silent tools - they don't produce verbose output
+    non_silent_tools = [tc for tc in (run_output.tools or []) if not tc.external_execution_silent]
+
+    # If all tools are silent, return None to indicate no panel should be shown
+    if not non_silent_tools:
+        return None
+
     tool_calls_content = Text("Run is paused. ")
-    if run_output.tools is not None:
-        if any(tc.requires_confirmation for tc in run_output.tools):
-            tool_calls_content.append("The following tool calls require confirmation:\n")
-        for tool_call in run_output.tools:
-            if tool_call.requires_confirmation:
-                args_str = ""
-                for arg, value in tool_call.tool_args.items() if tool_call.tool_args else {}:
-                    args_str += f"{arg}={value}, "
-                args_str = args_str.rstrip(", ")
-                tool_calls_content.append(f"• {tool_call.tool_name}({args_str})\n")
-        if any(tc.requires_user_input for tc in run_output.tools):
-            tool_calls_content.append("The following tool calls require user input:\n")
-        for tool_call in run_output.tools:
-            if tool_call.requires_user_input:
-                args_str = ""
-                for arg, value in tool_call.tool_args.items() if tool_call.tool_args else {}:
-                    args_str += f"{arg}={value}, "
-                args_str = args_str.rstrip(", ")
-                tool_calls_content.append(f"• {tool_call.tool_name}({args_str})\n")
-        if any(tc.external_execution_required for tc in run_output.tools):
-            tool_calls_content.append("The following tool calls require external execution:\n")
-        for tool_call in run_output.tools:
-            if tool_call.external_execution_required:
-                args_str = ""
-                for arg, value in tool_call.tool_args.items() if tool_call.tool_args else {}:
-                    args_str += f"{arg}={value}, "
-                args_str = args_str.rstrip(", ")
-                tool_calls_content.append(f"• {tool_call.tool_name}({args_str})\n")
+    if any(tc.requires_confirmation for tc in non_silent_tools):
+        tool_calls_content.append("The following tool calls require confirmation:\n")
+    for tool_call in non_silent_tools:
+        if tool_call.requires_confirmation:
+            args_str = ""
+            for arg, value in tool_call.tool_args.items() if tool_call.tool_args else {}:
+                args_str += f"{arg}={value}, "
+            args_str = args_str.rstrip(", ")
+            tool_calls_content.append(f"• {tool_call.tool_name}({args_str})\n")
+    if any(tc.requires_user_input for tc in non_silent_tools):
+        tool_calls_content.append("The following tool calls require user input:\n")
+    for tool_call in non_silent_tools:
+        if tool_call.requires_user_input:
+            args_str = ""
+            for arg, value in tool_call.tool_args.items() if tool_call.tool_args else {}:
+                args_str += f"{arg}={value}, "
+            args_str = args_str.rstrip(", ")
+            tool_calls_content.append(f"• {tool_call.tool_name}({args_str})\n")
+    if any(tc.external_execution_required for tc in non_silent_tools):
+        tool_calls_content.append("The following tool calls require external execution:\n")
+    for tool_call in non_silent_tools:
+        if tool_call.external_execution_required:
+            args_str = ""
+            for arg, value in tool_call.tool_args.items() if tool_call.tool_args else {}:
+                args_str += f"{arg}={value}, "
+            args_str = args_str.rstrip(", ")
+            tool_calls_content.append(f"• {tool_call.tool_name}({args_str})\n")
 
     # Create panel for response
     response_panel = create_panel(
@@ -122,6 +128,10 @@ def create_paused_run_output_panel(run_output: Union[RunPausedEvent, RunOutput])
 def get_paused_content(run_output: RunOutput) -> str:
     paused_content = ""
     for tool in run_output.tools or []:
+        # Skip silent tools - they don't produce verbose paused messages
+        if tool.external_execution_silent:
+            continue
+
         # Initialize flags for each tool
         confirmation_required = False
         user_input_required = False

agno/utils/string.py

@@ -89,7 +89,8 @@ def _clean_json_content(content: str) -> str:
     if "```json" in content:
         content = content.split("```json")[-1].strip()
         parts = content.split("```")
-        parts.pop(-1)
+        if len(parts) > 1:
+            parts.pop(-1)
         content = "".join(parts)
     elif "```" in content:
         content = content.split("```")[1].strip()

agno/vectordb/lancedb/lance_db.py

@@ -282,9 +282,10 @@ class LanceDb(VectorDb):
                 meta_data.update(filters)
                 document.meta_data = meta_data
 
-            # Only embed if the document doesn't already have an embedding
+            # Only embed if the document doesn't already have a valid embedding
             # This prevents duplicate embedding when called from async_insert or async_upsert
-            if document.embedding is None:
+            # Check for both None and empty list (async embedding failures return [])
+            if document.embedding is None or (isinstance(document.embedding, list) and len(document.embedding) == 0):
                 document.embed(embedder=self.embedder)
             cleaned_content = document.content.replace("\x00", "\ufffd")
             # Include content_hash in ID to ensure uniqueness across different content hashes
@@ -363,12 +364,21 @@ class LanceDb(VectorDb):
                 else:
                     logger.warning(f"Async batch embedding failed, falling back to individual embeddings: {e}")
                     embed_tasks = [doc.async_embed(embedder=self.embedder) for doc in documents]
-                    await asyncio.gather(*embed_tasks, return_exceptions=True)
+                    results = await asyncio.gather(*embed_tasks, return_exceptions=True)
+                    # Log any embedding failures (they will be re-tried in sync insert)
+                    for i, result in enumerate(results):
+                        if isinstance(result, Exception):
+                            log_warning(f"Async embedding failed for document {i}, will retry in sync insert: {result}")
         else:
             embed_tasks = [doc.async_embed(embedder=self.embedder) for doc in documents]
-            await asyncio.gather(*embed_tasks, return_exceptions=True)
+            results = await asyncio.gather(*embed_tasks, return_exceptions=True)
+            # Log any embedding failures (they will be re-tried in sync insert)
+            for i, result in enumerate(results):
+                if isinstance(result, Exception):
+                    log_warning(f"Async embedding failed for document {i}, will retry in sync insert: {result}")
 
         # Use sync insert to avoid sync/async table synchronization issues
+        # Sync insert will re-embed any documents that failed async embedding
         self.insert(content_hash, documents, filters)
 
     def upsert_available(self) -> bool:
@@ -414,13 +424,25 @@ class LanceDb(VectorDb):
                     if is_rate_limit:
                         raise e
                     else:
+                        logger.warning(f"Async batch embedding failed, falling back to individual embeddings: {e}")
                         embed_tasks = [doc.async_embed(embedder=self.embedder) for doc in documents]
-                        await asyncio.gather(*embed_tasks, return_exceptions=True)
+                        results = await asyncio.gather(*embed_tasks, return_exceptions=True)
+                        # Log any embedding failures (they will be re-tried in sync upsert)
+                        for i, result in enumerate(results):
+                            if isinstance(result, Exception):
+                                log_warning(
+                                    f"Async embedding failed for document {i}, will retry in sync upsert: {result}"
+                                )
             else:
                 embed_tasks = [doc.async_embed(embedder=self.embedder) for doc in documents]
-                await asyncio.gather(*embed_tasks, return_exceptions=True)
+                results = await asyncio.gather(*embed_tasks, return_exceptions=True)
+                # Log any embedding failures (they will be re-tried in sync upsert)
+                for i, result in enumerate(results):
+                    if isinstance(result, Exception):
+                        log_warning(f"Async embedding failed for document {i}, will retry in sync upsert: {result}")
 
         # Use sync upsert for reliability
+        # Sync upsert (via insert) will re-embed any documents that failed async embedding
         self.upsert(content_hash=content_hash, documents=documents, filters=filters)
 
     def search(
@@ -897,7 +919,7 @@ class LanceDb(VectorDb):
 
             # Get all documents and filter in Python (LanceDB doesn't support JSON operators)
             total_count = self.table.count_rows()
-            results = self.table.search().select(["id", "payload"]).limit(total_count).to_pandas()
+            results = self.table.search().select(["id", "payload", "vector"]).limit(total_count).to_pandas()
 
             if results.empty:
                 logger.debug("No documents found")

agno/workflow/workflow.py

@@ -3822,6 +3822,7 @@ class Workflow:
         stream_events: Optional[bool] = None,
         background: Optional[bool] = False,
         background_tasks: Optional[Any] = None,
+        dependencies: Optional[Dict[str, Any]] = None,
     ) -> WorkflowRunOutput: ...
 
     @overload
@@ -3841,6 +3842,7 @@ class Workflow:
         stream_events: Optional[bool] = None,
         background: Optional[bool] = False,
         background_tasks: Optional[Any] = None,
+        dependencies: Optional[Dict[str, Any]] = None,
     ) -> Iterator[WorkflowRunOutputEvent]: ...
 
     def run(
@@ -3855,10 +3857,11 @@ class Workflow:
         images: Optional[List[Image]] = None,
         videos: Optional[List[Video]] = None,
         files: Optional[List[File]] = None,
-        stream: bool = False,
+        stream: Optional[bool] = None,
         stream_events: Optional[bool] = None,
         background: Optional[bool] = False,
         background_tasks: Optional[Any] = None,
+        dependencies: Optional[Dict[str, Any]] = None,
         **kwargs: Any,
     ) -> Union[WorkflowRunOutput, Iterator[WorkflowRunOutputEvent]]:
         """Execute the workflow synchronously with optional streaming"""
@@ -3901,8 +3904,9 @@ class Workflow:
 
         log_debug(f"Workflow Run Start: {self.name}", center=True)
 
-        # Use simple defaults
-        stream = stream or self.stream or False
+        # Use stream override value when necessary
+        if stream is None:
+            stream = self.stream or False
         stream_events = stream_events or self.stream_events
 
         # Can't stream events if streaming is disabled
@@ -3937,6 +3941,7 @@ class Workflow:
             session_state=session_state,
             workflow_id=self.id,
             workflow_name=self.name,
+            dependencies=dependencies,
         )
 
         # Execute workflow agent if configured
@@ -4004,6 +4009,7 @@ class Workflow:
         background: Optional[bool] = False,
         websocket: Optional[WebSocket] = None,
         background_tasks: Optional[Any] = None,
+        dependencies: Optional[Dict[str, Any]] = None,
     ) -> WorkflowRunOutput: ...
 
     @overload
@@ -4024,6 +4030,7 @@ class Workflow:
         background: Optional[bool] = False,
         websocket: Optional[WebSocket] = None,
         background_tasks: Optional[Any] = None,
+        dependencies: Optional[Dict[str, Any]] = None,
     ) -> AsyncIterator[WorkflowRunOutputEvent]: ...
 
     def arun(  # type: ignore
@@ -4038,11 +4045,12 @@ class Workflow:
         images: Optional[List[Image]] = None,
         videos: Optional[List[Video]] = None,
         files: Optional[List[File]] = None,
-        stream: bool = False,
+        stream: Optional[bool] = None,
         stream_events: Optional[bool] = None,
         background: Optional[bool] = False,
         websocket: Optional[WebSocket] = None,
         background_tasks: Optional[Any] = None,
+        dependencies: Optional[Dict[str, Any]] = None,
         **kwargs: Any,
     ) -> Union[WorkflowRunOutput, AsyncIterator[WorkflowRunOutputEvent]]:
         """Execute the workflow synchronously with optional streaming"""
@@ -4108,12 +4116,14 @@ class Workflow:
             session_id=session_id,
             user_id=user_id,
             session_state=session_state,
+            dependencies=dependencies,
         )
 
         log_debug(f"Async Workflow Run Start: {self.name}", center=True)
 
-        # Use simple defaults
-        stream = stream or self.stream or False
+        # Use stream override value when necessary
+        if stream is None:
+            stream = self.stream or False
         stream_events = stream_events or self.stream_events
 
         # Can't stream events if streaming is disabled