Adaptadores de Framework

Los adaptadores son subpath exports sin dependencias que convierten capacidades al formato de herramienta de tu framework (el término propio de cada framework). Cuando un framework necesita una de sus propias fábricas, tú la inyectas: sin peer dependencies, sin acoplamiento de versiones.

Cargue el conjunto de capacidades una vez, convierta en el límite con el modelo y conserve el CapabilitySet original para el despacho:

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

OpenAI (chat completions)

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)

Es distinto del adaptador de chat completions. Inyecta la fábrica tool del Agents SDK; el JSON Schema se pasa como parameters en bruto con strict: false.

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)

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

Produce declaraciones de funciones para el SDK unificado de Google GenAI (@google/genai).

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

Pasa el propio helper jsonSchema del AI SDK para que los parámetros se ajusten correctamente. Mastra consume herramientas del Vercel AI SDK de forma nativa, por lo que queda cubierto por este adaptador.

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

Inyecta la propia fábrica tool de LangChain para que los objetos devueltos sean herramientas LangChain genuinas y enlazables; el adaptador mantiene cero dependencias.

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

Inyecta la fábrica tool de LlamaIndex. Acepta JSON Schema en bruto, por lo que no se requiere Zod.

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 produce herramientas de function calling incrustadas (cada una con una function vinculada) para runWithTools de @cloudflare/ai-utils.

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 y otros

toJSONSchemaTools emite definiciones simples { name, description, parameters }: el común denominador mínimo para cualquier proveedor compatible con OpenAI o bucle de agente personalizado, con executeByName para el despacho.

Algunos frameworks están cubiertos intencionalmente por los adaptadores anteriores en lugar de tener su propio subpath:

• Mastra consume herramientas del Vercel AI SDK de forma nativa; usa el adaptador ai-sdk.
• Claude Agent SDK (@anthropic-ai/claude-agent-sdk) requiere un esquema Zod y registro de MCP en proceso. Usa el adaptador anthropic de la API de Messages.
• CrewAI es un framework de Python. Usa la salida neutra de JSON Schema como puente hasta que exista un SDK de Python de Vinkius.

Advertencias de despacho

Los helpers de despacho de los adaptadores llaman a capability.execute(args) sin ExecuteOptions: esas ejecuciones no llevan una clave de idempotencia ni la señal del llamador y reciben un único intento de transporte. Los nombres desconocidos pasados a los dispatchers de los adaptadores lanzan un Error simple, no un VinkiusError. Cuando una operación requiera cancelación o idempotencia, resuelve la Capability y llama directamente a execute(). Consulta Error handling.