Vinkius AI Connect

Vinkius Connect (@vinkius/connect) transforma a aplicação de IA que você está construindo em uma plataforma de conectividade para os seus próprios usuários. Uma única API de backend: cada um dos seus usuários tem os próprios conectores, as próprias credenciais e as próprias capacidades de IA, e seus agentes os chamam a partir de qualquer runtime de modelo. A Vinkius cuida da conectividade, da autenticação, das permissões, dos protocolos e da execução por trás dessas capacidades. Sua aplicação identifica o usuário. Essa divisão de trabalho é o produto.

Construído para quem está publicando produtos de IA

Você está construindo um copiloto, uma plataforma de agentes, um assistente vertical. Seus usuários precisam que a sua IA aja no mundo real: abrir a issue, enviar a mensagem, consultar o banco de dados, registrar o ticket. Sem uma camada de conectividade, isso significa construir cada integração você mesmo: fluxos de OAuth por provedor, armazenamento criptografado de tokens, tratamento de protocolos, mudanças constantes de APIs, revisões de segurança. Meses de infraestrutura antes do seu produto fazer algo real, e uma superfície de ataque que fica sob sua responsabilidade pela vida da empresa.

Esse trabalho é a taxa de integração. A Vinkius Connect a elimina: os conectores já vêm prontos e são mantidos, as credenciais são tratadas com isolamento por usuário, e as capacidades que o seu agente chama chegam por uma única API de backend. Você compete com o seu produto. A infraestrutura já está pronta.

As três decisões abaixo são o que torna isso possível, e são elas que mantêm a plataforma invisível para os seus usuários enquanto a sua empresa fica com o cliente.

Uma conta. Muitos usuários. Zero exposição.

Crie uma Application no painel da Vinkius Cloud. Por baixo dela, seu backend provisiona quantos usuários o seu produto precisar, e cada um deles é endereçado pelo seu próprio external_id: alice_123, uma chave de banco de dados, um hash opaco. O que quer que o seu sistema de autenticação já use.

Esse design traz uma consequência que a maioria das plataformas de integração não oferece:

• Isolamento por usuário. Cada usuário conecta os próprios conectores e armazena as próprias credenciais. Dois usuários podem conectar a mesma integração do GitHub mantendo estado de conexão, credenciais e capacidades completamente separados. Nada cruza a fronteira.
• Os usuários reais nunca são expostos à Vinkius. O SDK não exige e-mail, nome nem perfil. A Vinkius conhece apenas o identificador opaco que o seu backend repassa e os metadados não secretos que você escolher anexar. O seu relacionamento com o cliente, a sua base de usuários e os dados do seu produto ficam do seu lado: a Vinkius é infraestrutura invisível sob o seu produto, não mais uma plataforma entre você e os seus usuários.
• As credenciais permanecem somente para escrita. O seu backend define as credenciais de conector de um usuário e pode verificar quais campos estão configurados, mas ninguém (nem o seu código, nem o modelo, nem o dashboard) as lê de volta.

Para as garantias de segurança por trás disso, consulte Security; para as regras de escopo de rota, consulte Authentication and scope.

Milhares de conectores desde o primeiro dia

Qualquer pessoa que esteja construindo algo com IA pode implementar a Vinkius e ter o catálogo desde o primeiro dia: GitHub, Slack, Notion, bancos de dados, APIs internas e mais, já mantidos e crescendo todos os dias. Você não constrói integrações, não armazena tokens, não lida com a burocracia do OAuth. Seus usuários conectam uma conta uma única vez, dentro do seu produto, e cada turno do agente simplesmente funciona a partir do primeiro dia do seu lançamento.

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, conexão e capacidade

vinkius.user('alice_123') e .connector('github') são handles. Criá-los não executa nenhuma requisição. Operações como connect(), credentials.set(), capabilities() e execute() atravessam a rede.

Dois planos sobre uma única credencial

O SDK é dividido em dois planos sobre a mesma credencial vk_app_sk_*:

• Plano de controle, provisionamento e estado: users, connectors, credentials, catalog.
• Plano de execução, runtime: capabilities() e execute().

user.capabilities() é o contrato principal: ele retorna as capacidades de IA disponíveis para aquele usuário, como objetos executáveis e independentes de framework. Um conector não é uma capacidade. Um único conector pode fornecer muitas 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

O escopo do usuário faz parte da rota

Toda operação de usuário é endereçada tanto pelas credenciais da aplicação quanto pelo externalId passado pelo backend. Dois usuários podem conectar o mesmo conector e ainda manter estados de conexão e credenciais separados.

Não aceite externalId como uma entrada irrestrita do cliente. Resolva-o a partir da sessão ou verifique se o chamador está autorizado a agir em nome dele antes de criar o handle. Consulte Authentication and scope.

Capacidades são a fronteira de execução

Uma Capability contém um nome de exibição com namespace para consulta voltada ao modelo, um nome bruto da ação do conector usado na execução, uma descrição e um contrato de entrada em JSON Schema, o conector e o ID da conexão necessários para rotear a requisição, e execute(args, { signal, idempotencyKey }):

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

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

Um CapabilitySet vazio é um resultado normal. Trate a disponibilidade das capacidades como dados de runtime, em vez de pressupor que todos os usuários têm as mesmas ferramentas.

Os adapters permanecem na fronteira com o modelo

As capacidades principais não dependem de um provedor de modelos. Os subpaths dos adapters mapeiam seus nomes, descrições e schemas para formatos estruturais de provedores ou frameworks: OpenAI, Anthropic, Gemini, Vercel AI SDK, LangChain, LlamaIndex, Cloudflare Workers AI e qualquer runtime compatível com OpenAI. O pacote do adapter não tem dependência de runtime desses frameworks externos, portanto sua aplicação continua responsável por escolher e testar uma versão compatível do framework. Consulte Framework adapters.

Comece agora

• npm: npmjs.com/package/@vinkius/connect
• GitHub: github.com/vinkius-labs/ai-connect-sdk, com exemplos executáveis no diretório examples do repositório
• Issues: github.com/vinkius-labs/ai-connect-sdk/issues

Próximos passos

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