AI Connect/Integration/フレームワークアダプタ

フレームワークアダプタ

VinkiusについてAIに質問

依存関係のない subpath export で、ユーザースコープの capability を OpenAI、Anthropic、Gemini、Vercel AI SDK、LangChain、LlamaIndex、Cloudflare Workers AI、または任意の OpenAI 互換ランタイムのツール形式に変換します。

アダプターは依存関係のない subpath export で、capability を各フレームワークのツール形式（各フレームワーク固有の用語）に変換します。フレームワークが独自のファクトリーを必要とする場合は、それを注入します。peer dependency もバージョンの結合もありません。

capability セットを一度読み込み、モデル境界で変換し、ディスパッチには元の CapabilitySet を使用してください：

typescript

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

フレームワーク	インポート	備考
OpenAI (chat completions)	`@vinkius/connect/openai`	`toOpenAITools`、`runOpenAIToolCall`
OpenAI Agents (`@openai/agents`)	`@vinkius/connect/openai-agents`	`toOpenAIAgentsTools`（`tool` を注入）
Anthropic (Messages)	`@vinkius/connect/anthropic`	`toAnthropicTools`、`runAnthropicToolUse`
Google Gemini	`@vinkius/connect/gemini`	`toGeminiTools`、`runGeminiFunctionCall`
Vercel AI SDK	`@vinkius/connect/ai-sdk`	`toAISDKTools`（`jsonSchema` を注入）
LangChain.js	`@vinkius/connect/langchain`	`toLangChainTools`（`tool` を注入）
LlamaIndex.TS	`@vinkius/connect/llamaindex`	`toLlamaIndexTools`（`tool` を注入）
Cloudflare Workers AI	`@vinkius/connect/workers-ai`	`toWorkersAITools`（`runWithTools` 用）
汎用 / ニュートラル	`@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)

chat completions 用アダプターとは別物です。Agents SDK の tool ファクトリーを注入してください。JSON Schema は strict: false 付きの生の parameters として渡されます。

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

統合された Google GenAI SDK（@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

パラメーターが正しくラップされるよう、AI SDK 自前の jsonSchema ヘルパーを渡してください。Mastra は Vercel AI SDK のツールをネイティブに利用するため、このアダプターでカバーされます。

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

LangChain 独自の tool ファクトリーを注入してください。そうすることで、返されるオブジェクトはバインド可能な本物の LangChain ツールになります。アダプターは依存関係ゼロを保ちます。

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

LlamaIndex の tool ファクトリーを注入します。生の JSON Schema を受け付けるため、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 は、@cloudflare/ai-utils の runWithTools 向けに、バインド済みの function を持つ組み込み function calling ツールを生成します。

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),
});

ニュートラルおよびその他のフレームワーク

toJSONSchemaTools はプレーンな { name, description, parameters } 定義を生成します。これは OpenAI 互換プロバイダーやカスタムエージェントループに共通する最小限の形式で、executeByName によるディスパッチが可能です。

一部のフレームワークは、専用の subpath ではなく、意図的に上記のアダプターでカバーされています：

Mastra は Vercel AI SDK のツールをネイティブに利用します。ai-sdk アダプターを使用してください。
Claude Agent SDK（@anthropic-ai/claude-agent-sdk）は Zod スキーマとインプロセスの MCP 登録を必要とします。Messages API の anthropic アダプターを使用してください。
CrewAI は Python フレームワークです。Vinkius の Python SDK が存在するまでの間、ニュートラルな JSON Schema 出力をブリッジとして使用してください。

ディスパッチに関する注意点

アダプターのディスパッチヘルパーは ExecuteOptions なしで capability.execute(args) を呼び出します。そのため、これらの実行にはべき等キーや呼び出し元のシグナルが含まれず、トランスポートは 1 回だけ試行されます。アダプターのディスパッチャーに不明な名前を渡すと、VinkiusError ではなくプレーンな Error がスローされます。操作にキャンセルやべき等性が必要な場合は、Capability を解決して execute() を直接呼び出してください。詳細は Error handling を参照してください。