Integração de pagamento Agno.
Não há pacote Agno, e você não precisa de um. Envolva o cliente blockchain0x real em um pequeno Toolkit e seu agente pode mover USDC na Base - abstração mínima, do jeito Agno.
Não existe um pacote específico para Agno, e você não precisa de um. O Agno transforma um método em uma tool, então você encapsula o cliente Python real em um toolkit pequeno e o adiciona ao seu . O agente pode enviar USDC, liquidar invoices e ler wallets, em qualquer modelo do Agno (OpenAI, Anthropic, DeepSeek, Llama, Mistral). Os pagamentos são liquidados na Base.
O framework Python leve. Sem imposto de abstração.
Agno (anteriormente Phidata) é o framework de agente que você procura quando deseja cerimônia mínima. Não há construtor de gráfico, Crew, Workflow - apenas Agente, Ferramentas e um método run(). As ferramentas são chamadas Python. O framework adiciona estrutura suficiente para chamar LLMs com suporte a ferramentas, gerenciar memória e produzir saída em streaming, depois sai do seu caminho.
A receita segue a mesma filosofia. Você escreve uma pequena subclasse Toolkit que registra um método chamando o cliente real - ela se parece e se comporta como qualquer outra ferramenta Agno. Nenhuma configuração especial além da instanciação, nenhum gráfico para conectar, nenhuma versão de adaptador para rastrear. A simplicidade é o ponto: se você quisesse gráficos, estaria no LangGraph.
Instale Agno e o SDK principal. Duas chaves.
Não há pacote blockchain0x Agno para adicionar. Você instala Agno (Python 3.10+, a linha 1.0+ após a renomeação de Phidata) e o SDK principal blockchain0x real, e então escreve o toolkit abaixo. Se você ainda estiver usando imports phi.*, execute pip install -U agno primeiro.
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 (ou o equivalente para qualquer modelo compatível com Agno que você use). BLOCKCHAIN0X_API_KEY é uma chave sk_test_ de testnet ou sk_live_ de mainnet do seu dashboard; o cliente a lê do ambiente. Se o seu agente também receber dinheiro, o handler de webhook também precisa de BLOCKCHAIN0X_WEBHOOK_SECRET.
Um Toolkit que paga, entregue a um Agente.
Abaixo está toda a integração. WalletTools é uma subclasse de Toolkit que registra send_usdc, que chama o cliente real blockchain0x. Adicione-o ao Agente e a chamada run() orquestra a invocação da ferramenta. Agno lê a assinatura do método e a docstring para construir o 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 pagamentos recebidos com um webhook assinado.
Se seu agente também recebe USDC, confirme com o webhook em vez de polling. O helper de verificação é enviado no SDK Node; em um serviço Python você verifica manualmente contra o HMAC documentado, que é tudo o que o helper faz. Exemplo FastAPI abaixo; o mesmo código funciona em qualquer framework Python assí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}
O algoritmo é HMAC-SHA256 sobre a string t.rawBody, uma comparação em tempo constante e uma janela de replay de 300 segundos. Leia o corpo bruto via await request.body(), nunca request.json() re-serialized, porque isso altera os bytes que a assinatura cobre. Os eventos enviados são payment.received, payment.sent, wallet.deployed e webhook.test. Para trabalhos de acompanhamento pesados, enfileire um trabalho (Celery, arq) e responda 200 imediatamente em vez de bloquear o manipulador.
O cliente que você está envolvendo é aberto. Leia-o.
Não existe um starter package do Agno para clonar - a receita acima é a integração. Os SDKs da blockchain0x são open source no GitHub; esta receita encapsula o Python SDK (blockchain0x-python), com a superfície completa de métodos na documentação. Leia como referência para os métodos do toolkit.
github.com/tosh-labs/blockchain0x-pythonA superfície completa de métodos e os escopos do SDK estão documentados em the docs. Comece com uma chave sk_test_ na Base Sepolia e depois mude para sk_live_ quando o toolkit fizer o que você espera.
Cinco coisas específicas do Agno para observar.
Agno é um dos frameworks de agente mais limpos para integrar, mas tem suas próprias armadilhas - especialmente em torno da renomeação do Phidata e da renderização de markdown.
Não há pacote Agno - você envolve o SDK em um Toolkit
Blockchain0x envia adaptadores para LangChain e CrewAI, além do servidor MCP; não há um pacote dedicado do Agno. A receita acima é o caminho: uma subclasse Toolkit que registra um método chamando o cliente real do blockchain0x. O Agno lê a assinatura do método e a docstring para construir o esquema da ferramenta, então mantenha a docstring precisa.
Confusão na migração de Phidata para Agno
Agno foi renomeado de Phidata em 2024. Códigos mais antigos que importam de phi.agent ou phi.tools ainda funcionam via um shim de compatibilidade, mas as importações agno.* são as atuais. A receita usa agno.* em todo o lugar; se seu código ainda estiver nas importações phi.*, execute pip install -U agno e mude os caminhos de importação antes de adicionar o Toolkit.
Os valores são unidades base de USDC, como strings
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.
Execução síncrona vs assíncrona
Agno suporta agent.run() (síncrono) e agent.arun() (assíncrono). Escolha um modo por agente - chame agent.run() e tente aguardar o resultado e você obterá uma coroutine onde esperava uma string. A chamada blockchain0x dentro do Toolkit é síncrona; se você estiver no caminho assíncrono e movimentando volume real, envolva-a com asyncio.to_thread para que o loop de eventos permaneça responsivo.
Verifique webhooks contra o corpo bruto
Se seu agente também recebe USDC, confirme com o webhook, não por polling. Verifique a assinatura sobre os bytes RAW da requisição (await request.body()), nunca request.json() re-serializado, porque o HMAC cobre os bytes exatos. É HMAC-SHA256 com uma janela de repetição de 300 segundos. O manipulador abaixo é tudo isso.