Integrazione dei pagamenti Agno.
Non esiste un pacchetto Agno, e non ne hai bisogno. Avvolgi il vero client blockchain0x in un piccolo Toolkit e il tuo agente può muovere USDC su Base - astrazione minima, il modo Agno.
Non esiste un package specifico per Agno, e non ne hai bisogno. Agno trasforma un metodo in uno strumento, quindi avvolgi il vero client Python in un piccolo toolkit e lo aggiungi al tuo . L'agente può inviare USDC, saldare fatture e leggere i wallet, su ogni modello Agno (OpenAI, Anthropic, DeepSeek, Llama, Mistral). I pagamenti si regolano su Base.
Il framework Python leggero. Nessuna tassa di astrazione.
Agno (precedentemente Phidata) è il framework per agenti a cui ti rivolgi quando desideri una cerimonia minima. Non c'è un costruttore di grafi, nessuna Crew, nessun Workflow - solo Agente, Strumenti e un metodo run(). Gli strumenti sono callable Python. Il framework aggiunge abbastanza impalcature per chiamare LLM con supporto per strumenti, gestire la memoria e produrre output in streaming, poi si fa da parte.
La ricetta segue la stessa filosofia. Scrivi una piccola sottoclasse Toolkit che registra un metodo che chiama il client reale - appare e si comporta come ogni altro strumento Agno. Nessuna configurazione speciale oltre all'istanza, nessun grafo da collegare, nessuna versione dell'adattatore da tenere sotto controllo. La semplicità è il punto: se volevi grafi saresti su LangGraph.
Installa Agno e il core SDK. Due chiavi.
Non esiste un pacchetto blockchain0x Agno da aggiungere. Installa Agno (Python 3.10+, la linea 1.0+ dopo la rinomina di Phidata) e il vero core SDK blockchain0x, quindi scrivi il toolkit qui sotto. Se sei ancora su importazioni phi.*, esegui prima pip install -U agno.
pip install agno blockchain0xexport OPENAI_API_KEY=sk-... export BLOCKCHAIN0X_API_KEY=sk_test_... # sk_test_ = Base Sepolia, sk_live_ = Base mainnet
OPENAI_API_KEY (o l'equivalente per qualunque modello supportato da Agno tu usi). BLOCKCHAIN0X_API_KEY è una chiave sk_test_ per testnet o sk_live_ per mainnet dalla tua dashboard; il client la legge dall'ambiente. Se il tuo agent riceve anche denaro, l'handler del webhook richiede inoltre BLOCKCHAIN0X_WEBHOOK_SECRET.
Un Toolkit che paga, consegnato a un Agente.
Di seguito è l'intera integrazione. WalletTools è una sottoclasse di Toolkit che registra send_usdc, che chiama il reale client blockchain0x. Aggiungilo all'Agente e la chiamata run() orchestra l'invocazione dello strumento. Agno legge la firma del metodo e la docstring per costruire lo schema.
from agno.agent import Agent from agno.models.openai import OpenAIChat from agno.tools import Toolkit from blockchain0x import Client blockchain0x = Client() # reads BLOCKCHAIN0X_API_KEY from the environment # Wrap the real client in an Agno Toolkit. No dedicated package needed. class WalletTools(Toolkit): def __init__(self): super().__init__(name="wallet_tools") self.register(self.send_usdc) def send_usdc(self, agent_id: str, to: str, amount_wei: str) -> str: """Send a USDC payment from an agent wallet. amount_wei is USDC base units (6 decimals), so "10000" is 0.01 USDC. """ return str( blockchain0x.payments.create(body={"agentId": agent_id, "to": to, "amountWei": amount_wei}) ) agent = Agent( model=OpenAIChat(id="gpt-4o"), tools=[WalletTools()], instructions=["You pay vendor invoices in USDC within owner-set limits."], ) result = agent.run("Pay 0.01 USDC from agent agt_123 to 0xVendor for the dataset.") print(result.content)
When agent.run() executes, the model decides to pay, calls send_usdc, the SDK submits the transfer, and you get a transaction hash back. amount_wei is base units, so 0.01 USDC is "10000". A sk_test_ key keeps it on Base Sepolia until you switch to sk_live_. Register more methods on the toolkit - read a wallet, settle an invoice - the same way.
Conferma i pagamenti in entrata con un webhook firmato.
Se il tuo agente riceve anche USDC, confermalo con il webhook piuttosto che tramite polling. L'helper di verifica è incluso nel Node SDK; in un servizio Python verifichi manualmente contro l'HMAC documentato, che è tutto ciò che fa l'helper. Esempio FastAPI qui sotto; lo stesso codice funziona in qualsiasi framework Python asincrono.
import hmac, hashlib, os, time from fastapi import FastAPI, Request, HTTPException app = FastAPI() SECRET = os.environ["BLOCKCHAIN0X_WEBHOOK_SECRET"].encode() @app.post("/webhooks/payment") async def receive(request: Request): raw = await request.body() # RAW bytes - do not parse first sig = request.headers.get("X-Blockchain0x-Signature", "") ts = request.headers.get("X-Blockchain0x-Timestamp", "") parts = dict(p.split("=", 1) for p in sig.split(",") if "=" in p) t, v1 = parts.get("t", ts), parts.get("v1", sig) want = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest() if not hmac.compare_digest(want, v1) or abs(time.time() - int(t)) > 300: raise HTTPException(status_code=401) if request.headers.get("X-Blockchain0x-Event-Type") == "payment.received": await trigger_followup() # USDC landed - run the next step return {"ok": True}
L'algoritmo è HMAC-SHA256 sulla stringa t.rawBody, un confronto a tempo costante e una finestra di replay di 300 secondi. Leggi il corpo grezzo tramite await request.body(), mai request.json() rieseguito, perché ciò cambia i byte coperti dalla firma. Gli eventi spediti sono payment.received, payment.sent, wallet.deployed e webhook.test. Per lavori di follow-up pesanti, accoda un lavoro (Celery, arq) e rispondi 200 immediatamente anziché bloccare il gestore.
Il client che stai avvolgendo è aperto. Leggilo.
Non esiste un starter package Agno da clonare - la ricetta sopra è l'integrazione. Gli SDK blockchain0x sono open source su GitHub; questa ricetta incapsula il Python SDK (blockchain0x-python), con la superficie completa dei metodi nella documentazione. Consultala come riferimento per i metodi del toolkit.
github.com/tosh-labs/blockchain0x-pythonLa superficie completa dei metodi dell'SDK e gli scope sono documentati in the docs. Inizia con una chiave sk_test_ su Base Sepolia, poi passa a sk_live_ quando il toolkit si comporta come previsto.
Cinque cose specifiche di Agno da tenere d'occhio.
Agno è uno dei framework per agenti più puliti con cui integrarsi, ma ha le sue insidie - specialmente riguardo alla rinominazione di Phidata e al rendering markdown.
Non esiste un pacchetto Agno - avvolgi l'SDK in un Toolkit
Blockchain0x fornisce adattatori per LangChain e CrewAI oltre al server MCP; non esiste un pacchetto Agno dedicato. La ricetta sopra è il percorso: una sottoclasse di Toolkit che registra un metodo che chiama il reale client blockchain0x. Agno legge la firma del metodo e la docstring per costruire lo schema dello strumento, quindi mantieni la docstring accurata.
Confusione nella migrazione da Phidata a Agno
Agno è stato rinominato da Phidata nel 2024. Le vecchie codebase che importano da phi.agent o phi.tools funzionano ancora tramite un compatibilità shim, ma gli import agno.* sono quelli attuali. La ricetta utilizza agno.* in tutto; se il tuo codice è ancora su import phi.*, esegui pip install -U agno e cambia i percorsi di importazione prima di aggiungere il Toolkit.
Gli importi sono unità base USDC, come stringhe
payments.create takes amountWei: a string of USDC base units (6 decimals), so 0.01 USDC is "10000" and 5 USDC is "5000000". Type the method argument as str. It also does not retry by default and can answer 503 until the chain adapter is wired for your network - return a clear message rather than letting the agent loop.
Esecuzione sincronizzata vs asincrona
Agno supporta agent.run() (sincrono) e agent.arun() (asincrono). Scegli un modo per agente - chiama agent.run() e prova ad attendere il risultato e ottieni una coroutine dove ti aspettavi una stringa. La chiamata blockchain0x all'interno del Toolkit è sincrona; se sei sul percorso asincrono e gestisci un volume reale, avvolgila con asyncio.to_thread in modo che il ciclo degli eventi rimanga reattivo.
Verifica i webhook rispetto al corpo grezzo
Se il tuo agente riceve anche USDC, confermalo con il webhook, non tramite polling. Verifica la firma sui byte RAW della richiesta (await request.body()), mai request.json() ri-serializzato, perché l'HMAC copre i byte esatti. È HMAC-SHA256 con una finestra di replay di 300 secondi. Il gestore qui sotto è l'intero processo.