Arquitecturas de agentes de IA onchain: cinco patrones de construcción
Escrito por Uttam Singh
Los agentes de IA que leen y escriben estado onchain pasaron de las demos a producción. Los modelos pueden razonar, las wallets de agentes pueden firmar bajo permisos acotados, y la infraestructura puede enviar un evento a un agente segundos después de que ocurre onchain. La arquitectura es donde los builds todavía fallan. Los agentes hacen polling de eventos a los que podrían suscribirse, mantienen poder de firma en el mismo proceso que lee input no confiable, o aprenden en mainnet con fondos reales.
Un agente onchain es un loop: observar, decidir, actuar. Los agentes en producción organizan ese loop en cinco formas recurrentes, y cada una tiene un ejemplo desarrollado más abajo. Nuestra guía para construir agentes onchain cubre los primitivos que están debajo de todas ellas (una wallet, un riel de pago, un feed de datos); esta página trata sobre cómo organizar esos primitivos.
¿Cómo se construye un agente de wallet watcher en tiempo real?
Registra las direcciones que te interesan con un webhook y deja que la chain venga a ti. Hacer polling de balances en un loop consume cómputo y de todas formas se pierde el momento exacto. Un pipeline de push entrega la transferencia segundos después de que ocurre, que es todo el trabajo de un watcher.
Supongamos que el agente hace seguimiento de las wallets de contrapartes de un fondo y marca cualquier movimiento grande de USDC. En Alchemy, un solo webhook de Address Activity cubre transferencias nativas, ERC-20, ERC-721 y ERC-1155 para hasta 100,000 direcciones, así que un solo webhook vigila toda la lista de contrapartes. Si el agente corre como un proceso de larga duración y preferís no exponer una URL pública, las suscripciones WebSocket hacen el mismo trabajo en proceso. Suscribite con alchemy_minedTransactions y obtenés transacciones confirmadas ya filtradas a tus direcciones, sin necesidad de parsear logs. En Solana, el streaming de Yellowstone gRPC cubre el mismo espacio a $75 por TB con reconexiones sin gaps. Cuando no estés seguro de qué transporte conviene, nuestra comparación de webhooks vs WebSockets vs gRPC traza las líneas en detalle.
El handler en sí debería hacer casi nada. Verificá que la entrega venga de Alchemy, hacé dedupe, pasale el evento al paso de decisión del agente, y recién entonces confirmá la recepción:
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);Tres hábitos mantienen este patrón confiable en producción. Verificá la firma HMAC antes de confiar en una entrega, porque sin eso cualquiera que se entere de la URL del endpoint puede hacer POST de una transferencia falsa y manipular a tu agente. Emparejá los tokens por dirección de contrato, nunca por símbolo, ya que cualquiera puede deployar un token que se llame a sí mismo USDC y enviarlo a una dirección vigilada. Y las entregas son at-least-once, así que el registro de dedupe no es opcional. El set en memoria funciona para un proceso de larga duración; un servicio que reinicia o corre réplicas necesita el registro en algún lugar compartido y durable, como una key de Redis o una fila de base de datos, porque un despertar duplicado para un agente de trading es una transacción duplicada. El filtro mecánico pertenece al handler mientras el modelo se mantiene afuera de eso, porque una llamada a un LLM por transferencia cuesta más que la infraestructura que entregó la transferencia.
¿Cómo se deja que un agente de IA monitoree eventos de smart contracts y reaccione automáticamente?
Suscribite a los logs del contrato, filtrá para quedarte con el uno o dos eventos que importan, y hacé que el handler sea idempotente. Los eventos de contrato son el trigger más limpio que puede obtener un agente, ya que el contrato indica exactamente qué pasó y en qué orden.
Dos superficies cubren esto en Alchemy. Los webhooks personalizados toman un filtro GraphQL, así que podés hacer match por dirección de contrato y topics de eventos y recibir únicamente los logs que pediste. Eso conviene para reactores serverless. Para un agente de ejecución continua, una suscripción WebSocket a logs mantiene todo en un solo proceso. Acá hay un reactor observando un pool de Uniswap v3, el tipo de feed que un agente de trading usa para notar cuando un solo swap mueve el precio:
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);
}
},
});La verificación log.removed importa más de lo que parece. Las chains se reorganizan, y un log sobre el que tu agente ya actuó puede desaparecer de la chain canónica unos bloques después. Un handler idempotente más una regla de profundidad de confirmación (esperar unos bloques antes de acciones irreversibles) es la defensa estándar. La otra disciplina del reactor es la misma que la del watcher. El filtro de la suscripción hace la eliminación barata, y el modelo solo ve eventos que sobrevivieron a ese filtro.
¿Qué se necesita para construir un agente de rebalanceo de portfolio DeFi?
Cuatro piezas: balances actuales, precios actuales, una regla de drift, y un swap path. El agente lee las primeras dos, verifica la tercera, y solo toca la cuarta cuando la regla se activa.
Tomemos un agente de tesorería que mantiene un split 50/30/20 de WETH, USDC y WBTC. Los balances vienen de la Portfolio API, que devuelve los tokens de una wallet en varias redes en una sola solicitud en lugar de un fan-out de llamadas por chain. Los valores vienen de la Prices API. La regla de drift es aritmética. Un punto de partida común es una banda de cinco puntos porcentuales alrededor de cada peso objetivo. Verificala con un timer, porque el drift mayormente viene de que los precios se mueven y no de que los tokens se muevan, y un cambio de precio no produce ningún evento onchain al que reaccionar. Una transferencia reportada por el watcher (patrón uno) es el trigger suplementario que captura depósitos y retiros en el momento en que ocurren.
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
}
}El lado de ejecución no debería sostener una private key en crudo. Con una wallet de agente acotada, la key permanece en custodia y la sesión solo lleva las capacidades que otorgaste. Gastar un ERC-20 requiere un allowance para el router antes del swap. Aprobar el monto exacto cada vez cuesta una transacción extra y no deja ningún allowance permanente para que un atacante drene:
# 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-interactiveNotá la forma del loop. El agente propone, y otra cosa aprueba. Al principio esa otra cosa sos vos. Más adelante puede ser una verificación de políticas sobre tamaño, slippage y lista de activos permitidos. Nuestra descripción general de agentes de IA en DeFi cubre por qué esa separación es la norma en los agentes DeFi en producción, y el gas sponsorship elimina la última tarea operativa al pagar las fees bajo una política que controlás, así el agente nunca necesita administrar un balance de gas.
¿Cuál es la mejor arquitectura para un sistema multiagente de detectar-y-luego-ejecutar?
Dividí a los agentes por privilegio, no por carga de trabajo. El detector lee todo y no puede firmar nada. El executor firma transacciones y no cree nada que no haya reverificado.
Pensalo como un analista y un trader. El analista observa el mercado todo el día y puede hablar con cualquiera. El trader toma las señales del analista, las verifica, y es el único con acceso a la cuenta.
El planteo popular de este patrón viene de las herramientas generales para agentes, donde un modelo planificador produce pasos y agentes ejecutores corren herramientas. Ese planteo trata sobre orquestación. Onchain, la división se justifica por una razón más difícil: la custodia. Un detector consume input no confiable todo el día: ruido del mempool, APIs de terceros, streams de eventos, a veces feeds sociales. Cualquiera de eso puede traer una inyección de prompts. Si el proceso que lee el input hostil es también el proceso que sostiene el poder de firma, un mensaje envenenado puede convertirse en una transacción firmada. Separalos, y lo peor que puede hacer un detector comprometido es proponer algo malo que el executor descarta.
El detector se construye con los patrones uno y dos, conectado a infraestructura de push en lugar de un loop de polling. Emite señales a través de una cola, y la cola funciona también como tu log de auditoría. Mantené el contrato de la señal pequeño y verificable:
{
"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"
}El executor aplica tres reglas antes de actuar sobre cualquier señal:
- Reverificá la evidencia onchain. Leé vos mismo la transacción referenciada en lugar de confiar en el resumen del detector. El trabajo del detector fue notar; probar es trabajo del executor.
- Aplicá el vencimiento. Actuar sobre una oportunidad vencida es cómo los sistemas de detectar-y-luego-ejecutar pierden dinero incluso sin un atacante en el medio.
- Limitá el gasto en la capa de wallet. Un presupuesto por señal y por día vive en la sesión acotada, que podés revocar desde el dashboard en el momento en que el comportamiento se vea sospechoso.
Del lado de las herramientas, el executor necesita solo dos cosas: una conexión RPC para verificación y una superficie de firma. El detector es la mitad más hambrienta, y emparejarlo con datos indexados (la Transfers API para historial, la Portfolio API para estado) mantiene su gasto de tokens en razonamiento en lugar de en decodificar datos crudos de la chain. Nuestra comparación de APIs de blockchain para agentes autónomos cubre el lado de infraestructura de esa elección.
¿Cómo se prueban de forma segura las transacciones de un agente de IA antes de pasar a mainnet?
Poné cuatro puertas entre el agente y el valor real: hacé dry-run de cada transacción, limitá lo que la key puede gastar, ensayá el loop completo en una testnet, y mantené una aprobación humana en todo lo que mueva fondos.
- Primero dry-run. El CLI de Alchemy previsualiza cualquier envío sin firmar ni transmitir (
alchemy evm send 0xRecipient 0.4 --dry-run). En código, elsimulateContractde viem valida una llamada a contrato contra el estado de mainnet en vivo sin enviarla, así que el ensayo usa precios reales y profundidad de pool real en lugar de un fixture desactualizado. - Limitá la key. Una session wallet acotada vence en el cronograma que definas y solo puede hacer lo que aprobaste, y las políticas de gas sponsorship agregan listas de permitidos y límites de gasto en la capa de fees. Una key limitada convierte un bug en el peor caso de un drenaje de cuenta a una pérdida acotada.
- Ensayá en una testnet. Apuntá el mismo código a un endpoint de Sepolia o Base Sepolia y fondeá el agente desde nuestros faucets de testnet. El ensayo no vale nada si el código cambia entre el ensayo y producción, así que mantené el nombre de la red en configuración y no cambies nada más.
- Poné puertas a las acciones que mueven fondos. Mientras el agente es joven, cada envío, swap y aprobación espera un sí explícito. La mayoría de los equipos relaja las puertas deliberadamente, un tipo de acción a la vez, a medida que el log de auditoría construye el caso de que el agente se comporta bien.
Los equipos que hacen esto bien tratan la promoción como una secuencia y no como un interruptor: primero solo lectura contra mainnet, luego escrituras en testnet, luego escrituras limitadas en mainnet, luego un presupuesto completo. Cada etapa produce logs que justifican la siguiente.
Empezá con las piezas que ya existen
Cada patrón de esta página corre sobre infraestructura que podés usar hoy. El CLI de Alchemy maneja wallets, envíos, swaps y administración de webhooks desde un solo binario que un agente puede operar con --json --no-interactive. El servidor MCP hospedado expone 168 herramientas entre RPC, simulación y datos, y el plugin de Alchemy para Claude Code instala toda la superficie en un solo comando. Podés empezar con un tier gratuito sin contratos y sin compromiso mínimo, y un agente incluso puede registrarse por sí mismo con su propia wallet y pagar en USDC. Cualquiera sea el patrón con el que empieces, el loop se mantiene igual: observar, decidir, actuar.
Preguntas frecuentes
¿Cuál es la mejor arquitectura para un sistema multiagente donde un agente detecta oportunidades y otro ejecuta?
Dividir por privilegio: un detector que lee streams de eventos pero no sostiene ninguna key, una cola que lleva señales pequeñas y firmadas, y un executor que reverifica cada señal onchain antes de actuar. En Alchemy, el detector corre sobre webhooks o suscripciones WebSocket y el executor firma a través de una wallet de agente acotada con límites de gasto y revocación instantánea.
¿Cuál es la mejor infraestructura para un agente de wallet watcher en tiempo real?
Entrega de eventos basada en push en lugar de polling. Los webhooks de Address Activity de Alchemy hacen seguimiento de transferencias en hasta 100,000 direcciones por webhook, las suscripciones WebSocket transmiten transacciones minadas filtradas a tus direcciones, y Yellowstone gRPC cubre Solana. Un pipeline de push despierta al agente segundos después de que la transferencia ocurre, sin la latencia y el costo de cómputo de un loop de polling.
¿Qué herramientas debería usar un agente de coding con IA para monitorear actividad de wallets?
El servidor MCP de Alchemy le da a un agente de coding 168 herramientas que cubren RPC, historial de transacciones y datos de portfolio, y el CLI de Alchemy crea y administra webhooks desde la línea de comandos. Para el runtime en sí, un webhook de Address Activity o una suscripción alchemy_minedTransactions entrega eventos de wallet, y la Transfers API completa el historial.
¿Qué necesito para construir un agente de rebalanceo de portfolio DeFi?
Balances, precios, una regla de drift, y un swap path. La Portfolio API de Alchemy devuelve balances multired en una sola llamada, la Prices API los valoriza, y una verificación de drift (comúnmente una banda de cinco puntos alrededor de los pesos objetivo) decide cuándo actuar. Ejecutá a través de una wallet de agente acotada para que el agente proponga y una política o una persona apruebe.
¿Cómo dejo que un agente de IA monitoree eventos de smart contracts y reaccione automáticamente?
Suscribite a los logs del contrato y pasale los eventos que coinciden al agente. Los webhooks personalizados de Alchemy filtran por dirección de contrato y topics de eventos con GraphQL antes de la entrega, y las suscripciones WebSocket a logs hacen lo mismo en proceso. Hacé que el handler sea idempotente, saltá los logs reorganizados, y dejá que el modelo razone solo sobre eventos que pasaron el filtro mecánico.
¿Cómo pruebo de forma segura las transacciones de un agente de IA antes de pasar a mainnet?
Poné las puertas en capas: previsualizá transacciones con el flag de dry-run del CLI de Alchemy, validá llamadas a contratos contra el estado en vivo con simulación basada en eth_call, limitá la wallet del agente con sesiones acotadas y límites de gasto de la política de gas, ensayá en Sepolia o Base Sepolia con fondos de los faucets de Alchemy, y mantené la aprobación humana en cada acción que mueva fondos hasta que el log de auditoría gane puertas más laxas.
Resúmenes relacionados
Infra10 de septiembre de 2026
Las mejores APIs de blockchain para construir agentes autónomos onchain
Una comparación de los principales proveedores de APIs de blockchain para agentes autónomos onchain, que abarca funciones nativas para agentes, cobertura de chains y las capacidades que importan cuando tu usuario es una máquina.
DeFi12 de junio de 2026
¿Qué son los agentes de IA para DeFi? Casos de uso, riesgos y arquitectura
Los agentes de IA para DeFi, también llamados agentes DeFAI, son sistemas autónomos que pueden razonar, firmar y liquidar operaciones onchain bajo controles de políticas.
Técnico19 de mayo de 2026
Webhooks vs. WebSockets vs. gRPC
Tres protocolos dominan la entrega de datos en tiempo real. Así es como se diferencian webhooks, WebSockets y gRPC, cuándo falla cada uno y cómo elegir entre ellos.
Construye magia blockchain
Alchemy combina los productos y herramientas de desarrollo Web3 más potentes con recursos, comunidad y un soporte legendario.