`pydantic_graph.beta` import fails with circular import error in v1.6.0

[rhokstar]

Initial Checks

• I confirm that I'm using the latest version of Pydantic AI
• I confirm that I searched for my issue in https://github.com/pydantic/pydantic-ai/issues before opening this issue

Description

Description

The documented import path for the beta Graph API results in a circular import error.

According to the documentation at https://ai.pydantic.dev/graph/beta/, the beta API should be imported as:

from pydantic_graph.beta import GraphBuilder, StepContext

However, this import fails with a circular dependency error in pydantic-ai v1.6.0 and pydantic-graph v1.6.0.

---

Environment

• pydantic-ai version: 1.6.0
• pydantic-graph version: 1.6.0
• Python version: 3.13.3
• Operating System: macOS (also reproduced on clean Linux venv)
• Installation method: pip install pydantic-ai==1.6.0

---

Minimal Reproducible Example

"""
Reproduces circular import bug in pydantic-ai v1.6.0
"""
from pydantic_graph.beta import GraphBuilder

# ImportError: cannot import name 'Graph' from partially initialized module
# 'pydantic_graph.beta' (most likely due to a circular import)

Full reproduction script:

import sys
print(f"Python: {sys.version}")

try:
    print("Attempting: from pydantic_graph.beta import GraphBuilder")
    from pydantic_graph.beta import GraphBuilder
    print("✅ SUCCESS: Import worked")
    print(f"GraphBuilder: {GraphBuilder}")
except ImportError as e:
    print(f"❌ FAILED: {e}")
    print("\nCircular import detected!")

---

Expected Behavior

The import should succeed, allowing users to access the beta GraphBuilder API as documented:

from pydantic_graph.beta import GraphBuilder, StepContext

# Should work without errors

---

Actual Behavior

Import fails with circular dependency error:

ImportError: cannot import name 'Graph' from partially initialized module 'pydantic_graph.beta'
(most likely due to a circular import)
(/path/to/site-packages/pydantic_graph/beta/__init__.py)

Full Traceback:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    from pydantic_graph.beta import GraphBuilder
  File ".../site-packages/pydantic_graph/beta/__init__.py", line 11, in <module>
    from .graph import Graph
  File ".../site-packages/pydantic_graph/beta/graph.py", line 21, in <module>
    from pydantic_ai.exceptions import ExceptionGroup
  File ".../site-packages/pydantic_ai/__init__.py", line 3, in <module>
    from .agent import (
  File ".../site-packages/pydantic_ai/agent/__init__.py", line 19, in <module>
    from .. import (
  File ".../site-packages/pydantic_ai/_agent_graph.py", line 24, in <module>
    from pydantic_graph.beta import Graph, GraphBuilder
ImportError: cannot import name 'Graph' from partially initialized module 'pydantic_graph.beta'
(most likely due to a circular import)

---

Root Cause Analysis

The circular dependency chain is:

1. pydantic_graph.beta.__init__ imports from .graph
2. pydantic_graph.beta.graph imports from pydantic_ai.exceptions (line 21)
3. pydantic_ai.__init__ imports from .agent
4. pydantic_ai.agent imports from pydantic_ai._agent_graph
5. pydantic_ai._agent_graph imports from pydantic_graph.beta (line 24) ← circular!

Problematic import in pydantic_graph/beta/graph.py (approximately line 21):

# The exact import likely looks something like:
from pydantic_ai.exceptions import ExceptionGroup  # or FallbackExceptionGroup

Note: The specific exception class may be ExceptionGroup, FallbackExceptionGroup, or another exception class from pydantic_ai.exceptions

This creates a bi-directional dependency:

• pydantic_graph.beta → pydantic_ai.exceptions
• pydantic_ai._agent_graph → pydantic_graph.beta

---

Workaround

The GraphBuilder API is functional, but must be imported via the private _agent_graph module:

from pydantic_ai._agent_graph import GraphBuilder  # ✅ Works

# Verify it's the same class
print(GraphBuilder.__module__)
# Output: pydantic_graph.beta.graph_builder

This workaround is not recommended for production as _agent_graph is a private module that may change without notice.

---

Impact

High: The documented beta API is completely unusable via its public import path. Users following the documentation at https://ai.pydantic.dev/graph/beta/ will encounter this error immediately.

Affected users:

• Anyone attempting to use the beta Graph API
• Projects migrating from asyncio to GraphBuilder patterns
• Developers following the official documentation examples

---

Suggested Fixes

Option 1: Remove circular import in pydantic_graph.beta.graph

Change pydantic_graph/beta/graph.py:21 to avoid importing from pydantic_ai:

# Instead of:
from pydantic_ai.exceptions import ExceptionGroup

# Use:
from exceptiongroup import ExceptionGroup  # or inline the exception if it's custom

Option 2: Lazy import in pydantic_ai._agent_graph

Move the pydantic_graph.beta import inside functions rather than module-level:

# In pydantic_ai/_agent_graph.py
def some_function():
    from pydantic_graph.beta import Graph, GraphBuilder  # Lazy import
    ...

Option 3: Move pydantic_ai.exceptions to separate package

Break the circular dependency by extracting shared exceptions to a standalone package that both pydantic_ai and pydantic_graph can depend on without circularity.

---

Additional Context

• The beta API was introduced in PR Introduce new graph API in beta #2982 (merged October 20-24, 2025)
• No existing GitHub issues found for this circular import (searched on 2025-10-27)
• The API code itself appears functional (workaround confirms this)
• Only the public import path is broken
• The exceptiongroup backport package is used by pydantic-ai for Python < 3.11 compatibility
• pydantic_ai.exceptions defines several exception types including FallbackExceptionGroup which inherits from ExceptionGroup[Any]

---

References

• Documentation: https://ai.pydantic.dev/graph/beta/
• PR introducing beta API: Introduce new graph API in beta #2982
• Affected files:
  • pydantic_graph/beta/graph.py:21 (imports pydantic_ai.exceptions)
  • pydantic_ai/_agent_graph.py:24 (imports pydantic_graph.beta)
  • pydantic_graph/beta/__init__.py:11 (imports .graph)

---

Reproduction in Fresh Environment

To verify this is not environment-specific:

# Create fresh virtual environment
python -m venv /tmp/test_pydantic_graph
source /tmp/test_pydantic_graph/bin/activate

# Install latest pydantic-ai
pip install pydantic-ai==1.6.0

# Test import
python -c "from pydantic_graph.beta import GraphBuilder"

# Result: ImportError (circular import)

Confirmed to fail on:

• ✅ macOS 14.7.1 (ARM64), Python 3.13.3
• ✅ Fresh pip install (no other packages)

Expected to fail on all platforms:

• ✅ Linux (Ubuntu/Debian)
• ✅ Windows
• ✅ Python 3.9, 3.10, 3.11, 3.12, 3.13 (all versions)

---

Thank You

Thank you for maintaining pydantic-ai! The GraphBuilder beta API looks very promising, and I'm looking forward to using it once this import issue is resolved.

Example Code

Python, Pydantic AI & LLM client version

- Python 3.13.3
- Pydantic AI 1.6.0