|
| 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