{"id":139,"library":"pydantic-ai","title":"Pydantic AI","description":"Pydantic AI is a Python agent framework built by the Pydantic team, designed for quickly and confidently building production-grade applications and workflows with Generative AI. It leverages Pydantic for structured output validation, type safety, and dependency injection, offering a model-agnostic approach to interacting with various LLM providers. The library integrates seamlessly with observability platforms like Pydantic Logfire for monitoring and debugging.","status":"active","version":"1.75.0","language":"python","source_language":"en","source_url":"https://github.com/pydantic/pydantic-ai","tags":["AI","LLM","Agent Framework","Pydantic","Generative AI","Structured Output","Type Safety"],"install":[{"cmd":"pip install pydantic-ai","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for data validation, structured outputs, and type safety.","package":"pydantic","optional":false},{"reason":"Commonly used for asynchronous HTTP requests within agents and tools, often passed via dependency injection.","package":"httpx","optional":true}],"imports":[{"note":"The primary interface for creating and managing AI agents.","symbol":"Agent","correct":"from pydantic_ai import Agent"},{"note":"Used for accessing dependencies within agent components (system prompts, tools, output validators).","symbol":"RunContext","correct":"from pydantic_ai import RunContext"},{"note":"An example of importing a built-in capability to extend agent behavior.","symbol":"Thinking","correct":"from pydantic_ai.capabilities import Thinking"},{"note":"Pydantic models for structured outputs should be imported directly from `pydantic`, not `pydantic_ai`.","wrong":"from pydantic_ai import BaseModel","symbol":"BaseModel","correct":"from pydantic import BaseModel"}],"quickstart":{"code":"import os\nfrom pydantic_ai import Agent\n\n# Set your API key for Anthropic (or other model provider)\n# os.environ['ANTHROPIC_API_KEY'] = os.environ.get('ANTHROPIC_API_KEY', '')\n\n# Define a simple agent with instructions and a model\nagent = Agent(\n    'anthropic:claude-sonnet-4-6', # Example model string, replace with your preferred model and provider\n    instructions='Be concise, reply with one sentence.',\n)\n\n# Run the agent synchronously\nresult = agent.run_sync('Where does \"hello world\" come from?')\nprint(result.output)","lang":"python","description":"This quickstart demonstrates how to create a basic Pydantic AI agent, configure it with a model and instructions, and run it to get a concise response."},"warnings":[{"fix":"Consult the official 'Upgrade Guide' and 'Version Policy' documentation, especially for migrations to V2. Address deprecation warnings as they appear in V1.","message":"Pydantic AI V2 is expected in April 2026. While V1 commits to API stability, functionality explicitly marked as deprecated will be removed in V2. Always review the upgrade guide for significant version bumps.","severity":"breaking","affected_versions":">=1.0.0 (upcoming V2)"},{"fix":"Avoid using beta features in production environments unless explicitly accepting the risk of breaking changes. Monitor release notes for beta features graduating to stable status.","message":"Minor releases may introduce 'beta features' with unstable APIs and behaviors that are not backward-compatible. These are typically in `beta` modules.","severity":"gotcha","affected_versions":"All V1.x.x minor releases"},{"fix":"Keep `pydantic-ai` updated and regularly review release notes and the official documentation for changes, new features, and updated patterns. Follow the project's GitHub releases closely.","message":"The library is under rapid development with frequent minor releases (sometimes daily). This means new features are added often, and while V1 aims for stability, interfaces can evolve quickly in minor ways or introduce new best practices.","severity":"gotcha","affected_versions":"All V1.x.x releases"},{"fix":"Refer to the official documentation for the correct model string format for each supported provider and model.","message":"Model specification uses a provider-prefixed string (e.g., `openai:gpt-5.2`, `anthropic:claude-sonnet-4-6`). Incorrectly formatted model strings will result in runtime errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Thoroughly understand the 'Dependencies' section in the official documentation. Ensure `RunContext` is correctly typed when used in agent components and that dependencies are correctly provided during `agent.run()` calls.","message":"Dependency injection with `deps_type` on `Agent` and `RunContext` is a core concept. Misunderstanding how dependencies are passed to system prompts, tools, and output validators can lead to unexpected behavior or errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T08:24:29.346Z","next_check":"2026-06-30T00:00:00.000Z","problems":[{"fix":"For modern Jupyter/IPython (7.0+), you can directly use `await agent.run()`. For legacy environments or to avoid conflicts, use `nest_asyncio` and `agent.run_sync()`: \n```python\nimport nest_asyncio\nfrom pydantic_ai import Agent\n\nnest_asyncio.apply()\nagent = Agent('openai:gpt-5.2')\nresult = agent.run_sync('Who let the dogs out?')\n```","cause":"This error occurs when attempting to run asynchronous `pydantic-ai` agent methods (e.g., `agent.run()`) in environments like Jupyter Notebooks or Google Colab where an asyncio event loop is already active.","error":"RuntimeError: This event loop is already running."},{"fix":"Set the API key as an environment variable (e.g., `export OPENAI_API_KEY='your_key_here'`) before running your application, or pass it directly when initializing the `Agent` or model:\n```python\nfrom pydantic_ai import Agent\n\n# Option 1: Pass as a keyword argument\nagent = Agent('openai:gpt-4', api_key='your_openai_api_key')\n\n# Option 2: Ensure environment variable is set\n# os.environ['OPENAI_API_KEY'] = 'your_openai_api_key'\nagent = Agent('openai:gpt-4')\n```","cause":"The configured Large Language Model (LLM) provider (e.g., OpenAI, Anthropic, Google) requires an API key for authentication, but it was not provided as an argument during model initialization or set in the corresponding environment variable (e.g., `OPENAI_API_KEY`).","error":"UserError: API key must be provided or set in the [MODEL]_API_KEY environment variable."},{"fix":"Install the library using pip:\n```bash\npip install pydantic-ai\n```\nEnsure you are using the correct Python environment where the package was installed.","cause":"The `pydantic-ai` library has not been installed in your current Python environment, or the Python interpreter being used does not have access to the installed package.","error":"ModuleNotFoundError: No module named 'pydantic_ai'"},{"fix":"Ensure you are using the latest stable versions of `pydantic-ai` and the `openai` library. If using a custom `base_url` (e.g., for local models like Ollama), verify the URL is correct and the server is running. Sometimes, an explicit `client` configuration might be required for advanced setups. Upgrading `pydantic-ai` (`pip install --upgrade pydantic-ai`) often resolves such issues.","cause":"This `AttributeError` often arises when there's a misconfiguration or an outdated version of `pydantic-ai` or its dependencies, leading to the `OpenAIModel` instance not properly initializing its internal client object, especially with custom `base_url` setups or older API versions.","error":"AttributeError: 'OpenAIModel' object has no attribute 'client'"},{"fix":"Upgrade both `pydantic-ai` and the `openai` library to their latest compatible versions. Also, ensure your `pydantic` library is up to date, as `pydantic-ai` relies heavily on it. This error was notably resolved in some cases by updating to Pydantic 2.11.0a2 and above.","cause":"This `TypeError` typically indicates a compatibility issue between `pydantic-ai`'s internal use of Pydantic and the installed version of `openai` or `pydantic` itself, particularly when handling complex type hints like `typing.Union` in LLM responses or model definitions.","error":"TypeError: Cannot instantiate typing.Union"}],"ecosystem":"pypi","meta_description":null,"install_score":35,"install_tag":"stale","quickstart_score":23,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"logfire","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"openai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"logfire","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.69,"mem_mb":63.2,"disk_size":"340M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.65,"mem_mb":63.2,"disk_size":"340M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":4.76,"mem_mb":63.2,"disk_size":"340M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":5.2,"mem_mb":63.5,"disk_size":"347M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"logfire","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"openai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"logfire","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":6.14,"mem_mb":68,"disk_size":"366M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":6.25,"mem_mb":68,"disk_size":"366M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":6.24,"mem_mb":68,"disk_size":"366M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":7.24,"mem_mb":68.4,"disk_size":"373M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"logfire","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"openai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"logfire","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":7.32,"mem_mb":67,"disk_size":"353M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":7.62,"mem_mb":67,"disk_size":"353M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":7.68,"mem_mb":67,"disk_size":"353M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":7.43,"mem_mb":67.4,"disk_size":"360M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"logfire","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"openai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"logfire","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":7.03,"mem_mb":67.7,"disk_size":"352M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":7.07,"mem_mb":67.7,"disk_size":"352M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":6.9,"mem_mb":67.7,"disk_size":"352M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":6.72,"mem_mb":67.7,"disk_size":"359M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"logfire","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"openai","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"logfire","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.12,"mem_mb":39.1,"disk_size":"249M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"openai","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.2,"mem_mb":30.5,"disk_size":"245M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.24,"mem_mb":30.5,"disk_size":"245M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}