Vinkius AI Connect

Vinkius Connect (@vinkius/connect) convierte la aplicación de IA que estás construyendo en una plataforma de conectividad para tus propios usuarios. Una única API de backend: cada uno de tus usuarios tiene sus propios conectores, sus propias credenciales y sus propias capacidades de IA, y tus agentes los invocan desde cualquier runtime de modelos. Vinkius gestiona la conectividad, la autenticación, los permisos, los protocolos y la ejecución detrás de esas capacidades. Tu aplicación identifica al usuario. Esa división del trabajo es el producto.

Construido para los que lanzan productos de IA

Estás construyendo un copiloto, una plataforma de agentes, un asistente vertical. Tus usuarios necesitan que tu IA actúe en el mundo real: abrir el issue, enviar el mensaje, consultar la base de datos, crear el ticket. Sin una capa de conectividad, eso significa construir cada integración tú mismo: flujos de OAuth por proveedor, almacenamiento cifrado de tokens, manejo de protocolos, cambios constantes de APIs, revisiones de seguridad. Meses de fontanería antes de que tu producto haga algo real, y una superficie de ataque que seguirá siendo tuya durante toda la vida de la empresa.

Ese trabajo es el impuesto de integración. Vinkius Connect lo elimina: los conectores ya están construidos y se mantienen por ti, las credenciales se gestionan con aislamiento por usuario, y las capacidades que tu agente invoca llegan a través de una única API de backend. Compite en tu producto. La fontanería ya está hecha.

Las tres decisiones que aparecen a continuación son las que hacen esto posible, y son la razón por la que la plataforma sigue siendo invisible para tus usuarios mientras tu negocio se queda con el cliente.

Una cuenta. Muchos usuarios. Cero exposición.

Crea una Application en el panel de Vinkius Cloud. Bajo ella, tu backend aprovisiona tantos usuarios como tu producto necesite, y cada uno se direcciona con tu propio external_id: alice_123, una clave de base de datos, un hash opaco. Lo que tu sistema de autenticación ya use.

Ese diseño conlleva una consecuencia que la mayoría de las plataformas de integración no ofrece:

• Aislamiento por usuario. Cada usuario conecta sus propios conectores y almacena sus propias credenciales. Dos usuarios pueden conectar la misma integración de GitHub manteniendo un estado de conexión, credenciales y capacidades completamente separados. Nada cruza el límite.
• Tus usuarios reales nunca se exponen a Vinkius. El SDK no requiere correo electrónico, nombre ni perfil. Vinkius solo conoce el identificador opaco que pasa tu backend y los metadatos no secretos que decidas adjuntar. Tu relación con el cliente, tu base de usuarios y los datos de tu producto permanecen de tu lado: Vinkius es infraestructura invisible bajo tu producto, no otra plataforma interpuesta entre tú y tus usuarios.
• Las credenciales son de solo escritura. Tu backend define las credenciales de conector de un usuario y puede comprobar qué campos están configurados, pero nadie (ni tu código, ni el modelo, ni el dashboard) las vuelve a leer.

Para conocer las garantías de seguridad detrás de esto, consulta Security; para las reglas de alcance de ruta, consulta Authentication and scope.

Miles de conectores desde el primer día

Cualquier persona que construya algo con IA puede implementar Vinkius y tener el catálogo desde el primer día: GitHub, Slack, Notion, bases de datos, APIs internas y más, ya mantenidos y creciendo cada día. No construyes integraciones, no almacenas tokens, no tocas la fontanería de OAuth. Tus usuarios conectan una cuenta una sola vez, dentro de tu producto, y cada turno del agente simplemente funciona desde el primer día del lanzamiento.

import { Vinkius } from '@vinkius/connect';

const vinkius = new Vinkius({
  appId: process.env.VINKIUS_APP_ID!,
  apiKey: process.env.VINKIUS_APP_KEY!,
});

async function configureAndListActions(
  externalId: string,
  credentials: Record<string, string>,
) {
  const user = vinkius.user(externalId);
  const connector = user.connector('github');

  const schema = await connector.credentials.schema();
  await connector.connect();
  const credentialState = await connector.credentials.set(credentials);
  const capabilities = await user.capabilities({ include: ['github'] });

  return {
    schema,
    configured: credentialState.configured,
    actions: capabilities.map(({ name, description }) => ({ name, description })),
  };
}

Conector, conexión y capacidad

vinkius.user('alice_123') y .connector('github') son identificadores. Crearlos no realiza ninguna solicitud. Las operaciones como connect(), credentials.set(), capabilities() y execute() atraviesan la red.

Dos planos sobre una sola credencial

El SDK se divide en dos planos sobre la misma credencial vk_app_sk_*:

• Plano de control, aprovisionamiento y estado: users, connectors, credentials, catalog.
• Plano de ejecución, runtime: capabilities() y execute().

user.capabilities() es el contrato principal: devuelve las capacidades de IA disponibles para ese usuario, como objetos ejecutables e independientes del framework. Un conector no es una capacidad. Un único conector puede proporcionar muchas capacidades:

GitHub connector
       │
       ├── list repositories
       ├── create issue
       ├── create pull request
       ├── review code
       └── search code

const capabilities = await vinkius.user('alice_123').capabilities();
// the capabilities available to this user

El alcance de usuario forma parte de la ruta

Cada operación de usuario se dirige mediante las credenciales de tu aplicación y el externalId que proporciona tu backend. Dos usuarios pueden conectar el mismo conector y mantener separados el estado y las credenciales de sus conexiones.

No aceptes externalId como una entrada de cliente sin restricciones. Resuélvelo a partir de la sesión o comprueba que el llamador esté autorizado a actuar en su nombre antes de crear el identificador. Consulta Authentication and scope.

Las capacidades son el límite de ejecución

Una Capability contiene un nombre visible con espacio de nombres para buscarla desde un modelo, un nombre de acción sin procesar del conector que se usa para la ejecución, una descripción y un contrato de entrada JSON Schema, el conector y el ID de conexión necesarios para dirigir la solicitud, y execute(args, { signal, idempotencyKey }):

const capabilities = await vinkius.user('alice_123').capabilities();

for (const capability of capabilities) {
  console.log(capability.name, capability.inputSchema);
}

Un CapabilitySet vacío es un resultado normal. Trata la disponibilidad de capacidades como datos en tiempo de ejecución, en lugar de suponer que todos los usuarios disponen de las mismas herramientas.

Los adaptadores permanecen en el límite con el modelo

Las capacidades principales no dependen de un proveedor de modelos. Las rutas secundarias de los adaptadores asignan sus nombres, descripciones y esquemas a estructuras de proveedores o frameworks: OpenAI, Anthropic, Gemini, Vercel AI SDK, LangChain, LlamaIndex, Cloudflare Workers AI y cualquier runtime compatible con OpenAI. El paquete del adaptador no tiene dependencias en tiempo de ejecución de esos frameworks externos, por lo que tu aplicación sigue siendo responsable de elegir y probar una versión compatible del framework. Consulta Framework adapters.

Comienza ahora

• npm: npmjs.com/package/@vinkius/connect
• GitHub: github.com/vinkius-labs/ai-connect-sdk, con ejemplos ejecutables en el directorio examples del repositorio
• Issues: github.com/vinkius-labs/ai-connect-sdk/issues

Próximos pasos

• Install and configure the client
• Run the connect-to-execute quickstart
• Discover what the platform does behind every call