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

agno/knowledge/reader/field_labeled_csv_reader.py

@@ -2,7 +2,7 @@ import asyncio
 import csv
 import io
 from pathlib import Path
-from typing import IO, Any, Iterable, List, Optional, Sequence, Tuple, Union
+from typing import IO, Any, List, Optional, Union
 
 try:
     import aiofiles
@@ -12,12 +12,7 @@ except ImportError:
 from agno.knowledge.chunking.strategy import ChunkingStrategyType
 from agno.knowledge.document.base import Document
 from agno.knowledge.reader.base import Reader
-from agno.knowledge.reader.csv_reader import (
-    _convert_xls_cell_value,
-    _get_workbook_name,
-    _infer_file_extension,
-    _stringify_spreadsheet_cell_value,
-)
+from agno.knowledge.reader.utils import stringify_cell_value
 from agno.knowledge.types import ContentType
 from agno.utils.log import log_debug, log_error, log_warning
 
@@ -47,7 +42,7 @@ class FieldLabeledCSVReader(Reader):
     @classmethod
     def get_supported_content_types(cls) -> List[ContentType]:
         """Get the list of supported content types."""
-        return [ContentType.CSV, ContentType.XLSX, ContentType.XLS]
+        return [ContentType.CSV]
 
     def _format_field_name(self, field_name: str) -> str:
         """Format field name to be more readable."""
@@ -72,17 +67,7 @@ class FieldLabeledCSVReader(Reader):
         return None
 
     def _convert_row_to_labeled_text(self, headers: List[str], row: List[str], entry_index: int) -> str:
-        """
-        Convert a CSV row to field-labeled text format.
-
-        Args:
-            headers: Column headers
-            row: Data row values
-            entry_index: Index of this entry (for title rotation)
-
-        Returns:
-            Formatted text with field labels
-        """
+        """Convert a CSV row to field-labeled text format."""
         lines = []
 
         title = self._get_title_for_entry(entry_index)
@@ -91,7 +76,7 @@ class FieldLabeledCSVReader(Reader):
 
         for i, (header, value) in enumerate(zip(headers, row)):
             # Normalize line endings before stripping to handle embedded newlines
-            clean_value = _stringify_spreadsheet_cell_value(value).strip() if value else ""
+            clean_value = stringify_cell_value(value).strip() if value else ""
 
             if self.skip_empty_fields and not clean_value:
                 continue
@@ -105,155 +90,11 @@ class FieldLabeledCSVReader(Reader):
 
         return "\n".join(lines)
 
