> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pydantic AI Integration

> Build type-safe AI agents with StackOne tools and Pydantic AI

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

## Overview

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

```python theme={null}
import json
from stackone_ai import StackOneToolSet
from pydantic_ai import Agent, Tool

def create_agent_for_account(account_id: str):
    # Initialize toolset and fetch tools
    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,
            )
        )

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

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

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

## Dynamic Tool Loading

Use `fetch_tools()` to load only the tools available for specific accounts:

```python theme={null}
from stackone_ai import StackOneToolSet

toolset = StackOneToolSet()

# Load all tools for specific accounts (most common)
tools = toolset.fetch_tools(
    account_ids=["account-123", "account-456"]
)

# Optional: Filter by operation type for security
tools = toolset.fetch_tools(
    account_ids=["account-123"],
    actions=["*_list_*", "*_get_*"]  # Only list and get operations (read-only)
)
```

## Structured Outputs

Leverage Pydantic AI's type-safe responses:

```python theme={null}
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

```python theme={null}
# Get from user/tenant context
account_id = request.user.stackone_account_id
account_id = get_account_for_tenant(tenant_id)
```

### Error Handling

```python theme={null}
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}")
```

### Tool Filtering

```python theme={null}
# Only expose read operations (optional - for security)
tools = toolset.fetch_tools(
    account_ids=[account_id],
    actions=["*_list_*", "*_get_*"]  # Only list and get
)

# Or exclude dangerous operations
tools = toolset.fetch_tools(
    account_ids=[account_id],
    actions=["!*_delete_*"]  # Everything except deletes
)
```

## Next Steps

* [Basic Usage](/agents/python/basic-usage) for fetching and executing tools
* [Tool Filtering](/agents/python/tool-filtering) for security
* [Tool Search](/agents/python/tool-search) for natural language tool discovery