docs: add Deep Agents integration page

docs.json

@@ -152,6 +152,7 @@
                                 "group": "Agent Frameworks",
                                 "pages": [
                                     "integrate/add-to-your-agent/langchain",
+                                    "integrate/add-to-your-agent/deep-agents",
                                     "integrate/add-to-your-agent/langsmith-deployment",
                                     "integrate/add-to-your-agent/strands",
                                     "integrate/add-to-your-agent/agentcore"

integrate/add-to-your-agent/deep-agents.mdx

@@ -0,0 +1,179 @@
+---
+title: "Deep Agents"
+description: "Charge for a capability that lives inside a Deep Agents subagent, using Nevermined x402"
+icon: "sitemap"
+frameworks: ["deepagents", "langchain", "langgraph", "python"]
+---
+
+<Note>
+  **Start here:** need to register a service and create a plan first? Follow the
+  [5-minute setup](/integrate/quickstart/5-minute-setup).
+</Note>
+
+<Card title="Runnable tutorial" icon="play" href="https://github.com/nevermined-io/tutorials/tree/main/langchain-deep-agent-py">
+  **`langchain-deep-agent-py`** — a freemium market-research agent on the Deep
+  Agents harness, where the paid tool lives inside a subagent. Clone, fill in
+  `.env`, run `poetry run buyer` to watch the free path and the paid path
+  back to back.
+</Card>
+
+[Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview) is LangChain's agent *harness*: `create_deep_agent()` returns a compiled LangGraph graph that already has planning, a filesystem, and subagent delegation built in. You reach for it when one agent needs to plan a job and hand pieces of it to specialists.
+
+**The Nevermined integration does not change.** `@requires_payment` works on a Deep Agents tool exactly as it does on a plain LangChain one — this page is about the one property that makes that true, and the two harness behaviours you should design around.
+
+## The delegation hop
+
+A buyer supplies an x402 access token **once**, on the run:
+
+```python
+graph.invoke(
+    {"messages": [{"role": "user", "content": "Research the EV market"}]},
+    config={"configurable": {"payment_token": access_token}},
+)
+```
+
+The supervisor never handles that token. It delegates through the built-in `task` tool, and LangGraph copies `configurable` down into the subagent's own tool calls — so the decorator finds the token one hop below where it was supplied:
+
+```
+main agent  ──task()──▶  research-sub  ──▶  market_research  [PAID]
+     ▲                                            │
+     └──────── x402 token supplied here ──────────┘
+                config.configurable.payment_token
+```
+
+This is the property the whole pattern rests on. A deep agent's premise is that the supervisor hands work to subagents; if payment context did not survive that hop, every paid tool would have to sit on the main agent and the harness would be useless for monetized capabilities.
+
+<Note>
+  The buyer does not need to know the agent's internal topology. The contract is
+  the same one the [LangChain guide](/integrate/add-to-your-agent/langchain)
+  describes — put the token on the run and let the graph route it.
+</Note>
+
+## Quick start
+
+Give the paid tool **only** to the subagent, so every paid call has to cross a delegation boundary:
+
+```python
+from deepagents import create_deep_agent
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import tool
+from payments_py import PaymentOptions, Payments
+from payments_py.x402.langchain import (
+    PaymentRequiredError,
+    last_settlement,
+    requires_payment,
+)
+
+payments = Payments.get_instance(PaymentOptions(nvm_api_key=NVM_API_KEY))
+
+
+@requires_payment(payments=payments, plan_id=PLAN_ID, credits=5)
+def _market_research_paid(topic: str, config: RunnableConfig) -> str:
+    """verify_permissions runs before this body, settle_permissions after."""
+    return run_analyst(topic)
+
+
+@tool
+def market_research(topic: str, config: RunnableConfig) -> str:
+    """Produce a market analysis on the given topic. PAID."""
+    try:
+        # Forward `config` explicitly — the decorator reads the token from it.
+        return _market_research_paid(topic, config=config)
+    except PaymentRequiredError:
+        return "PAYMENT_REQUIRED: authorize and ask again."
+
+
+research_subagent = {
+    "name": "research-sub",
+    "description": "Performs paid market research on a single topic.",
+    "system_prompt": (
+        "Call `market_research` once and return its output verbatim. "
+        "Never answer the research question from your own knowledge."
+    ),
+    "tools": [market_research],
+}
+
+graph = create_deep_agent(
+    model="openai:gpt-4o-mini",
+    tools=[],
+    subagents=[research_subagent],
+    system_prompt="Delegate every research request to `research-sub`.",
+)
+```
+
+Because `create_deep_agent()` returns a compiled graph, deployment is unchanged — point `langgraph.json` at it and `langgraph dev` or LangSmith Deployment will serve it:
+
+```json
+{
+  "dependencies": ["."],
+  "graphs": { "deep_research": "./src/agent.py:graph" }
+}
+```
+
+## Two harness behaviours to design around
+
+These are properties of the harness, not bugs. Both are worth handling before you put a deep agent in front of paying users.
+
+<Warning>
+  **A deep agent can bill several times per user turn.** The supervisor — not
+  you — decides how many subagent calls a request warrants, so a single user
+  message may settle credits more than once.
+</Warning>
+
+Cap it explicitly rather than trusting the model to be frugal. Count paid calls per run, keyed on `config["configurable"]["thread_id"]` (or `run_id`), and return a plain refusal once the cap is hit:
+
+```python
+if not budget.try_consume(config):
+    return "BUDGET_EXHAUSTED: this run already used its paid-call allowance."
+```
+
+Refund the reservation when a call raises `PaymentRequiredError` — otherwise a user who authorizes mid-run gets fewer paid calls than they paid for.
+
+<Warning>
+  **Two LLM layers can paraphrase the paid tool's output.** The subagent relays
+  to the supervisor, which relays to the user. A plain ReAct agent has one such
+  layer, so this is strictly worse.
+</Warning>
+
+Instruct both system prompts to pass the tool's text through verbatim, and treat the tool's return value — not the chat reply — as the source of truth when you need the settlement receipt.
+
+There is a sharper version of the same problem worth testing for explicitly: a capable supervisor sometimes answers a research question **from its own knowledge** instead of delegating, silently giving the paid capability away for free. Forbid it in both prompts, and re-test that path whenever you change models — it is prompt-dependent, not structural.
+
+## Version requirements
+
+`deepagents` requires the LangChain v1 stack (`langchain>=1.3.18`, `langchain-core>=1.6.1`). If your existing project pins an older `langchain-core`, give the deep agent its own virtualenv rather than upgrading around it.
+
+```bash
+pip install deepagents "payments-py[langsmith]" langchain-openai
+```
+
+## Observability
+
+Set `LANGSMITH_TRACING=true` and `LANGSMITH_API_KEY` to emit `nvm:verify` and `nvm:settlement` spans. On a deep agent these nest under the `task` span, so you can see **which subagent hop incurred each charge** — which is exactly what you need when reasoning about the multi-billing behaviour above.
+
+```bash
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY=lsv2_...
+# Only needed if your LangSmith account is NOT in GCP US:
+# LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com
+```
+
+## Which harness should I use?
+
+| | Plain LangGraph ReAct | Deep Agents |
+| --- | --- | --- |
+| Constructor | `create_react_agent` | `create_deep_agent` |
+| Paid tool lives on | the agent itself | a subagent, one `task()` hop away |
+| LLM layers between tool and user | 1 | 2 |
+| Paid calls per user turn | one per tool call the model makes | supervisor decides — cap it |
+| Built-in planning / filesystem / subagents | no | yes |
+| Buyer-side contract | `config.configurable.payment_token` | **identical** |
+
+Start from the [LangChain guide](/integrate/add-to-your-agent/langchain) if you want the smallest thing that works. Come here when the agent needs to plan, delegate, or manage its own context — and note that the payment integration itself does not change.
+
+## Related
+
+- [LangChain integration](/integrate/add-to-your-agent/langchain) — the decorator and HTTP-middleware approaches in full.
+- [LangSmith Deployment](/integrate/add-to-your-agent/langsmith-deployment) — hosting a gated graph.
+- [`langchain-deep-agent-py`](https://github.com/nevermined-io/tutorials/tree/main/langchain-deep-agent-py) — the runnable tutorial for this page.
+- [`langchain-research-agent-py`](https://github.com/nevermined-io/tutorials/tree/main/langchain-research-agent-py) — the same freemium pattern on `create_react_agent`.

integrate/add-to-your-agent/langchain.mdx

@@ -1,6 +1,6 @@
 ---
 title: "LangChain"
 description: "Add Nevermined x402 payments to your LangChain and LangGraph agents"
 icon: "link-simple"
 frameworks: ["langchain", "langgraph", "python", "typescript"]
 ---
@@ -25,14 +25,20 @@
 | **`requiresPayment` wrapper/decorator** | Direct tool invocation, CLI scripts, notebooks | Per-tool wrapper |
 | **Payment middleware on HTTP server** | Serving the agent over HTTP | HTTP middleware |
 
 Both use the same Nevermined plan, credits, and settlement flow — choose whichever fits your deployment model.
 
+<Note>
+  Building on the [Deep Agents](https://docs.langchain.com/oss/python/deepagents/overview)
+  harness? `@requires_payment` works there unchanged, including on a tool that
+  lives inside a subagent — see [Deep Agents](/integrate/add-to-your-agent/deep-agents).
+</Note>
+
 ## Installation
 
 <Tabs>
   <Tab title="TypeScript">
     ```bash
     npm install @nevermined-io/payments @langchain/core @langchain/openai zod
     ```
 
     <Note>
@@ -109,7 +115,7 @@
         { payments, planId: PLAN_ID, credits: 1 }
       ),
       {
         name: 'search_data',
         description: 'Search for data on a given topic. Costs 1 credit.',
         schema: z.object({ query: z.string() }),
       }
@@ -126,11 +132,11 @@
 
     ```python filename="agent.py"
     import os
     from dotenv import load_dotenv
     from langchain_core.runnables import RunnableConfig
     from langchain_core.tools import tool
     from payments_py import Payments, PaymentOptions
     from payments_py.x402.langchain import requires_payment
 
     load_dotenv()
 
@@ -194,7 +200,7 @@
   </Tab>
   <Tab title="Python">
     ```python filename="client.py"
     from payments_py import Payments, PaymentOptions
     from payments_py.x402 import X402TokenOptions, DelegationConfig, CreateDelegationPayload
 
     # Subscriber side — acquire token
@@ -256,10 +262,10 @@
   </Tab>
   <Tab title="Python">
     ```python
     llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
     tools = [search_data, summarize_data, research_topic]
     llm_with_tools = llm.bind_tools(tools)
     tool_map = {t.name: t for t in tools}
 
     messages = [HumanMessage(content="Search for AI trends")]
     ai_message = llm_with_tools.invoke(messages)
@@ -315,7 +321,7 @@
 
 ### Discovery-first flow with `createPaidReactAgent`
 
 If the buyer **doesn't** know the plan id / scheme / provider up front, the x402 way is to invoke the agent without a token, let the protected tool raise `PaymentRequiredError`, and read the requirements off the exception. By default LangGraph's `ToolNode` would catch that exception and stringify it into a `ToolMessage` for the LLM — losing the `X402PaymentRequired` payload. Both SDKs ship a paid-agent helper for exactly this — `createPaidReactAgent` (TypeScript) / `create_paid_react_agent` (Python) — that builds the underlying `ToolNode` with `handleToolErrors: false` / `handle_tool_errors=False`, so the exception propagates to `agent.invoke()`'s caller with the payload intact.
 
 <Tabs>
   <Tab title="TypeScript">
@@ -396,7 +402,7 @@
     ```python
     from payments_py.x402.langchain import (
         PaymentRequiredError,
         create_paid_react_agent,
         requires_payment,
     )
     from payments_py.x402.types import (
@@ -464,14 +470,14 @@
 <Note>
   Create the delegation that backs the payment signature **first** (with
   `createDelegation`), then pass its `delegationId` in the token's
   `delegationConfig`. This applies to both card-delegation and crypto
   (`nvm:erc4337`) plans. Passing creation fields inline instead of a
   `delegationId` is deprecated and emits a runtime warning — see the x402
   Protocol module reference ([TypeScript](/api-reference/typescript/x402) ·
   [Python](/api-reference/python/x402-module)) for the full token-options
   surface. This discovery flow covers Stripe and Braintree. For **Visa**-priced
   plans, `createDelegation` from the SDK is rejected (`BCK.VISA.0014`) — create
   the Visa delegation in the Nevermined app and reuse its `delegationId` here.
 </Note>
 
 <Note>
@@ -482,7 +488,7 @@
 
 ### Reading the settlement receipt
 
 After a successful agent call, the buyer can read the settlement receipt — credits redeemed, remaining balance, transaction hash, network, payer — via `lastSettlement()` (TypeScript) / `last_settlement()` (Python). LangGraph copies `configurable` per node, so the in-place `payment_settlement` write is invisible to the outer scope; the accessor reads it from a module-level slot instead.
 
 <Tabs>
   <Tab title="TypeScript">
@@ -528,14 +534,14 @@
 
 ### Trace payments in LangSmith
 
 Once payment protection is wired up, you can have every paid tool call surface as structured spans in [LangSmith](https://smith.langchain.com) — no code changes required, just two env vars and an optional dependency. **Both SDKs emit the identical `nvm:verify` / `nvm:settlement` span shape** (the cross-SDK [observability-spans-v1 contract](https://github.com/nevermined-io/nvm-monorepo/blob/main/docs/specs/observability-spans-v1.md)), so a single trace can be correlated across a TypeScript buyer and a Python seller — e.g. filter on `nvm.tx_hash`.
 
 **Install the optional dependency:**
 
 <Tabs>
   <Tab title="TypeScript">
     ```bash
     pnpm add langsmith
     ```
 
     `langsmith` is an optional peer dependency — the `requiresPayment` wrapper emits the spans automatically when it is installed and tracing is enabled.
@@ -557,7 +563,7 @@
 # LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com
 ```
 
 That's it. Running the same agent invocation now produces a trace tree with two dedicated Nevermined child spans nested under the tool:
 
 ```text
 LangGraph
@@ -567,7 +573,7 @@
         └── nvm:settlement  1.88s     ← around the facilitator settle call
 ```
 
 Each Nevermined span carries `nvm.*` metadata for audit + reconciliation:
 
 | Span | Attributes |
 | ---- | ---------- |
@@ -579,9 +585,9 @@
 **Failed discovery probes are first-class too.** When the buyer's first `agent.invoke()` runs without a `payment_token` (the discovery-first flow), the `nvm:verify` span still opens, carries the static `nvm.plan_ids` / `nvm.scheme` / `nvm.network`, and is marked failed by the raised `PaymentRequiredError`. That gives you "which plan was the probe against?" filterability instead of an opaque LangChain crash.
 
 <Warning title="Sensitive data in traces">
   The `payment_token` the buyer passes in `configurable.payment_token` would normally be captured into the parent tool span's metadata by LangChain and inherited by every child span. The full token grants access to the protected tool until it expires. Both SDKs **proactively strip it from the parent span's metadata** before opening any `nvm:*` child, so the full credential never reaches a Nevermined-emitted attribute. The abbreviated `nvm.payment_token` (first 16 chars + `…` + last 4 chars) remains available for correlation.
 
   A too-short token (≤ 20 chars — almost always a misconfiguration, since real x402 access tokens are JWTs) is **redacted, not exported**: at most the first 4 chars are surfaced followed by a `…(short)` marker, and a token of 4 chars or fewer reveals **nothing** (just `…(short)`). A warning is logged, so a wrong value passed as the token never lands in a trace.
 
   Other channels (custom callbacks, an explicit metadata write that includes the token, tool signatures that contain the token) are not covered — strip them yourself or set `export LANGSMITH_HIDE_INPUTS=true` for blanket coverage.
 </Warning>
@@ -908,7 +914,7 @@
   <Tab title="Python">
     ```python
     from langchain_core.tools import tool
     from langchain_openai import ChatOpenAI
     from langgraph.prebuilt import create_react_agent
 
     # Plain tools — no payment decorators
@@ -1000,7 +1006,7 @@
     import json
     import os
     import httpx
     from payments_py import Payments, PaymentOptions
     from payments_py.x402 import X402TokenOptions, DelegationConfig, CreateDelegationPayload
 
     SERVER_URL = os.environ.get("SERVER_URL", "http://localhost:8000")
@@ -1069,8 +1075,8 @@
 | ----- | ----------- |
 | `creditsRedeemed` | Number of credits charged |
 | `remainingBalance` | Subscriber's remaining credit balance |
 | `transaction` | Blockchain transaction hash |
 | `network` | Blockchain network (CAIP-2 format) |
 | `payer` | Subscriber wallet address |
 
 ---
@@ -1082,7 +1088,7 @@
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     const myTool = tool(
       requiresPayment(
         (args) => `Result for ${args.query}`,
         {
@@ -1129,7 +1135,7 @@
 <Tabs>
   <Tab title="TypeScript">
     ```typescript
     const myTool = tool(
       requiresPayment(
         (args) => `Result`,
         { payments, planId: PLAN_ID, credits: 1, network: 'eip155:84532' }
@@ -1202,7 +1208,7 @@
 
 <CardGroup cols={2}>
   <Card title="Express Middleware (TS)" icon="js" href="/integrate/add-to-your-agent/express">
     Deep dive into paymentMiddleware for Express
   </Card>
 
   <Card title="FastAPI Middleware (Python)" icon="python" href="/integrate/add-to-your-agent/fastapi">