How to beginner · 3 min read

How to use tools in Pydantic AI

Q: How to use tools in Pydantic AI

In pydantic_ai, define tools as Python functions decorated with @agent.tool inside an Agent instance. Call agent.run_sync() or agent.run() to invoke the agent, which can automatically call these tools based on user input.

Quick answer

In pydantic_ai, define tools as Python functions decorated with @agent.tool inside an Agent instance. Call agent.run_sync() or agent.run() to invoke the agent, which can automatically call these tools based on user input.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install pydantic-ai openai>=1.0

Setup

Install pydantic-ai and openai packages, and set your OpenAI API key as an environment variable.

Run pip install pydantic-ai openai
Set OPENAI_API_KEY in your environment

bash

pip install pydantic-ai openai

output

Collecting pydantic-ai
Collecting openai
Installing collected packages: openai, pydantic-ai
Successfully installed openai-1.x.x pydantic-ai-x.x.x

Step by step

Create an Agent with a system prompt and define tools as functions decorated with @agent.tool. The agent can call these tools automatically based on user queries.

python

import os
from pydantic_ai import Agent

# Ensure your OpenAI API key is set in environment
# export OPENAI_API_KEY="your_api_key"

# Define a simple tool

def main():
    agent = Agent(
        "openai:gpt-4o-mini",
        system_prompt="You are a helpful assistant with tool access.",
        api_key=os.environ["OPENAI_API_KEY"]
    )

    @agent.tool
def get_weather(ctx, location: str) -> str:
        # Dummy weather tool
        return f"The weather in {location} is sunny and 75°F."

    # Run the agent with a prompt that triggers the tool
    result = agent.run_sync("What's the weather in New York City?")
    print("Agent response:", result.data.answer)

if __name__ == "__main__":
    main()

output

Agent response: The weather in New York City is sunny and 75°F.

Common variations

You can use agent.run() for async calls, define multiple tools, or change the model by specifying a different model string like openai:gpt-4o. Tools can accept multiple typed parameters for structured inputs.

python

import asyncio
import os
from pydantic_ai import Agent

async def main_async():
    agent = Agent(
        "openai:gpt-4o",
        system_prompt="You are an assistant with multiple tools.",
        api_key=os.environ["OPENAI_API_KEY"]
    )

    @agent.tool
def add_numbers(ctx, a: int, b: int) -> int:
        return a + b

    response = await agent.run("Add 5 and 7 using your tool.")
    print("Async agent response:", response.data.answer)

if __name__ == "__main__":
    asyncio.run(main_async())

output

Async agent response: 12

Troubleshooting

If the agent does not call your tool, ensure your tool function is decorated with @agent.tool and the tool name matches the expected usage.
Check that OPENAI_API_KEY is correctly set in your environment.
Use typed parameters in tool functions to help the agent parse arguments correctly.

✅

Key Takeaways

Define tools as Python functions decorated with @agent.tool inside your Agent instance.
Invoke the agent with run_sync() or run() to enable automatic tool calling based on user input.
Use typed parameters in tool functions for structured argument parsing.
Set your OpenAI API key in the environment variable OPENAI_API_KEY before running.
Async usage is supported with agent.run() and Python async/await syntax.

Verified 2026-04 · openai:gpt-4o-mini, openai:gpt-4o

Verify ↗