-    def _excel_rows_to_field_labeled_documents(
-        self,
-        *,
-        workbook_name: str,
-        sheets: Iterable[Tuple[str, Iterable[Sequence[Any]]]],
-    ) -> List[Document]:
-        """Convert Excel rows to field-labeled documents (one document per data row).
-
-        For each sheet: first row = headers, subsequent rows = data.
-        Each data row becomes a Document with field-labeled content.
-        """
-        documents = []
-        global_row_index = 0
-
-        for sheet_index, (sheet_name, rows) in enumerate(sheets, start=1):
-            rows_list = list(rows)
-
-            if not rows_list:
-                log_debug(f"Sheet '{sheet_name}' is empty, skipping")
-                continue
-
-            # First row is headers
-            headers = [_stringify_spreadsheet_cell_value(h).strip() for h in rows_list[0]]
-            if not any(headers):
-                log_debug(f"Sheet '{sheet_name}' has no valid headers, skipping")
-                continue
-
-            data_rows = rows_list[1:]
-            if not data_rows:
-                log_debug(f"Sheet '{sheet_name}' has only headers, skipping")
-                continue
-
-            log_debug(f"Processing sheet '{sheet_name}' with {len(headers)} headers and {len(data_rows)} rows")
-
-            for row_in_sheet, row in enumerate(data_rows):
-                # Convert cell values to strings
-                str_row = [_stringify_spreadsheet_cell_value(v) for v in row]
-
-                # Normalize row length
-                normalized_row = str_row[: len(headers)]
-                while len(normalized_row) < len(headers):
-                    normalized_row.append("")
-
-                # Skip entirely empty rows
-                if not any(v.strip() for v in normalized_row):
-                    continue
-
-                labeled_text = self._convert_row_to_labeled_text(headers, normalized_row, global_row_index)
-
-                if labeled_text.strip():
-                    doc_id = f"{workbook_name}_{sheet_name}_row_{row_in_sheet + 1}"
-                    documents.append(
-                        Document(
-                            id=doc_id,
-                            name=workbook_name,
-                            meta_data={
-                                "sheet_name": sheet_name,
-                                "sheet_index": sheet_index,
-                                "row_index": row_in_sheet,
-                                "headers": headers,
-                                "source": "field_labeled_csv_reader",
-                            },
-                            content=labeled_text,
-                        )
-                    )
-                    global_row_index += 1
-
-        return documents
-
-    def _read_xlsx(self, file: Union[Path, IO[Any]], *, workbook_name: str) -> List[Document]:
-        """Read .xlsx file and convert rows to field-labeled documents."""
-        try:
-            import openpyxl  # type: ignore
-        except ImportError as e:
-            raise ImportError(
-                "`openpyxl` not installed. Please install it via `pip install agno[csv]` or `pip install openpyxl`."
-            ) from e
-
-        if isinstance(file, Path):
-            workbook = openpyxl.load_workbook(filename=str(file), read_only=True, data_only=True)
-        else:
-            file.seek(0)
-            raw = file.read()
-            if isinstance(raw, str):
-                raw = raw.encode("utf-8", errors="replace")
-            workbook = openpyxl.load_workbook(filename=io.BytesIO(raw), read_only=True, data_only=True)
-
-        try:
-            return self._excel_rows_to_field_labeled_documents(
-                workbook_name=workbook_name,
-                sheets=[(worksheet.title, worksheet.iter_rows(values_only=True)) for worksheet in workbook.worksheets],
-            )
-        finally:
-            workbook.close()
-
-    def _read_xls(self, file: Union[Path, IO[Any]], *, workbook_name: str) -> List[Document]:
-        """Read .xls file and convert rows to field-labeled documents."""
-        try:
-            import xlrd  # type: ignore
-        except ImportError as e:
-            raise ImportError(
-                "`xlrd` not installed. Please install it via `pip install agno[csv]` or `pip install xlrd`."
-            ) from e
-
-        if isinstance(file, Path):
-            workbook = xlrd.open_workbook(filename=str(file))
-        else:
-            file.seek(0)
-            raw = file.read()
-            if isinstance(raw, str):
-                raw = raw.encode("utf-8", errors="replace")
-            workbook = xlrd.open_workbook(file_contents=raw)
-
-        sheets: List[Tuple[str, Iterable[Sequence[Any]]]] = []
-        for sheet_index in range(workbook.nsheets):
-            sheet = workbook.sheet_by_index(sheet_index)
-
-            def _iter_sheet_rows(_sheet: Any = sheet, _datemode: int = workbook.datemode) -> Iterable[Sequence[Any]]:
-                for row_index in range(_sheet.nrows):
-                    yield [
-                        _convert_xls_cell_value(
-                            _sheet.cell_value(row_index, col_index),
-                            _sheet.cell_type(row_index, col_index),
-                            _datemode,
-                        )
-                        for col_index in range(_sheet.ncols)
-                    ]
-
-            sheets.append((sheet.name, _iter_sheet_rows()))
-
-        return self._excel_rows_to_field_labeled_documents(workbook_name=workbook_name, sheets=sheets)
-
     def read(
         self, file: Union[Path, IO[Any]], delimiter: str = ",", quotechar: str = '"', name: Optional[str] = None
     ) -> List[Document]:
+        """Read a CSV file and convert each row to a field-labeled document."""
         try:
-            file_extension = _infer_file_extension(file, name)
-
-            # Handle Excel files
-            if file_extension in {ContentType.XLSX, ContentType.XLS}:
-                workbook_name = _get_workbook_name(file, name)
-                log_debug(f"Reading Excel file: {workbook_name}{file_extension}")
-
-                if file_extension == ContentType.XLSX:
-                    return self._read_xlsx(file, workbook_name=workbook_name)
-                else:
-                    return self._read_xls(file, workbook_name=workbook_name)
-
-            # Handle CSV files
             if isinstance(file, Path):
                 if not file.exists():
                     raise FileNotFoundError(f"Could not find file: {file}")
@@ -318,6 +159,8 @@ class FieldLabeledCSVReader(Reader):
             log_debug(f"Successfully created {len(documents)} labeled documents from CSV")
             return documents
 
