AI Connect/Integration/Adaptadores de Framework

Adaptadores de Framework

Pergunte à IA sobre a Vinkius

Subpath exports sem dependências que convertem capacidades com escopo de usuário no formato de ferramentas de OpenAI, Anthropic, Gemini, Vercel AI SDK, LangChain, LlamaIndex, Cloudflare Workers AI ou qualquer runtime compatível com OpenAI.

Adapters são subpath exports sem dependências que convertem capacidades no formato de ferramenta do seu framework (o termo próprio de cada framework). Quando um framework precisa de uma de suas próprias fábricas, você a injeta: sem peer dependency, sem acoplamento de versões.

Carregue o conjunto de capacidades uma vez, converta na fronteira com o modelo e mantenha o CapabilitySet original para o despacho:

typescript

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

Framework	Import	Observações
OpenAI (chat completions)	`@vinkius/connect/openai`	`toOpenAITools`, `runOpenAIToolCall`
OpenAI Agents (`@openai/agents`)	`@vinkius/connect/openai-agents`	`toOpenAIAgentsTools` (injete `tool`)
Anthropic (Messages)	`@vinkius/connect/anthropic`	`toAnthropicTools`, `runAnthropicToolUse`
Google Gemini	`@vinkius/connect/gemini`	`toGeminiTools`, `runGeminiFunctionCall`
Vercel AI SDK	`@vinkius/connect/ai-sdk`	`toAISDKTools` (injete `jsonSchema`)
LangChain.js	`@vinkius/connect/langchain`	`toLangChainTools` (injete `tool`)
LlamaIndex.TS	`@vinkius/connect/llamaindex`	`toLlamaIndexTools` (injete `tool`)
Cloudflare Workers AI	`@vinkius/connect/workers-ai`	`toWorkersAITools` (para `runWithTools`)
Qualquer um / neutro	`@vinkius/connect/json-schema`	`toJSONSchemaTools`, `executeByName`

OpenAI (chat completions)

typescript

import OpenAI from 'openai';
import { toOpenAITools, runOpenAIToolCall } from '@vinkius/connect/openai';

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

const completion = await openai.chat.completions.create({
  model: 'your-model',
  messages: [{ role: 'user', content: 'Open a GitHub issue titled "Ship it"' }],
  tools: toOpenAITools(capabilities),
});

const call = completion.choices[0]?.message.tool_calls?.[0];
if (call) {
  const result = await runOpenAIToolCall(capabilities, call);
  console.log(result.content);
}

OpenAI Agents (@openai/agents)

Distinto do adapter de chat completions. Injete a fábrica tool do Agents SDK; o JSON Schema é passado como parameters bruto com strict: false.

typescript

import { Agent, tool } from '@openai/agents';
import { toOpenAIAgentsTools } from '@vinkius/connect/openai-agents';

const capabilities = await vinkius.user('alice_123').capabilities();
const agent = new Agent({
  name: 'assistant',
  tools: toOpenAIAgentsTools(capabilities, { tool }),
});

Anthropic (Messages)

typescript

import { toAnthropicTools, runAnthropicToolUse } from '@vinkius/connect/anthropic';

const capabilities = await vinkius.user('alice_123').capabilities();
const tools = toAnthropicTools(capabilities); // pass as `tools` to messages.create
// on a returned tool_use block: await runAnthropicToolUse(capabilities, block)

Google Gemini

Produz declarações de funções para o SDK unificado do Google GenAI (@google/genai).

typescript

import { toGeminiTools, runGeminiFunctionCall } from '@vinkius/connect/gemini';

const capabilities = await vinkius.user('alice_123').capabilities();
const response = await model.generateContent({
  contents,
  tools: [{ functionDeclarations: toGeminiTools(capabilities) }],
});

// on a returned functionCall part:
const result = await runGeminiFunctionCall(capabilities, functionCall);

Vercel AI SDK

Passe o próprio helper jsonSchema do AI SDK para que os parâmetros sejam encapsulados corretamente. O Mastra consome ferramentas do Vercel AI SDK nativamente, portanto é coberto por este adapter.

typescript

import { jsonSchema } from 'ai';
import { toAISDKTools } from '@vinkius/connect/ai-sdk';

const capabilities = await vinkius.user('alice_123').capabilities();
const tools = toAISDKTools(capabilities, { jsonSchema });

LangChain.js

Injete a própria fábrica tool do LangChain para que os objetos retornados sejam ferramentas LangChain genuínas e vinculáveis; o adapter permanece sem dependências.

typescript

import { tool } from '@langchain/core/tools';
import { toLangChainTools } from '@vinkius/connect/langchain';

const capabilities = await vinkius.user('alice_123').capabilities();
const tools = toLangChainTools(capabilities, { tool });
const model = chat.bindTools(tools);

LlamaIndex.TS

Injete a fábrica tool do LlamaIndex. Ele aceita JSON Schema bruto, portanto não é necessário Zod.

typescript

import { tool } from 'llamaindex';
import { toLlamaIndexTools } from '@vinkius/connect/llamaindex';

const capabilities = await vinkius.user('alice_123').capabilities();
const tools = toLlamaIndexTools(capabilities, { tool });

Cloudflare Workers AI

toWorkersAITools produz ferramentas de function calling incorporadas (cada uma com uma function vinculada) para o runWithTools do @cloudflare/ai-utils.

typescript

import { runWithTools } from '@cloudflare/ai-utils';
import { toWorkersAITools } from '@vinkius/connect/workers-ai';

const capabilities = await vinkius.user('alice_123').capabilities();
const res = await runWithTools(env.AI, 'your-model', {
  messages,
  tools: toWorkersAITools(capabilities),
});

Frameworks neutros e outros

toJSONSchemaTools emite definições simples { name, description, parameters }: o menor denominador comum para qualquer provedor compatível com OpenAI ou loop de agente personalizado, com executeByName para o despacho.

Alguns frameworks são intencionalmente cobertos pelos adapters acima em vez de terem seu próprio subpath:

Mastra consome ferramentas do Vercel AI SDK nativamente; use o adapter ai-sdk.
Claude Agent SDK (@anthropic-ai/claude-agent-sdk) exige um schema Zod e registro de MCP em processo. Use o adapter anthropic da Messages API.
CrewAI é um framework Python. Use a saída neutra de JSON Schema como ponte até que exista um SDK Python da Vinkius.

Ressalvas de despacho

Os helpers de despacho dos adapters chamam capability.execute(args) sem ExecuteOptions: essas execuções não carregam uma chave de idempotência nem o sinal do chamador e recebem uma tentativa de transporte. Nomes desconhecidos passados aos dispatchers dos adapters lançam um Error simples, não um VinkiusError. Quando uma operação exigir cancelamento ou idempotência, resolva a Capability e chame execute() diretamente. Veja Error handling.