[AAASM-3530] 📝 (docs): Declare framework compatibility + reconcile pydantic-ai range

README.md

@@ -21,6 +21,34 @@ Python SDK for **AI Agent Assembly** — a governance-native runtime for AI agen
 - **Native PyO3 fast path** (optional) — drop into a Rust runtime client when you need sub-millisecond policy checks.
 - **Typed throughout** — Pydantic models for every gateway payload, mypy strict on adapter base and registry.
 
+## Framework compatibility
+
+The SDK governs these AI-agent frameworks; install whichever one your agent already
+uses alongside `agent-assembly` and the matching adapter activates automatically (the
+frameworks are **not** runtime dependencies of the SDK — you pin the framework, within
+the supported range). **Tested version** is the exact line exercised by the live smoke
+suite (AAASM-3525) and the integration tests; older releases within the supported range
+are expected to work but are not continuously tested.
+
+| Framework | Import name | Supported range | Tested version |
+| --- | --- | --- | --- |
+| LangChain | `langchain` | `>=0.1.0` | `0.3.x` line |
+| LangGraph | `langgraph` | `>=0.1.0` | `0.2.x` line |
+| Pydantic AI | `pydantic_ai` | `>=0.1.0` | `>=0.3.0` |
+| CrewAI | `crewai` | `>=0.1.0` | `1.14.x` |
+| Google ADK | `google.adk` | `>=1.0.0,<2.0` | `1.x` line |
+| MCP | `mcp` | `>=1.0.0` | `1.27.x` |
+| OpenAI Agents | `agents` | `>=0.1.0` | `0.17.x` |
+
+Python framework compatibility is documented **authoritatively in the SDK docs** —
+[Framework compatibility](./docs/compatibility/frameworks.md) — because the Python
+adapters and the ranges they advertise via `get_supported_versions()` are the source of
+truth (Python-specific detail, version-sync policy, and the Pydantic AI hook-point note
+live there). The core docs provide a cross-SDK
+[index/hub](https://ai-agent-assembly.github.io/agent-assembly/stable/reference/framework-compatibility.html)
+that links out to each SDK's own page (Python here, plus Node and Go) — an index, not the
+canonical matrix (a `/stable/` link — it 404s until the first GA release, by design).
+
 ## Project status
 
 **Pre-1.0 (`0.x`) — published and usable, API not yet frozen.** The SDK is released to

docs/compatibility/frameworks.md

@@ -0,0 +1,107 @@
+# Framework compatibility
+
+**In plain terms:** this page answers *which AI-agent frameworks does the Python SDK
+govern, and at what versions?* — so you can confirm compatibility *before* you
+integrate, rather than discovering an unsupported framework version at runtime.
+
+Agent Assembly governs third-party agent frameworks without those frameworks needing to
+be aware of it. You call `init_assembly()` once and the SDK detects which supported
+frameworks are importable in your process and installs governance hooks for each (see
+[Framework support](../examples/framework-support.md) for the adapter ↔ example status,
+and [Core Concepts](../concepts/index.md#the-adapter-pattern) for the adapter pattern).
+
+## Authoritative for Python — and where the cross-SDK index lives
+
+**This page is the authoritative framework-compatibility reference for the Python SDK.**
+The Python adapters under `agent_assembly/adapters/` and the ranges each one advertises
+via `FrameworkAdapter.get_supported_versions()` are the source of truth — so the Python
+table below is what to trust for Python, not a mirror of some other page.
+
+The core docs host a **cross-SDK index/hub** that links out to each language SDK's own
+compatibility page (this one for Python, plus the Node and Go equivalents). It is an
+index, not the canonical matrix — each SDK's page is authoritative for its own language,
+because the adapters live in the SDK:
+
+- **[Cross-SDK framework-compatibility index →](https://ai-agent-assembly.github.io/agent-assembly/stable/reference/framework-compatibility.html)**
+
+!!! note "The `/stable/` link 404s until GA"
+    That URL points at the `stable` documentation channel, which only activates at the
+    first general-availability (`vX.Y.0`) release. Until then it returns *404 Not Found*
+    by design — the same convention the other compatibility links follow. The Python
+    table below is authoritative for the Python SDK regardless.
+
+## Supported frameworks (Python SDK)
+
+The Python SDK ships an adapter for each framework below under
+`agent_assembly/adapters/`. The **Supported range** column is the constraint the adapter
+itself advertises (`FrameworkAdapter.get_supported_versions()`); the **Tested version**
+column is the exact release exercised by the live smoke suite (AAASM-3525) and the
+`importorskip`-guarded integration tests. Where a framework's adapter accepts a broad
+`>=` range but only one line is exercised in CI, the **Tested version** is the honest
+statement of what is actually validated — older releases within the range are expected
+to work but are not continuously tested.
+
+| Framework | Import name | Adapter | Supported range | Tested version |
+| --- | --- | --- | --- | --- |
+| LangChain | `langchain` | `agent_assembly.adapters.langchain` | `>=0.1.0` | `0.3.x` line |
+| LangGraph | `langgraph` | `agent_assembly.adapters.langgraph` | `>=0.1.0` | `0.2.x` line |
+| Pydantic AI | `pydantic_ai` | `agent_assembly.adapters.pydantic_ai` | `>=0.1.0` (both the `<0.3` `Tool._run` and `>=0.3` `AbstractToolset.call_tool` hook points) | `>=0.3.0` — see [note below](#pydantic-ai-version-range) |
+| CrewAI | `crewai` | `agent_assembly.adapters.crewai` | `>=0.1.0` | `1.14.x` |
+| Google ADK | `google.adk` | `agent_assembly.adapters.google_adk` | `>=1.0.0,<2.0` | `1.x` line |
+| MCP | `mcp` | `agent_assembly.adapters.mcp` | `>=1.0.0` | `1.27.x` |
+| OpenAI Agents | `agents` | `agent_assembly.adapters.openai_agents` | `>=0.1.0` | `0.17.x` |
+
+!!! note "Adapter present vs. example present"
+    Every framework above has an adapter that is implemented and registered —
+    `init_assembly()` detects and hooks the framework whenever it is installed. Whether a
+    *runnable end-to-end example* exists for each is tracked separately in
+    [Framework support](../examples/framework-support.md).
+
+### Pydantic AI version range
+
+The Pydantic AI adapter supports **both** the legacy and current framework lines: on
+`<0.3.0` it patches the internal `pydantic_ai.tools.Tool._run` hook, and on `>=0.3.0`
+(where that entry point was renamed) it patches `AbstractToolset.call_tool` plus the
+concrete toolsets that override it. The hook point is auto-detected at
+`init_assembly()` time, so a single adapter covers both.
+
+The **tested line is `pydantic-ai>=0.3.0`** — that is the version installed by the SDK's
+own dev/test dependency group and exercised by the `importorskip`-guarded integration
+test, so it is the line we continuously validate. Earlier `0.1.x`–`0.2.x` releases still
+work through the `Tool._run` hook but are not exercised in CI.
+
+> **Note on older docs:** an earlier revision of the
+> [Pydantic AI example](../examples/pydantic-ai.md) pinned `pydantic-ai>=0.1.0,<0.3.0`
+> and stated that governance hooks only attach on the `0.1.x`–`0.2.x` line. That
+> predated the `>=0.3.0` `AbstractToolset.call_tool` support and is no longer accurate;
+> the example and that pin now track the tested `>=0.3.0` line.
+
+## Declaring frameworks in your own project
+
+The frameworks above are **not** runtime dependencies of `agent-assembly` — installing
+the SDK does not pull in LangChain, CrewAI, and so on. You install whichever framework
+your agent already uses, alongside the SDK, and the matching adapter activates
+automatically:
+
+```bash
+pip install agent-assembly langchain   # or crewai, pydantic-ai, mcp, openai-agents, ...
+```
+
+The SDK deliberately does **not** declare these frameworks as `pip install
+agent-assembly[langchain]`-style optional extras: the agent framework is the user's own
+choice and version, the SDK governs whatever is importable, and pinning a framework as an
+extra would imply the SDK owns its version. Pin the framework yourself, within the
+**Supported range** above.
+
+## How this matrix is kept in sync
+
+This table is sourced from two places that are the actual source of truth, so it does not
+drift silently:
+
+- **Supported range** ← each adapter's `get_supported_versions()` in
+  `agent_assembly/adapters/<framework>/adapter.py`.
+- **Tested version** ← the framework pins in the SDK's `pyproject.toml` `test`
+  dependency group and the live smoke suite (AAASM-3525).
+
+When an adapter's supported range changes or a tested-version pin is bumped, update the
+corresponding row here.

docs/compatibility/index.md

@@ -5,6 +5,7 @@ core runtime does a given SDK build talk to?*, and *how do versions and releases
 
 | Page | What it answers |
 | --- | --- |
+| [Framework compatibility](frameworks.md) | Which AI-agent frameworks the SDK governs (LangChain, LangGraph, Pydantic AI, CrewAI, Google ADK, MCP, OpenAI Agents) and at what version ranges / tested versions. |
 | [Runtime compatibility](runtime.md) | Supported Python versions, and how the pure-Python client vs. the pinned native extension each track the core runtime. |
 | [Release process](release-process.md) | How a version goes from `master` to PyPI (platform wheels, Trusted Publisher) and the docs site. |
 | [Release notes](release-notes.md) | Per-release change history. |

docs/examples/pydantic-ai.md

@@ -14,19 +14,21 @@ Integrate Agent Assembly with [Pydantic AI](https://ai.pydantic.dev/) to enforce
 
 This example builds on [Pydantic AI](https://ai.pydantic.dev/), the agent framework from the Pydantic team.
 
-The Agent Assembly Pydantic AI adapter hooks the internal `Tool._run` entry point, which exists in the Pydantic AI `0.1.x`–`0.2.x` line. Accordingly, `pyproject.toml` pins:
+The Agent Assembly Pydantic AI adapter auto-detects the framework's tool-execution hook across versions (`Tool._run` on `<0.3.0`, `AbstractToolset.call_tool` on `>=0.3.0`). This example targets the tested `>=0.3.0` line, so `pyproject.toml` pins:
 
 ```toml
 dependencies = [
     "agent-assembly>=0.0.1a2",
-    # The Agent Assembly Pydantic AI adapter patches `Tool._run`, which is
-    # present in the 0.1.x–0.2.x line. Newer 1.x releases renamed that internal
-    # entry point; pin to the supported range so governance hooks attach.
-    "pydantic-ai>=0.1.0,<0.3.0",
+    # The Agent Assembly Pydantic AI adapter auto-detects the tool-execution
+    # hook across versions: `Tool._run` on <0.3.0, and `AbstractToolset.call_tool`
+    # on >=0.3.0 (where that internal entry point was renamed). `>=0.3.0` is the
+    # tested line — the SDK's own dev/test group pins it, so it is the version
+    # exercised in CI.
+    "pydantic-ai>=0.3.0",
 ]
 ```
 
-Newer Pydantic AI `1.x` releases renamed that internal API, so the governance hooks would not attach there. The example requires Python `>= 3.12` and the Agent Assembly Python SDK `>= 0.0.1a2`.
+The adapter installs governance hooks on both the legacy (`<0.3.0`) and current (`>=0.3.0`) Pydantic AI lines; `>=0.3.0` is the continuously-tested line and the one this example targets. The example requires Python `>= 3.12` and the Agent Assembly Python SDK `>= 0.0.1a2`. For the full version-range table, see [Framework compatibility](../compatibility/frameworks.md).
 
 ## How it works
 
@@ -136,16 +138,16 @@ Pending tools route to `wait_for_tool_approval`, which denies them offline becau
 
 ## Notes & caveats
 
-!!! warning "Pydantic AI version pin"
-    The adapter hooks the internal `Tool._run` entry point, which exists in the Pydantic AI `0.1.x`–`0.2.x` line. `pyproject.toml` pins `pydantic-ai>=0.1.0,<0.3.0` so the governance hooks attach. Newer `1.x` releases renamed that internal API. If governance hooks do not fire, ensure `pydantic-ai` resolves to the pinned `0.1.x`–`0.2.x` range.
+!!! note "Pydantic AI version support"
+    The adapter auto-detects the tool-execution hook across versions: it patches `pydantic_ai.tools.Tool._run` on `<0.3.0`, and `AbstractToolset.call_tool` (plus the concrete toolsets that override it) on `>=0.3.0`, where that internal entry point was renamed. The **tested line is `pydantic-ai>=0.3.0`** — the SDK's own dev/test group pins it, so it is the version exercised in CI. Earlier `0.1.x`–`0.2.x` releases still work through the `Tool._run` hook but are not continuously tested. See [Framework compatibility](../compatibility/frameworks.md) for the full matrix.
 
 !!! note "Offline TestModel"
     The agent is driven by Pydantic AI's built-in `TestModel`, so the demo runs deterministically with no API key and no network. No running Agent Assembly gateway is required for the offline demo.
 
 !!! tip "Troubleshooting"
     - `ModuleNotFoundError: agent_assembly` → run `uv sync` first.
     - `ModuleNotFoundError: pydantic_ai` → run `uv sync`; `pydantic-ai` is a required dependency.
-    - Governance hooks do not fire → ensure `pydantic-ai` resolves to the pinned `0.1.x`–`0.2.x` range.
+    - Governance hooks do not fire → ensure `pydantic-ai` resolves within the supported range (`>=0.1.0`; `>=0.3.0` is the tested line).
     - `PolicyViolationError` in tests → expected; the deny/pending policy rules are intentional.
 
 To move to production mode: start an Agent Assembly gateway (or use your SaaS workspace URL), copy `.env.example` to `.env` and fill in credentials, swap `TestModel` for a real model (e.g. `openai:gpt-4o`) and set `OPENAI_API_KEY`, then run with the gateway environment variables:

mkdocs.yml

@@ -200,6 +200,7 @@ nav:
       - Models: api-reference/models.md
   - Compatibility & Versioning:
       - compatibility/index.md
+      - Framework compatibility: compatibility/frameworks.md
       - Runtime compatibility: compatibility/runtime.md
       - Release process: compatibility/release-process.md
       - Release notes: compatibility/release-notes.md