Pydantic AI Integration
Relevant source files
The following files were used as context for generating this wiki page:
Pydantic AI Integration provides a native bridge between the StackOne AI SDK and the Pydantic AI framework. It allows developers to register SaaS tools discovered or fetched via StackOne directly into Pydantic AI agents as valid tools. The integration ensures that served schemas are passed through to the model with minimal loss of detail, preserving constraints like enums, bounds, and nested structures.
Sources: README.md:12-18, stackone_ai/tools.py:726-764, CLAUDE.md:12-15
Integration Architecture
The integration follows a lazy-loading pattern where Pydantic AI dependencies are only imported when an integration method is called. This prevents the core SDK from requiring the pydantic-ai-slim package unless the specific functionality is used.
Sources: pyproject.toml:41-45, stackone_ai/tools.py:739-744, CLAUDE.md:88-95
Schema Conversion Flow
StackOne tools convert their internal representation into a format compatible with pydantic_ai.tools.Tool. The system uses Tool.from_schema to define the function metadata, ensuring the JSON Schema served by the MCP server reaches the LLM.
Key Components and Methods
The integration is exposed through three main interfaces depending on the level of abstraction required.
StackOneTool.to_pydantic_ai_tool()
Converts a single tool instance into a Pydantic AI Tool. It wraps the execute method of the StackOne tool in a function that Pydantic AI agents can invoke. If the tool execution fails with a StackOneError or ValueError, the adapter raises a pydantic_ai.exceptions.ModelRetry to allow the agent to correct its arguments.
Sources: stackone_ai/tools.py:726-764, tests/test_integrations_pydantic_ai.py:53-67
Tools.to_pydantic_ai()
Converts a collection of tools (a Tools object) into a list of Pydantic AI Tool instances. This is used after filtering tools via fetch_tools().
Sources: stackone_ai/tools.py:906-911, tests/test_integrations_pydantic_ai.py:72-80
StackOneToolSet.pydantic_ai()
Provides a high-level shortcut to fetch all available tools and convert them in one call. It accepts an optional account_ids parameter to scope the discovery.
Sources: tests/test_integrations_pydantic_ai.py:83-118, README.md:135-136
| Feature | Method | Returns | Description |
|---|---|---|---|
| Single Tool | to_pydantic_ai_tool() | pydantic_ai.tools.Tool | Converts one specific tool. |
| Tool Collection | to_pydantic_ai() | list[pydantic_ai.tools.Tool] | Converts a set of filtered tools. |
| Toolset Shortcut | pydantic_ai() | list[pydantic_ai.tools.Tool] | Discovers and converts all tools. |
Sources: stackone_ai/tools.py:726, stackone_ai/tools.py:906, tests/test_integrations_pydantic_ai.py:83
Tool Execution and Error Handling
When a Pydantic AI agent invokes a StackOne tool, the integration manages the data flow between the agent's generated arguments and the StackOne API.
Execution Sequence
The following diagram illustrates the sequence of a tool call initiated by a Pydantic AI Agent.
Model Retry Logic
The integration explicitly handles failures by raising ModelRetry. This informs the LLM that the tool call failed and provides the server's error message (e.g., a missing required field) so the model can attempt a corrected call.
Sources: stackone_ai/tools.py:756-762, tests/test_integrations_pydantic_ai.py:133-154
Installation and Requirements
To use this integration, you must install the pydantic-ai extra.
uv add 'stackone-ai[pydantic-ai]'
Sources: README.md:38-41, pyproject.toml:44
If the package is missing when to_pydantic_ai_tool() is called, the SDK raises an ImportError with a specific hint to install the stackone-ai[pydantic-ai] extra.
Sources: stackone_ai/tools.py:739-744, tests/test_integrations_pydantic_ai.py:133-154
Summary
The Pydantic AI Integration allows for seamless use of StackOne SaaS tools within AI agents. It prioritizes schema fidelity by passing served JSON Schemas directly to Pydantic AI and implements robust error handling through the ModelRetry mechanism, enabling agents to self-correct during multi-turn interactions.