Integración de pagos de Agno.
No hay paquete Agno, y no necesitas uno. Envuelve el cliente real de blockchain0x en un pequeño Toolkit y tu agente puede mover USDC en Base - mínima abstracción, al estilo Agno.
No existe un paquete específico de Agno, y no lo necesitas. Agno convierte un método en una herramienta, así que envuelves el cliente Python real de en un pequeño toolkit y lo agregas a tu . El agente puede enviar USDC, liquidar facturas y leer wallets, en cualquier modelo de Agno (OpenAI, Anthropic, DeepSeek, Llama, Mistral). Los pagos se liquidan en Base.
El marco de trabajo ligero de Python. Sin impuesto de abstracción.
Agno (anteriormente Phidata) es el marco de agentes que eliges cuando deseas una ceremonia mínima. No hay constructor de gráficos, no hay Crew, no hay flujo de trabajo - solo Agente, Herramientas y un método run(). Las herramientas son llamadas de Python. El marco agrega suficiente andamiaje para llamar a LLMs con soporte de herramientas, gestionar memoria y producir salida en streaming, luego se aparta de tu camino.
La receta sigue la misma filosofía. Escribes una pequeña subclase de Toolkit que registra un método que llama al cliente real - se ve y se comporta como cualquier otra herramienta de Agno. No hay configuración especial más allá de la instanciación, no hay gráfico que conectar, no hay versión de adaptador que rastrear. La simplicidad es el punto: si quisieras gráficos estarías en LangGraph.
Instala Agno y el SDK principal. Dos claves.
No hay paquete de blockchain0x Agno para agregar. Instalas Agno (Python 3.10+, la línea 1.0+ después del cambio de nombre de Phidata) y el verdadero SDK principal de blockchain0x, luego escribes el kit de herramientas a continuación. Si aún estás en las importaciones phi.*, ejecuta pip install -U agno primero.
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 el equivalente para cualquier modelo soportado por Agno que uses). BLOCKCHAIN0X_API_KEY es una clave sk_test_ de testnet o sk_live_ de mainnet de tu panel; el cliente la lee del entorno. Si tu agente también recibe dinero, el manejador de webhook necesita adicionalmente BLOCKCHAIN0X_WEBHOOK_SECRET.
Un Toolkit que paga, entregado a un Agente.
A continuación se presenta toda la integración. WalletTools es una subclase de Toolkit que registra send_usdc, que llama al cliente real de blockchain0x. Agrégalo al Agente y la llamada run() orquesta la invocación de la herramienta. Agno lee la firma del método y la docstring para construir el esquema.
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.
Confirme los pagos entrantes con un webhook firmado.
Si tu agente también recibe USDC, confírmalo con el webhook en lugar de sondear. El ayudante de verificación se envía en el SDK de Node; en un servicio de Python verificas manualmente contra el HMAC documentado, que es todo lo que hace el ayudante. Ejemplo de FastAPI a continuación; el mismo código funciona en cualquier marco de Python asíncrono.
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}
El algoritmo es HMAC-SHA256 sobre la cadena t.rawBody, una comparación en tiempo constante y una ventana de repetición de 300 segundos. Lee el cuerpo sin procesar a través de await request.body(), nunca request.json() re-serializado, porque eso cambia los bytes que cubre la firma. Los eventos enviados son payment.received, payment.sent, wallet.deployed y webhook.test. Para trabajos de seguimiento pesados, encola un trabajo (Celery, arq) y responde 200 inmediatamente en lugar de bloquear el controlador.
El cliente que estás envolviendo es abierto. Léelo.
No hay un paquete de inicio de Agno para clonar - la receta anterior es la integración. Los SDK de blockchain0x son de código abierto en GitHub; esta receta envuelve el SDK de Python (blockchain0x-python), con la superficie completa de métodos en la documentación. Léelo como referencia para los métodos del kit de herramientas.
github.com/tosh-labs/blockchain0x-pythonLa superficie completa de métodos del SDK y los alcances están documentados en la documentación. Comienza con una clave sk_test_ contra Base Sepolia, luego cambia a sk_live_ cuando el kit de herramientas haga lo que esperas.
Cinco cosas específicas de Agno a tener en cuenta.
Agno es uno de los marcos de agentes más limpios para integrar, pero tiene sus propias complicaciones - especialmente en torno al cambio de nombre de Phidata y la renderización de markdown.
No hay paquete Agno - envuelves el SDK en un Toolkit
Blockchain0x envía adaptadores para LangChain y CrewAI además del servidor MCP; no hay un paquete dedicado de Agno. La receta anterior es el camino: una subclase de Toolkit que registra un método que llama al cliente real de blockchain0x. Agno lee la firma del método y la docstring para construir el esquema de herramientas, así que mantenga la docstring precisa.
Confusión de migración de Phidata a Agno
Agno fue renombrado de Phidata en 2024. Las bases de código más antiguas que importan desde phi.agent o phi.tools aún funcionan a través de un adaptador de compatibilidad, pero las importaciones agno.* son las actuales. La receta utiliza agno.* en toda su extensión; si tu código aún está en importaciones phi.*, ejecuta pip install -U agno y cambia las rutas de importación antes de agregar el Toolkit.
Las cantidades son unidades base de USDC, como cadenas
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.
Ejecución síncrona vs asíncrona
Agno admite agent.run() (sincrónico) y agent.arun() (asincrónico). Elige un modo por agente - llama a agent.run() y trata de esperar el resultado y obtendrás una coroutine donde esperabas una cadena. La llamada de blockchain0x dentro del Toolkit es sincrónica; si estás en la ruta asincrónica y moviendo volumen real, envuélvela con asyncio.to_thread para que el bucle de eventos permanezca receptivo.
Verificar webhooks contra el cuerpo sin procesar
Si tu agente también recibe USDC, confírmalo con el webhook, no mediante polling. Verifica la firma sobre los bytes de la solicitud RAW (await request.body()), nunca request.json() re-serializado, porque el HMAC cubre los bytes exactos. Es HMAC-SHA256 con una ventana de repetición de 300 segundos. El controlador a continuación es todo.