SDK WeChat + TypeScript: Integra Agentes Fácilmente

weixin-agent-sdk es un SDK en TypeScript creado por wong2 el 22 de marzo de 2026 para conectar cualquier agente de IA (Claude, Codex, kimi-cli) a WeChat vía el protocolo iLink Bot API. Exporta tres elementos: la interfaz Agent, login() y start(agent).

TypeScript es un lenguaje de programación de código abierto desarrollado y mantenido por Microsoft, que extiende JavaScript añadiendo tipado estático opcional. Está diseñado para facilitar el desarrollo de aplicaciones a gran escala y se compila a JavaScript estándar.

El boom de los SDK de WeChat iLink para agentes IA

En la tercera semana de marzo 2026, GitHub se llenó de proyectos con un objetivo en común: enchufar un agente de IA a WeChat usando el protocolo iLink Bot API que Tencent liberó a través de @tencent-weixin/openclaw-weixin. No fue una tendencia gradual: en menos de una semana surgieron cuatro implementaciones distintas, en cuatro lenguajes distintos, cada una con su propia arquitectura.

Los números al momento de escribir esto: weixin-agent-sdk tiene 249 stars, weixin-bot tiene 196, wechatbot tiene 74, y weixin-agent-rs fue presentado en el newsletter de ruanyf/weekly. Nada mal para proyectos de menos de dos semanas de vida.

¿Por qué tanto interés de golpe? Porque WeChat tiene más de 1.300 millones de usuarios activos y, hasta ahora, integrarte como bot era un proceso burocrático con cuentas verificadas, revisiones manuales y limitaciones de API. iLink cambió eso: cualquiera puede conectar un agente usando la cuenta personal de WeChat, sin aprobaciones. Eso abrió la canilla.

¿Qué es weixin-agent-sdk y cómo funciona?

La arquitectura del SDK es deliberadamente minimalista. Wong2 la diseñó para que implementar un agente propio sea cosa de pocas líneas. El repositorio tiene tres packages: sdk (el núcleo), agent-acp (el adaptador para el protocolo ACP) y example-openai (un ejemplo funcional con la API de OpenAI).

El flujo de uso es lineal: escaneás el QR con tu cuenta de WeChat usando login(), y después llamás start(agent) para iniciar el loop de mensajes. Desde ese momento, cada mensaje que te llegue en WeChat pasa por tu agente y la respuesta vuelve al chat. El SDK maneja el long polling, la gestión del context_token y la reconexión automática cuando la sesión expira.

Lo que exporta el SDK son exactamente tres cosas. Ni más, ni menos.

La interfaz Agent: request y response simplificados

Implementar la interfaz Agent es todo lo que tenés que hacer. ChatRequest te llega con tres campos: conversationId (para identificar la sesión), text (el mensaje del usuario), y media opcional que puede ser imagen, audio, video o archivo, cada uno con su filePath local y mimeType. Lo explicamos a fondo en comparativa de seguridad y privacidad en GitHub.

Tu agente devuelve un ChatResponse con text (que puede venir en markdown, el SDK lo convierte a texto plano antes de enviarlo) y media opcional para adjuntar imagen, video o archivo usando una URL. El ejemplo de agente echo más simple posible se ve así:

import { Agent, ChatRequest, ChatResponse } from 'weixin-agent-sdk';

const echoAgent: Agent = {
 async chat(request: ChatRequest): Promise<ChatResponse> {
 return { text: request.text };
 }
};

Eso es todo. Si recibe “hola”, devuelve “hola”. Desde ahí podés complejizarlo tanto como quieras.

SDK WeChat agente TypeScript con ACP: Claude, Codex y kimi-cli en WeChat

El package agent-acp es donde se pone interesante. ACP (Agent Client Protocol) es un protocolo abierto para comunicación entre agentes, y weixin-agent-sdk lo implementa para poder lanzar agentes de IA existentes como subprocesos, comunicándose por JSON-RPC sobre stdio.

En la práctica, esto significa que podés hacer:

# Claude Code como agente de WeChat
npx weixin-acp start -- claude-agent-acp

# OpenAI Codex
npx weixin-acp start -- codex-acp

# Kimi CLI
npx weixin-acp start -- kimi acp

No hay que escribir un adaptador por cada agente. Si el agente habla ACP, enchufalo y listo. El SDK lanza el proceso, le manda los mensajes de WeChat formateados en JSON-RPC, y recibe las respuestas. (Spoiler: no todos los agentes de IA implementan ACP todavía, así que verificá antes de asumir que tu favorito está soportado.)

El detalle técnico que importa: la comunicación es síncrona por stdio. El agente vive como subproceso del SDK. Si el agente se cuelga o tarda mucho, el SDK espera. Hay que tener eso en cuenta si pensás desplegar esto en producción.

Comparativa: los 4 SDKs de WeChat iLink que surgieron en marzo 2026

Los cuatro comparten la misma base: login por QR, long polling para recibir mensajes, gestión del context_token y reconexión automática cuando la sesión expira. La diferencia está en lo que ofrecen arriba de esa base. Cubrimos ese tema en detalle en guía sobre herramientas de IA y GPU.

