Adaptateurs de Framework

Les adaptateurs sont des sous-chemins d’export sans dépendance qui convertissent les capacités au format d’outil de votre framework (le terme propre à chacun). Lorsqu’un framework requiert l’une de ses propres fabriques, vous l’injectez : aucune peer dependency, aucun couplage de version.

Chargez l’ensemble de capacités une seule fois, convertissez à la frontière avec le modèle et conservez le CapabilitySet d’origine pour le dispatch :

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)

À ne pas confondre avec l’adaptateur chat completions. Injectez la fabrique tool du Agents SDK ; le JSON Schema est transmis comme parameters brut avec 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

Produit des déclarations de fonctions pour le SDK Google GenAI unifié (@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

Transmettez le propre helper jsonSchema de l’AI SDK afin que les paramètres soient correctement enveloppés. Mastra consomme nativement les outils du Vercel AI SDK ; il est donc couvert par cet adaptateur.

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

Injectez la propre fabrique tool de LangChain afin que les objets renvoyés soient de véritables outils LangChain liables ; l’adaptateur reste sans dépendance.

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

Injectez la fabrique tool de LlamaIndex. Il accepte le JSON Schema brut, donc Zod n’est pas nécessaire.

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 produit des outils de function calling embarqués (chacun avec une function liée) pour 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 neutres et autres

toJSONSchemaTools émet des définitions simples { name, description, parameters } : le plus petit dénominateur commun pour tout fournisseur compatible OpenAI ou boucle d’agent personnalisée, avec executeByName pour le dispatch.

Quelques frameworks sont volontairement couverts par les adaptateurs ci-dessus plutôt que par leur propre sous-chemin :

• Mastra consomme nativement les outils du Vercel AI SDK ; utilisez l’adaptateur ai-sdk.
• Claude Agent SDK (@anthropic-ai/claude-agent-sdk) requiert un schéma Zod et un enregistrement MCP en cours. Utilisez l’adaptateur anthropic de l’API Messages.
• CrewAI est un framework Python. Utilisez la sortie JSON Schema neutre comme passerelle en attendant qu’un SDK Python Vinkius existe.

Réserves sur le dispatch

Les helpers de dispatch des adaptateurs appellent capability.execute(args) sans ExecuteOptions : ces exécutions n’emportent ni clé d’idempotence ni signal de l’appelant et ne disposent que d’une tentative de transport. Les noms inconnus transmis aux dispatchers des adaptateurs lèvent une simple Error, et non une VinkiusError. Lorsqu’une opération exige une annulation ou une idempotence, résolvez la Capability et appelez directement execute(). Voir Error handling.