+        except FileNotFoundError:
+            raise
         except Exception as e:
             log_error(f"Error reading: {getattr(file, 'name', str(file)) if isinstance(file, IO) else file}: {e}")
             return []
@@ -330,20 +173,8 @@ class FieldLabeledCSVReader(Reader):
         page_size: int = 1000,
         name: Optional[str] = None,
     ) -> List[Document]:
+        """Read a CSV file asynchronously and convert each row to a field-labeled document."""
         try:
-            file_extension = _infer_file_extension(file, name)
-
-            # Handle Excel files (use asyncio.to_thread for sync openpyxl/xlrd)
-            if file_extension in {ContentType.XLSX, ContentType.XLS}:
-                workbook_name = _get_workbook_name(file, name)
-                log_debug(f"Reading Excel file async: {workbook_name}{file_extension}")
-
-                if file_extension == ContentType.XLSX:
-                    return await asyncio.to_thread(self._read_xlsx, file, workbook_name=workbook_name)
-                else:
-                    return await asyncio.to_thread(self._read_xls, file, workbook_name=workbook_name)
-
-            # Handle CSV files
             if isinstance(file, Path):
                 if not file.exists():
                     raise FileNotFoundError(f"Could not find file: {file}")
@@ -399,12 +230,13 @@ class FieldLabeledCSVReader(Reader):
                         )
                         documents.append(document)
             else:
+                # Large files: paginate and process in parallel
                 pages = []
                 for i in range(0, total_rows, page_size):
                     pages.append(data_rows[i : i + page_size])
 
                 async def _process_page(page_number: int, page_rows: List[List[str]]) -> List[Document]:
-                    """Process a page of rows into documents"""
+                    """Process a page of rows into documents."""
                     page_documents = []
                     start_row_index = (page_number - 1) * page_size
 
@@ -443,6 +275,8 @@ class FieldLabeledCSVReader(Reader):
             log_debug(f"Successfully created {len(documents)} labeled documents from CSV")
             return documents
 
+        except FileNotFoundError:
+            raise
         except Exception as e:
             log_error(f"Error reading async: {getattr(file, 'name', str(file)) if isinstance(file, IO) else file}: {e}")
             return []

agno/knowledge/reader/reader_factory.py