Implementación paso a paso: agente OpenAI en WeChat

El package example-openai es un punto de partida funcional. Soporta conversación multi-turno usando un Map para guardar el historial por conversationId, y acepta entradas de imágenes además de texto.

Los pasos para correrlo:

• Clonar el repositorio e instalar dependencias: pnpm install
• Configurar tu API key de OpenAI en las variables de entorno.
• Escanear el QR: pnpm run login. Abre WeChat en el celular, escaneás y listo.
• Iniciar el agente: pnpm run start. Desde ese momento, los mensajes que te lleguen pasan por OpenAI.

Internamente, la función callMyAI() del ejemplo toma el conversationId, recupera el historial del Map, agrega el mensaje nuevo, llama a la API de OpenAI y guarda la respuesta en el historial antes de devolverla. Multi-turn sin configuración adicional.

Actualizás el modelo en la config, cambiás el system prompt, arranca el agente, le mandás un mensaje desde WeChat, tardás 3 segundos en ver la respuesta y pensás “¿por qué no existía esto antes?”. La verdad es que el SDK hace muy bien lo que promete.

Descubrimientos clave del protocolo iLink Bot API

El proyecto epiral/weixin-bot tiene algo valioso que los otros no tienen: docs/protocol-spec.md, un documento de más de 1.200 líneas donde documentaron lo que descubrieron haciendo ingeniería inversa del protocolo iLink. Datos que no encontrás en ningún manual oficial.

Los hallazgos más importantes:

• context_token obligatorio: si no lo reenviás en cada respuesta, el mensaje simplemente no se entrega. Sin error, sin aviso. El mensaje desaparece.
• message_state GENERATING existe pero no sirve: el cliente de WeChat no renderiza ese estado, así que no hay forma nativa de mostrar que estás generando una respuesta (como el puntito animado de otros chats).
• sendtyping es la única salida: para mostrar “escribiendo…” mientras el agente procesa, hay que usar el comando sendtyping. Es la única forma de dar feedback visual al usuario.
• Sesiones expiran con errcode -14: cuando ves ese código, la sesión caducó y necesitás re-escanear el QR. Los SDKs más maduros (weixin-bot, wechatbot) manejan esto con reconexión automática.

Ojo: estos son hallazgos de la comunidad, no documentación oficial de Tencent. Tomalo con pinzas, porque el protocolo puede cambiar sin aviso.

¿Cuál SDK elegir? Guía según tu stack

Si necesitás ACP (Claude, Codex, kimi-cli)

weixin-agent-sdk. No hay alternativa con soporte ACP nativo. Si tu agente habla ese protocolo, es el camino más corto.

Si preferís Python con feedback visual

weixin-bot es la opción. Tiene el estado “escribiendo” implementado, documentación del protocolo más completa, y funciona en Python y Node. Viene flojo en stars comparado con weixin-agent-sdk, pero la documentación del protocolo que acompaña lo hace muy valioso para entender qué está pasando bajo el capó. Te puede servir nuestra cobertura de comparativa entre Microsoft y GitHub.

Si necesitás algo production-ready en múltiples lenguajes

wechatbot de corespeed tiene el stack más diverso: TypeScript, Python, Go y Rust en el mismo proyecto, con middleware pipeline y storage pluggable. Ideal si tu equipo trabaja en más de un lenguaje o necesitás persistencia de conversaciones con algo más que un Map en memoria. (Sí, otra vez el problema del estado en memoria cuando el proceso se reinicia.)

Si Rust es tu lenguaje y necesitás multi-cuenta

weixin-agent-rs. Presentado en el newsletter de Ruan Yifeng, apunta a casos de uso donde una sola cuenta no alcanza y el rendimiento importa. Está menos documentado que los otros, pero el ecosistema Rust tiene sus ventajas para este tipo de procesos long-running.

Qué está confirmado / Qué no

• Confirmado: weixin-agent-sdk publicado el 22/03/2026 por wong2, licencia MIT, 249 stars. Estructura de tres packages documentada en el README.
• Confirmado: ACP usa JSON-RPC sobre stdio. Los comandos de lanzamiento para Claude, Codex y kimi están en el README del proyecto.
• Confirmado: el protocolo iLink requiere reenviar context_token. Documentado en epiral/weixin-bot protocol-spec.md.
• No confirmado / habría que verificar: la estabilidad del protocolo iLink a largo plazo. Tencent no garantizó públicamente soporte para este tipo de integración con cuentas personales. Todo indica que funciona hoy, pero podría cambiar.
• No confirmado: compatibilidad con todos los agentes que implementan ACP. El SDK dice que soporta el protocolo, pero no hay una lista oficial de agentes verificados más allá de los tres ejemplos del README.

Errores comunes al usar weixin-agent-sdk

No reenviar el context_token. Es el error más silencioso y frustrante: el agente procesa el mensaje, genera la respuesta, la envía… y no llega. Sin error, sin log. El protocolo iLink descarta el mensaje si el token no coincide. Si algo “no llega”, ese es el primer lugar donde mirar.

