docs: introduce langchain-runcycles for LangChain agent users

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -13,6 +13,7 @@ body:
         - cycles-protocol
         - cycles-client-python
         - cycles-client-typescript
+        - langchain-runcycles
         - cycles-spring-boot-starter
         - cycles-mcp-server
         - cycles-openai-agents

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -13,6 +13,7 @@ body:
         - cycles-protocol
         - cycles-client-python
         - cycles-client-typescript
+        - langchain-runcycles
         - cycles-spring-boot-starter
         - cycles-mcp-server
         - cycles-openai-agents

AUDIT.md

@@ -239,3 +239,17 @@ Metadata-only release retargeting the package for category-search discovery on P
 Driven by Python-side adoption diagnostic finding the biggest sub-gap was discovery, not SDK feature parity. Companion changes: GitHub topics on this repo (`governance` dropped, `mcp` added) and Python framework integration guide retitling on `runcycles/docs` (PR #568).
 
 Protocol conformance: No protocol or wire-format changes. Existing test suite at 100% coverage; no test additions.
+
+## LangChain Agent Middleware Integration Pointer (added 2026-05-10)
+
+**Files:** `README.md`, `examples/langchain_integration.py`
+**Version:** unreleased (next 0.4.x — docs/examples only)
+
+Documentation-only update pointing users at the new sibling package [`langchain-runcycles`](https://github.com/runcycles/langchain-runcycles) for LangChain **agent middleware** integration. No SDK code changes; no protocol changes.
+
+- **README.md**: Added a new `## Integrations` section listing `langchain-runcycles` (PyPI: `langchain-runcycles`) as the canonical path for `langchain.agents.create_agent` workflows. The existing `examples/langchain_integration.py` row is reframed as the right fit for **non-agent** LangChain runnables (bare `ChatOpenAI`, chains, RAG); middleware requires `create_agent` so the two patterns serve different surfaces and both remain supported.
+- **examples/langchain_integration.py**: Updated the file-level docstring to point at `langchain-runcycles` for agent workflows while preserving the callback-handler example as-is. No code changes.
+
+Background: LangChain 1.x introduced an `AgentMiddleware` API with `wrap_tool_call`, `before_model`, and `wrap_model_call` hooks. The new package wraps that API on top of this SDK's existing `decide` / `create_reservation` / `commit_reservation` / `release_reservation` surface — no new SDK methods needed. Splitting into a sibling repo follows LangChain's [publishing guidance](https://docs.langchain.com/oss/python/contributing/publish-langchain) ("New integrations should be published as standalone PyPI packages") and the `langchain-<service>` naming convention used by `langchain-anthropic`, `langchain-openai`, etc.
+
+Protocol conformance: No protocol or wire-format changes. The new sibling package consumes this SDK as a normal dependency.

README.md

@@ -443,10 +443,18 @@ The [`examples/`](examples/) directory contains runnable integration examples:
 | [anthropic_integration.py](examples/anthropic_integration.py) | Guard Anthropic messages with per-tool budget tracking |
 | [streaming_usage.py](examples/streaming_usage.py) | `stream_reservation()` context manager with auto-commit |
 | [fastapi_integration.py](examples/fastapi_integration.py) | FastAPI middleware, dependency injection, per-tenant budgets |
-| [langchain_integration.py](examples/langchain_integration.py) | LangChain callback handler for budget-aware agents |
+| [langchain_integration.py](examples/langchain_integration.py) | LangChain callback handler for non-agent runnables (`ChatOpenAI` etc.) — for agents using `create_agent`, see [`langchain-runcycles`](https://pypi.org/project/langchain-runcycles/) below |
 
 See [examples/README.md](examples/README.md) for setup instructions.
 
+## Integrations
+
+Sibling packages and integrations published separately:
+
+| Package | Purpose |
+|---|---|
+| [`langchain-runcycles`](https://github.com/runcycles/langchain-runcycles) (PyPI: [`langchain-runcycles`](https://pypi.org/project/langchain-runcycles/)) | LangChain agent middleware — pre-tool-call authorization (`CyclesToolGate`) and fan-out caps (`CyclesFanOutGate`) for `create_agent` workflows. Use this for agent-style LangChain code; the [callback handler example](examples/langchain_integration.py) in this repo remains the right fit for bare-runnable (non-agent) LangChain usage. |
+
 ## Development
 
 ```bash

examples/langchain_integration.py

@@ -1,7 +1,21 @@
-"""Integrating Cycles with LangChain.
+"""Integrating Cycles with LangChain via the BaseCallbackHandler API.
 
-Demonstrates a custom callback handler that creates budget reservations
-for every LLM call in a LangChain chain or agent.
+This example uses LangChain's traditional callback-handler pattern to wrap each
+LLM call with a Cycles reservation. It is the right fit for **non-agent**
+LangChain workflows — bare ``ChatOpenAI``/``ChatAnthropic`` runnables, chains,
+RAG pipelines, etc.
+
+For LangChain **agents** built with ``langchain.agents.create_agent`` (the
+``wrap_tool_call`` / ``before_model`` middleware API introduced in LangChain
+1.x), use the dedicated middleware package instead:
+
+    pip install langchain-runcycles
+    # https://github.com/runcycles/langchain-runcycles
+
+That package exposes ``CyclesToolGate`` (pre-tool-call authorization) and
+``CyclesFanOutGate`` (turn-cap / fan-out halts) — both work with sync and
+async agents and offer features the callback handler cannot, such as denying
+a tool call before it runs and halting an agent loop on remote policy.
 
 Requirements:
     pip install runcycles langchain langchain-openai