@recepbayraktar/openapi-agent-tools

Generate framework-agnostic tool descriptors from OpenAPI specs with a Hey API plugin.

Install

pnpm add -D @recepbayraktar/openapi-agent-tools @hey-api/openapi-ts

Quick Start

// openapi-ts.config.ts
import { defineConfig } from "@hey-api/openapi-ts";

export default defineConfig({
  input: "./openapi.json",
  output: "./src/generated",
  plugins: [
    "@hey-api/client-fetch",
    {
      name: "@recepbayraktar/openapi-agent-tools",
    },
  ],
});

npx openapi-ts

Default output file:

src/generated/tool-descriptors.gen.ts

Generated Exports

• toolDescriptors: ToolDescriptor[]
• toolDescriptorMap: Record<string, ToolDescriptor>

Provider Integrations

Descriptor output stays provider-agnostic by default.

If you enable a provider integration, the generated file also includes provider-specific exports.

Vercel AI SDK

{
  name: "@recepbayraktar/openapi-agent-tools",
  providers: {
    vercelAiSdk: {
      enabled: true,
    },
  },
}

When enabled, generated output adds a direct tools export compatible with AI SDK tool maps.

import { tools as generatedTools } from "./generated/tool-descriptors.gen";

export const tools = {
  ...generatedTools,
  get_user_by_id: {
    ...generatedTools.get_user_by_id,
    execute: async (input) => api.getUserById(input),
  },
};

Generated tools expose both inputSchema and parameters for AI SDK version compatibility.

Notes

• Every operation should define operationId.
• If filters remove all operations, generation fails with E_SPEC_NO_OPERATIONS_MATCHED.
• toolName collisions fail generation.

Docs

• Getting Started
• Configuration
• Generated Output
• Examples
• Troubleshooting

Development

pnpm install
pnpm lint
pnpm test
pnpm build