From 7531f9486a14bd81a5d7a9113934a9f5307cbfef Mon Sep 17 00:00:00 2001 From: Albert Mavashev Date: Sun, 10 May 2026 07:58:36 -0400 Subject: [PATCH 1/2] docs: point LangChain agent users at langchain-runcycles sibling package MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documentation-only update introducing langchain-runcycles (https://github.com/runcycles/langchain-runcycles, PyPI: langchain-runcycles) as the canonical path for LangChain agent middleware integration with Cycles. No SDK code or protocol changes. - README.md: new "## Integrations" section listing langchain-runcycles as the right fit for langchain.agents.create_agent workflows. The existing examples/langchain_integration.py row is reframed as the callback-handler path for non-agent runnables (bare ChatOpenAI, chains, RAG) — the two patterns serve different surfaces and both remain supported. - examples/langchain_integration.py: docstring updated to point agent-using readers at langchain-runcycles. Code unchanged. - AUDIT.md: new entry "LangChain Agent Middleware Integration Pointer (added 2026-05-10)" documenting the docs-only nature of this change and the rationale for splitting the agent middleware into a sibling package per LangChain's publishing guidance (https://docs.langchain.com/oss/python/contributing/publish-langchain). The new package wraps the existing decide / create_reservation / commit_reservation / release_reservation / stream_reservation surface; no SDK methods were added to this repo. --- AUDIT.md | 14 ++++++++++++++ README.md | 10 +++++++++- examples/langchain_integration.py | 20 +++++++++++++++++--- 3 files changed, 40 insertions(+), 4 deletions(-) diff --git a/AUDIT.md b/AUDIT.md index 79ab246..0acd90f 100644 --- a/AUDIT.md +++ b/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-` 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. diff --git a/README.md b/README.md index a6c76ac..2c290ec 100644 --- a/README.md +++ b/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 diff --git a/examples/langchain_integration.py b/examples/langchain_integration.py index f991e14..771f09a 100644 --- a/examples/langchain_integration.py +++ b/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 From f9319183abca11491259933f25b38fd3df26e3c9 Mon Sep 17 00:00:00 2001 From: Albert Mavashev Date: Sun, 10 May 2026 08:14:51 -0400 Subject: [PATCH 2/2] chore(github): add langchain-runcycles to issue-template dropdowns Sibling-repo consistency follow-up to commit 80a0736 (which introduced langchain-runcycles in README + examples but missed the issue templates). Users opening bugs or feature requests can now select langchain-runcycles as the affected repository. Files: .github/ISSUE_TEMPLATE/bug_report.yml, .github/ISSUE_TEMPLATE/feature_request.yml Inserted after cycles-client-typescript to keep the Python-adjacent integrations grouped. --- .github/ISSUE_TEMPLATE/bug_report.yml | 1 + .github/ISSUE_TEMPLATE/feature_request.yml | 1 + 2 files changed, 2 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 2568cfc..3e2e771 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 140f521..0600489 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.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