Pydantic AI

Build production-ready AI agents with Pydantic AI’s type-safe framework and direct access to business data through StackOne’s Tools.

Supported languages: Python.

Type-safe agents with Pydantic validation
Structured outputs with full type checking
Dynamic tool loading based on StackOne Linked Accounts
OpenAI-compatible tool integration

Calling actions

Install

# Requires Python 3.10 or higher
# uv or pip

# Using uv (recommended)
uv add 'stackone-ai[mcp]' pydantic-ai

# Using pip
pip install 'stackone-ai[mcp]' pydantic-ai

# Optional: install with example dependencies
uv add 'stackone-ai[mcp,examples]'
pip install 'stackone-ai[mcp,examples]'

export STACKONE_API_KEY=your_api_key_here

Fetch Tools

Two approaches to retrieving tools:

Fetch Tools (with filtering) — fetch all tools upfront with optional filters applied.
Search & Execute — hand the model just tool_search + tool_execute and let the agent discover what it needs at runtime.

See Tool Discovery for more details on which may be best in your scenario.

Fetch tools
Search & execute

Fetch StackOne tools for the linked account and convert each one to a Pydantic AI Tool with its schema:

import json
from stackone_ai import StackOneToolSet
from pydantic_ai import Tool

# Get account ID from your app's auth context or StackOne dashboard
account_id = "your-account-id"

# Initialize toolset and fetch tools.
# Optionally narrow the fetch with filters:
#   providers=["hibob", "workday"]    — only these connectors
#   actions=["*_list_*", "*_get_*"]   — glob patterns, e.g. read-only actions
toolset = StackOneToolSet()
tools = toolset.fetch_tools(account_ids=[account_id])

# Convert each StackOne tool to a Pydantic AI Tool with proper schema
pydantic_tools = []
for stackone_tool in tools:
    params_schema = stackone_tool.to_openai_function()["function"]["parameters"]

    def execute(t=stackone_tool, **kwargs: object) -> str:
        return json.dumps(t.execute(kwargs))

    pydantic_tools.append(
        Tool.from_schema(
            execute,
            name=stackone_tool.name,
            description=stackone_tool.description,
            json_schema=params_schema,
        )
    )

The LLM receives only 2 tools and searches the catalog autonomously:

from stackone_ai import StackOneToolSet

toolset = StackOneToolSet(
    search={"method": "semantic", "top_k": 3},
    execute={"account_ids": ["your-account-id"]},
)

# LLM receives only 2 tools - it searches and executes autonomously.
# .pydantic_ai() returns Pydantic AI tools directly, so no conversion is needed
pydantic_tools = toolset.pydantic_ai(mode="search_and_execute")

Run the agent loop

Create the agent with the tools and run it — Pydantic AI executes tool calls automatically, so the same code works for both approaches:

from pydantic_ai import Agent

# Create agent with tools
agent = Agent(
    "openai:gpt-5.4",
    system_prompt="You are a helpful HR assistant.",
    tools=pydantic_tools,
)

result = agent.run_sync("List the first 5 employees")
print(result.output)

Structured outputs

Leverage Pydantic AI’s type-safe responses:

from pydantic import BaseModel
from pydantic_ai import Agent

class EmployeeSummary(BaseModel):
    total_count: int
    departments: list[str]
    average_tenure_years: float

agent = Agent(
    model=OpenAIModel('gpt-5.4'),
    result_type=EmployeeSummary,
    system_prompt="Analyze employee data and return structured summaries."
)

# Returns validated EmployeeSummary instance
result = agent.run_sync("Summarize the employee base")
summary: EmployeeSummary = result.data

print(f"Total employees: {summary.total_count}")
print(f"Departments: {', '.join(summary.departments)}")

Best practices

Account ID from context

# Get from user/tenant context
account_id = request.user.stackone_account_id
account_id = get_account_for_tenant(tenant_id)

Error handling

from stackone_ai.models import StackOneError, StackOneAPIError

try:
    result = agent.run_sync(message)
except StackOneAPIError as e:
    print(f"API error: {e.message}")
except StackOneError as e:
    print(f"StackOne error: {e.message}")

Multi-account usage

Each tool execution runs against a specific customer account. Set account IDs once on the toolset, or pass them per request.

# Set accounts on the toolset for all subsequent calls
toolset.set_accounts(["account-123", "account-456"])
tools = toolset.fetch_tools()

# Or pass account IDs per request
tools = toolset.fetch_tools(account_ids=["account-123", "account-456"])

# Loop over customer accounts dynamically
customer_accounts = ["account-1", "account-2", "account-3"]

for account_id in customer_accounts:
    tools = toolset.fetch_tools(
        actions=["workday_list_workers"],
        account_ids=[account_id],
    )
    employee_tool = tools.get_tool("workday_list_workers")
    if employee_tool:
        employees = employee_tool.call()
        print(f"Found {len(employees['data'])} employees")

Error handling

from stackone_ai.models import StackOneError, StackOneAPIError

try:
    result = employee_tool.call(id="employee-123")
    print("Success:", result)
except StackOneAPIError as e:
    print(f"API error: {e.message}")
except StackOneError as e:
    print(f"StackOne error: {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

File downloads (binary responses)

Actions that download a file (for example googledrive_unified_download_file, documents_download_file, or any *_unified_download_file) return raw bytes plus metadata, not parsed JSON. The SDK decides from the response Content-Type: JSON is parsed as usual, and anything else is treated as a file download.call() and execute() both return the dict directly (it isn’t wrapped in a result object), so read its values with dict keys like result["content"].

tools = toolset.fetch_tools(actions=["googledrive_*"], account_ids=["your-account-id"])
download = tools.get_tool("googledrive_unified_download_file")

result = download.execute({"id": "file-id"})

# result describes 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, from both call() and execute():

Key	Type	Description
`content`	`bytes`	Raw file bytes. Not JSON-serializable (see note).
`content_type`	`str`	File MIME type (for example `application/pdf`), or `application/octet-stream`.
`status_code`	`int`	HTTP status of the download response.
`headers`	`dict`	Response headers.
`file_name`	`str \| None`	Filename from `Content-Disposition` (RFC 5987 `filename*` aware), else `None`.

content is raw bytes and is not JSON-serializable. If you forward tool results to an LLM (or anything that re-serializes to JSON), handle or strip the content key. For example, base64-encode it on the LLM-facing path.

Troubleshooting

Execute a tool

Direct execution is useful for testing and debugging. In production, your agent framework handles tool calls automatically.

tools = toolset.fetch_tools(account_ids=["your-account-id"])
employee_tool = tools.get_tool("workday_list_workers")

# call() with keyword arguments
result = employee_tool.call(id="employee-123", include_details=True)
print(result["data"])

# execute() with dictionary payloads
result = employee_tool.execute({"id": "employee-123", "include_details": True})

# execute() with OpenAI-style arguments
payload = {"arguments": {"id": "employee-123"}}
result = employee_tool.execute(payload)

Calling actions

Structured outputs

Best practices

Account ID from context

Error handling

Multi-account usage

Troubleshooting

Execute a tool

Next steps

Observability

Tool Defense

​Calling actions

​Structured outputs

​Best practices

​Account ID from context

​Error handling

​Multi-account usage

​Troubleshooting

​Execute a tool

​Next steps

Observability

Tool Defense

Calling actions

Structured outputs

Best practices

Account ID from context

Error handling

Multi-account usage

Troubleshooting

Execute a tool

Next steps