@@ -18,7 +18,11 @@ class ReaderFactory:
         },
         "csv": {
             "name": "CsvReader",
-            "description": "Parses CSV, XLSX, and XLS files with custom delimiter support",
+            "description": "Parses CSV files with custom delimiter support",
+        },
+        "excel": {
+            "name": "ExcelReader",
+            "description": "Processes Excel workbooks (.xlsx and .xls) with sheet filtering and row-based chunking",
         },
         "field_labeled_csv": {
             "name": "FieldLabeledCsvReader",
@@ -93,11 +97,23 @@ class ReaderFactory:
 
         config: Dict[str, Any] = {
             "name": "CSV Reader",
-            "description": "Parses CSV, XLSX, and XLS files with custom delimiter support",
+            "description": "Parses CSV files with custom delimiter support",
         }
         config.update(kwargs)
         return CSVReader(**config)
 
+    @classmethod
+    def _get_excel_reader(cls, **kwargs) -> Reader:
+        """Get Excel reader instance."""
+        from agno.knowledge.reader.excel_reader import ExcelReader
+
+        config: Dict[str, Any] = {
+            "name": "Excel Reader",
+            "description": "Processes Excel workbooks (.xlsx and .xls) with sheet filtering and row-based chunking",
+        }
+        config.update(kwargs)
+        return ExcelReader(**config)
+
     @classmethod
     def _get_field_labeled_csv_reader(cls, **kwargs) -> Reader:
         """Get Field Labeled CSV reader instance."""
@@ -288,6 +304,7 @@ class ReaderFactory:
         reader_class_map: Dict[str, tuple] = {
             "pdf": ("agno.knowledge.reader.pdf_reader", "PDFReader"),
             "csv": ("agno.knowledge.reader.csv_reader", "CSVReader"),
+            "excel": ("agno.knowledge.reader.excel_reader", "ExcelReader"),
             "field_labeled_csv": ("agno.knowledge.reader.field_labeled_csv_reader", "FieldLabeledCSVReader"),
             "docx": ("agno.knowledge.reader.docx_reader", "DocxReader"),
             "pptx": ("agno.knowledge.reader.pptx_reader", "PPTXReader"),
@@ -335,15 +352,15 @@ class ReaderFactory:
 
         if extension in [".pdf", "application/pdf"]:
             return cls.create_reader("pdf")
+        elif extension in [".csv", "text/csv"]:
+            return cls.create_reader("csv")
         elif extension in [
-            ".csv",
             ".xlsx",
             ".xls",
-            "text/csv",
             "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
             "application/vnd.ms-excel",
         ]:
-            return cls.create_reader("csv")
+            return cls.create_reader("excel")
         elif extension in [".docx", ".doc", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"]:
             return cls.create_reader("docx")
         elif extension == ".pptx":

agno/knowledge/reader/utils/__init__.py

@@ -0,0 +1,17 @@
+from agno.knowledge.reader.utils.spreadsheet import (
+    convert_xls_cell_value,
+    excel_rows_to_documents,
+    get_workbook_name,
+    infer_file_extension,
+    row_to_csv_line,
+    stringify_cell_value,
+)
+
+__all__ = [
+    "convert_xls_cell_value",
+    "excel_rows_to_documents",
+    "get_workbook_name",
+    "infer_file_extension",
+    "row_to_csv_line",
+    "stringify_cell_value",
+]

agno/knowledge/reader/utils/spreadsheet.py

@@ -0,0 +1,114 @@
+from datetime import date, datetime
+from pathlib import Path
+from typing import IO, Any, Iterable, List, Optional, Sequence, Tuple, Union
+from uuid import uuid4
+
+from agno.knowledge.document.base import Document
+from agno.utils.log import log_debug
+
+
+def stringify_cell_value(value: Any) -> str:
+    """Convert cell value to string, normalizing dates and line endings."""
+    if value is None:
+        return ""
+
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+
+    result = str(value)
+    # Normalize all line endings to space to preserve row integrity in CSV-like output
+    # Must handle CRLF first before individual CR/LF to avoid double-spacing
+    result = result.replace("\r\n", " ")  # Windows (CRLF)
+    result = result.replace("\r", " ")  # Old Mac (CR)
+    result = result.replace("\n", " ")  # Unix (LF)
+    return result
+
+
+def get_workbook_name(file: Union[Path, IO[Any]], name: Optional[str]) -> str:
+    """Extract workbook name from file path or name parameter."""
+    if name:
+        return Path(name).stem
+    if isinstance(file, Path):
+        return file.stem
+    # getattr returns None when attribute exists but is None, so check explicitly
+    file_name = getattr(file, "name", None)
+    if file_name:
+        return Path(file_name).stem
+    return "workbook"
+
+
+def infer_file_extension(file: Union[Path, IO[Any]], name: Optional[str]) -> str:
+    """Infer file extension from Path, IO object, or explicit name."""
+    if isinstance(file, Path):
+        return file.suffix.lower()
+
+    file_name = getattr(file, "name", None)
+    if isinstance(file_name, str) and file_name:
+        return Path(file_name).suffix.lower()
+
+    if name:
+        return Path(name).suffix.lower()
+
+    return ""
+
+
+def convert_xls_cell_value(cell_value: Any, cell_type: int, datemode: int) -> Any:
+    """Convert xlrd cell value to Python type (dates and booleans need conversion)."""
+    try:
+        import xlrd
+    except ImportError:
+        return cell_value
+
+    if cell_type == xlrd.XL_CELL_DATE:
+        try:
+            date_tuple = xlrd.xldate_as_tuple(cell_value, datemode)
+            return datetime(*date_tuple)
+        except Exception:
+            return cell_value
+    if cell_type == xlrd.XL_CELL_BOOLEAN:
+        return bool(cell_value)
+    return cell_value
+
+
+def row_to_csv_line(row_values: Sequence[Any]) -> str:
+    """Convert row values to CSV-like string, trimming trailing empty cells."""
+    values = [stringify_cell_value(v) for v in row_values]
+    while values and values[-1] == "":
+        values.pop()
+
+    return ", ".join(values)
+
+
+def excel_rows_to_documents(
+    *,
+    workbook_name: str,
+    sheets: Iterable[Tuple[str, int, Iterable[Sequence[Any]]]],
+) -> List[Document]:
+    """Convert Excel sheet rows to Documents (one per sheet)."""
+    documents = []
+    for sheet_name, sheet_index, rows in sheets:
+        lines = []
+        for row in rows:
+            line = row_to_csv_line(row)
+            if line:
+                lines.append(line)
+
+        if not lines:
+            log_debug(f"Sheet '{sheet_name}' is empty, skipping")
+            continue
+
+        documents.append(
+            Document(
+                name=workbook_name,
+                id=str(uuid4()),
+                meta_data={"sheet_name": sheet_name, "sheet_index": sheet_index},
+                content="\n".join(lines),
+            )
+        )
+
+    return documents

agno/models/base.py

@@ -2109,6 +2109,7 @@ class Model(ABC):
                         tool_name=fc.function.name,
                         tool_args=fc.arguments,
                         requires_confirmation=True,
+                        external_execution_silent=fc.function.external_execution_silent,
                     )
                 )
 
@@ -2128,6 +2129,7 @@ class Model(ABC):
                         tool_args=fc.arguments,
                         requires_user_input=True,
                         user_input_schema=user_input_schema,
+                        external_execution_silent=fc.function.external_execution_silent,
                     )
                 )
 
