Python: [Feature]: Crypto Payroll Agent — end-to-end sample with on-chain batch payments

[plagtech]

Description

What problem does it solve?

The current sample set covers travel planning, content generation, M365, RAG, and workflows — but no sample demonstrates an agent handling irreversible financial operations with real side effects. Developers building payment or fintech agents don't have a reference for guardrail patterns (spend ceilings, recipient caps, confirmation gates) on actions that move real value.

What would the expected behavior be?

A self-contained sample in python/samples/05-end-to-end/crypto_payroll_agent/ where an AI agent accepts a natural-language payroll instruction (e.g. "Pay Alice 50 USDC and Bob 30 USDC on Base"), resolves it into structured recipient/amount data, calls a payment gateway's REST API to build the unsigned transaction, signs locally, broadcasts, and confirms settlement — all through MAF tool functions.

The sample would include:

• 3–4 tool functions (estimate batch cost, get token info, execute batch, check transaction)
• A guardrail callback enforcing recipient count ≤ 200, address format validation, and a configurable MAX_BATCH_USD spending ceiling
• README with setup, walkthrough, and on-chain proof transactions from verification
• Tests runnable without a funded wallet (mocked gateway responses)

The payment gateway used would be Spraay Protocol (gateway.spraay.app), operated by Plagtech LLC — my company. The gateway charges a 0.3% protocol fee on batches and $0.02 per API call. These fees would be documented in the sample README. The gateway is the only Spraay-specific dependency; the agent architecture, tool patterns, and guardrail approach are framework-general.

Are there any alternatives you've considered?

The sample could also fit in microsoft/Agent-Framework-Samples under 09.Cases/ if that's a better home for third-party integration demos.

Prior art

I've contributed similar payment-agent samples to other frameworks:

• NVIDIA NeMo-Agent-Toolkit-Examples #27 (merged) — RTP payment tools
• Strands Agents Docs #825 (merged) — batch payment integration on the official Strands docs site
• Oracle AI Developer Hub #131 (merged) — x402 partner notebook

Questions for maintainers

1. Is python/samples/05-end-to-end/ the right location?
2. Any preference on LLM provider the sample should target (GitHub Models, Azure OpenAI, OpenAI)?
3. Should tools use @tool or @kernel_function? I'll match whichever convention the existing samples follow.

Code Sample

from agent_framework import Agent

# Tool functions would call the Spraay gateway REST API
# Example: estimate a batch payment
@tool
async def estimate_batch(token: str, recipients: list[str], amounts: list[str]) -> str:
    """Estimate gas and fees for a batch payment on Base."""
    response = await httpx.AsyncClient().post(
        "https://gateway.spraay.app/api/v1/batch/estimate",
        json={"token": token, "recipients": recipients, "amounts": amounts}
    )
    return response.json()

agent = Agent(
    client=...,  # Azure OpenAI or GitHub Models
    name="PayrollAgent",
    instructions="You are a payroll agent that executes batch crypto payments on Base.",
    tools=[estimate_batch, execute_batch, get_token_info, check_transaction],
)

Language/SDK

Python