AI Connect/How to create/Cómo crear
Cómo crear
Cinco construcciones de extremo a extremo que ninguna otra plataforma ofrece: un chatbot de consumo, copilotos departamentales, una flota de agentes, automatizaciones desatendidas y un SaaS multi-tenant. Cada una parte de una sola Application key y convierte a un tipo distinto de actor en un usuario aislado, con sus propios conectores, credenciales y capacidades.
La Guía de inicio le mostró una llamada. Lea esta línea despacio, porque es todo el futuro en una sola frase: con una única Application key, cada usuario de su producto obtiene miles de conexiones de IA desde el primer día, cada usuario aislado con sus propios conectores, credenciales y capacidades, y ninguno de ellos expuesto jamás a Vinkius. Ninguna plataforma del mercado ofrece esa frase. Las cinco construcciones completas de esta sección muestran cómo se ve en producción: un chatbot de consumo, copilotos departamentales, una flota de agentes, automatizaciones desatendidas y un SaaS multi-tenant, cada una escrita para que un desarrollador empiece por lo más alto y termine con una IA funcional que actúa en el mundo real.
El primitivo debajo de las cinco es el que el resto de la industria no ofrece: cualquier entidad que necesite actuar se convierte en un usuario. Los análisis de costes de la industria estiman en seis cifras, a lo largo de tres años, una versión propia de esa arquitectura, y aun así nunca termina de entregarse. En el AI Connect SDK es la línea de salida, no la línea de meta.
La idea que lo destraba todo
En todos los tutoriales aparece la misma línea:
const user = vinkius.user(externalId);Ese externalId es un valor que tú defines. No es una cuenta de Vinkius, no es un correo electrónico, no es un ser humano. Es una cadena opaca y segura para URL que tu backend ya controla, y el SDK la trata como la frontera que aísla conectores, credenciales y capacidades. Como es opaca, puede nombrar cualquier cosa que necesite actuar:
Tu externalId nombra… | Es… | Por qué importa |
|---|---|---|
alice_123 | un usuario final humano | cada cliente trae su propio GitHub, Slack, Gmail |
dept-finance | un departamento | el copilot de finanzas actúa sobre las cuentas propias de finanzas |
triage-agent | un agente de IA autónomo | cada agente obtiene sus propios conectores y límite de gasto |
svc-nightly-sync | una cuenta de servicio | un cron conecta la base de datos sin intervención humana |
cus_acme_u_9f2 | un usuario dentro de tu cliente | todo tu SaaS entrega conectores, aislados por inquilino |
Un "usuario" en el AI Connect SDK es cualquier entidad que deba poseer un conjunto aislado de conexiones y capacidades. No tiene por qué ser una persona. Este único cambio de perspectiva es la razón por la que el SDK escala de un chatbot de fin de semana a una flota de agentes y a una plataforma corporativa white-label sin cambiar una sola llamada.
Piense en lo radical que es eso. Toda plataforma de conectividad que la industria ha entregado hasta hoy conecta una aplicación con un servicio. Ninguna le entrega a tu producto su propio modelo de usuarios por entidad, con credenciales que tu código jamás puede leer de vuelta. La línea de arriba sí, y esa es la diferencia entre alquilar conectividad para tu app y poseer una plataforma de conectividad para tus usuarios.
Elige tu construcción
| Construcción | Quién es el "usuario" | Qué entregas |
|---|---|---|
| Chatbot de consumo multiusuario | un humano por cuenta | un asistente de producto donde la IA de cada usuario ve sus propias herramientas |
| Copilotes departamentales para una empresa de logística | un departamento | asistentes internos, uno por equipo, con una sola clave de app |
| Una flota de agentes de IA, cada uno su propio usuario | un agente autónomo | un enjambre donde cada agente tiene conectores delimitados y medición propia |
| Automatizaciones desatendidas y cuentas de servicio | un proceso, no una persona | jobs programados, webhooks y CI que conectan sistemas sin navegador |
| Un SaaS de IA multi-tenant | un usuario dentro de tu cliente | IA white-label para cada cliente de tu plataforma |
El flujo que comparten todas las construcciones
Sea cual sea la entidad que modelen, el bucle de ejecución es idéntico. Apréndelo una vez y podrás construir las cinco de memoria:
- Crea un cliente en tu servidor a partir de una sola Application key.
- Identifica al actor: entrega a
vinkius.user(externalId)el id que es dueño de la acción. - Conecta un conector:
user.connector('github').connect(), almacena credenciales una vez, nunca las leas de vuelta. - Descubre capacidades:
user.capabilities()devuelve solo lo que este actor tiene listo. - Entrégalas a un modelo: un adaptador convierte el conjunto a OpenAI, Anthropic, Gemini, Vercel AI SDK, LangChain o JSON Schema a secas.
- Ejecuta y retroalimenta: ejecuta la llamada a tool del modelo;
isErrorpermite al agente recuperarse en lugar de fallar.
Empieza por la construcción más cercana a lo que ya tienes. Si operas un bot de soporte, comienza con el chatbot. Si eres un equipo de plataforma interna, comienza con los copilotes departamentales. Si estás lanzando el próximo producto nativo de IA, comienza con el SaaS multi-tenant. Cada página termina con una lista de verificación de producción para que puedas publicar, no solo prototipar.
La barrera protectora, bajo el capó
Todas las construcciones de abajo se apoyan en la misma arquitectura, y entenderla es lo que hace creíble la promesa de que "no eres dueño de la infraestructura de integración", en lugar de simples palabras de marketing.
- Dos planos, un secreto. Un plano de control (
users,connectors,credentials,catalog) sobre REST, y un plano de ejecución (listar y ejecutar capacidades) que habla JSON-RPC directamente con el runtime de cada conexión. Todo se alcanza con una sola clavevk_app_sk_*; el runtime habla el protocolo MCP internamente, pero eso nunca aparece en tu vocabulario. - Medición y revocación por conexión. Cada conexión posee su propio token de datos
vk_live_*. El gasto y la revocación inmediata operan por conexión, y por eso un departamento, un agente o una cuenta de servicio pueden aislarse de forma financiera y operativa, no solo lógica. - Credenciales de solo escritura. Tu servidor almacena los secretos de conector de un usuario y puede ver qué campos están configurados, pero nada, ni tu código, ni el modelo, ni el panel, lee nunca los valores de vuelta.
- Redacción por defecto. Los
hooksde observabilidad reciben datos ya depurados:Authorization, campos con forma de credencial y segmentos de URLvk_live_*se enmascaran antes de que se ejecute tu callback. - Cero dependencias de runtime, en todas partes.
fetchnativo, doble ESM/CJS, tipado, funciona en Node 18+, Bun, Deno y el edge, por lo que el mismo objetivo de compilación cubre un contenedor cron y un Worker. - Reintento e idempotencia bien pensados. Los fallos transitorios se reintentan automáticamente con backoff de jitter completo, y declarar una
idempotencyKeyes lo que hace seguro reintentar incluso una escritura no idempotente.
Nada de lo anterior es una función que configuras por construcción, todo se hereda por cada external_id que creas. Esa herencia es la barrera: el aislamiento, la medición y las garantías de seguridad se aplican automáticamente, por igual, a humanos, departamentos, agentes, procesos e inquilinos.
Antes de empezar
Todas las construcciones asumen los mismos tres prerequisitos, tratados a fondo en Instalación y Autenticación y alcance:
- Node.js 18+ o cualquier runtime de servidor con
fetch(Bun, Deno, edge, Cloudflare Workers) @vinkius/connectinstalado- Un App ID de Vinkius (
vk_app_…) y una Application Key (vk_app_sk_…) en variables de entorno del servidor
Cada fragmento de esta sección se ejecuta en tu servidor. La Application Key y las credenciales de conector de tus usuarios nunca deben aparecer en un bundle de navegador, en un binario móvil o en un prompt de modelo. Publica una ruta de backend delgada delante del SDK; el navegador habla con tu ruta, tu ruta habla con Vinkius.
¿Listo? Ninguna otra plataforma del mercado puede alojar esta sección, porque ninguna ofrece su premisa: que un usuario es cualquier entidad que necesita actuar. Elige una construcción y termínala, con una IA que actúa para cada usuario que definas.
What you just got
Not a pitch: the properties this build inherits automatically.
Connections and capabilities resolve only inside one external_id. No cross-actor leakage is possible, and you wrote none of that enforcement.
Your server stores secrets and can read back which fields are configured, never the values. Not your code, the model, or a dashboard can exfiltrate them.
Every connection owns a vk_live_* token, so cost and revocation are per connection. One call to disconnect() is a complete, auditable stop.
One CapabilitySet converts to OpenAI, Anthropic, Gemini, Vercel AI SDK, LangChain, LlamaIndex, Workers AI or neutral JSON Schema. Only the last line changes.
idempotencyKey, timeoutMs and AbortSignal per call; automatic full-jitter retries on transient failures; typed VinkiusError branches. No bespoke harness.
Give it to your AI agent
An Agent Skill (SKILL.md) for this build. Preview the first lines below, then copy or download it into your repo under .claude/skills/: Claude Code, Cursor or any Agent-Skills-compatible agent follows it to implement this pattern correctly.