@@ -2176,6 +2178,7 @@ class Model(ABC):
                         tool_name=fc.function.name,
                         tool_args=fc.arguments,
                         external_execution_required=True,
+                        external_execution_silent=fc.function.external_execution_silent,
                     )
                 )
 
@@ -2270,6 +2273,7 @@ class Model(ABC):
                         tool_name=fc.function.name,
                         tool_args=fc.arguments,
                         requires_confirmation=True,
+                        external_execution_silent=fc.function.external_execution_silent,
                     )
                 )
             # If the function requires user input, we yield a message to the user
@@ -2288,6 +2292,7 @@ class Model(ABC):
                         tool_args=fc.arguments,
                         requires_user_input=True,
                         user_input_schema=user_input_schema,
+                        external_execution_silent=fc.function.external_execution_silent,
                     )
                 )
             # If the function is from the user control flow tools, we handle it here
@@ -2340,6 +2345,7 @@ class Model(ABC):
                         tool_name=fc.function.name,
                         tool_args=fc.arguments,
                         external_execution_required=True,
+                        external_execution_silent=fc.function.external_execution_silent,
                     )
                 )
 

agno/models/moonshot/__init__.py

@@ -0,0 +1,3 @@
+from agno.models.moonshot.moonshot import MoonShot
+
+__all__ = ["MoonShot"]

agno/models/moonshot/moonshot.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass, field
+from os import getenv
+from typing import Any, Dict, Optional
+
+from agno.exceptions import ModelAuthenticationError
+from agno.models.openai.like import OpenAILike
+
+
+@dataclass
+class MoonShot(OpenAILike):
+    """
+    A class for interacting with MoonShot models.
+
+    Attributes:
+        id (str): The model id. Defaults to "kimi-k2-thinking".
+        name (str): The model name. Defaults to "Moonshot".
+        provider (str): The provider name. Defaults to "Moonshot".
+        api_key (Optional[str]): The API key.
+        base_url (str): The base URL. Defaults to "https://api.moonshot.ai/v1".
+    """
+
+    id: str = "kimi-k2-thinking"
+    name: str = "Moonshot"
+    provider: str = "Moonshot"
+
+    api_key: Optional[str] = field(default_factory=lambda: getenv("MOONSHOT_API_KEY"))
+    base_url: str = "https://api.moonshot.ai/v1"
+
+    def _get_client_params(self) -> Dict[str, Any]:
+        # Fetch API key from env if not already set
+        if not self.api_key:
+            self.api_key = getenv("MOONSHOT_API_KEY")
+            if not self.api_key:
+                # Raise error immediately if key is missing
+                raise ModelAuthenticationError(
+                    message="MOONSHOT_API_KEY not set. Please set the MOONSHOT_API_KEY environment variable.",
+                    model_name=self.name,
+                )
+
+        # Define base client params
+        base_params = {
+            "api_key": self.api_key,
+            "organization": self.organization,
+            "base_url": self.base_url,
+            "timeout": self.timeout,
+            "max_retries": self.max_retries,
+            "default_headers": self.default_headers,
+            "default_query": self.default_query,
+        }
+
+        # Create client_params dict with non-None values
+        client_params = {k: v for k, v in base_params.items() if v is not None}
+
+        # Add additional client params if provided
+        if self.client_params:
+            client_params.update(self.client_params)
+        return client_params

agno/models/openrouter/responses.py

