---
title: "Arquiteturas de agentes de IA onchain: cinco padrões de build"
description: "Cinco padrões de build para agentes de IA onchain, cada um com um exemplo prático: wallet watchers, reactors orientados a eventos, portfolio rebalancers, splits multi-agente detect-then-execute e testes seguros pre-mainnet."
---
# Arquiteturas de agentes de IA onchain: cinco padrões de build
Agentes de IA que leem e escrevem estado onchain saíram das demos e foram para produção. Os modelos conseguem raciocinar, wallets de agentes conseguem 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 builds ainda dão errado. Agentes fazem polling de eventos aos quais poderiam se inscrever, mantêm poder de assinatura no mesmo processo que lê input não confiável, ou aprendem na mainnet com fundos reais.
Um agente onchain é um loop: observar, decidir, agir. Agentes em produção organizam esse loop em cinco formas recorrentes, e cada uma tem um exemplo resolvido abaixo. Nosso [guia para construir agentes onchain](https://www.alchemy.com/blog/how-to-build-onchain-agents) cobre os primitivos por trás de todas elas (uma wallet, um rail de pagamento, um feed de dados); esta página trata de como você organiza esses primitivos.
## Como construir um agente de observação de wallet em tempo real?
Registre os endereços que importam com um webhook e deixe a chain vir até você. Fazer polling de saldos em loop consome computação e ainda assim perde o momento exato. Um pipeline push entrega a transferência segundos depois que ela acontece, o que é exatamente o trabalho de um watcher.
Digamos que o agente monitore as wallets de contraparte de um fundo e sinalize qualquer movimentação grande de USDC. Na Alchemy, um único [Address Activity webhook](https://www.alchemy.com/webhooks) cobre transferências nativas, ERC-20, ERC-721 e ERC-1155 para [até 100.000 endereços](https://www.alchemy.com/docs/reference/webhook-types), então um único webhook monitora toda a lista de contrapartes. Se o agente roda como um processo de longa duração e você prefere não expor uma URL pública, as [WebSocket subscriptions](https://www.alchemy.com/docs/reference/subscription-api) fazem o mesmo trabalho no próprio processo. Ao se inscrever com `alchemy_minedTransactions`, você recebe transações confirmadas já filtradas para os seus endereços, sem necessidade de parsing de logs. No Solana, o [Yellowstone gRPC streaming](https://www.alchemy.com/solana-grpc) preenche o mesmo papel a $75 por TB com reconexões sem gaps. Quando não estiver claro qual transporte se encaixa, nossa [comparação entre webhooks, WebSockets e gRPC](https://www.alchemy.com/overviews/webhooks-vs-websockets-vs-grpc) detalha as diferenças.
O próprio handler deve fazer quase nada. Comprove que a entrega veio da Alchemy, faça deduplicação, passe o evento para o passo de decisão do agente, e só então confirme o recebimento:
();
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 fazer um POST simulando uma transferência falsa e enganar seu agente. Compare tokens pelo endereço do contrato, nunca pelo símbolo, já que qualquer pessoa pode implantar um token que se autodenomina USDC e enviá-lo a um endereço monitorado. E as entregas são "pelo menos uma vez" (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 manter esse registro em algum lugar compartilhado e durável, como uma chave Redis ou uma linha de 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 de 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?
Inscreva-se nos 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 que ordem.
Duas superfícies cobrem isso na Alchemy. Os [custom webhooks](https://www.alchemy.com/docs/reference/custom-webhooks-quickstart) 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 a reactors serverless. Para um agente de longa duração, uma WebSocket logs subscription mantém tudo em um único processo. Aqui está um reactor observando um pool da Uniswap v3, o tipo de feed que um agente de trading usa para perceber quando um único swap move o preço:
{
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. Chains sofrem reorganizações, 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 reactor é a mesma do watcher. O filtro da subscription faz a eliminação barata, e o modelo só vê 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 é acionada.
Considere um agente de tesouraria que mantém uma divisão 50/30/20 entre WETH, USDC e WBTC. Os saldos vêm da [Portfolio API](https://www.alchemy.com/docs/reference/portfolio-apis), 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](https://www.alchemy.com/docs/reference/prices-api-quickstart). A regra de desvio é aritmética. Um ponto de partida comum é uma faixa de cinco pontos percentuais em torno de cada peso-alvo. Verifique isso em um timer, porque o desvio geralmente vem da variação de preços e não da movimentação de tokens, e uma mudança de preço não gera nenhum evento onchain ao qual reagir. Uma transferência reportada pelo watcher (padrão um) é o gatilho complementar que captura depósitos e saques no momento em que acontecem.
BAND) {
propose({ symbol, drift }); // propose: log it and request approval; never swap directly
}
}`}
/>
O lado da execução não deve manter uma chave privada crua. Com uma [scoped agent wallet](https://www.alchemy.com/blog/agent-wallets-alchemy-cli), a chave permanece sob custódia e a sessão carrega apenas as capacidades que você concedeu. Gastar um ERC-20 exige um allowance para o router antes do swap. Aprovar o valor exato a cada vez custa uma transação extra e não deixa nenhum allowance permanente para um atacante drenar:
Note a forma 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 allowlist de ativos. Nossa [visão geral de agentes de IA em DeFi](https://www.alchemy.com/overviews/defi-ai-agents) explica por que essa separação é a norma entre agentes de DeFi em produção, e o [gas sponsorship](https://www.alchemy.com/gasless-transactions) elimina a última tarefa operacional ao pagar taxas sob uma política que você controla, então o agente nunca precisa gerenciar um saldo de gas.
## Qual é a melhor arquitetura para um sistema multi-agente 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 confia 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 do tooling geral de agentes, no qual 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 sério: custódia. Um detector consome input não confiável o dia inteiro: ruído do mempool, APIs de terceiros, streams de eventos, às vezes feeds sociais. Qualquer um desses pode carregar uma prompt injection. Se o processo que lê input hostil também é o processo que detém poder de assinatura, uma única mensagem envenenada pode virar uma transação assinada. Separe-os, e o pior que um detector comprometido pode fazer é gerar uma sugestão 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 serve como seu log de auditoria. Mantenha o contrato do sinal pequeno e verificável:
O executor aplica três regras antes de agir sobre qualquer sinal:
- **Reverifique a evidência onchain.** Leia você mesmo a transação referenciada, em vez de confiar no resumo do detector. O trabalho do detector foi perceber; provar é trabalho do executor.
- **Aplique a 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 da wallet.** Um orçamento por sinal e por dia vive na [scoped session](https://www.alchemy.com/blog/agent-wallets-alchemy-cli), que você pode revogar pelo dashboard no momento em que o comportamento parecer errado.
Do lado das ferramentas, o executor precisa de apenas duas coisas: uma conexão RPC para verificação e uma superfície de assinatura. O detector é a metade mais faminta por dados, e combiná-lo com dados indexados (a [Transfers API](https://www.alchemy.com/docs/reference/transfers-api-quickstart) para histórico, a Portfolio API para estado) mantém seu gasto de tokens focado em raciocínio, em vez de em decodificar dados brutos da chain. Nossa [comparação de APIs de blockchain para agentes autônomos](https://www.alchemy.com/overviews/best-blockchain-apis-for-autonomous-onchain-agents) 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: faça dry-run de 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.
- **Faça dry-run primeiro.** O Alchemy CLI faz preview de qualquer envio sem assinar ou transmitir (`alchemy evm send 0xRecipient 0.4 --dry-run`). No código, o `simulateContract` do viem valida uma chamada de contrato contra o estado ao vivo da mainnet sem submetê-la, então o ensaio usa preços reais e profundidade de pool real, em vez de um fixture desatualizado.
- **Limite a chave.** Uma scoped session wallet expira no cronograma que você define e só pode fazer aquilo para o qual você a autorizou, e as [políticas de gas sponsorship](https://www.alchemy.com/gasless-transactions) adicionam allowlists e limites de gasto na camada de taxas. Uma chave limitada transforma um bug de pior caso de uma drenagem 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 [testnet faucets](https://www.alchemy.com/faucets). 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 na configuração e não mude mais nada.
- **Bloqueie 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 evidências 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 orçamento completo. Cada etapa produz logs que justificam a próxima.
## Comece com as peças que já existem
Todo padrão desta página roda sobre infraestrutura que você pode usar hoje. O [Alchemy CLI](https://www.alchemy.com/agents) 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](https://www.alchemy.com/docs/alchemy-mcp-server) hospedado expõe 168 ferramentas cobrindo RPC, simulação e dados, e o [plugin da Alchemy para Claude Code](https://www.alchemy.com/blog/alchemy-claude-plugin-now-live) instala toda essa superfície com 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 a própria wallet](https://www.alchemy.com/blog/ai-agents-can-now-sign-up-for-alchemy) 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 multi-agente 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 WebSocket subscriptions e o executor assina através de uma scoped agent wallet com limites de gasto e revogação instantânea.
### Qual é a melhor infraestrutura para um agente de observação de wallet em tempo real?
Entrega de eventos baseada em push, em vez de polling. Os Address Activity webhooks da Alchemy monitoram transferências em até 100.000 endereços por webhook, as WebSocket subscriptions transmitem transações minadas já filtradas para os seus endereços, e o Yellowstone gRPC cobre Solana. Um pipeline push desperta o agente segundos depois que a transferência acontece, sem a latência e o custo de 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 Alchemy CLI cria e gerencia webhooks pela linha de comando. Para o runtime em si, um Address Activity webhook ou uma subscription `alchemy_minedTransactions` entrega eventos de wallet, e a Transfers API preenche o histórico retroativamente.
### O que 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 scoped agent wallet para 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?
Inscreva-se nos logs do contrato e passe os eventos correspondentes para o agente. Os custom webhooks da Alchemy filtram por endereço de contrato e tópicos de evento com GraphQL antes da entrega, e as WebSocket log subscriptions fazem o mesmo no próprio 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?
Empilhe os portões: faça preview de transações com a flag de dry-run do Alchemy CLI, valide chamadas de contrato contra o estado ao vivo com simulação baseada em `eth_call`, limite a wallet do agente com scoped sessions 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.