---
title: "Arquitecturas de agentes de IA onchain: cinco patrones de construcción"
description: "Cinco patrones de construcción para agentes de IA onchain, cada uno con un ejemplo práctico: monitores de wallets, reactores basados en eventos, rebalanceadores de portafolios, divisiones multiagente de detectar-y-ejecutar, y pruebas seguras previas a mainnet."
---
# Arquitecturas de agentes de IA onchain: cinco patrones de construcción
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 empujar 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](https://www.alchemy.com/blog/how-to-build-onchain-agents) cubre las primitivas debajo de todas ellas (una wallet, un riel de pagos, un feed de datos); esta página trata sobre cómo organizar esas primitivas.
## ¿Cómo construyes un agente de wallet watcher en tiempo real?
Registra las direcciones que te interesan con un webhook y deja que la cadena venga a ti. Hacer polling de balances en un loop consume cómputo y aun así se pierde el momento exacto. Un pipeline de push entrega la transferencia segundos después de que ocurre, que es exactamente el trabajo de un watcher.
Supongamos que el agente rastrea las wallets contraparte de un fondo y marca cualquier movimiento grande de USDC. En Alchemy, un solo [Address Activity webhook](https://www.alchemy.com/webhooks) cubre transferencias nativas, ERC-20, ERC-721 y ERC-1155 para [hasta 100,000 direcciones](https://www.alchemy.com/docs/reference/webhook-types), así que un webhook vigila toda la lista de contrapartes. Si el agente corre como un proceso de larga duración y prefieres no exponer una URL pública, las [suscripciones WebSocket](https://www.alchemy.com/docs/reference/subscription-api) hacen el mismo trabajo dentro del proceso. Suscríbete con `alchemy_minedTransactions` y obtienes transacciones confirmadas ya filtradas a tus direcciones, sin necesidad de parsear logs. En Solana, [Yellowstone gRPC streaming](https://www.alchemy.com/solana-grpc) cubre el mismo rol a $75 por TB con reconexiones sin huecos. Cuando no estés seguro de qué transporte te conviene, nuestra [comparación de webhooks vs WebSockets vs gRPC](https://www.alchemy.com/overviews/webhooks-vs-websockets-vs-grpc) traza las diferencias en detalle.
El handler en sí debería hacer casi nada. Verifica que la entrega venga de Alchemy, deduplícala, pásale el evento al paso de decisión del agente, y solo entonces confírmala:
();
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. Verifica la firma HMAC antes de confiar en una entrega, porque sin eso cualquiera que descubra la URL del endpoint puede hacer POST de una transferencia falsa y manipular a tu agente. Compara los tokens por dirección de contrato, nunca por símbolo, ya que cualquiera puede desplegar 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 deduplicación no es opcional. El set en memoria funciona para un solo proceso de larga duración; un servicio que se reinicia o corre réplicas necesita el registro en algún lugar compartido y durable, como una clave 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 va en el handler mientras el modelo se mantiene fuera de eso, porque una llamada a un LLM por transferencia cuesta más que la infraestructura que entregó la transferencia.
## ¿Cómo dejas que un agente de IA monitoree eventos de smart contracts y reaccione automáticamente?
Suscríbete a los logs del contrato, filtra a los uno o dos eventos que importan, y haz que el handler sea idempotente. Los eventos de contratos son el trigger más limpio que un agente puede obtener, ya que el contrato indica exactamente qué pasó y en qué orden.
Dos superficies cubren esto en Alchemy. Los [webhooks personalizados](https://www.alchemy.com/docs/reference/custom-webhooks-quickstart) toman un filtro GraphQL, así que puedes hacer match en una dirección de contrato y topics de eventos y recibir únicamente los logs que pediste. Eso conviene a reactores serverless. Para un agente de ejecución prolongada, una suscripción de logs por WebSocket mantiene todo en un solo proceso. Aquí 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:
{
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 de `log.removed` importa más de lo que parece. Las cadenas se reorganizan, y un log sobre el que tu agente ya actuó puede desaparecer de la cadena 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 ese filtro.
## ¿Qué necesitas para construir un agente de rebalanceo de portfolio DeFi?
Cuatro piezas: balances actuales, precios actuales, una regla de drift, y una ruta de swap. El agente lee las primeras dos, revisa la tercera, y solo toca la cuarta cuando la regla se activa.
Toma un agente de tesorería que mantiene una división 50/30/20 de WETH, USDC y WBTC. Los balances vienen de la [Portfolio API](https://www.alchemy.com/docs/reference/portfolio-apis), que devuelve los tokens de una wallet a través de varias redes en una sola solicitud en lugar de un fan-out de llamadas por cadena. Los valores vienen de la [Prices API](https://www.alchemy.com/docs/reference/prices-api-quickstart). 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. Revísala con un timer, porque el drift viene mayormente 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 cual reaccionar. Una transferencia reportada por el watcher (patrón uno) es el trigger complementario que captura depósitos y retiros en el momento en que ocurren.
BAND) {
propose({ symbol, drift }); // propose: log it and request approval; never swap directly
}
}`}
/>
El lado de ejecución no debería sostener una clave privada en crudo. Con una [wallet de agente acotada](https://www.alchemy.com/blog/agent-wallets-alchemy-cli), la clave permanece en custodia y la sesión lleva solo las capacidades que otorgaste. Gastar un ERC-20 necesita 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 lo drene:
Nota la forma del loop. El agente propone, y algo más aprueba. Al principio ese algo eres tú. Más adelante puede ser una verificación de política sobre tamaño, slippage, y lista de activos permitidos. Nuestro [resumen de agentes de IA en DeFi](https://www.alchemy.com/overviews/defi-ai-agents) cubre por qué esa separación es la norma en los agentes DeFi de producción, y el [patrocinio de gas](https://www.alchemy.com/gasless-transactions) elimina la última tarea operativa al pagar las fees bajo una política que tú controlas, así el agente nunca necesita administrar un balance de gas.
## ¿Cuál es la mejor arquitectura para un sistema multi-agente de detect-then-execute?
Divide los agentes por privilegio, no por carga de trabajo. El detector lee todo y no puede firmar nada. El ejecutor firma transacciones y no cree nada que no haya reverificado él mismo.
Piénsalo 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 revisa, y es el único con acceso a la cuenta.
El enfoque popular de este patrón viene de las herramientas de agentes en general, donde un modelo planificador produce pasos y agentes ejecutores corren herramientas. Ese enfoque trata de orquestación. Onchain, la división gana su complejidad por una razón más dura, 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 llevar una inyección de prompt. Si el proceso que lee input hostil es también el proceso que tiene poder de firma, un mensaje envenenado puede convertirse en una transacción firmada. Sepáralos, y lo peor que un detector comprometido puede hacer es generar una mala sugerencia que el ejecutor descarta.
El detector se construye a partir de 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 además funciona como tu log de auditoría. Mantén el contrato de la señal pequeño y verificable:
El ejecutor aplica tres reglas antes de actuar sobre cualquier señal:
- **Reverifica la evidencia onchain.** Lee tú mismo la transacción referenciada en lugar de confiar en el resumen del detector. El trabajo del detector fue notar; probar es trabajo del ejecutor.
- **Aplica el vencimiento.** Actuar sobre una oportunidad vencida es cómo los sistemas detect-then-execute pierden dinero incluso sin un atacante en el loop.
- **Limita el gasto a nivel de wallet.** Un presupuesto por señal y por día vive en la [sesión acotada](https://www.alchemy.com/blog/agent-wallets-alchemy-cli), que puedes revocar desde el dashboard en el momento en que el comportamiento se vea sospechoso.
Del lado de las herramientas, el ejecutor 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 combinarlo con datos indexados (la [Transfers API](https://www.alchemy.com/docs/reference/transfers-api-quickstart) para historial, la Portfolio API para estado) mantiene su gasto de tokens en razonamiento en lugar de en decodificar datos crudos de la cadena. Nuestra [comparación de APIs de blockchain para agentes autónomos](https://www.alchemy.com/overviews/best-blockchain-apis-for-autonomous-onchain-agents) cubre el lado de infraestructura de esa elección.
## ¿Cómo pruebas transacciones de agentes de IA de forma segura antes de pasar a mainnet?
Coloca cuatro puertas entre el agente y el valor real: haz dry-run de cada transacción, limita lo que la clave puede gastar, ensaya el loop completo en una testnet, y mantén una aprobación humana en cualquier cosa que mueva fondos.
- **Haz dry-run primero.** El Alchemy CLI previsualiza cualquier envío sin firmar ni transmitirlo (`alchemy evm send 0xRecipient 0.4 --dry-run`). En código, el `simulateContract` de viem valida una llamada a contrato contra el estado en vivo de mainnet sin enviarla, así el ensayo usa precios reales y profundidad de pool real en lugar de un fixture obsoleto.
- **Limita la clave.** Una wallet de sesión acotada expira según el cronograma que definas y solo puede hacer aquello para lo que la aprobaste, y las [políticas de patrocinio de gas](https://www.alchemy.com/gasless-transactions) agregan listas de permitidos y límites de gasto a nivel de fee. Una clave limitada convierte un bug de peor caso de un drenaje de cuenta en una pérdida acotada.
- **Ensaya en una testnet.** Apunta el mismo código a un endpoint de Sepolia o Base Sepolia y financia al agente desde nuestros [faucets de testnet](https://www.alchemy.com/faucets). El ensayo no vale nada si el código cambia entre el ensayo y producción, así que mantén el nombre de la red en la configuración y no cambies nada más.
- **Bloquea 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 afloja las puertas deliberadamente, un tipo de acción a la vez, a medida que el log de auditoría construye evidencia de que el agente se comporta bien.
Los equipos que hacen esto bien tratan la promoción como una secuencia en lugar de 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.
## Empieza con las piezas que ya existen
Cada patrón de esta página corre sobre infraestructura que puedes usar hoy. El [Alchemy CLI](https://www.alchemy.com/agents) 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](https://www.alchemy.com/docs/alchemy-mcp-server) hospedado expone 168 herramientas a través de RPC, simulación y datos, y el [plugin de Alchemy para Claude Code](https://www.alchemy.com/blog/alchemy-claude-plugin-now-live) instala toda la superficie en un solo comando. Puedes empezar en un tier gratuito sin contratos y sin compromiso mínimo, e incluso un agente puede [registrarse por sí mismo con su propia wallet](https://www.alchemy.com/blog/ai-agents-can-now-sign-up-for-alchemy) y pagar en USDC. Sea cual 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 multi-agente donde un agente detecta oportunidades y otro las ejecuta?
Divide por privilegio: un detector que lee streams de eventos pero no tiene claves, una cola que lleva señales pequeñas y firmadas, y un ejecutor que reverifica cada señal onchain antes de actuar. En Alchemy, el detector corre sobre webhooks o suscripciones WebSocket y el ejecutor 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 rastrean 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 codificación de IA para monitorear actividad de wallets?
El servidor MCP de Alchemy le da a un agente de codificación 168 herramientas que cubren RPC, historial de transacciones y datos de portfolio, y el Alchemy CLI 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 hacia atrás.
### ¿Qué necesito para construir un agente de rebalanceo de portfolio DeFi?
Balances, precios, una regla de drift, y una ruta de swap. La Portfolio API de Alchemy devuelve balances multi-red en una sola llamada, la Prices API los valora, y una verificación de drift (comúnmente una banda de cinco puntos alrededor de los pesos objetivo) decide cuándo actuar. Ejecuta a través de una wallet de agente acotada para que el agente proponga y una política o un humano apruebe.
### ¿Cómo dejo que un agente de IA monitoree eventos de smart contracts y reaccione automáticamente?
Suscríbete a los logs del contrato y pásale al agente los eventos que hacen match. Los webhooks personalizados de Alchemy filtran por dirección de contrato y topics de eventos con GraphQL antes de la entrega, y las suscripciones de logs por WebSocket hacen lo mismo dentro del proceso. Haz el handler idempotente, omite los logs reorganizados, y deja que el modelo razone solo sobre eventos que pasaron el filtro mecánico.
### ¿Cómo pruebo transacciones de agentes de IA de forma segura antes de pasar a mainnet?
Coloca las puertas en capas: previsualiza transacciones con la flag de dry-run del Alchemy CLI, valida llamadas a contratos contra el estado en vivo con simulación basada en `eth_call`, limita la wallet del agente con sesiones acotadas y límites de gasto de política de gas, ensaya en Sepolia o Base Sepolia con fondos de los faucets de Alchemy, y mantén la aprobación humana en cada acción que mueva fondos hasta que el log de auditoría gane puertas más flexibles.