Guardar el historial de conversación solo en memoria. El ejemplo de OpenAI usa un Map en memoria, que está bien para desarrollo. Pero en producción, si el proceso se reinicia (por un crash, un deploy, o una sesión expirada que forzó reconexión), perdés todo el historial. Cualquiera que haya desplegado un chatbot sin persistencia sabe que los usuarios se irritan cuando el bot “olvida” lo que se habló cinco minutos antes.

Asumir que message_state GENERATING da feedback visual. No lo hace. El cliente de WeChat no renderiza ese estado. Si no implementás sendtyping explícitamente, el usuario ve silencio mientras el agente procesa. En respuestas que tardan 5-10 segundos (que con modelos grandes es normal), eso se siente como un bug.

No manejar el errcode -14. La sesión expira. Siempre. Si tu código no contempla ese error y no tiene lógica de reconexión, el bot simplemente deja de funcionar hasta que alguien lo reinicia a mano. weixin-bot y wechatbot ya manejan esto; si usás weixin-agent-sdk, tenés que implementarlo vos. Ya lo cubrimos antes en guía de gadgets para IA móvil.

Preguntas Frecuentes

¿Qué es weixin-agent-sdk y para qué sirve?

Es un SDK en TypeScript publicado el 22 de marzo de 2026 por el desarrollador wong2 para conectar agentes de IA a WeChat usando el protocolo iLink Bot API. Exporta tres elementos (la interfaz Agent, login() y start()) y maneja todo el protocolo de bajo nivel: long polling, context_token y reconexión. La diferencia con otros SDKs similares es el soporte nativo para ACP, que te permite enchufar Claude, Codex o kimi-cli sin escribir adaptadores.

¿Se puede usar weixin-agent-sdk con Python o solo TypeScript?

El SDK en sí es TypeScript puro. Si tu agente habla ACP, podés conectarlo independientemente del lenguaje en que esté escrito, porque la comunicación es por JSON-RPC sobre stdio. Si necesitás Python nativo sin ACP, weixin-bot es la alternativa directa: tiene implementaciones en Python y Node.

¿Qué diferencia hay entre weixin-agent-sdk y wechatbot de corespeed?

weixin-agent-sdk está optimizado para integraciones ACP (Claude, Codex, kimi) con una API minimalista de tres exports. wechatbot apunta a equipos que necesitan producción con soporte en cuatro lenguajes (TypeScript, Python, Go, Rust), middleware pipeline y storage pluggable. Son herramientas con distintos perfiles: uno es simple y directo, el otro es más completo pero también más complejo de configurar.

¿Qué es el protocolo ACP y cómo se integra con WeChat?

ACP (Agent Client Protocol) es un protocolo abierto de comunicación entre agentes que usa JSON-RPC sobre stdio. weixin-agent-sdk actúa como puente: recibe mensajes de WeChat, los formatea en JSON-RPC y los envía al proceso del agente (Claude, Codex, etc.) como subproceso. El agente responde por el mismo canal y el SDK devuelve la respuesta a WeChat. Para más contexto sobre cómo se implementan agentes con este tipo de protocolos, este tutorial sobre Claude Agent SDK da buena base.

Conclusión

Marzo 2026 fue el mes en que conectar un agente de IA a WeChat pasó de ser un proceso complicado a ser cosa de un QR y tres líneas de código. Cuatro proyectos open-source en menos de una semana, cada uno con su enfoque, todos derivados del mismo protocolo iLink que Tencent liberó con @tencent-weixin/openclaw-weixin.

weixin-agent-sdk se posiciona como la opción más directa si tu agente habla ACP. La interfaz es limpia, el setup es rápido, y el soporte para Claude, Codex y kimi-cli llega sin trabajo extra. Eso sí: es un proyecto de dos semanas, el protocolo de Tencent no tiene garantías oficiales para este tipo de integración, y hay detalles de producción (persistencia, manejo de errcode -14, feedback visual) que tenés que resolver vos.

Si estás evaluando desplegarlo en algún entorno cloud o servidor propio, donweb.com tiene opciones de VPS donde este tipo de proceso Node/TypeScript long-running corre sin dramas. Lo que no rinde es correr esto en un hosting compartido con procesos con timeout. ¿Alguien lo probó así? Bueno, nosotros sí, y el resultado fue el esperado.

La conclusión práctica: si necesitás ACP, usá weixin-agent-sdk. Si necesitás Python, usá weixin-bot. Si necesitás producción multi-lenguaje, mirá wechatbot. Y si alguno de los cuatro deja de funcionar porque Tencent cambió el protocolo, no digas que no te avisé.

Fuentes

• wong2/weixin-agent-sdk — Repositorio oficial del SDK en GitHub
• epiral/weixin-bot — SDK con documentación del protocolo iLink (1200+ líneas)
• corespeed-io/wechatbot — Implementación multi-lenguaje con middleware pipeline
• ruanyf/weekly issue #9343 — Presentación de weixin-agent-rs
• WebReactiva — Tutorial Claude Agent SDK