stackone-ai 2.8.0__tar.gz → 2.9.1__tar.gz

stackone_ai-2.9.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "2.9.1"
+}

{stackone_ai-2.8.0 → stackone_ai-2.9.1}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.9.1](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.9.0...stackone-ai-v2.9.1) (2026-06-03)
+
+
+### Bug Fixes
+
+* **models:** handle binary file downloads in tool execution ([#190](https://github.com/StackOneHQ/stackone-ai-python/issues/190)) ([8983c68](https://github.com/StackOneHQ/stackone-ai-python/commit/8983c68dd2fdbdbdd52af531a9a9f1de6d72e1b8))
+* **search:** make ToolsetConfigError actionable and fix misleading docs ([#188](https://github.com/StackOneHQ/stackone-ai-python/issues/188)) ([d332c27](https://github.com/StackOneHQ/stackone-ai-python/commit/d332c27d2f7b827e7ca043f60c37cb0831a92361))
+
+## [2.9.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.8.0...stackone-ai-v2.9.0) (2026-04-30)
+
+
+### Features
+
+* **integrations:** add native Pydantic AI support ([#184](https://github.com/StackOneHQ/stackone-ai-python/issues/184)) ([8216ab6](https://github.com/StackOneHQ/stackone-ai-python/commit/8216ab6c0776b0753cf3e68461bf5e8a9b044b06))
+
 ## [2.8.0](https://github.com/StackOneHQ/stackone-ai-python/compare/stackone-ai-v2.7.0...stackone-ai-v2.8.0) (2026-04-20)
 
 

{stackone_ai-2.8.0 → stackone_ai-2.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackone-ai
-Version: 2.8.0
+Version: 2.9.1
 Summary: agents performing actions on your SaaS
 Author-email: StackOne <support@stackone.com>
 License-File: LICENSE
@@ -29,6 +29,8 @@ Requires-Dist: pydantic-ai>=1.83.0; extra == 'examples'
 Requires-Dist: python-dotenv>=1.0.1; extra == 'examples'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.3.0; extra == 'mcp'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim<2.0.0,>=1.83.0; extra == 'pydantic-ai'
 Description-Content-Type: text/markdown
 
 # StackOne AI SDK
@@ -59,6 +61,7 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
   - LangChain Tools
   - CrewAI Tools
   - LangGraph Tool Node
+  - Pydantic AI Toolset
 
 ## Requirements
 
@@ -146,6 +149,35 @@ tools = toolset.fetch_tools(providers=["hibob"])
   - Glob pattern: `["*_list_employees"]` matches all tools ending with `_list_employees`
   - Provider prefix: `["workday_*"]` matches all Workday tools
 
+## File Downloads
+
+Actions that return a file — e.g. `googledrive_unified_download_file`, `documents_download_file`, any `*_unified_download_file` — resolve to **raw bytes plus metadata**, not parsed JSON. The SDK decides this from the response `Content-Type`: a JSON content type is parsed as before; anything else is treated as a file download. This applies to both `tool.execute()` and `tool.call()`.
+
+```python
+tools = toolset.fetch_tools(actions=["googledrive_*"], account_ids=[account_id])
+download = tools.get_tool("googledrive_unified_download_file")
+
+result = download.execute({"id": "file-id"})
+
+# `result` is a dict describing the file — write the bytes straight to disk:
+with open(result["file_name"] or "download.bin", "wb") as f:
+    f.write(result["content"])
+```
+
+The returned dict:
+
+| Key            | Type          | Description                                                                                  |
+| -------------- | ------------- | -------------------------------------------------------------------------------------------- |
+| `content`      | `bytes`       | Raw file bytes. **Not JSON-serializable** — see the caveat below.                            |
+| `content_type` | `str`         | The file's MIME type (e.g. `application/pdf`), or `application/octet-stream` if unspecified. |
+| `status_code`  | `int`         | HTTP status of the download response.                                                        |
+| `headers`      | `dict`        | Response headers.                                                                            |
+| `file_name`    | `str \| None` | Filename from the `Content-Disposition` header (handles RFC 5987 `filename*`), else `None`.  |
+
+> **Caveat:** `content` holds raw bytes, which are not JSON-serializable. If you forward tool results to an LLM — or anywhere that re-serializes them to JSON — handle or strip the `content` key (for example, base64-encode it on the LLM-facing path).
+
+JSON responses are unchanged: any action returning `application/json` (or a `…+json` type) is parsed and returned as a dict exactly as before.
+
 ## Implicit Feedback (Beta)
 
 The Python SDK can emit implicit behavioral feedback to LangSmith so you can triage low-quality tool results without manually tagging runs.
@@ -228,6 +260,46 @@ for tool_call in response.tool_calls:
 
 </details>
 
+<details>
+<summary>Pydantic AI Integration</summary>
+
+StackOne tools convert to Pydantic AI `Tool` instances via `.to_pydantic_ai()`, parallel to `.to_openai()` and `.to_langchain()`:
+
+Prerequisites:
+
+```bash
+pip install 'stackone-ai[pydantic-ai]'
+```
+
+```python
+import os
+from pydantic_ai import Agent
+from stackone_ai import StackOneToolSet
+
+toolset = StackOneToolSet()
+tools = toolset.fetch_tools(
+    actions=["workday_list_workers", "workday_get_worker"],
+    account_ids=[os.environ["STACKONE_ACCOUNT_ID"]],
+).to_pydantic_ai()
+
+agent = Agent("openai:gpt-5.4", tools=tools)
+result = agent.run_sync("List the first 5 employees")
+print(result.output)
+```
+
+For the full catalog (or the meta search/execute tools), use the `.pydantic_ai()` method on `StackOneToolSet` — parallel to `.openai()` / `.langchain()`:
+
+```python
+toolset = StackOneToolSet()
+tools = toolset.pydantic_ai(account_ids=[os.environ["STACKONE_ACCOUNT_ID"]])
+
+# For agent-driven discovery, enable search on the constructor:
+# toolset = StackOneToolSet(search={"method": "auto"})
+# tools = toolset.pydantic_ai(mode="search_and_execute")
+```
+
+</details>
+
 <details>
 <summary>LangGraph Integration</summary>
 
@@ -354,15 +426,15 @@ Search for tools using natural language queries. Works with both semantic (cloud
 
 ```python
 import os
+from stackone_ai import StackOneToolSet
 
-# Get a callable search tool
-toolset = StackOneToolSet()
+# Get a callable search tool — search must be enabled on the toolset
+toolset = StackOneToolSet(search={"method": "auto"})
 account_id = os.getenv("STACKONE_ACCOUNT_ID")
-all_tools = toolset.fetch_tools(account_ids=[account_id])
 search_tool = toolset.get_search_tool()
 
-# Search for relevant tools — returns a Tools collection
-tools = search_tool("manage employees", top_k=5)
+# Search for relevant tools — returns a Tools collection scoped to the account
+tools = search_tool("manage employees", top_k=5, account_ids=[account_id])
 
 # Execute a discovered tool directly
 tools[0](limit=10)
@@ -376,7 +448,9 @@ Discover tools using natural language instead of exact names. Queries like "onbo
 import os
 from stackone_ai import StackOneToolSet
 
-toolset = StackOneToolSet()
+# Search must be enabled on the constructor — pass `search={}` for defaults,
+# or set a backend / top_k explicitly.
+toolset = StackOneToolSet(search={"method": "auto"})
 
 # Search by intent — returns Tools collection ready for any framework
 account_id = os.getenv("STACKONE_ACCOUNT_ID")

{stackone_ai-2.8.0 → stackone_ai-2.9.1}/README.md

@@ -26,6 +26,7 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
   - LangChain Tools
   - CrewAI Tools
   - LangGraph Tool Node
+  - Pydantic AI Toolset
 
 ## Requirements
 
@@ -113,6 +114,35 @@ tools = toolset.fetch_tools(providers=["hibob"])
   - Glob pattern: `["*_list_employees"]` matches all tools ending with `_list_employees`
   - Provider prefix: `["workday_*"]` matches all Workday tools
 
+## File Downloads
+
+Actions that return a file — e.g. `googledrive_unified_download_file`, `documents_download_file`, any `*_unified_download_file` — resolve to **raw bytes plus metadata**, not parsed JSON. The SDK decides this from the response `Content-Type`: a JSON content type is parsed as before; anything else is treated as a file download. This applies to both `tool.execute()` and `tool.call()`.
+
+```python
+tools = toolset.fetch_tools(actions=["googledrive_*"], account_ids=[account_id])
+download = tools.get_tool("googledrive_unified_download_file")
+
+result = download.execute({"id": "file-id"})
+
+# `result` is a dict describing the file — write the bytes straight to disk:
+with open(result["file_name"] or "download.bin", "wb") as f:
+    f.write(result["content"])
+```
+
+The returned dict:
+
+| Key            | Type          | Description                                                                                  |
+| -------------- | ------------- | -------------------------------------------------------------------------------------------- |
+| `content`      | `bytes`       | Raw file bytes. **Not JSON-serializable** — see the caveat below.                            |
+| `content_type` | `str`         | The file's MIME type (e.g. `application/pdf`), or `application/octet-stream` if unspecified. |
+| `status_code`  | `int`         | HTTP status of the download response.                                                        |
+| `headers`      | `dict`        | Response headers.                                                                            |
+| `file_name`    | `str \| None` | Filename from the `Content-Disposition` header (handles RFC 5987 `filename*`), else `None`.  |
+
+> **Caveat:** `content` holds raw bytes, which are not JSON-serializable. If you forward tool results to an LLM — or anywhere that re-serializes them to JSON — handle or strip the `content` key (for example, base64-encode it on the LLM-facing path).
+
+JSON responses are unchanged: any action returning `application/json` (or a `…+json` type) is parsed and returned as a dict exactly as before.
+
 ## Implicit Feedback (Beta)
 
 The Python SDK can emit implicit behavioral feedback to LangSmith so you can triage low-quality tool results without manually tagging runs.
@@ -195,6 +225,46 @@ for tool_call in response.tool_calls:
 
 </details>
 
+<details>
+<summary>Pydantic AI Integration</summary>
+
+StackOne tools convert to Pydantic AI `Tool` instances via `.to_pydantic_ai()`, parallel to `.to_openai()` and `.to_langchain()`:
+
+Prerequisites:
+
+```bash
+pip install 'stackone-ai[pydantic-ai]'
+```
+
+```python
+import os
+from pydantic_ai import Agent
+from stackone_ai import StackOneToolSet
+
+toolset = StackOneToolSet()
+tools = toolset.fetch_tools(
+    actions=["workday_list_workers", "workday_get_worker"],
+    account_ids=[os.environ["STACKONE_ACCOUNT_ID"]],
+).to_pydantic_ai()
+
+agent = Agent("openai:gpt-5.4", tools=tools)
+result = agent.run_sync("List the first 5 employees")
+print(result.output)
+```
+
+For the full catalog (or the meta search/execute tools), use the `.pydantic_ai()` method on `StackOneToolSet` — parallel to `.openai()` / `.langchain()`:
+
+```python
+toolset = StackOneToolSet()
+tools = toolset.pydantic_ai(account_ids=[os.environ["STACKONE_ACCOUNT_ID"]])
+
+# For agent-driven discovery, enable search on the constructor:
+# toolset = StackOneToolSet(search={"method": "auto"})
+# tools = toolset.pydantic_ai(mode="search_and_execute")
+```
+
+</details>
+
 <details>
 <summary>LangGraph Integration</summary>
 
@@ -321,15 +391,15 @@ Search for tools using natural language queries. Works with both semantic (cloud
 
 ```python
 import os
+from stackone_ai import StackOneToolSet
 
-# Get a callable search tool
-toolset = StackOneToolSet()
+# Get a callable search tool — search must be enabled on the toolset
+toolset = StackOneToolSet(search={"method": "auto"})
 account_id = os.getenv("STACKONE_ACCOUNT_ID")
-all_tools = toolset.fetch_tools(account_ids=[account_id])
 search_tool = toolset.get_search_tool()
 
-# Search for relevant tools — returns a Tools collection
-tools = search_tool("manage employees", top_k=5)
+# Search for relevant tools — returns a Tools collection scoped to the account
+tools = search_tool("manage employees", top_k=5, account_ids=[account_id])
 
 # Execute a discovered tool directly
 tools[0](limit=10)
@@ -343,7 +413,9 @@ Discover tools using natural language instead of exact names. Queries like "onbo
 import os
 from stackone_ai import StackOneToolSet
 
-toolset = StackOneToolSet()
+# Search must be enabled on the constructor — pass `search={}` for defaults,
+# or set a backend / top_k explicitly.
+toolset = StackOneToolSet(search={"method": "auto"})
 
 # Search by intent — returns Tools collection ready for any framework
 account_id = os.getenv("STACKONE_ACCOUNT_ID")

{stackone_ai-2.8.0 → stackone_ai-2.9.1}/examples/pydantic_ai_integration.py

@@ -3,11 +3,13 @@
 ```bash
 uv run examples/pydantic_ai_integration.py
 ```
+
+Install with `pip install 'stackone-ai[pydantic-ai]'` (or
+`pip install 'stackone-ai[examples]'` to run this file).
 """
 
 from __future__ import annotations
 
-import json
 import os
 
 try:
@@ -18,31 +20,15 @@ except ModuleNotFoundError:
     pass
 
 try:
-    from pydantic_ai import Agent, Tool
+    from pydantic_ai import Agent
 except ImportError:
-    print("Install pydantic-ai to run this example: pip install pydantic-ai")
+    print("Install pydantic-ai to run this example: pip install 'stackone-ai[pydantic-ai]'")
     raise SystemExit(1) from None
 
 from stackone_ai import StackOneToolSet
 
 
-def _to_pydantic_ai_tool(stackone_tool) -> Tool:
-    """Convert a StackOneTool to a Pydantic AI Tool with the proper JSON schema."""
-    params_schema = stackone_tool.to_openai_function()["function"]["parameters"]
-
-    def execute(**kwargs: object) -> str:
-        return json.dumps(stackone_tool.execute(kwargs))
-
-    return Tool.from_schema(
-        execute,
-        name=stackone_tool.name,
-        description=stackone_tool.description,
-        json_schema=params_schema,
-    )
-
-
 def pydantic_ai_integration() -> None:
-    account_id = os.getenv("STACKONE_ACCOUNT_ID")
     for var in ["STACKONE_API_KEY", "STACKONE_ACCOUNT_ID", "OPENAI_API_KEY"]:
         if not os.getenv(var):
             print(f"Set {var} to run this example.")
@@ -51,12 +37,14 @@ def pydantic_ai_integration() -> None:
     toolset = StackOneToolSet()
     tools = toolset.fetch_tools(
         actions=["workday_list_workers", "workday_get_worker", "workday_get_current_user"],
-        account_ids=[account_id],
-    )
-    pydantic_tools = [_to_pydantic_ai_tool(t) for t in tools]
-    print(f"Loaded {len(pydantic_tools)} tools for Pydantic AI.")
+        account_ids=[os.environ["STACKONE_ACCOUNT_ID"]],
+    ).to_pydantic_ai()
 
-    agent = Agent("openai:gpt-5.4", system_prompt="You are a helpful HR assistant.", tools=pydantic_tools)
+    agent = Agent(
+        "openai:gpt-5.4",
+        system_prompt="You are a helpful HR assistant.",
+        tools=tools,
+    )
     result = agent.run_sync("List the first 5 employees")
     print(f"Result:\n{result.output}")
 

{stackone_ai-2.8.0 → stackone_ai-2.9.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackone-ai"
-version = "2.8.0"
+version = "2.9.1"
 description = "agents performing actions on your SaaS"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,6 +37,7 @@ packages = ["stackone_ai"]
 
 [project.optional-dependencies]
 mcp = ["mcp>=1.3.0"]
+pydantic-ai = ["pydantic-ai-slim>=1.83.0,<2.0.0"]
 examples = [
   "crewai>=0.102.0",
   "langchain-openai>=1.1.14",

{stackone_ai-2.8.0 → stackone_ai-2.9.1}/stackone_ai/__init__.py

@@ -23,4 +23,4 @@ __all__ = [
     "SemanticSearchResponse",
     "SemanticSearchError",
 ]
-__version__ = "2.8.0"
+__version__ = "2.9.1"

{stackone_ai-2.8.0 → stackone_ai-2.9.1}/stackone_ai/models.py

@@ -3,16 +3,20 @@ from __future__ import annotations
 import base64
 import json
 import logging
+import re
 from collections.abc import Sequence
 from datetime import datetime, timezone
 from enum import Enum
-from typing import Annotated, Any, ClassVar, TypeAlias, cast
-from urllib.parse import quote
+from typing import TYPE_CHECKING, Annotated, Any, ClassVar, TypeAlias, cast
+from urllib.parse import quote, unquote
 
 import httpx
 from langchain_core.tools import BaseTool
 from pydantic import BaseModel, BeforeValidator, Field, PrivateAttr
 
+if TYPE_CHECKING:
+    from pydantic_ai.tools import Tool as PydanticAITool
+
 # Type aliases for common types
 JsonDict: TypeAlias = dict[str, Any]
 Headers: TypeAlias = dict[str, str]
@@ -54,6 +58,47 @@ def validate_method(v: str) -> str:
     return method
 
 
+def _is_json_content_type(content_type: str) -> bool:
+    """Whether a response body should be parsed as JSON based on its Content-Type.
+
+    Only genuine JSON media types are parsed (``application/json`` and structured
+    suffixes such as ``application/problem+json``). Anything else - including a
+    missing Content-Type - is treated as opaque content (a file download), so the
+    raw bytes are returned instead of being force-decoded as UTF-8/JSON. This mirrors
+    how the StackOne generated SDKs default unknown bodies to ``application/octet-stream``.
+    """
+    media_type = content_type.split(";", 1)[0].strip().lower()
+    return media_type == "application/json" or media_type.endswith("+json")
+
+
+def _filename_from_content_disposition(value: str | None) -> str | None:
+    """Extract the filename from a Content-Disposition header value, if present.
+
+    Handles both the plain ``filename="example.pdf"`` form and the RFC 5987 extended
+    ``filename*=UTF-8''example%20file.pdf`` form (which takes precedence when present).
+    The extended form is percent-decoded using its declared charset (RFC 5987 permits
+    both ``UTF-8`` and ``ISO-8859-1``); an unknown or empty charset falls back to UTF-8.
+    """
+    if not value:
+        return None
+    extended = re.search(r"filename\*\s*=\s*([^']*)'[^']*'([^;]+)", value, re.IGNORECASE)
+    if extended:
+        charset = extended.group(1).strip() or "utf-8"
+        encoded = extended.group(2).strip().strip('"')
+        try:
+            return unquote(encoded, encoding=charset, errors="replace") or None
+        except LookupError:
+            # Unrecognised charset label - decode as UTF-8 rather than failing.
+            return unquote(encoded, encoding="utf-8", errors="replace") or None
+    quoted = re.search(r'filename\s*=\s*"([^"]*)"', value, re.IGNORECASE)
+    if quoted:
+        return quoted.group(1).strip() or None
+    bare = re.search(r"filename\s*=\s*([^;]+)", value, re.IGNORECASE)
+    if bare:
+        return bare.group(1).strip().strip('"') or None
+    return None
+
+
 class ExecuteConfig(BaseModel):
     """Configuration for executing a tool against an API endpoint"""
 
@@ -203,7 +248,14 @@ class StackOneTool(BaseModel):
             options: Execution options (e.g. feedback metadata)
 
         Returns:
-            API response as dict
+            For JSON responses, the parsed API response as a dict.
+
+            For file downloads (any non-JSON Content-Type, e.g. a
+            ``documents_download_file`` action), a dict describing the file:
+            ``{"content": <bytes>, "content_type": str, "status_code": int,
+            "headers": dict, "file_name": str | None}``. Note ``content`` holds
+            the raw bytes and is therefore not JSON-serializable - callers that
+            re-serialize tool results (e.g. for an LLM) should handle this key.
 
         Raises:
             StackOneAPIError: If the API request fails
@@ -254,9 +306,23 @@ class StackOneTool(BaseModel):
             response_status = response.status_code
             response.raise_for_status()
 
-            result = response.json()
-            result_payload = cast(JsonDict, result) if isinstance(result, dict) else {"result": result}
-            return result_payload
+            content_type = response.headers.get("content-type", "")
+            if _is_json_content_type(content_type):
+                result = response.json()
+                result_payload = cast(JsonDict, result) if isinstance(result, dict) else {"result": result}
+                return result_payload
+
+            # Non-JSON bodies are file downloads (e.g. documents_download_file), which the
+            # API serves as raw binary with the file's own MIME type and a Content-Disposition
+            # header. Return the bytes plus metadata rather than forcing a JSON/UTF-8 decode.
+            # The shape mirrors the StackOne generated SDKs' download response.
+            return {
+                "content": response.content,
+                "content_type": content_type or "application/octet-stream",
+                "status_code": response.status_code,
+                "headers": dict(response.headers),
+                "file_name": _filename_from_content_disposition(response.headers.get("content-disposition")),
+            }
 
         except json.JSONDecodeError as exc:
             status = "error"
@@ -467,6 +533,36 @@ class StackOneTool(BaseModel):
 
         return StackOneLangChainTool()
 
+    def to_pydantic_ai_tool(self) -> PydanticAITool:
+        """Convert this tool to a Pydantic AI ``Tool``.
+
+        Requires ``stackone-ai[pydantic-ai]`` (installs ``pydantic-ai-slim``).
+
+        Returns:
+            A ``pydantic_ai.tools.Tool`` ready to pass to ``Agent(tools=[...])``.
+        """
+        try:
+            from pydantic_ai.tools import Tool
+        except ImportError as e:
+            raise ImportError(
+                "Install `pydantic-ai-slim` (or `stackone-ai[pydantic-ai]`) "
+                "to use the Pydantic AI integration."
+            ) from e
+
+        openai_function = self.to_openai_function()
+        json_schema = openai_function["function"]["parameters"]
+        parent_tool = self
+
+        def implementation(**kwargs: Any) -> Any:
+            return parent_tool.execute(kwargs)
+
+        return Tool.from_schema(
+            function=implementation,
+            name=self.name,
+            description=self.description,
+            json_schema=json_schema,
+        )
+
     def set_account_id(self, account_id: str | None) -> None:
         """Set the account ID for this tool
 
@@ -577,3 +673,13 @@ class Tools:
             Sequence of tools in LangChain format
         """
         return [tool.to_langchain() for tool in self.tools]
+
+    def to_pydantic_ai(self) -> list[PydanticAITool]:
+        """Convert all tools to Pydantic AI ``Tool`` instances.
+
+        Requires ``stackone-ai[pydantic-ai]`` (installs ``pydantic-ai-slim``).
+
+        Returns:
+            List of ``pydantic_ai.tools.Tool`` ready to pass to ``Agent(tools=[...])``.
+        """
+        return [tool.to_pydantic_ai_tool() for tool in self.tools]

{stackone_ai-2.8.0 → stackone_ai-2.9.1}/stackone_ai/toolset.py

@@ -11,7 +11,7 @@ import threading
 from collections.abc import Coroutine, Sequence
 from dataclasses import dataclass
 from importlib import metadata
-from typing import Any, Literal, TypedDict, TypeVar
+from typing import TYPE_CHECKING, Any, Literal, TypedDict, TypeVar
 
 from pydantic import BaseModel, Field, PrivateAttr, ValidationError, field_validator
 
@@ -32,6 +32,9 @@ from stackone_ai.semantic_search import (
 )
 from stackone_ai.utils.normalize import _normalize_action_name
 
+if TYPE_CHECKING:
+    from pydantic_ai.tools import Tool as PydanticAITool
+
 logger = logging.getLogger("stackone.tools")
 
 SearchMode = Literal["auto", "semantic", "local"]
@@ -642,13 +645,14 @@ class StackOneToolSet:
 
         Example::
 
-            toolset = StackOneToolSet()
+            toolset = StackOneToolSet(search={"method": "auto"})
             search_tool = toolset.get_search_tool()
             tools = search_tool("manage employee records", account_ids=["acc-123"])
         """
         if self._search_config is None:
             raise ToolsetConfigError(
-                "Search is disabled. Initialize StackOneToolSet with a search config to enable."
+                "Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
+                "StackOneToolSet(...) to enable. See README 'Search Tool' for options."
             )
 
         config: SearchConfig = {**self._search_config}
@@ -661,7 +665,8 @@ class StackOneToolSet:
         """Build tool_search + tool_execute tools scoped to this toolset."""
         if self._search_config is None:
             raise ToolsetConfigError(
-                "Search is disabled. Initialize StackOneToolSet with a search config to enable."
+                "Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
+                "StackOneToolSet(...) to enable. See README 'Search Tool' for options."
             )
 
         if account_ids:
@@ -710,8 +715,8 @@ class StackOneToolSet:
             toolset = StackOneToolSet()
             tools = toolset.openai()
 
-            # Meta tools for agent-driven discovery
-            toolset = StackOneToolSet()
+            # Meta tools for agent-driven discovery — search must be enabled
+            toolset = StackOneToolSet(search={"method": "auto"})
             tools = toolset.openai(mode="search_and_execute")
         """
         effective_account_ids = account_ids or (
@@ -752,6 +757,47 @@ class StackOneToolSet:
 
         return self.fetch_tools(account_ids=effective_account_ids).to_langchain()
 
+    def pydantic_ai(
+        self,
+        *,
+        mode: Literal["search_and_execute"] | None = None,
+        account_ids: list[str] | None = None,
+    ) -> list[PydanticAITool]:
+        """Get tools as Pydantic AI ``Tool`` instances.
+
+        Args:
+            mode: Tool mode.
+                ``None`` (default): fetch all tools and convert to Pydantic AI tools.
+                ``"search_and_execute"``: return two meta tools (tool_search + tool_execute)
+                that let the LLM discover and execute tools on-demand.
+            account_ids: Account IDs to scope tools. Overrides the ``execute``
+                config from the constructor.
+
+        Returns:
+            List of Pydantic AI ``Tool`` objects ready to pass to ``Agent(tools=...)``.
+
+        Requires ``stackone-ai[pydantic-ai]`` (installs ``pydantic-ai-slim``).
+
+        Examples::
+
+            # All tools
+            toolset = StackOneToolSet()
+            tools = toolset.pydantic_ai()
+            agent = Agent("openai:gpt-5.4", tools=tools)
+
+            # Meta tools for agent-driven discovery — search must be enabled
+            toolset = StackOneToolSet(search={"method": "auto"})
+            tools = toolset.pydantic_ai(mode="search_and_execute")
+        """
+        effective_account_ids = account_ids or (
+            self._execute_config.get("account_ids") if self._execute_config else None
+        )
+
+        if mode == "search_and_execute":
+            return self._build_tools(account_ids=effective_account_ids).to_pydantic_ai()
+
+        return self.fetch_tools(account_ids=effective_account_ids).to_pydantic_ai()
+
     def execute(
         self,
         tool_name: str,
@@ -886,7 +932,8 @@ class StackOneToolSet:
         """
         if self._search_config is None:
             raise ToolsetConfigError(
-                "Search is disabled. Initialize StackOneToolSet with a search config to enable."
+                "Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
+                "StackOneToolSet(...) to enable. See README 'Search Tool' for options."
             )
 
         # Merge constructor defaults with per-call overrides
@@ -1039,7 +1086,8 @@ class StackOneToolSet:
         """
         if self._search_config is None:
             raise ToolsetConfigError(
-                "Search is disabled. Initialize StackOneToolSet with search config to enable."
+                "Search is disabled. Pass search={} (or search={'method': 'auto'}) to "
+                "StackOneToolSet(...) to enable. See README 'Search Tool' for options."
             )
 
         # Merge constructor defaults with per-call overrides