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

# Adapters overview

> How hexgate wraps third-party agent frameworks, and which versions are verified.

## How framework wrapping works

In addition to its native `create_agent(...)` runtime, `hexgate` ships adapters
that wrap agents built with **OpenAI Agents SDK**, **LangChain / LangGraph**,
**Google ADK**, or **Pydantic AI** to add two things without touching the agent's
logic:

1. **Tool-call policy enforcement.** Each tool the agent can invoke is gated by a
   `PolicyEnforcer` that returns a typed `Decision` (allow / deny / needs-approval)
   per call. Non-allow outcomes render as a `[policy_denied]` / `[approval_required]`
   marker the model sees as tool output (or, for pydantic\_ai, a `ModelRetry`)
   rather than aborting the run, so the agent can recover.
2. **User-aware observability.** Every run is traced through Langfuse with the
   active [`HexgateContext`](/concepts/user-scope)'s identity (user id, session id, role)
   propagated onto the spans.

The four integrations differ in shape because the underlying SDKs do:

|                   | OpenAI Agents SDK                                                        | LangChain / LangGraph                                                                               | Google ADK                                                                                  | Pydantic AI                                                                     |
| ----------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Entry point       | `HexgateRunner` (replaces `Runner`)                                      | `wrap_langchain_agent` (returns a proxy)                                                            | `HexgateRunner` (replaces `Runner`)                                                         | `wrap_pydantic_agent` (returns a proxy)                                         |
| Tool wrapping     | Copies each `FunctionTool`, replaces `on_invoke_tool`                    | Mutates each `BaseTool` in place (`install_enforcer_on_tool`), sets `handle_tool_error=True`        | Copies each `BaseTool` (normalizing bare callables to `FunctionTool`), replaces `run_async` | Copies each `Tool` and overrides `function_schema.call`                         |
| Denial behavior   | Returns `decision.as_error_message()` as tool output                     | Returns `{"ok": False, "error": decision.as_error_payload()}`                                       | Returns `decision.as_error_message()` as tool output                                        | Raises `ModelRetry(decision.as_error_message())`                                |
| Tracing           | `OpenAIAgentsInstrumentor` + `propagate_attributes`                      | Langfuse `CallbackHandler` in each `RunnableConfig` + `propagate_attributes`                        | `GoogleADKInstrumentor` + `propagate_attributes`                                            | `Agent.instrument_all()` + `propagate_attributes`                               |
| Per-call identity | `hexgate_context: HexgateContext` on `run` / `run_sync` / `run_streamed` | `hexgate_context: HexgateContext` on `invoke` / `ainvoke` / `stream` / `astream` / `astream_events` | `hexgate_context: HexgateContext` on `run` / `run_async`                                    | `hexgate_context: HexgateContext` on `run` / `run_sync` / `run_stream` / `iter` |

Role resolution happens **at call time** from the active `HexgateContext` contextvar — one
wrapped agent serves many users concurrently because the scope is per-call. All
adapters resolve the API key the same way: from the explicit `api_key=` argument,
falling back to the `HEXGATE_API_KEY` environment variable.

## Compatible framework versions

hexgate's adapters are exercised against a framework-version matrix. Policy
enforcement is verified across these ranges:

| Framework             | Package            | Verified compatible | Notes                                                                                                                                                                                           |
| --------------------- | ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OpenAI Agents SDK     | `openai-agents`    | **0.8.0 – 0.18.3**  | below 0.8.0 the adapter cannot import (`RunState` was added in 0.8.0)                                                                                                                           |
| LangChain / LangGraph | `langchain`        | **1.2.15 – 1.3.14** | 1.1.0/1.2.5 have a known import break. 1.0.0 also tests clean but sits below the enforced `langchain>=1.2.15` floor, so it can't be installed alongside hexgate. Pairs with `langgraph>=1.1.10` |
| Google ADK            | `google-adk`       | **1.14.0 – 2.5.0**  | spans the 1.x → 2.x line                                                                                                                                                                        |
| Pydantic AI           | `pydantic-ai-slim` | **1.88.0 – 2.12.0** | spans the 1.x → 2.x line                                                                                                                                                                        |
| deepagents            | `deepagents`       | **0.1.4 – 0.6.12**  | no adapter of its own — produces a LangGraph graph wrapped via `wrap_langchain_agent`                                                                                                           |

Upper bounds are the latest versions tested, not hard ceilings — newer releases
may work but aren't verified yet. Minimums for pinned dependencies (`openai-agents`,
`langchain`, `langgraph`, `google-adk`, `pydantic-ai-slim`) are enforced by hexgate's
requirements. `langgraph>=1.1.10` is floored alongside `langchain>=1.2.15`: it's the
langgraph of that verified set, and older langgraph is the transitive import break
that fails langchain 1.1.0/1.2.5.