@@ -5,8 +5,8 @@ from typing import Any, Dict, List, Optional, Type, Union
 from pydantic import BaseModel
 
 from agno.exceptions import ModelAuthenticationError
-from agno.models.openai.open_responses import OpenResponses
 from agno.models.message import Message
+from agno.models.openai.open_responses import OpenResponses
 
 
 @dataclass
@@ -143,4 +143,4 @@ class OpenRouterResponses(OpenResponses):
         # Check for OpenAI reasoning models hosted on OpenRouter
         if self.id.startswith("openai/o3") or self.id.startswith("openai/o4"):
             return True
-        return False
+        return False

agno/models/response.py

@@ -52,6 +52,9 @@ class ToolExecution:
 
     external_execution_required: Optional[bool] = None
 
+    # If True (and external_execution_required=True), suppresses verbose paused messages
+    external_execution_silent: Optional[bool] = None
+
     @property
     def is_paused(self) -> bool:
         return bool(self.requires_confirmation or self.requires_user_input or self.external_execution_required)
@@ -84,6 +87,7 @@ class ToolExecution:
             if "user_input_schema" in data
             else None,
             external_execution_required=data.get("external_execution_required"),
+            external_execution_silent=data.get("external_execution_silent"),
             metrics=Metrics(**(data.get("metrics", {}) or {})),
             **{"created_at": data["created_at"]} if "created_at" in data else {},
         )

agno/models/utils.py

@@ -139,6 +139,11 @@ def _get_model_class(model_id: str, model_provider: str) -> Model:
 
         return MistralChat(id=model_id)
 
+    elif model_provider == "moonshot":
+        from agno.models.moonshot import MoonShot
+
+        return MoonShot(id=model_id)
+
     elif model_provider == "nebius":
         from agno.models.nebius import Nebius
 

agno/os/routers/knowledge/knowledge.py

@@ -989,9 +989,11 @@ def attach_routes(router: APIRouter, knowledge_instances: List[Union[Knowledge,
                                 "text": ["web_search"],
                                 "topic": ["arxiv"],
                                 "file": ["csv", "gcs"],
-                                ".csv": ["csv"],
-                                ".xlsx": ["csv"],
-                                ".xls": ["csv"],
+                                ".csv": ["csv", "field_labeled_csv"],
+                                ".xlsx": ["excel"],
+                                ".xls": ["excel"],
+                                "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ["excel"],
+                                "application/vnd.ms-excel": ["excel"],
                                 ".docx": ["docx"],
                                 ".doc": ["docx"],
                                 ".json": ["json"],

agno/run/base.py

@@ -246,6 +246,10 @@ class BaseRunOutputEvent:
             data["requirements"] = requirements_list if requirements_list else None
 
         # Filter data to only include fields that are actually defined in the target class
+        # CustomEvent accepts arbitrary fields, so skip filtering for it
+        if cls.__name__ == "CustomEvent":
+            return cls(**data)
+
         from dataclasses import fields
 
         supported_fields = {f.name for f in fields(cls)}

agno/tools/decorator.py

@@ -70,6 +70,7 @@ def tool(
     requires_user_input: Optional[bool] = None,
     user_input_fields: Optional[List[str]] = None,
     external_execution: Optional[bool] = None,
+    external_execution_silent: Optional[bool] = None,
     pre_hook: Optional[Callable] = None,
     post_hook: Optional[Callable] = None,
     tool_hooks: Optional[List[Callable]] = None,
@@ -98,6 +99,7 @@ def tool(*args, **kwargs) -> Union[Function, Callable[[F], Function]]:
         requires_user_input: Optional[bool] - If True, the function will require user input before execution
         user_input_fields: Optional[List[str]] - List of fields that will be provided to the function as user input
         external_execution: Optional[bool] - If True, the function will be executed outside of the agent's context
+        external_execution_silent: Optional[bool] - If True (and external_execution=True), suppresses verbose paused messages (e.g., "I have tools to execute...")
         pre_hook: Optional[Callable] - Hook that runs before the function is executed.
         post_hook: Optional[Callable] - Hook that runs after the function is executed.
         tool_hooks: Optional[List[Callable]] - List of hooks that run before and after the function is executed.
@@ -135,6 +137,7 @@ def tool(*args, **kwargs) -> Union[Function, Callable[[F], Function]]:
             "requires_user_input",
             "user_input_fields",
             "external_execution",
+            "external_execution_silent",
             "pre_hook",
             "post_hook",
             "tool_hooks",