Arquiteturas de agentes de IA onchain: cinco padrões de build
Escrito por Uttam Singh
Agentes de IA que leem e escrevem estado onchain saíram das demos e foram para produção. Os modelos conseguem raciocinar, as wallets de agentes podem assinar sob permissões delimitadas, e a infraestrutura consegue enviar um evento a um agente segundos depois que ele acontece onchain. A arquitetura é onde as construções ainda dão errado. Agentes fazem polling de eventos aos quais poderiam se inscrever, mantêm poder de assinatura no mesmo processo que lê entradas não confiáveis, ou aprendem na mainnet com fundos reais.
Um agente onchain é um loop: observar, decidir, agir. Agentes em produção organizam esse loop em cinco formatos recorrentes, e cada um tem um exemplo trabalhado abaixo. Nosso guia para construir agentes onchain cobre as primitivas por trás de todos eles (uma wallet, um trilho de pagamento, um feed de dados); esta página trata de como você organiza essas primitivas.
Como construir um agente de vigilância de wallets em tempo real?
Registre os endereços que importam com um webhook e deixe a chain vir até você. Fazer polling de saldos em um loop consome computação e ainda assim perde o momento. Um pipeline push entrega a transferência segundos depois que ela acontece, que é exatamente a função de um watcher.
Suponha que o agente acompanhe as wallets de contrapartes de um fundo e sinalize qualquer movimentação grande de USDC. Na Alchemy, um único Address Activity webhook cobre transferências nativas, ERC-20, ERC-721 e ERC-1155 para até 100.000 endereços, então um webhook observa toda a lista de contrapartes. Se o agente roda como um processo de longa duração e você preferir não expor uma URL pública, assinaturas WebSocket cumprem a mesma função dentro do próprio processo. Assine com alchemy_minedTransactions e você recebe transações confirmadas já filtradas para seus endereços, sem necessidade de parsing de logs. No Solana, o streaming Yellowstone gRPC preenche o mesmo papel por $75 por TB com reconexões sem gaps. Quando não tiver certeza de qual transporte se encaixa, nossa comparação entre webhooks, WebSockets e gRPC detalha as diferenças.
O handler em si deve fazer quase nada. Comprove que a entrega veio da Alchemy, elimine duplicatas, passe o evento para o passo de decisão do agente e só então confirme o recebimento:
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const SIGNING_KEY = process.env.ALCHEMY_WEBHOOK_SIGNING_KEY!; // from the webhook's dashboard settings
const USDC = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"; // canonical USDC contract on Ethereum mainnet
const seen = new Set<string>();
function remember(key: string) {
seen.add(key);
if (seen.size > 10_000) seen.delete(seen.values().next().value!); // bound the set; only recent deliveries repeat
}
function wake(signal: unknown) {
// The agent's decide step starts here. Queue the signal;
// don't run model reasoning inside the request handler.
}
const app = express();
app.use(
express.json({
verify: (req, _res, buf) => {
(req as { rawBody?: Buffer }).rawBody = buf; // keep the raw bytes for the HMAC check
},
})
);
app.post("/hooks/address-activity", (req, res) => {
const sig = Buffer.from(String(req.headers["x-alchemy-signature"] ?? ""), "hex");
const expected = createHmac("sha256", SIGNING_KEY)
.update((req as { rawBody?: Buffer }).rawBody ?? Buffer.alloc(0))
.digest();
if (sig.length !== expected.length || !timingSafeEqual(sig, expected)) {
return res.sendStatus(401); // not signed with our key; never process it
}
for (const transfer of req.body.event.activity) {
const key = `${transfer.hash}:${transfer.log?.logIndex ?? "native"}`; // one tx can carry several transfers
if (seen.has(key)) continue; // repeat delivery, already handled
if (transfer.rawContract?.address?.toLowerCase() === USDC && transfer.value > 50_000) {
wake({ kind: "large-transfer", ...transfer }); // if this throws, the key stays unmarked and the retry redelivers
}
remember(key); // mark handled only after the handoff succeeded
}
res.sendStatus(200); // ack only after queueing: a crash above gets retried, not lost
});
app.listen(8080);Três hábitos mantêm esse padrão confiável em produção. Verifique a assinatura HMAC antes de confiar em uma entrega, porque sem isso qualquer pessoa que descobrir a URL do endpoint pode enviar um POST com uma transferência falsa e direcionar seu agente. Combine tokens pelo endereço do contrato, nunca pelo símbolo, já que qualquer um pode implantar um token que se autodenomina USDC e enviá-lo a um endereço monitorado. E as entregas são at-least-once, então o registro de deduplicação não é opcional. O conjunto em memória funciona para um único processo de longa duração; um serviço que reinicia ou roda réplicas precisa desse registro em algum lugar compartilhado e durável, como uma chave no Redis ou uma linha em banco de dados, porque um despertar duplicado para um agente de trading é uma transação duplicada. O filtro mecânico pertence ao handler, enquanto o modelo fica fora dele, porque uma chamada de LLM por transferência custa mais do que a infraestrutura que entregou a transferência.
Como permitir que um agente de IA monitore eventos de smart contracts e reaja automaticamente?
Assine os logs do contrato, filtre para o um ou dois eventos que importam, e torne o handler idempotente. Eventos de contrato são o gatilho mais limpo que um agente pode ter, já que o contrato declara exatamente o que aconteceu e em qual ordem.
Duas superfícies cobrem isso na Alchemy. Webhooks customizados aceitam um filtro GraphQL, então você pode filtrar por endereço de contrato e tópicos de evento e receber apenas os logs que pediu. Isso serve bem para reatores serverless. Para um agente de longa duração, uma assinatura de logs via WebSocket mantém tudo em um único processo. Aqui está um reator observando um pool do Uniswap v3, o tipo de feed que um agente de trading usa para perceber quando um único swap move o preço:
import { createPublicClient, webSocket, parseAbiItem } from "viem";
import { mainnet } from "viem/chains";
function react(args: unknown) {
// Decide step: is this swap big enough to act on?
}
const client = createPublicClient({
chain: mainnet,
transport: webSocket("wss://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY"),
});
client.watchEvent({
address: "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640", // USDC/WETH 0.05% pool
event: parseAbiItem(
"event Swap(address indexed sender, address indexed recipient, int256 amount0, int256 amount1, uint160 sqrtPriceX96, uint128 liquidity, int24 tick)"
),
onLogs: (logs) => {
for (const log of logs) {
if (log.removed) continue; // reorg removal notice; irreversible actions also need the confirmation-depth rule below
react(log.args);
}
},
});A verificação log.removed importa mais do que parece. As chains se reorganizam, e um log sobre o qual seu agente já agiu pode desaparecer da chain canônica alguns blocos depois. Um handler idempotente somado a uma regra de profundidade de confirmação (esperar alguns blocos antes de ações irreversíveis) é a defesa padrão. A outra disciplina do reator é a mesma do watcher. O filtro da assinatura faz a eliminação barata, e o modelo só vê os eventos que sobreviveram a ela.
O que você precisa para construir um agente de rebalanceamento de portfólio DeFi?
Quatro peças: saldos atuais, preços atuais, uma regra de desvio e um caminho de swap. O agente lê as duas primeiras, verifica a terceira, e só toca na quarta quando a regra dispara.
Considere um agente de tesouraria mantendo uma divisão de 50/30/20 entre WETH, USDC e WBTC. Os saldos vêm da Portfolio API, que retorna os tokens de uma wallet em várias redes em uma única requisição, em vez de um fan-out de chamadas por chain. Os valores vêm da Prices API. A regra de desvio é aritmética. Um ponto de partida comum é uma faixa de cinco pontos percentuais ao redor de cada peso alvo. Verifique isso em um temporizador, porque o desvio vem majoritariamente de movimentações de preço, não de tokens se movendo, e uma mudança de preço não produz nenhum evento onchain para reagir. Uma transferência reportada pelo watcher (padrão um) é o gatilho complementar que captura depósitos e saques no momento em que acontecem.
const TARGET = { WETH: 0.5, USDC: 0.3, WBTC: 0.2 } as const;
const BAND = 0.05; // rebalance when a weight drifts 5 points from target
const WALLET = "0xYourTreasuryWallet"; // the wallet the agent manages
const res = await fetch(
`https://api.g.alchemy.com/data/v1/${process.env.ALCHEMY_API_KEY}/assets/tokens/by-address`,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
addresses: [{ address: WALLET, networks: ["eth-mainnet"] }],
}),
}
);
const { data } = await res.json();
// Price each balance with the Prices API, sum to a total, then:
for (const [symbol, target] of Object.entries(TARGET)) {
const drift = weightOf(symbol, data) - target; // weightOf: your portfolio math
if (Math.abs(drift) > BAND) {
propose({ symbol, drift }); // propose: log it and request approval; never swap directly
}
}O lado de execução não deve manter uma chave privada crua. Com uma agent wallet delimitada, a chave permanece em custódia e a sessão carrega apenas as capacidades que você concedeu. Gastar um ERC-20 exige uma allowance para o router antes do swap. Aprovar o valor exato a cada vez custa uma transação extra e não deixa allowance permanente para um atacante drenar:
# before each swap: let the router from your quote spend exactly this swap's WETH
alchemy evm approve 0xRouterFromQuote --token-address 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 --amount 0.4 -n eth-mainnet
# swap WETH into USDC (Ethereum mainnet contract addresses)
alchemy evm swap execute \
--from 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 \
--to 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 \
--amount 0.4 --slippage 0.5 -n eth-mainnet \
--signer session --json --no-interactiveRepare no formato do loop. O agente propõe, e outra coisa aprova. No início, essa outra coisa é você. Mais adiante pode ser uma verificação de política sobre tamanho, slippage e lista de ativos permitidos. Nosso panorama de agentes de IA em DeFi cobre por que essa separação é a norma entre agentes DeFi em produção, e o patrocínio de gas elimina a última tarefa operacional ao pagar taxas sob uma política que você controla, de modo que o agente nunca precisa gerenciar um saldo de gas.
Qual é a melhor arquitetura para um sistema multiagente de detectar-e-executar?
Divida os agentes por privilégio, não por carga de trabalho. O detector lê tudo e não pode assinar nada. O executor assina transações e não acredita em nada que não tenha reverificado.
Pense nisso como um analista e um trader. O analista observa o mercado o dia todo e pode conversar com qualquer um. O trader recebe as recomendações do analista, as verifica, e é o único com acesso à conta.
O enquadramento popular desse padrão vem de ferramentas de agentes em geral, onde um modelo planejador produz etapas e agentes executores rodam ferramentas. Esse enquadramento é sobre orquestração. Onchain, a divisão justifica sua complexidade por um motivo mais difícil: custódia. Um detector consome entrada não confiável o dia todo: ruído do mempool, APIs de terceiros, streams de eventos, às vezes feeds sociais. Qualquer um desses pode carregar uma injeção de prompt. Se o processo que lê entrada hostil também for o processo que detém poder de assinatura, uma mensagem envenenada pode virar uma transação assinada. Separe-os, e o pior que um detector comprometido pode fazer é sugerir algo ruim que o executor descarta.
O detector é construído a partir dos padrões um e dois, conectado a infraestrutura push em vez de um loop de polling. Ele emite sinais por uma fila, e a fila também funciona como seu log de auditoria. Mantenha o contrato do sinal pequeno e verificável:
{
"kind": "arb-opportunity",
"pair": "WETH/USDC",
"evidence": { "txHash": "0x…", "block": 23411005 },
"proposal": { "action": "swap", "from": "WETH", "to": "USDC", "amount": "0.4" },
"observedAt": "2026-09-05T09:14:03Z",
"expiresAt": "2026-09-05T09:14:33Z"
}O executor impõe três regras antes de agir sobre qualquer sinal:
- Reverifique a evidência onchain. Leia a transação referenciada você mesmo, em vez de confiar no resumo do detector. O trabalho do detector foi perceber; provar é trabalho do executor.
- Imponha o prazo de expiração. Agir sobre uma oportunidade obsoleta é como sistemas de detectar-e-executar perdem dinheiro mesmo sem um atacante no loop.
- Limite o gasto na camada de wallet. Um orçamento por sinal e por dia vive na sessão delimitada, que você pode revogar pelo dashboard no momento em que o comportamento parecer errado.
Do lado das ferramentas, o executor precisa apenas de duas coisas: uma conexão RPC para verificação e uma superfície de assinatura. O detector é a metade mais faminta, e combiná-lo com dados indexados (a Transfers API para histórico, a Portfolio API para estado) mantém seu gasto de tokens focado em raciocínio em vez de decodificar dados brutos da chain. Nossa comparação de APIs de blockchain para agentes autônomos cobre o lado de infraestrutura dessa escolha.
Como testar transações de agentes de IA com segurança antes de ir para a mainnet?
Coloque quatro portões entre o agente e valor real: dry-run em toda transação, limite o que a chave pode gastar, ensaie o loop completo em uma testnet, e mantenha aprovação humana em qualquer coisa que movimente fundos.
- Dry-run primeiro. O CLI da Alchemy pré-visualiza qualquer envio sem assinar ou fazer broadcast (
alchemy evm send 0xRecipient 0.4 --dry-run). No código, osimulateContractdo viem valida uma chamada de contrato contra o estado real da mainnet sem submetê-la, de modo que o ensaio usa preços reais e profundidade de pool real em vez de um fixture desatualizado. - Limite a chave. Uma session wallet delimitada expira no cronograma que você definir e só pode fazer o que você aprovou, e políticas de patrocínio de gas adicionam listas de permissão e limites de gasto na camada de taxas. Uma chave limitada transforma um bug de pior caso de um drenamento de conta em uma perda limitada.
- Ensaie em uma testnet. Aponte o mesmo código para um endpoint Sepolia ou Base Sepolia e financie o agente com nossos faucets de testnet. O ensaio não vale nada se o código muda entre o ensaio e a produção, então mantenha o nome da rede em configuração e não altere mais nada.
- Restrinja ações que movimentam fundos. Enquanto o agente é jovem, todo envio, swap e aprovação espera um sim explícito. A maioria das equipes afrouxa os portões deliberadamente, um tipo de ação por vez, à medida que o log de auditoria constrói um histórico de que o agente se comporta bem.
Equipes que fazem isso bem tratam a promoção como uma sequência, não como um interruptor: primeiro somente leitura contra a mainnet, depois escritas em testnet, depois escritas limitadas em mainnet, depois um orçamento completo. Cada etapa produz logs que justificam a próxima.
Comece pelas peças que já existem
Todo padrão desta página roda sobre infraestrutura que você pode usar hoje. O Alchemy CLI cuida de wallets, envios, swaps e gerenciamento de webhooks a partir de um único binário que um agente pode operar com --json --no-interactive. O servidor MCP hospedado expõe 168 ferramentas cobrindo RPC, simulação e dados, e o plugin Alchemy para Claude Code instala toda a superfície em um único comando. Você pode começar em um tier gratuito, sem contratos e sem compromisso mínimo, e um agente pode até se cadastrar sozinho com sua própria wallet e pagar em USDC. Qualquer que seja o padrão pelo qual você comece, o loop permanece o mesmo: observar, decidir, agir.
Perguntas frequentes
Qual é a melhor arquitetura para um sistema multiagente em que um agente detecta oportunidades e outro executa?
Divida por privilégio: um detector que lê streams de eventos mas não detém chaves, uma fila carregando pequenos sinais assinados, e um executor que reverifica cada sinal onchain antes de agir. Na Alchemy, o detector roda sobre webhooks ou assinaturas WebSocket e o executor assina através de uma agent wallet delimitada com limites de gasto e revogação instantânea.
Qual é a melhor infraestrutura para um agente de vigilância de wallets em tempo real?
Entrega de eventos baseada em push, em vez de polling. Os Address Activity webhooks da Alchemy acompanham transferências em até 100.000 endereços por webhook, as assinaturas WebSocket transmitem transações minadas filtradas para seus endereços, e o Yellowstone gRPC cobre o Solana. Um pipeline push desperta o agente segundos depois que a transferência acontece, sem o custo de latência e computação de um loop de polling.
Quais ferramentas um agente de codificação de IA deve usar para monitorar atividade de wallet?
O servidor MCP da Alchemy oferece a um agente de codificação 168 ferramentas cobrindo RPC, histórico de transações e dados de portfólio, e o CLI da Alchemy cria e gerencia webhooks pela linha de comando. Para o próprio runtime, um Address Activity webhook ou uma assinatura alchemy_minedTransactions entrega eventos de wallet, e a Transfers API preenche o histórico retroativamente.
O que eu preciso para construir um agente de rebalanceamento de portfólio DeFi?
Saldos, preços, uma regra de desvio e um caminho de swap. A Portfolio API da Alchemy retorna saldos multi-rede em uma única chamada, a Prices API os avalia, e uma verificação de desvio (comumente uma faixa de cinco pontos em torno dos pesos alvo) decide quando agir. Execute através de uma agent wallet delimitada, de modo que o agente proponha e uma política ou um humano aprove.
Como permitir que um agente de IA monitore eventos de smart contracts e reaja automaticamente?
Assine os logs do contrato e passe os eventos correspondentes para o agente. Os webhooks customizados da Alchemy filtram por endereço de contrato e tópicos de evento com GraphQL antes da entrega, e as assinaturas de logs via WebSocket fazem o mesmo dentro do processo. Torne o handler idempotente, ignore logs reorganizados, e deixe o modelo raciocinar apenas sobre eventos que passaram pelo filtro mecânico.
Como testar transações de agentes de IA com segurança antes de ir para a mainnet?
Coloque os portões em camadas: pré-visualize transações com a flag de dry-run do CLI da Alchemy, valide chamadas de contrato contra o estado real com simulação baseada em eth_call, limite a wallet do agente com sessões delimitadas e limites de gasto de política de gas, ensaie em Sepolia ou Base Sepolia com fundos dos faucets da Alchemy, e mantenha aprovação humana em toda ação que movimente fundos até que o log de auditoria justifique portões mais soltos.
Visões gerais relacionadas
Infra10 de setembro de 2026
As melhores APIs de blockchain para construir agentes onchain autônomos
Uma comparação dos principais provedores de API de blockchain para agentes onchain autônomos, cobrindo recursos agent-native, cobertura de chains e as capacidades que importam quando seu usuário é uma máquina.
DeFi12 de junho de 2026
O que são agentes de IA para DeFi? Casos de uso, riscos e arquitetura
Agentes de IA para DeFi, também chamados de agentes DeFAI, são sistemas autônomos que podem raciocinar, assinar e liquidar onchain sob controles de política.
Técnico19 de maio de 2026
Webhooks vs. WebSockets vs. gRPC
Três protocolos dominam a entrega de dados em tempo real. Veja como webhooks, WebSockets e gRPC se diferenciam, quando cada um falha e como escolher entre eles.
Construa magia blockchain
A Alchemy combina os produtos e ferramentas de desenvolvimento Web3 mais poderosos com recursos, comunidade e suporte lendário.