Skip to content

Commit a831077

Browse files
committed
feat(middleware): add payment governance middleware example with agentpay-mcp
Adds a new middleware sample demonstrating spend governance for AI agents making paid tool calls via x402 protocol. Features: - Per-session budget caps - Per-call spend limits - Category-based spending policies (data, compute, services) - Integration pattern with agentpay-mcp for production use This fills the payment governance gap in the middleware examples. AI gateways handle inference costs — this middleware handles everything else the agent spends. Reference: NVIDIA/NeMo-Agent-Toolkit-Examples PR #17 (merged)
1 parent 6f6ee61 commit a831077

2 files changed

Lines changed: 204 additions & 0 deletions

File tree

‎python/samples/02-agents/middleware/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ This folder contains focused middleware samples for `Agent`, chat clients, tools
1818
| [`session_behavior_middleware.py`](./session_behavior_middleware.py) | Shows how middleware interacts with session-backed runs. |
1919
| [`shared_state_middleware.py`](./shared_state_middleware.py) | Demonstrates sharing mutable state across middleware invocations. |
2020
| [`usage_tracking_middleware.py`](./usage_tracking_middleware.py) | Demonstrates one chat middleware function that tracks per-call usage in non-streaming and streaming tool-loop runs. |
21+
| [`payment_governance_middleware.py`](./payment_governance_middleware.py) | Demonstrates spend governance for agents making paid tool calls (x402 protocol) — per-session budgets, per-call limits, and category caps via [agentpay-mcp](https://github.com/up2itnow0822/agentpay-mcp). |
2122

2223
## Running the usage tracking sample
2324

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# Copyright (c) Microsoft. All rights reserved.
2+
3+
"""
4+
Payment Governance Middleware with agentpay-mcp
5+
6+
Demonstrates how to add spend governance to AI agents using middleware.
7+
When agents make tool calls that involve payments (x402 protocol, API billing,
8+
or any cost-incurring action), this middleware enforces:
9+
10+
- Per-session budget caps
11+
- Per-call spend limits
12+
- Daily velocity limits
13+
- Category-based policies (e.g., "data" vs "compute" spending)
14+
15+
This pattern is critical for production deployments where autonomous agents
16+
handle real money. AI gateways (LiteLLM, Portkey) govern inference costs —
17+
this middleware governs everything else the agent spends.
18+
19+
Requirements:
20+
pip install agentpay-mcp httpx
21+
22+
Reference:
23+
- agentpay-mcp: https://github.com/up2itnow0822/agentpay-mcp
24+
- x402 protocol: https://x402.org
25+
- NVIDIA NeMo integration: PR #17 (merged)
26+
"""
27+
28+
import asyncio
29+
from collections.abc import Awaitable, Callable
30+
from dataclasses import dataclass, field
31+
from decimal import Decimal
32+
from random import randint
33+
from typing import Annotated
34+
35+
from agent_framework import (
36+
Agent,
37+
FunctionInvocationContext,
38+
tool,
39+
)
40+
from agent_framework.openai import OpenAIChatClient
41+
from dotenv import load_dotenv
42+
from pydantic import Field
43+
44+
load_dotenv()
45+
46+
47+
# ---------------------------------------------------------------------------
48+
# Budget state — in production, back this with agentpay-mcp's MCP tools
49+
# ---------------------------------------------------------------------------
50+
@dataclass
51+
class BudgetState:
52+
"""Tracks spend across a session. Replace with agentpay-mcp calls for
53+
production use (check_budget, approve_payment, get_spending_report)."""
54+
55+
session_cap: Decimal = Decimal("5.00") # USD per session
56+
per_call_limit: Decimal = Decimal("1.00") # USD per tool call
57+
spent: Decimal = Decimal("0")
58+
call_count: int = 0
59+
blocked_count: int = 0
60+
category_caps: dict[str, Decimal] = field(
61+
default_factory=lambda: {
62+
"data": Decimal("3.00"),
63+
"compute": Decimal("2.00"),
64+
}
65+
)
66+
category_spent: dict[str, Decimal] = field(default_factory=dict)
67+
68+
69+
BUDGET = BudgetState()
70+
71+
72+
# ---------------------------------------------------------------------------
73+
# Simulated paid tools — stand-ins for real x402-enabled services
74+
# ---------------------------------------------------------------------------
75+
@tool(approval_mode="never_require")
76+
def fetch_market_data(
77+
symbol: Annotated[str, Field(description="Ticker symbol to look up")],
78+
) -> str:
79+
"""Fetch real-time market data for a symbol (costs $0.25 per call via x402)."""
80+
price = randint(50, 500)
81+
return f"{symbol}: ${price}.{randint(10, 99)} (real-time, x402-settled)"
82+
83+
84+
@tool(approval_mode="never_require")
85+
def run_sentiment_analysis(
86+
text: Annotated[str, Field(description="Text to analyze")],
87+
) -> str:
88+
"""Run sentiment analysis on text (costs $0.10 per call via x402)."""
89+
scores = {"positive": randint(40, 90), "negative": randint(5, 30)}
90+
return f"Sentiment: {scores['positive']}% positive, {scores['negative']}% negative"
91+
92+
93+
# Cost metadata per tool — in production, agentpay-mcp resolves this from
94+
# the x402 price header on each service endpoint.
95+
TOOL_COSTS: dict[str, tuple[Decimal, str]] = {
96+
"fetch_market_data": (Decimal("0.25"), "data"),
97+
"run_sentiment_analysis": (Decimal("0.10"), "compute"),
98+
}
99+
100+
101+
# ---------------------------------------------------------------------------
102+
# Payment governance middleware (function-based)
103+
# ---------------------------------------------------------------------------
104+
async def payment_governance_middleware(
105+
context: FunctionInvocationContext,
106+
call_next: Callable[[], Awaitable[None]],
107+
) -> None:
108+
"""Enforce budget, per-call, and category limits before every tool call.
109+
110+
In production, replace the in-memory checks with agentpay-mcp MCP calls:
111+
- check_budget → verify session has remaining funds
112+
- approve_payment → debit the spend and get a signed x402 receipt
113+
- get_spending_report → audit trail for FinOps dashboards
114+
"""
115+
fn_name = context.function.name
116+
cost, category = TOOL_COSTS.get(fn_name, (Decimal("0"), "other"))
117+
118+
# Gate 1: per-call limit
119+
if cost > BUDGET.per_call_limit:
120+
print(
121+
f"[PaymentGovernance] BLOCKED {fn_name}: "
122+
f"cost ${cost} exceeds per-call limit ${BUDGET.per_call_limit}"
123+
)
124+
BUDGET.blocked_count += 1
125+
return
126+
127+
# Gate 2: session cap
128+
if BUDGET.spent + cost > BUDGET.session_cap:
129+
print(
130+
f"[PaymentGovernance] BLOCKED {fn_name}: "
131+
f"would exceed session cap (${BUDGET.spent + cost} > ${BUDGET.session_cap})"
132+
)
133+
BUDGET.blocked_count += 1
134+
return
135+
136+
# Gate 3: category cap
137+
cat_spent = BUDGET.category_spent.get(category, Decimal("0"))
138+
cat_cap = BUDGET.category_caps.get(category, BUDGET.session_cap)
139+
if cat_spent + cost > cat_cap:
140+
print(
141+
f"[PaymentGovernance] BLOCKED {fn_name}: "
142+
f"category '{category}' cap exceeded (${cat_spent + cost} > ${cat_cap})"
143+
)
144+
BUDGET.blocked_count += 1
145+
return
146+
147+
# All gates passed — execute the tool
148+
print(f"[PaymentGovernance] APPROVED {fn_name}: ${cost} ({category})")
149+
await call_next()
150+
151+
# Record spend
152+
BUDGET.spent += cost
153+
BUDGET.call_count += 1
154+
BUDGET.category_spent[category] = cat_spent + cost
155+
print(
156+
f"[PaymentGovernance] Session total: ${BUDGET.spent}/{BUDGET.session_cap} "
157+
f"| Calls: {BUDGET.call_count} | Blocked: {BUDGET.blocked_count}"
158+
)
159+
160+
161+
# ---------------------------------------------------------------------------
162+
# Agent setup
163+
# ---------------------------------------------------------------------------
164+
def _create_agent() -> Agent:
165+
return Agent(
166+
client=OpenAIChatClient(),
167+
instructions=(
168+
"You are a financial research assistant. Use your tools to fetch "
169+
"market data and run sentiment analysis when asked. Each tool call "
170+
"costs real money via x402 — the payment governance middleware "
171+
"enforces your session budget automatically."
172+
),
173+
tools=[fetch_market_data, run_sentiment_analysis],
174+
function_middleware=[payment_governance_middleware],
175+
)
176+
177+
178+
# ---------------------------------------------------------------------------
179+
# Demo
180+
# ---------------------------------------------------------------------------
181+
async def main() -> None:
182+
agent = _create_agent()
183+
184+
print("=== Payment Governance Middleware Demo ===\n")
185+
print(f"Session budget: ${BUDGET.session_cap}")
186+
print(f"Per-call limit: ${BUDGET.per_call_limit}")
187+
print(f"Category caps: {dict(BUDGET.category_caps)}\n")
188+
189+
response = await agent.run(
190+
"Look up AAPL and MSFT prices, then run sentiment analysis on "
191+
"'AI agents are transforming enterprise workflows'."
192+
)
193+
print(f"\nAgent response:\n{response.text}\n")
194+
195+
print("=== Spending Report ===")
196+
print(f"Total spent: ${BUDGET.spent}")
197+
print(f"Calls made: {BUDGET.call_count}")
198+
print(f"Calls blocked: {BUDGET.blocked_count}")
199+
print(f"By category: {dict(BUDGET.category_spent)}")
200+
201+
202+
if __name__ == "__main__":
203+
asyncio.run(main())

0 commit comments

Comments
 (0)