From 986134060c73a15a92b45b87f0655ae3a4989170 Mon Sep 17 00:00:00 2001 From: Felix Arntz Date: Fri, 23 Oct 2026 16:52:04 -0500 Subject: [PATCH 1/6] unify package README.md files to a simpler format, avoiding a docs dump causing duplicate info --- packages/alibaba/README.md | 178 +------ packages/amazon-bedrock/README.md | 93 +--- packages/anthropic-aws/README.md | 24 +- packages/anthropic/README.md | 18 +- packages/assemblyai/README.md | 18 +- packages/azure/README.md | 18 +- packages/baseten/README.md | 18 +- packages/black-forest-labs/README.md | 101 +--- packages/bytedance/README.md | 171 +----- packages/cartesia/README.md | 18 +- packages/cerebras/README.md | 26 +- packages/code-mode/README.md | 37 +- packages/cohere/README.md | 18 +- packages/deepgram/README.md | 52 +- packages/deepinfra/README.md | 18 +- packages/deepseek/README.md | 18 +- packages/devtools/README.md | 94 +--- packages/elevenlabs/README.md | 18 +- packages/fal/README.md | 35 +- packages/fireworks/README.md | 34 +- packages/fish-audio/README.md | 33 +- packages/gateway/README.md | 18 +- packages/gladia/README.md | 18 +- packages/gmicloud/README.md | 30 +- packages/google-vertex/README.md | 265 +--------- packages/google/README.md | 18 +- packages/groq/README.md | 108 +--- packages/harness-acp/README.md | 40 +- packages/harness-claude-code/README.md | 27 +- packages/harness-cline/README.md | 13 +- packages/harness-codex/README.md | 47 +- packages/harness-cursor/README.md | 12 +- packages/harness-deepagents/README.md | 48 +- packages/harness-fx/README.md | 10 +- packages/harness-github-copilot/README.md | 10 +- packages/harness-grok-build/README.md | 10 +- packages/harness-opencode/README.md | 29 +- packages/harness-pi/README.md | 12 +- packages/harness/README.md | 28 +- packages/heygen/README.md | 10 +- packages/huggingface/README.md | 18 +- packages/hume/README.md | 18 +- packages/klingai/README.md | 148 +----- packages/langchain/README.md | 280 +--------- packages/llamaindex/README.md | 34 ++ packages/luma/README.md | 30 +- packages/mcp/README.md | 148 +----- packages/minimax/README.md | 49 +- packages/mistral/README.md | 18 +- packages/moonshotai/README.md | 70 +-- packages/open-responses/README.md | 25 +- packages/openai-compatible/README.md | 79 +-- packages/openai/README.md | 43 +- packages/otel/README.md | 92 +--- packages/perplexity/README.md | 61 +-- packages/policy-opa/README.md | 612 +--------------------- packages/prodia/README.md | 52 +- packages/quiverai/README.md | 32 +- packages/react/README.md | 62 ++- packages/replicate/README.md | 23 +- packages/revai/README.md | 18 +- packages/rsc/README.md | 28 + packages/sandbox-just-bash/README.md | 12 +- packages/sandbox-vercel/README.md | 19 +- packages/svelte/README.md | 48 +- packages/togetherai/README.md | 18 +- packages/tool-bash/README.md | 81 +-- packages/tool-web-fetch/README.md | 54 +- packages/topaz/README.md | 38 +- packages/tui/README.md | 53 +- packages/typesafe-ai/README.md | 32 +- packages/valibot/README.md | 9 +- packages/voyage/README.md | 18 +- packages/vue/README.md | 46 +- packages/workflow-harness/README.md | 143 +---- packages/workflow/README.md | 50 +- packages/xai/README.md | 18 +- packages/zai/README.md | 26 +- 78 files changed, 451 insertions(+), 3947 deletions(-) diff --git a/packages/alibaba/README.md b/packages/alibaba/README.md index dbed1046c77e..a0ce98d078ba 100644 --- a/packages/alibaba/README.md +++ b/packages/alibaba/README.md @@ -6,10 +6,8 @@ The **[Alibaba provider](https://ai-sdk.dev/providers/ai-sdk-providers/alibaba)* ## Setup -The Alibaba provider is available in the `@ai-sdk/alibaba` module. You can install it with - ```bash -npm i @ai-sdk/alibaba +npm i ai @ai-sdk/alibaba ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `alibaba` from `@ai-sdk/alibaba`: - -```ts -import { alibaba } from '@ai-sdk/alibaba'; -``` - -## Language Model Example +## Usage ```ts import { alibaba } from '@ai-sdk/alibaba'; @@ -40,166 +30,4 @@ const { text } = await generateText({ }); ``` -## Thinking Mode Example (Qwen Reasoning Models) - -Alibaba's Qwen models support thinking/reasoning mode for complex problem-solving: - -```ts -import { alibaba } from '@ai-sdk/alibaba'; -import { generateText } from 'ai'; - -const { text, reasoningText } = await generateText({ - model: alibaba('qwen3-max'), - providerOptions: { - alibaba: { - enableThinking: true, - thinkingBudget: 2048, - }, - }, - prompt: 'How many "r"s are in the word "strawberry"?', -}); - -console.log('Reasoning:', reasoningText); -console.log('Answer:', text); -``` - -## Preserved Thinking Example (Multi-Turn Reasoning) - -For models that support preserved thinking, the AI SDK sends reasoning from -previous assistant messages back as Alibaba `reasoning_content` by default -(`preserve_thinking`), so the model can build on its earlier thought process: - -```ts -import { alibaba } from '@ai-sdk/alibaba'; -import { generateText } from 'ai'; - -const providerOptions = { - alibaba: { - enableThinking: true, - thinkingBudget: 2048, - }, -}; - -const opening = { - role: 'user' as const, - content: 'Is Kafka or RocketMQ a better fit for transactional messages?', -}; - -const first = await generateText({ - model: alibaba('qwen3.7-max'), - messages: [opening], - providerOptions, -}); - -const second = await generateText({ - model: alibaba('qwen3.7-max'), - messages: [ - opening, - ...first.responseMessages, // append unchanged to keep the reasoning parts - { role: 'user', content: 'Which tradeoff mattered most?' }, - ], - providerOptions, -}); -``` - -When continuing the conversation, append `responseMessages` unchanged so the -reasoning parts survive to be serialized as `reasoning_content`. Set the -`preserveThinking` provider option to `false` to opt out. Keep in mind: - -- `preserveThinking` does not enable thinking by itself. -- It is enabled by default only for models that Alibaba documents as supporting - preserved thinking; for other models the option is not sent unless you set it - explicitly. See Alibaba's - [preserved-thinking documentation](https://docs.qwencloud.com/developer-guides/text-generation/thinking#preserve-thinking-in-multi-turn). -- Reasoning from the current tool-call round is always sent back with tool - results, as Alibaba recommends. -- Preserved reasoning increases input token usage and billing. -- Historical reasoning remains separate from visible assistant text; it is never - merged into `content`. - -## Embedding Model Example - -```ts -import { alibaba, type AlibabaEmbeddingModelOptions } from '@ai-sdk/alibaba'; -import { embed } from 'ai'; - -const { embedding, usage } = await embed({ - model: alibaba.embedding('text-embedding-v4'), - value: 'sunny day at the beach', - providerOptions: { - alibaba: { - textType: 'document', - dimension: 1024, - outputType: 'dense', - } satisfies AlibabaEmbeddingModelOptions, - }, -}); -``` - -## Tool Calling Example - -```ts -import { alibaba } from '@ai-sdk/alibaba'; -import { generateText, tool } from 'ai'; -import { z } from 'zod'; - -const { text } = await generateText({ - model: alibaba('qwen-plus'), - tools: { - weather: tool({ - description: 'Get the weather in a location', - inputSchema: z.object({ - location: z.string().describe('The location to get the weather for'), - }), - execute: async ({ location }) => ({ - location, - temperature: 72 + Math.floor(Math.random() * 21) - 10, - }), - }), - }, - prompt: 'What is the weather in San Francisco?', -}); -``` - -## Explicit Caching Example - -Alibaba supports both implicit and explicit prompt caching to reduce costs for repeated prompts. - -**Implicit caching** works automatically - the provider caches appropriate content without any configuration. For more control, you can use **explicit caching** by marking specific messages with `cacheControl`: - -```ts -import { alibaba } from '@ai-sdk/alibaba'; -import { generateText } from 'ai'; - -const longDocument = '... large document content ...'; - -const { text, usage } = await generateText({ - model: alibaba('qwen-plus'), - messages: [ - { - role: 'user', - content: [ - { - type: 'text', - text: 'Context: Please analyze this document.', - }, - { - type: 'text', - text: longDocument, - providerOptions: { - alibaba: { - cacheControl: { type: 'ephemeral' }, - }, - }, - }, - ], - }, - ], -}); -``` - -**Note:** The minimum content length for a cache block is 1,024 tokens. - -## Documentation - -Please check out the **[Alibaba provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/alibaba)** for more information. +See the [Alibaba Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/alibaba) for more information. diff --git a/packages/amazon-bedrock/README.md b/packages/amazon-bedrock/README.md index 2d3a340127e1..abb300690179 100644 --- a/packages/amazon-bedrock/README.md +++ b/packages/amazon-bedrock/README.md @@ -7,10 +7,8 @@ contains language model support for the Amazon Bedrock [converse API](https://do ## Setup -The Amazon Bedrock provider is available in the `@ai-sdk/amazon-bedrock` module. You can install it with - ```bash -npm i @ai-sdk/amazon-bedrock +npm i ai @ai-sdk/amazon-bedrock ``` ## Skill for Coding Agents @@ -21,90 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `bedrock` from `@ai-sdk/amazon-bedrock`: - -```ts -import { bedrock } from '@ai-sdk/amazon-bedrock'; -``` - -## Authentication - -The Amazon Bedrock provider supports two authentication methods with automatic fallback: - -### API Key Authentication (Recommended) - -API key authentication provides a simpler setup process compared to traditional AWS SigV4 authentication. You can authenticate using either environment variables or direct configuration. - -#### Using Environment Variable - -Set the `AWS_BEARER_TOKEN_BEDROCK` environment variable with your API key: - -```bash -export AWS_BEARER_TOKEN_BEDROCK=your-api-key-here -``` - -```ts -import { bedrock } from '@ai-sdk/amazon-bedrock'; -import { generateText } from 'ai'; - -const { text } = await generateText({ - model: bedrock('us.anthropic.claude-haiku-5-5'), - prompt: 'Write a vegetarian lasagna recipe for 4 people.', - // API key is automatically loaded from AWS_BEARER_TOKEN_BEDROCK -}); -``` - -#### Using Direct Configuration - -You can also pass the API key directly in the provider configuration: - -```ts -import { bedrock } from '@ai-sdk/amazon-bedrock'; -import { generateText } from 'ai'; - -const bedrockWithApiKey = bedrock.withSettings({ - apiKey: process.env.AWS_BEARER_TOKEN_BEDROCK, // or your API key directly - region: 'us-east-1', // Optional: specify region -}); - -const { text } = await generateText({ - model: bedrockWithApiKey('us.anthropic.claude-haiku-5-5'), - prompt: 'Write a vegetarian lasagna recipe for 4 people.', -}); -``` - -### SigV4 Authentication (Fallback) - -If no API key is provided, the provider automatically falls back to AWS SigV4 authentication using standard AWS credentials: - -```ts -import { bedrock } from '@ai-sdk/amazon-bedrock'; -import { generateText } from 'ai'; - -// Uses AWS credentials from environment variables or AWS credential chain -const { text } = await generateText({ - model: bedrock('us.anthropic.claude-haiku-5-5'), - prompt: 'Write a vegetarian lasagna recipe for 4 people.', -}); -``` - -This method requires standard AWS environment variables: - -- `AWS_ACCESS_KEY_ID` -- `AWS_SECRET_ACCESS_KEY` -- `AWS_SESSION_TOKEN` (optional, for temporary credentials) - -### Authentication Precedence - -The provider uses the following authentication precedence: - -1. **API key from direct configuration** (`apiKey` in `withSettings()`) -2. **API key from environment variable** (`AWS_BEARER_TOKEN_BEDROCK`) -3. **SigV4 authentication** (AWS credential chain fallback) - -## Example +## Usage ```ts import { bedrock } from '@ai-sdk/amazon-bedrock'; @@ -116,6 +31,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Amazon Bedrock provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/amazon-bedrock)** for more information. +See the [Amazon Bedrock Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/amazon-bedrock) for more information. diff --git a/packages/anthropic-aws/README.md b/packages/anthropic-aws/README.md index 8d22bd66fee9..83cd7528f63f 100644 --- a/packages/anthropic-aws/README.md +++ b/packages/anthropic-aws/README.md @@ -5,29 +5,13 @@ gives you access to the Anthropic Messages API hosted in AWS at `aws-external-anthropic.{region}.api.aws`, authenticated with AWS SigV4 or an AWS-provisioned API key. -Same wire format and feature set as `@ai-sdk/anthropic` — model IDs, streaming, -prompt caching, tool use, computer use, Agent Skills, and `anthropic-beta` -headers all match the first-party Claude API. - ## Setup ```bash -npm install @ai-sdk/anthropic-aws +npm i ai @ai-sdk/anthropic-aws ``` -## Provider Instance - -```ts -import { createAnthropicAws } from '@ai-sdk/anthropic-aws'; - -// SigV4 — picks up AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN -const anthropicAws = createAnthropicAws({ - region: 'us-west-2', - workspaceId: 'wrkspc_…', -}); -``` - -## Example +## Usage ```ts import { createAnthropicAws } from '@ai-sdk/anthropic-aws'; @@ -41,6 +25,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Claude Platform on AWS provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/anthropic-aws)** for more information. +See the [Claude Platform on AWS Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/anthropic-aws) for more information. diff --git a/packages/anthropic/README.md b/packages/anthropic/README.md index d4690cf8cdfe..cee8a3dc38e3 100644 --- a/packages/anthropic/README.md +++ b/packages/anthropic/README.md @@ -6,10 +6,8 @@ The **[Anthropic provider](https://ai-sdk.dev/providers/ai-sdk-providers/anthrop ## Setup -The Anthropic provider is available in the `@ai-sdk/anthropic` module. You can install it with - ```bash -npm i @ai-sdk/anthropic +npm i ai @ai-sdk/anthropic ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `anthropic` from `@ai-sdk/anthropic`: - -```ts -import { anthropic } from '@ai-sdk/anthropic'; -``` - -## Example +## Usage ```ts import { anthropic } from '@ai-sdk/anthropic'; @@ -40,6 +30,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Anthropic provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/anthropic)** for more information. +See the [Anthropic Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/anthropic) for more information. diff --git a/packages/assemblyai/README.md b/packages/assemblyai/README.md index fc4930387235..23717e28b0c6 100644 --- a/packages/assemblyai/README.md +++ b/packages/assemblyai/README.md @@ -7,10 +7,8 @@ contains transcription model support for the AssemblyAI transcription API. ## Setup -The AssemblyAI provider is available in the `@ai-sdk/assemblyai` module. You can install it with - ```bash -npm i @ai-sdk/assemblyai +npm i ai @ai-sdk/assemblyai ``` ## Skill for Coding Agents @@ -21,15 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `assemblyai` from `@ai-sdk/assemblyai`: - -```ts -import { assemblyai } from '@ai-sdk/assemblyai'; -``` - -## Example +## Usage ```ts import { assemblyai } from '@ai-sdk/assemblyai'; @@ -43,6 +33,4 @@ const { text } = await transcribe({ }); ``` -## Documentation - -Please check out the **[AssemblyAI provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/assemblyai)** for more information. +See the [AssemblyAI Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/assemblyai) for more information. diff --git a/packages/azure/README.md b/packages/azure/README.md index 9b8e79795aae..8574c07e6a55 100644 --- a/packages/azure/README.md +++ b/packages/azure/README.md @@ -6,10 +6,8 @@ The **[Azure provider](https://ai-sdk.dev/providers/ai-sdk-providers/azure)** fo ## Setup -The Azure provider is available in the `@ai-sdk/azure` module. You can install it with - ```bash -npm i @ai-sdk/azure +npm i ai @ai-sdk/azure ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `azure` from `@ai-sdk/azure`: - -```ts -import { azure } from '@ai-sdk/azure'; -``` - -## Example +## Usage ```ts import { azure } from '@ai-sdk/azure'; @@ -40,6 +30,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Azure provider](https://ai-sdk.dev/providers/ai-sdk-providers/azure)** for more information. +See the [Azure OpenAI Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/azure) for more information. diff --git a/packages/baseten/README.md b/packages/baseten/README.md index 77516051f49b..79d7c432353f 100644 --- a/packages/baseten/README.md +++ b/packages/baseten/README.md @@ -6,10 +6,8 @@ The **[Baseten provider](https://ai-sdk.dev/providers/ai-sdk-providers/baseten)* ## Setup -The Baseten provider is available in the `@ai-sdk/baseten` module. You can install it with - ```bash -npm i @ai-sdk/baseten +npm i ai @ai-sdk/baseten ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `baseten` from `@ai-sdk/baseten`: - -```ts -import { baseten } from '@ai-sdk/baseten'; -``` - -## Language Model Example (Model APIs) +## Usage ```ts import { baseten } from '@ai-sdk/baseten'; @@ -40,6 +30,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Baseten provider](https://ai-sdk.dev/providers/ai-sdk-providers/baseten)** for more information. +See the [Baseten Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/baseten) for more information. diff --git a/packages/black-forest-labs/README.md b/packages/black-forest-labs/README.md index 10b04758b884..03ce0ca1d51a 100644 --- a/packages/black-forest-labs/README.md +++ b/packages/black-forest-labs/README.md @@ -6,10 +6,8 @@ The **[Black Forest Labs provider](https://ai-sdk.dev/providers/ai-sdk-providers ## Setup -The Black Forest Labs provider is available in the `@ai-sdk/black-forest-labs` module. You can install it with - ```bash -pnpm add @ai-sdk/black-forest-labs +npm i ai @ai-sdk/black-forest-labs ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `blackForestLabs` from `@ai-sdk/black-forest-labs`: - -```ts -import { blackForestLabs } from '@ai-sdk/black-forest-labs'; -``` - -## Image Generation Example +## Usage ```ts import fs from 'node:fs'; @@ -45,89 +35,4 @@ fs.writeFileSync(filename, image.uint8Array); console.log(`Image saved to ${filename}`); ``` -## Video Generation Example - -```ts -import { blackForestLabs } from '@ai-sdk/black-forest-labs'; -import { experimental_generateVideo as generateVideo } from 'ai'; - -const { video } = await generateVideo({ - model: blackForestLabs.video('flux-3-video'), - prompt: 'A white kitten chases a butterfly across a sunlit garden.', - aspectRatio: '16:9', - duration: 8, -}); -``` - -## Additional Options - -If you want to pass additional inputs to the model besides the prompt, use the `providerOptions.blackForestLabs` property: - -```ts -import { - blackForestLabs, - type BlackForestLabsImageProviderOptions, -} from '@ai-sdk/black-forest-labs'; -import { generateImage } from 'ai'; - -const { image } = await generateImage({ - model: blackForestLabs.image('flux-pro-1.1'), - prompt: 'A cat wearing an intricate robe', - aspectRatio: '16:9', - providerOptions: { - blackForestLabs: { - outputFormat: 'png', - } satisfies BlackForestLabsImageProviderOptions, - }, -}); -``` - -## Configuring Base URL - -By default, the provider uses `https://api.bfl.ai/v1`. You can override this to use regional or legacy endpoints: - -```ts -import { createBlackForestLabs } from '@ai-sdk/black-forest-labs'; - -const blackForestLabs = createBlackForestLabs({ - baseURL: 'https://api.eu.bfl.ai/v1', - apiKey: process.env.BFL_API_KEY, -}); -``` - -## Configuring Polling - -You can customize how often the client polls for completion and how long it waits before timing out. The defaults differ by model type: 500ms / 60s for images, and 2s / 10 minutes for video. - -```ts -import { createBlackForestLabs } from '@ai-sdk/black-forest-labs'; - -const blackForestLabs = createBlackForestLabs({ - apiKey: process.env.BFL_API_KEY, - // Poll every 500ms, timeout after 5 minutes - pollIntervalMillis: 500, - pollTimeoutMillis: 5 * 60_000, -}); -``` - -You can also override these polling settings per request via `providerOptions.blackForestLabs`: - -```ts -import { blackForestLabs } from '@ai-sdk/black-forest-labs'; -import { generateImage } from 'ai'; - -const { image } = await generateImage({ - model: blackForestLabs.image('flux-pro-1.1'), - prompt: 'A cat wearing an intricate robe', - providerOptions: { - blackForestLabs: { - pollIntervalMillis: 250, - pollTimeoutMillis: 30_000, - }, - }, -}); -``` - -## Documentation - -See the [Black Forest Labs provider](https://ai-sdk.dev/providers/ai-sdk-providers/black-forest-labs) for more information. +See the [Black Forest Labs Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/black-forest-labs) for more information. diff --git a/packages/bytedance/README.md b/packages/bytedance/README.md index ac0506bf2ec1..b21ebb3f2a05 100644 --- a/packages/bytedance/README.md +++ b/packages/bytedance/README.md @@ -6,10 +6,8 @@ The **ByteDance provider** for the [AI SDK](https://ai-sdk.dev/docs) contains vi ## Setup -The ByteDance provider is available in the `@ai-sdk/bytedance` module. You can install it with: - ```bash -npm i @ai-sdk/bytedance +npm i ai @ai-sdk/bytedance ``` ## Skill for Coding Agents @@ -20,23 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `byteDance` from `@ai-sdk/bytedance`: - -```ts -import { byteDance } from '@ai-sdk/bytedance'; -``` - -## Video Models - -This provider supports text-to-video, image-to-video, audio-video sync, first-and-last frame control, and multi-reference image generation. - -### Text-to-Video - -Generate video from a text prompt. - -Available models: `seedance-1-5-pro-251215`, `seedance-1-0-pro-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428` +## Usage ```ts import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; @@ -57,151 +39,4 @@ const { video } = await generateVideo({ console.log(video.url); ``` -### Image-to-Video - -Generate video from a first-frame image with an optional text prompt. - -Available models: `seedance-1-5-pro-251215`, `seedance-1-0-pro-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-i2v-250428` - -```ts -import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; -import { experimental_generateVideo as generateVideo } from 'ai'; - -const { video } = await generateVideo({ - model: byteDance.video('seedance-1-5-pro-251215'), - prompt: { - image: 'https://example.com/first-frame.png', - text: 'The cat slowly turns its head and blinks', - }, - duration: 5, - providerOptions: { - bytedance: { - watermark: false, - } satisfies ByteDanceVideoModelOptions, - }, -}); -``` - -### Image-to-Video with Audio - -Seedance 1.5 Pro supports generating synchronized audio alongside the video. - -```ts -import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; -import { experimental_generateVideo as generateVideo } from 'ai'; - -const { video } = await generateVideo({ - model: byteDance.video('seedance-1-5-pro-251215'), - prompt: { - image: 'https://example.com/pianist.png', - text: 'A young man sits at a piano, playing calmly. Gentle piano music plays in sync.', - }, - duration: 5, - providerOptions: { - bytedance: { - generateAudio: true, - watermark: false, - } satisfies ByteDanceVideoModelOptions, - }, -}); -``` - -### First-and-Last Frame Video - -Generate smooth transitions between a starting and ending keyframe image. - -```ts -import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; -import { experimental_generateVideo as generateVideo } from 'ai'; - -const { video } = await generateVideo({ - model: byteDance.video('seedance-1-5-pro-251215'), - prompt: { - image: 'https://example.com/first-frame.jpg', - text: 'Create a 360-degree orbiting camera shot based on this photo', - }, - duration: 5, - providerOptions: { - bytedance: { - lastFrameImage: 'https://example.com/last-frame.jpg', - generateAudio: true, - watermark: false, - } satisfies ByteDanceVideoModelOptions, - }, -}); -``` - -### Multi-Reference Image-to-Video - -Provide multiple reference images (1-4) that the model uses to faithfully reproduce object shapes, colors, and textures. Use `[Image 1]`, `[Image 2]`, etc. in your prompt to reference specific images. - -Available models: `seedance-1-0-lite-i2v-250428` - -```ts -import { byteDance, type ByteDanceVideoModelOptions } from '@ai-sdk/bytedance'; -import { experimental_generateVideo as generateVideo } from 'ai'; - -const { video } = await generateVideo({ - model: byteDance.video('seedance-1-0-lite-i2v-250428'), - prompt: - 'A boy from [Image 1] and a corgi from [Image 2], sitting on the lawn from [Image 3]', - aspectRatio: '16:9', - duration: 5, - providerOptions: { - bytedance: { - referenceImages: [ - 'https://example.com/boy.png', - 'https://example.com/corgi.png', - 'https://example.com/lawn.png', - ], - watermark: false, - } satisfies ByteDanceVideoModelOptions, - }, -}); -``` - -## Provider Options - -Use `providerOptions.bytedance` to configure video generation. You can type the -object with `ByteDanceVideoModelOptions`. - -| Option | Description | -| ----------------- | ------------------------------------------------------------------------------ | -| `watermark` | Whether to add a watermark to the generated video | -| `generateAudio` | Generate synchronized audio for supported Seedance models | -| `cameraFixed` | Whether to fix the camera during generation | -| `returnLastFrame` | Return the last frame of the generated video (useful for chaining) | -| `serviceTier` | `'default'` for online inference, `'flex'` for offline at 50% price | -| `draft` | Enable draft mode for low-cost 480p preview generation (Seedance 1.5 Pro only) | -| `lastFrameImage` | URL of last frame image for first-and-last frame generation | -| `referenceImages` | Array of reference image URLs for multi-reference generation | -| `referenceVideos` | Array of reference video URLs for reference-guided generation | -| `referenceAudio` | Array of reference audio URLs for audio-guided generation | -| `pollIntervalMs` | Poll interval for async generation (default: 3000ms) | -| `pollTimeoutMs` | Max wait time for generation (default: 300000ms) | - -Supported aspect ratios: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive` (image-to-video only). - -## Authentication - -Set the `ARK_API_KEY` environment variable: - -``` -ARK_API_KEY=your-api-key -``` - -Or pass it directly: - -```ts -import { createByteDance } from '@ai-sdk/bytedance'; - -const byteDance = createByteDance({ - apiKey: 'your-api-key', -}); -``` - -You can [obtain an API key](https://console.byteplus.com/ark/apiKey) from the BytePlus console. - -## Documentation - -Please check out the **[ByteDance provider](https://ai-sdk.dev/providers/ai-sdk-providers/bytedance)** for more information. +See the [ByteDance Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/bytedance) for more information. diff --git a/packages/cartesia/README.md b/packages/cartesia/README.md index d1535b0d094a..67e69f27a951 100644 --- a/packages/cartesia/README.md +++ b/packages/cartesia/README.md @@ -7,10 +7,8 @@ contains Sonic 3.5 speech generation, Ink-Whisper batch transcription, and Ink 2 ## Setup -The Cartesia provider is available in the `@ai-sdk/cartesia` module. You can install it with - ```bash -npm i @ai-sdk/cartesia +npm i ai @ai-sdk/cartesia ``` ## Skill for Coding Agents @@ -21,15 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `cartesia` from `@ai-sdk/cartesia`: - -```ts -import { cartesia } from '@ai-sdk/cartesia'; -``` - -## Example +## Usage ```ts import { cartesia } from '@ai-sdk/cartesia'; @@ -42,6 +32,4 @@ const { audio } = await generateSpeech({ }); ``` -## Documentation - -Please check out the **[Cartesia provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/cartesia)** for more information. +See the [Cartesia Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/cartesia) for more information. diff --git a/packages/cerebras/README.md b/packages/cerebras/README.md index b17d3485e65f..d987793ff186 100644 --- a/packages/cerebras/README.md +++ b/packages/cerebras/README.md @@ -6,10 +6,8 @@ The **Cerebras provider** for the [AI SDK](https://ai-sdk.dev/docs) contains lan ## Setup -The Cerebras provider is available in the `@ai-sdk/cerebras` module. You can install it with - ```bash -npm i @ai-sdk/cerebras +npm i ai @ai-sdk/cerebras ``` ## Skill for Coding Agents @@ -20,20 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `cerebras` from `@ai-sdk/cerebras`: - -```ts -import { cerebras } from '@ai-sdk/cerebras'; -``` - -## Available Models - -Cerebras offers a variety of high-performance language models: -https://inference-docs.cerebras.ai/models/overview - -## Example +## Usage ```ts import { cerebras } from '@ai-sdk/cerebras'; @@ -45,9 +30,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -For more information about Cerebras' high-speed inference capabilities and API documentation, please visit: - -- [Cerebras Inference Documentation](https://inference-docs.cerebras.ai/introduction) -- [Cerebras Website](https://cerebras.ai) +See the [Cerebras Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/cerebras) for more information. diff --git a/packages/code-mode/README.md b/packages/code-mode/README.md index 5a105be481d7..428ecc17cc6a 100644 --- a/packages/code-mode/README.md +++ b/packages/code-mode/README.md @@ -4,18 +4,12 @@ AI SDK tools. The code runs in an isolated QuickJS sandbox and returns a JSON-serializable value. -Use code mode when a model needs to call several tools, transform their results, -or run them concurrently. Only the tools you provide are available to the -generated code. - -## Installation +## Setup ```bash -pnpm add ai @ai-sdk/code-mode +npm i ai @ai-sdk/code-mode zod ``` -This package runs on the server and requires Node.js 22.13 or newer. - ## Usage ```ts @@ -74,29 +68,4 @@ const result = await generateText({ }); ``` -The model can then generate code like: - -```ts -const [inventory, demand] = await Promise.all([ - tools.getInventory({ productId: 'sku_123' }), - tools.getDemand({ productId: 'sku_123' }), -]); - -return { - sufficient: inventory.availableUnits >= demand.requestedUnits, - remaining: inventory.availableUnits - demand.requestedUnits, -}; -``` - -## Direct Execution - -Use `experimental_runCodeMode` to run code directly: - -```ts -import { experimental_runCodeMode as runCodeMode } from '@ai-sdk/code-mode'; - -const result = await runCodeMode({ - js: 'return await tools.getInventory({ productId: "sku_123" });', - tools: { getInventory }, -}); -``` +See the [Code Mode documentation](https://ai-sdk.dev/docs/ai-sdk-core/code-mode) for more information. diff --git a/packages/cohere/README.md b/packages/cohere/README.md index 30ae47bd1b46..53729e21c4ed 100644 --- a/packages/cohere/README.md +++ b/packages/cohere/README.md @@ -6,10 +6,8 @@ The **[Cohere provider](https://ai-sdk.dev/providers/ai-sdk-providers/cohere)** ## Setup -The Cohere provider is available in the `@ai-sdk/cohere` module. You can install it with - ```bash -npm i @ai-sdk/cohere +npm i ai @ai-sdk/cohere ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `cohere` from `@ai-sdk/cohere`: - -```ts -import { cohere } from '@ai-sdk/cohere'; -``` - -## Example +## Usage ```ts import { cohere } from '@ai-sdk/cohere'; @@ -40,6 +30,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Cohere provider](https://ai-sdk.dev/providers/ai-sdk-providers/cohere)** for more information. +See the [Cohere Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/cohere) for more information. diff --git a/packages/deepgram/README.md b/packages/deepgram/README.md index 47f75090104b..4ffc66d8335a 100644 --- a/packages/deepgram/README.md +++ b/packages/deepgram/README.md @@ -7,10 +7,8 @@ contains transcription model support for the Deepgram transcription API and spee ## Setup -The Deepgram provider is available in the `@ai-sdk/deepgram` module. You can install it with - ```bash -npm i @ai-sdk/deepgram +npm i ai @ai-sdk/deepgram ``` ## Skill for Coding Agents @@ -21,17 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `deepgram` from `@ai-sdk/deepgram`: - -```ts -import { deepgram } from '@ai-sdk/deepgram'; -``` - -## Examples - -### Transcription +## Usage ```ts import { deepgram } from '@ai-sdk/deepgram'; @@ -45,38 +33,4 @@ const { text } = await transcribe({ }); ``` -### Transcription with Language Detection - -```ts -import { deepgram } from '@ai-sdk/deepgram'; -import { transcribe } from 'ai'; - -const { text, language } = await transcribe({ - model: deepgram.transcription('nova-3'), - audio: new URL( - 'https://github.com/vercel/ai/raw/refs/heads/main/examples/ai-functions/data/galileo.mp3', - ), - providerOptions: { - deepgram: { - detectLanguage: true, - }, - }, -}); -``` - -### Text-to-Speech - -```ts -import { deepgram } from '@ai-sdk/deepgram'; -import { generateSpeech } from 'ai'; - -const { audio } = await generateSpeech({ - model: deepgram.speech('aura-2'), - voice: 'helena', - text: 'Hello, welcome to Deepgram!', -}); -``` - -## Documentation - -Please check out the **[Deepgram provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/deepgram)** for more information. +See the [Deepgram Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/deepgram) for more information. diff --git a/packages/deepinfra/README.md b/packages/deepinfra/README.md index 4a860e191435..314810839483 100644 --- a/packages/deepinfra/README.md +++ b/packages/deepinfra/README.md @@ -7,10 +7,8 @@ contains language model support for the DeepInfra API, giving you access to mode ## Setup -The DeepInfra provider is available in the `@ai-sdk/deepinfra` module. You can install it with - ```bash -npm i @ai-sdk/deepinfra +npm i ai @ai-sdk/deepinfra ``` ## Skill for Coding Agents @@ -21,15 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `deepinfra` from `@ai-sdk/deepinfra`: - -```ts -import { deepinfra } from '@ai-sdk/deepinfra'; -``` - -## Example +## Usage ```ts import { deepinfra } from '@ai-sdk/deepinfra'; @@ -41,6 +31,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[DeepInfra provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/deepinfra)** for more information. +See the [DeepInfra Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/deepinfra) for more information. diff --git a/packages/deepseek/README.md b/packages/deepseek/README.md index 8e4a80bcae99..677bfd8238bd 100644 --- a/packages/deepseek/README.md +++ b/packages/deepseek/README.md @@ -6,10 +6,8 @@ The **[DeepSeek provider](https://ai-sdk.dev/providers/ai-sdk-providers/deepseek ## Setup -The DeepSeek provider is available in the `@ai-sdk/deepseek` module. You can install it with - ```bash -npm i @ai-sdk/deepseek +npm i ai @ai-sdk/deepseek ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `deepseek` from `@ai-sdk/deepseek`: - -```ts -import { deepseek } from '@ai-sdk/deepseek'; -``` - -## Example +## Usage ```ts import { deepseek } from '@ai-sdk/deepseek'; @@ -40,6 +30,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[DeepSeek provider](https://ai-sdk.dev/providers/ai-sdk-providers/deepseek)** for more information. +See the [DeepSeek Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/deepseek) for more information. diff --git a/packages/devtools/README.md b/packages/devtools/README.md index 1f886b6f40eb..8033ba7ea94b 100644 --- a/packages/devtools/README.md +++ b/packages/devtools/README.md @@ -4,25 +4,14 @@ A local development tool for debugging and inspecting AI SDK applications. View > **Note**: This package is experimental and intended for local development only. Do not use in production environments. -## Installation +## Setup ```bash -npm install @ai-sdk/devtools -# or -pnpm add @ai-sdk/devtools +npm i ai @ai-sdk/devtools ``` -## Requirements - -- AI SDK v7 canary (`ai@canary`) -- Node.js compatible runtime - ## Usage -### 1. Register the telemetry integration - -Register `DevToolsTelemetry` globally so it captures all AI SDK calls: - ```typescript import { registerTelemetry } from 'ai'; import { DevToolsTelemetry } from '@ai-sdk/devtools'; @@ -30,81 +19,4 @@ import { DevToolsTelemetry } from '@ai-sdk/devtools'; registerTelemetry(DevToolsTelemetry()); ``` -Telemetry is enabled automatically once an integration is registered: - -```typescript -import { generateText } from 'ai'; - -const result = await generateText({ - model: yourModel, - prompt: 'What cities are in the United States?', -}); -``` - -You can also pass the integration to individual calls instead of registering it -globally: - -```typescript -import { streamText } from 'ai'; -import { DevToolsTelemetry } from '@ai-sdk/devtools'; - -const result = streamText({ - model: yourModel, - prompt: 'Hello!', - telemetry: { - integrations: [DevToolsTelemetry()], - }, -}); -``` - -### 2. Run the viewer - -```bash -npx @ai-sdk/devtools@latest -``` - -Open http://localhost:4983 to view your AI SDK interactions. - -The viewer uses the dark theme by default. Use the theme button in the header to -switch between dark and light themes. The browser remembers your selection for -the next time you open the viewer at the same origin. - -If you are using a monorepo, start DevTools from the same workspace where your -AI SDK code runs. The explicit `@latest` tag ensures that `npx` installs an -executable copy instead of selecting a transitive dependency whose binary is -not linked into that workspace. - -## How it works - -The `DevToolsTelemetry` integration hooks into the AI SDK telemetry lifecycle to -capture `generateText`, `streamText`, `generateObject`, and `streamObject` calls. -It captures: - -- Input parameters and prompts -- Output content and tool calls -- Token usage and timing -- Raw provider data - -Data is stored locally in a JSON file (`.devtools/generations.json`) and served through a web UI. - -### Data flow - -``` -AI SDK call -> DevToolsTelemetry -> JSON file -> Hono API -> React UI -``` - -### Key concepts - -- **Run**: A complete multi-step AI interaction, grouped by initial prompt -- **Step**: A single LLM call within a run - -## Development - -```bash -pnpm install -pnpm dev # Start dev server at http://localhost:5173 -``` - -## License - -MIT +See the [DevTools documentation](https://ai-sdk.dev/docs/ai-sdk-core/devtools) for more information. diff --git a/packages/elevenlabs/README.md b/packages/elevenlabs/README.md index efa0f03cba3f..c0d3d553bc40 100644 --- a/packages/elevenlabs/README.md +++ b/packages/elevenlabs/README.md @@ -7,10 +7,8 @@ contains speech generation plus batch and realtime transcription support for the ## Setup -The ElevenLabs provider is available in the `@ai-sdk/elevenlabs` module. You can install it with - ```bash -npm i @ai-sdk/elevenlabs +npm i ai @ai-sdk/elevenlabs ``` ## Skill for Coding Agents @@ -21,15 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `elevenlabs` from `@ai-sdk/elevenlabs`: - -```ts -import { elevenlabs } from '@ai-sdk/elevenlabs'; -``` - -## Example +## Usage ```ts import { elevenlabs } from '@ai-sdk/elevenlabs'; @@ -43,6 +33,4 @@ const { text } = await transcribe({ }); ``` -## Documentation - -Please check out the **[ElevenLabs provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/elevenlabs)** for more information. +See the [ElevenLabs Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/elevenlabs) for more information. diff --git a/packages/fal/README.md b/packages/fal/README.md index 824978e70e86..7063f3b761f3 100644 --- a/packages/fal/README.md +++ b/packages/fal/README.md @@ -6,10 +6,8 @@ The **[fal provider](https://ai-sdk.dev/providers/ai-sdk-providers/fal)** for th ## Setup -The fal provider is available in the `@ai-sdk/fal` module. You can install it with - ```bash -npm i @ai-sdk/fal +npm i ai @ai-sdk/fal ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `fal` from `@ai-sdk/fal`: - -```ts -import { fal } from '@ai-sdk/fal'; -``` - -## Image Generation Example +## Usage ```ts import { fal } from '@ai-sdk/fal'; @@ -44,23 +34,4 @@ fs.writeFileSync(filename, image.uint8Array); console.log(`Image saved to ${filename}`); ``` -## Additional Options - -If you want to pass additional inputs to the model besides the prompt, use the `providerOptions.fal` property: - -```ts -const { image } = await generateImage({ - model: fal.image('fal-ai/recraft-v3'), - prompt: 'A cat wearing a intricate robe', - size: '1920x1080', - providerOptions: { - fal: { - style: 'digital_illustration', - }, - }, -}); -``` - -## Documentation - -Please check out the **[fal provider](https://ai-sdk.dev/providers/ai-sdk-providers/fal)** for more information. +See the [fal Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/fal) for more information. diff --git a/packages/fireworks/README.md b/packages/fireworks/README.md index 57752dbf24fd..971b84e46c7b 100644 --- a/packages/fireworks/README.md +++ b/packages/fireworks/README.md @@ -6,10 +6,8 @@ The **[Fireworks provider](https://ai-sdk.dev/providers/ai-sdk-providers/firewor ## Setup -The Fireworks provider is available in the `@ai-sdk/fireworks` module. You can install it with - ```bash -npm i @ai-sdk/fireworks +npm i ai @ai-sdk/fireworks ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `fireworks` from `@ai-sdk/fireworks`: - -```ts -import { fireworks } from '@ai-sdk/fireworks'; -``` - -## Language Model Example +## Usage ```ts import { fireworks } from '@ai-sdk/fireworks'; @@ -40,22 +30,4 @@ const { text } = await generateText({ }); ``` -## Image Model Examples - -```ts -import { fireworks } from '@ai-sdk/fireworks'; -import { generateImage } from 'ai'; -import fs from 'fs'; - -const { image } = await generateImage({ - model: fireworks.image('accounts/fireworks/models/flux-1-dev-fp8'), - prompt: 'A serene mountain landscape at sunset', -}); -const filename = `image-${Date.now()}.png`; -fs.writeFileSync(filename, image.uint8Array); -console.log(`Image saved to ${filename}`); -``` - -## Documentation - -Please check out the **[Fireworks provider](https://ai-sdk.dev/providers/ai-sdk-providers/fireworks)** for more information. +See the [Fireworks Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/fireworks) for more information. diff --git a/packages/fish-audio/README.md b/packages/fish-audio/README.md index bdbd74a22662..99a54caabc9b 100644 --- a/packages/fish-audio/README.md +++ b/packages/fish-audio/README.md @@ -7,10 +7,8 @@ contains speech generation (S1 and S2 models) and speech-to-text transcription s ## Setup -The Fish Audio provider is available in the `@ai-sdk/fish-audio` module. You can install it with - ```bash -npm i @ai-sdk/fish-audio +npm i ai @ai-sdk/fish-audio ``` ## Skill for Coding Agents @@ -21,17 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `fishAudio` from `@ai-sdk/fish-audio`: - -```ts -import { fishAudio } from '@ai-sdk/fish-audio'; -``` - -## Example - -### Speech generation +## Usage ```ts import { fishAudio } from '@ai-sdk/fish-audio'; @@ -45,19 +33,4 @@ const { audio } = await generateSpeech({ }); ``` -### Transcription - -```ts -import { fishAudio } from '@ai-sdk/fish-audio'; -import { transcribe } from 'ai'; -import { readFile } from 'node:fs/promises'; - -const { text, segments } = await transcribe({ - model: fishAudio.transcription(), - audio: await readFile('audio.mp3'), -}); -``` - -## Documentation - -Please check out the **[Fish Audio provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/fish-audio)** for more information. +See the [Fish Audio Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/fish-audio) for more information. diff --git a/packages/gateway/README.md b/packages/gateway/README.md index 3e25d8c5e237..6ae6f21555bf 100644 --- a/packages/gateway/README.md +++ b/packages/gateway/README.md @@ -4,10 +4,8 @@ The Gateway provider for the [AI SDK](https://ai-sdk.dev/docs) allows the use of ## Setup -The Gateway provider is available in the `@ai-sdk/gateway` module. You can install it with - ```bash -npm i @ai-sdk/gateway +npm i ai @ai-sdk/gateway ``` ## Skill for Coding Agents @@ -18,15 +16,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `gateway` from `@ai-sdk/gateway`: - -```ts -import { gateway } from '@ai-sdk/gateway'; -``` - -## Example +## Usage ```ts import { gateway } from '@ai-sdk/gateway'; @@ -39,6 +29,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the [AI SDK documentation](https://ai-sdk.dev/docs) for more information. +See the [Gateway Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/ai-gateway) for more information. diff --git a/packages/gladia/README.md b/packages/gladia/README.md index dfc0b03647d1..a14924ce9734 100644 --- a/packages/gladia/README.md +++ b/packages/gladia/README.md @@ -7,10 +7,8 @@ contains transcription model support for the Gladia transcription API. ## Setup -The Gladia provider is available in the `@ai-sdk/gladia` module. You can install it with - ```bash -npm i @ai-sdk/gladia +npm i ai @ai-sdk/gladia ``` ## Skill for Coding Agents @@ -21,15 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `gladia` from `@ai-sdk/gladia`: - -```ts -import { gladia } from '@ai-sdk/gladia'; -``` - -## Example +## Usage ```ts import { gladia } from '@ai-sdk/gladia'; @@ -43,6 +33,4 @@ const { text } = await transcribe({ }); ``` -## Documentation - -Please check out the **[Gladia provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/gladia)** for more information. +See the [Gladia Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/gladia) for more information. diff --git a/packages/gmicloud/README.md b/packages/gmicloud/README.md index 0603443d1009..63a157acda0e 100644 --- a/packages/gmicloud/README.md +++ b/packages/gmicloud/README.md @@ -6,31 +6,11 @@ The **GMI Cloud provider** for the [AI SDK](https://ai-sdk.dev/docs) contains la ## Setup -The GMI Cloud provider is available in the `@ai-sdk/gmicloud` module. You can install it with - ```bash -npm i @ai-sdk/gmicloud +npm i ai @ai-sdk/gmicloud ``` -## Provider Instance - -You can import the default provider instance `gmicloud` from `@ai-sdk/gmicloud`: - -```ts -import { gmicloud } from '@ai-sdk/gmicloud'; -``` - -The GMI Cloud API key is read from the `GMI_CLOUD_APIKEY` environment variable by default. For custom configuration, use `createGmicloud`: - -```ts -import { createGmicloud } from '@ai-sdk/gmicloud'; - -const gmicloud = createGmicloud({ - apiKey: process.env.GMI_CLOUD_APIKEY ?? '', -}); -``` - -## Language Models +## Usage ```ts import { gmicloud } from '@ai-sdk/gmicloud'; @@ -42,8 +22,4 @@ const { text } = await generateText({ }); ``` -GMI Cloud serves an evolving catalog of open-weight models over chat completions, so model ids are typed as `string`. Embedding and image models are not supported. - -## Error diagnostics - -GMI Cloud's edge reports a generic banner in `error.message` on rejections and nests the backend engine's diagnostic in `error.details`. This provider unwraps the nested diagnostic, so `AI_APICallError.message` carries the engine's reason (e.g. `The request is invalid: Invalid max_tokens value, the valid range of max_tokens is [1, 393216].`) instead of `Backend request failed with status 400`. +See the [GMI Cloud Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/gmicloud) for more information. diff --git a/packages/google-vertex/README.md b/packages/google-vertex/README.md index 0a482bb78e6f..b9cd724a9d1a 100644 --- a/packages/google-vertex/README.md +++ b/packages/google-vertex/README.md @@ -2,16 +2,12 @@ The **[Google Vertex provider](https://ai-sdk.dev/providers/ai-sdk-providers/google-vertex)** for the [AI SDK](https://ai-sdk.dev/docs) contains language model support for the [Google Vertex AI](https://cloud.google.com/vertex-ai) APIs. -This library includes a Google Vertex Anthropic provider and a Google Vertex MaaS provider. These providers closely follow the core Google Vertex library's usage patterns. See more in the [Google Vertex Anthropic Provider](#google-vertex-anthropic-provider) and [Google Vertex MaaS Provider](#google-vertex-maas-provider) sections below. - > **Deploying to Vercel?** With Vercel's AI Gateway you can access Google Vertex AI (and hundreds of models from other providers) — no additional packages, API keys, or extra cost. [Get started with AI Gateway](https://vercel.com/ai-gateway). ## Setup -The Google Vertex provider is available in the `@ai-sdk/google-vertex` module. You can install it with - ```bash -npm i @ai-sdk/google-vertex +npm i ai @ai-sdk/google-vertex ``` ## Skill for Coding Agents @@ -22,13 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Google Vertex Provider - -The Google Vertex provider has two different authentication implementations depending on your runtime environment: - -### Node.js Runtime - -The Node.js runtime is the default runtime supported by the AI SDK. You can use the default provider instance to generate text with the `gemini-3.8-flash` model like this: +## Usage ```ts import { vertex } from '@ai-sdk/google-vertex'; @@ -40,253 +30,4 @@ const { text } = await generateText({ }); ``` -This provider supports all standard Google Cloud authentication options through the [`google-auth-library`](https://github.com/googleapis/google-auth-library-nodejs?tab=readme-ov-file#ways-to-authenticate). The most common authentication method is to set the path to a json credentials file in the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. Credentials can be obtained from the [Google Cloud Console](https://console.cloud.google.com/apis/credentials). - -### Edge Runtime - -The Edge runtime is supported through the `@ai-sdk/google-vertex/edge` module. Note the additional sub-module path `/edge` required to differentiate the Edge provider from the Node.js provider. - -You can use the default provider instance to generate text with the `gemini-3.8-flash` model like this: - -```ts -import { vertex } from '@ai-sdk/google-vertex/edge'; -import { generateText } from 'ai'; - -const { text } = await generateText({ - model: vertex('gemini-3.8-flash'), - prompt: 'Write a vegetarian lasagna recipe.', -}); -``` - -This method supports Google's [Application Default Credentials](https://github.com/googleapis/google-auth-library-nodejs?tab=readme-ov-file#application-default-credentials) through the environment variables `GOOGLE_CLIENT_EMAIL`, `GOOGLE_PRIVATE_KEY`, and (optionally) `GOOGLE_PRIVATE_KEY_ID`. The values can be obtained from a json credentials file obtained from the [Google Cloud Console](https://console.cloud.google.com/apis/credentials). - -## Google Vertex Anthropic Provider - -The Google Vertex Anthropic provider is available for both Node.js and Edge runtimes. It follows a similar usage pattern to the [core Google Vertex provider](#google-vertex-provider). - -### Node.js Runtime - -```ts -import { vertexAnthropic } from '@ai-sdk/google-vertex/anthropic'; -import { generateText } from 'ai'; - -const { text } = await generateText({ - model: vertexAnthropic('claude-sonnet-5-5'), - prompt: 'Write a vegetarian lasagna recipe.', -}); -``` - -### Edge Runtime - -```ts -import { vertexAnthropic } from '@ai-sdk/google-vertex/anthropic/edge'; -import { generateText } from 'ai'; - -const { text } = await generateText({ - model: vertexAnthropic('claude-sonnet-5-5'), - prompt: 'Write a vegetarian lasagna recipe.', -}); -``` - -## Prompt Caching Support for Anthropic Claude Models - -The Google Vertex Anthropic provider supports prompt caching for Anthropic Claude models. Prompt caching can help reduce latency and costs by reusing cached results for identical requests. Caches are unique to Google Cloud projects and have a five-minute lifetime. - -### Enabling Prompt Caching - -To enable prompt caching, you can use the `cacheControl` property in the settings. Here is an example demonstrating how to enable prompt caching: - -```ts -import { vertexAnthropic } from '@ai-sdk/google-vertex/anthropic'; -import { generateText } from 'ai'; -import fs from 'node:fs'; - -const errorMessage = fs.readFileSync('data/error-message.txt', 'utf8'); - -async function main() { - const result = await generateText({ - model: vertexAnthropic('claude-sonnet-5-5', { - cacheControl: true, - }), - messages: [ - { - role: 'user', - content: [ - { - type: 'text', - text: 'You are a JavaScript expert.', - }, - { - type: 'text', - text: `Error message: ${errorMessage}`, - providerOptions: { - anthropic: { - cacheControl: { type: 'ephemeral' }, - }, - }, - }, - { - type: 'text', - text: 'Explain the error message.', - }, - ], - }, - ], - }); - - console.log(result.text); - console.log(result.providerMetadata?.anthropic); -} - -main().catch(console.error); -``` - -## Custom Provider Configuration - -You can create a custom provider instance using the `createVertex` function. This allows you to specify additional configuration options. Below is an example with the default Node.js provider which includes a `googleAuthOptions` object. - -```ts -import { createVertex } from '@ai-sdk/google-vertex'; -import { generateText } from 'ai'; - -const customProvider = createVertex({ - project: 'your-project-id', - location: 'us-central1', - googleAuthOptions: { - credentials: { - client_email: 'your-client-email', - private_key: 'your-private-key', - }, - }, -}); - -const { text } = await generateText({ - model: customProvider('gemini-3.8-flash'), - prompt: 'Write a vegetarian lasagna recipe.', -}); -``` - -The `googleAuthOptions` object is not present in the Edge provider options but custom provider creation is otherwise identical. - -The Edge provider supports a `googleCredentials` option rather than `googleAuthOptions`. This can be used to specify the Google Cloud service account credentials and will take precedence over the environment variables used otherwise. - -```ts -import { createVertex } from '@ai-sdk/google-vertex/edge'; -import { generateText } from 'ai'; - -const customProvider = createVertex({ - project: 'your-project-id', - location: 'us-central1', - googleCredentials: { - clientEmail: 'your-client-email', - privateKey: 'your-private-key', - }, -}); - -const { text } = await generateText({ - model: customProvider('gemini-3.8-flash'), - prompt: 'Write a vegetarian lasagna recipe.', -}); -``` - -### Google Vertex Anthropic Provider Custom Configuration - -The Google Vertex Anthropic provider custom configuration is analogous to the above: - -```ts -import { createVertexAnthropic } from '@ai-sdk/google-vertex/anthropic'; -import { generateText } from 'ai'; - -const customProvider = createVertexAnthropic({ - project: 'your-project-id', - location: 'us-east5', -}); - -const { text } = await generateText({ - model: customProvider('claude-sonnet-5-5'), - prompt: 'Write a vegetarian lasagna recipe.', -}); -``` - -And for the Edge runtime: - -```ts -import { vertexAnthropic } from '@ai-sdk/google-vertex/anthropic/edge'; -import { generateText } from 'ai'; - -const customProvider = createVertexAnthropic({ - project: 'your-project-id', - location: 'us-east5', -}); - -const { text } = await generateText({ - model: customProvider('claude-sonnet-5-5'), - prompt: 'Write a vegetarian lasagna recipe.', -}); -``` - -## Google Vertex MaaS Provider - -The Google Vertex MaaS (Model as a Service) provider offers access to partner and open models hosted on Vertex AI through an OpenAI-compatible Chat Completions API. It is available for both Node.js and Edge runtimes. - -### Node.js Runtime - -```ts -import { vertexMaas } from '@ai-sdk/google-vertex/maas'; -import { generateText } from 'ai'; - -const { text } = await generateText({ - model: vertexMaas('deepseek-ai/deepseek-v3.2-maas'), - prompt: 'Write a vegetarian lasagna recipe.', -}); -``` - -### Edge Runtime - -```ts -import { vertexMaas } from '@ai-sdk/google-vertex/maas/edge'; -import { generateText } from 'ai'; - -const { text } = await generateText({ - model: vertexMaas('deepseek-ai/deepseek-v3.2-maas'), - prompt: 'Write a vegetarian lasagna recipe.', -}); -``` - -### Google Vertex MaaS Provider Custom Configuration - -```ts -import { createVertexMaas } from '@ai-sdk/google-vertex/maas'; -import { generateText } from 'ai'; - -const customProvider = createVertexMaas({ - project: 'your-project-id', - location: 'us-east5', -}); - -const { text } = await generateText({ - model: customProvider('deepseek-ai/deepseek-v3.2-maas'), - prompt: 'Write a vegetarian lasagna recipe.', -}); -``` - -And for the Edge runtime: - -```ts -import { createVertexMaas } from '@ai-sdk/google-vertex/maas/edge'; -import { generateText } from 'ai'; - -const customProvider = createVertexMaas({ - project: 'your-project-id', - location: 'us-east5', -}); - -const { text } = await generateText({ - model: customProvider('deepseek-ai/deepseek-v3.2-maas'), - prompt: 'Write a vegetarian lasagna recipe.', -}); -``` - -## Documentation - -Please check out the **[Google Vertex provider](https://ai-sdk.dev/providers/ai-sdk-providers/google-vertex)** for more information. +See the [Google Vertex AI Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/google-vertex) for more information. diff --git a/packages/google/README.md b/packages/google/README.md index b35c6b5ff942..62e330355c33 100644 --- a/packages/google/README.md +++ b/packages/google/README.md @@ -6,10 +6,8 @@ The **[Google provider](https://ai-sdk.dev/providers/ai-sdk-providers/google)** ## Setup -The Google provider is available in the `@ai-sdk/google` module. You can install it with - ```bash -npm i @ai-sdk/google +npm i ai @ai-sdk/google ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `google` from `@ai-sdk/google`: - -```ts -import { google } from '@ai-sdk/google'; -``` - -## Example +## Usage ```ts import { google } from '@ai-sdk/google'; @@ -40,6 +30,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Google provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/google)** for more information. +See the [Google Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/google) for more information. diff --git a/packages/groq/README.md b/packages/groq/README.md index e670b335942c..066c93a02749 100644 --- a/packages/groq/README.md +++ b/packages/groq/README.md @@ -7,10 +7,8 @@ contains language model support for the Groq chat and completion APIs, transcrip ## Setup -The Groq provider is available in the `@ai-sdk/groq` module. You can install it with - ```bash -npm i @ai-sdk/groq +npm i ai @ai-sdk/groq ``` ## Skill for Coding Agents @@ -21,103 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `groq` from `@ai-sdk/groq`: - -```ts -import { groq } from '@ai-sdk/groq'; -``` - -## Browser Search Tool - -The Groq provider includes a browser search tool that provides interactive web browsing capabilities. Unlike traditional web search, browser search navigates websites interactively, providing more detailed and comprehensive results. - -### Supported Models - -Browser search is only available for these models: - -- `openai/gpt-oss-20b` -- `openai/gpt-oss-120b` - -⚠️ **Important**: Using browser search with other models will generate a warning and the tool will be ignored. - -### Basic Usage - -```ts -import { groq } from '@ai-sdk/groq'; -import { generateText } from 'ai'; - -const result = await generateText({ - model: groq('openai/gpt-oss-120b'), // Must use supported model - prompt: - 'What are the latest developments in AI? Please search for recent news.', - tools: { - browser_search: groq.tools.browserSearch({}), - }, - toolChoice: 'required', // Ensure the tool is used -}); - -console.log(result.text); -``` - -### Streaming Example - -```ts -import { groq } from '@ai-sdk/groq'; -import { streamText } from 'ai'; - -const result = streamText({ - model: groq('openai/gpt-oss-120b'), - prompt: 'Search for the latest tech news and summarize it.', - tools: { - browser_search: groq.tools.browserSearch({}), - }, - toolChoice: 'required', -}); - -for await (const delta of result.stream) { - if (delta.type === 'text-delta') { - process.stdout.write(delta.text); - } -} -``` - -### Key Features - -- **Interactive Browsing**: Navigates websites like a human user -- **Comprehensive Results**: More detailed than traditional search snippets -- **Server-side Execution**: Runs on Groq's infrastructure, no setup required -- **Powered by Exa**: Uses Exa search engine for optimal results -- **Currently Free**: Available at no additional charge during beta - -### Best Practices - -- Use `toolChoice: 'required'` to ensure the browser search is activated -- Supported models only: `openai/gpt-oss-20b` and `openai/gpt-oss-120b` -- The tool works automatically - no configuration parameters needed -- Server-side execution means no additional API keys or setup required - -### Model Validation - -The provider automatically validates model compatibility: - -```ts -// ✅ Supported - will work -const result = await generateText({ - model: groq('openai/gpt-oss-120b'), - tools: { browser_search: groq.tools.browserSearch({}) }, -}); - -// ❌ Unsupported - will show warning and ignore tool -const result = await generateText({ - model: groq('gemma2-9b-it'), - tools: { browser_search: groq.tools.browserSearch({}) }, -}); -// Warning: "Browser search is only supported on models: openai/gpt-oss-20b, openai/gpt-oss-120b" -``` - -## Basic Text Generation +## Usage ```ts import { groq } from '@ai-sdk/groq'; @@ -129,8 +31,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Groq provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/groq)** for more information. - -For browser search details, see the **[Groq Browser Search Documentation](https://console.groq.com/docs/browser-search)**. +See the [Groq Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/groq) for more information. diff --git a/packages/harness-acp/README.md b/packages/harness-acp/README.md index 51efb09ceee8..d9a9b8952220 100644 --- a/packages/harness-acp/README.md +++ b/packages/harness-acp/README.md @@ -6,22 +6,16 @@ The adapter ships a bridge process that runs inside a sandbox and talks to the host over a WebSocket on a sandbox-proxied loopback port. The configured ACP agent runs alongside the bridge inside the sandbox. +-> **Note**: This package is experimental. + ## Setup ```bash npm i @ai-sdk/harness-acp @ai-sdk/harness @ai-sdk/sandbox-vercel ``` -The bridge installs the configured ACP agent inside the sandbox the -first time the session starts. - ## Usage -This example connects `HarnessAgent` to Codex ACP using direct OpenAI -authentication. The locked `package.json` declares -`@agentclientprotocol/codex-acp` together with every dependency of this -package's bridge manifest (`dist/bridge/package.json`) at the same versions: - ```ts import { readFileSync } from 'node:fs'; import { HarnessAgent } from '@ai-sdk/harness/agent'; @@ -102,32 +96,4 @@ try { } ``` -Set `CODEX_API_KEY` or `OPENAI_API_KEY` in the host environment. Sandboxes that -support additive request transformations receive only credential placeholders; -the real value is injected only when a matching outbound request contains the -expected placeholder. Other sandboxes -retain the legacy behavior of forwarding the value to the ACP process. Codex -ACP supports only `permissionMode: 'allow-all'` because its -restrictive modes enable Codex's internal sandbox. A bridge-backed ACP harness -requires a sandbox with at least one exposed port. - -`modelMapping` is required because ACP agents expose different model -selection operations. Use `session-config-option` with the ACP configuration -option ID as `path`, or `session-model` with the JSON-RPC request property as -`path` for agents such as Grok Build that use the legacy -`session/set_model` method. No model operation is sent when `HarnessAgent` has -no model configured. - -Use `instructionMapping` when the ACP agent exposes a native system -or developer prompt. A `session-meta` mapping writes `HarnessAgent` -instructions below the ACP session request's `_meta` field. A -`launch-env-json` mapping merges them into a JSON environment variable before -the agent starts. A `filesystem` mapping writes instructions to a -markdown file at a relative path under the agent's effective `$HOME`. -Without a mapping, the adapter preserves its backward-compatible behavior and -prepends instructions to the first user prompt. - -Skills are written to `.agents/skills` below the ACP agent's effective -`$HOME` and discovered natively by the agent. Set `skillsDirectory` -to another relative path, such as `.claude/skills`, when required by the -agent. +See the [ACP Harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/acp) for more information. diff --git a/packages/harness-claude-code/README.md b/packages/harness-claude-code/README.md index 94860878b2cb..1f4fd8fe78d2 100644 --- a/packages/harness-claude-code/README.md +++ b/packages/harness-claude-code/README.md @@ -2,14 +2,14 @@ `HarnessV1` adapter backed by [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk), which drives the `claude` CLI. The adapter ships a bridge process that runs inside a sandbox and talks to the host over a WebSocket on a sandbox-proxied loopback port. +-> **Note**: This package is experimental. + ## Setup ```bash -npm i @ai-sdk/harness-claude-code @ai-sdk/harness @ai-sdk/sandbox-vercel +npm i ai @ai-sdk/harness-claude-code @ai-sdk/harness @ai-sdk/sandbox-vercel zod ``` -The bridge installs `@anthropic-ai/claude-agent-sdk` and `@anthropic-ai/claude-code` inside the sandbox the first time the session starts. - ## Usage ```ts @@ -63,23 +63,4 @@ try { } ``` -The adapter needs a sandbox session with an exposed port. The caller owns the -sandbox lifecycle: ending the harness session does not stop the sandbox. - -## Runtime configuration - -Use `env` to add environment variables to the Claude Code process. Configured -values override variables inherited from the sandbox bridge process. - -```ts -const harness = createClaudeCode({ - env: { - DEPLOYMENT_ENV: 'staging', - }, -}); -``` - -Sub-agent messages and task/background notifications are surfaced as `raw` -stream parts. `agentProgressSummaries` adds periodic summaries to raw -`task_progress` messages, while `forwardSubagentText` includes sub-agent text -and thinking messages in the raw stream. +See the [Claude Code Harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/claude-code) for more information. diff --git a/packages/harness-cline/README.md b/packages/harness-cline/README.md index 5b0e4b400fd0..d26b89d94ea7 100644 --- a/packages/harness-cline/README.md +++ b/packages/harness-cline/README.md @@ -2,10 +2,12 @@ `HarnessV1` adapter backed by [`@cline/agents`](https://www.npmjs.com/package/@cline/agents). Cline runs in the host Node.js process and uses the sandbox as a remote filesystem and shell, so no bridge process is installed inside the sandbox. +-> **Note**: This package is experimental. + ## Setup ```bash -npm i @ai-sdk/harness-cline @ai-sdk/harness @ai-sdk/sandbox-vercel +npm i ai @ai-sdk/harness-cline @ai-sdk/harness @ai-sdk/sandbox-vercel zod ``` ## Usage @@ -52,11 +54,4 @@ try { } ``` -The adapter has no in-sandbox bridge, so the supplied session does not need -exposed ports. Its built-in tools operate on the sandbox from the host process. - -## Authentication - -The default `auto` authentication mode uses `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` when available and otherwise falls back to `CLINE_API_KEY`. Use `createCline({ auth: 'ai-gateway' })` or `createCline({ auth: 'direct' })` to select a mode explicitly, or pass an isolated authentication environment with `createCline({ auth: { CLINE_API_KEY: token } })`. `AI_GATEWAY_BASE_URL` and `CLINE_API_BASE_URL` configure their respective endpoints. - -See the [Cline harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/cline) for model configuration, reasoning, tools, skills, MCP, and session lifecycle details. +See the [Cline Harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/cline) for more information. diff --git a/packages/harness-codex/README.md b/packages/harness-codex/README.md index 4202fa04a8b7..cc42192bfdc0 100644 --- a/packages/harness-codex/README.md +++ b/packages/harness-codex/README.md @@ -2,14 +2,14 @@ `HarnessV1` adapter backed by the [Codex CLI](https://www.npmjs.com/package/@openai/codex). The adapter runs Codex app-server inside a sandbox and communicates with it over JSON-RPC. A bridge process connects app-server to the host over a WebSocket on a sandbox-proxied loopback port. +-> **Note**: This package is experimental. + ## Setup ```bash -npm i @ai-sdk/harness-codex @ai-sdk/harness @ai-sdk/sandbox-vercel +npm i ai @ai-sdk/harness-codex @ai-sdk/harness @ai-sdk/sandbox-vercel zod ``` -The bridge installs the Codex CLI inside the sandbox the first time the session starts. - ## Usage ```ts @@ -39,43 +39,4 @@ const agent = new HarnessAgent({ }); ``` -`codexConfig` accepts additional native Codex configuration. Values pass -through as provided, so use the snake_case keys from Codex's `config.toml` -reference. The adapter's managed values take precedence over conflicting -entries. - -> Codex does not auto-discover a skills directory the way the `claude` CLI -> does, so when you supply `skills: [...]` on the factory the adapter -> injects every skill inline into the user prompt on each turn. Use fewer, -> larger skills rather than many tiny ones. - -```ts -const agent = new HarnessAgent({ - harness: createCodex({ - skills: [ - { name: 'haiku-mode', description: 'Answer in haikus.', content: '...' }, - ], - }), -}); - -const sandboxSession = await createVercelNetworkSandboxSession({ - runtime: 'node24', - ports: [4000], - template: await agent.getSandboxTemplate(), -}); -const session = await agent.createSession({ sandboxSession }); - -try { - const result = await agent.generate({ - session, - prompt: 'List the files in this workspace and describe their purpose.', - }); - console.log(result.text); -} finally { - await session.destroy(); - await sandboxSession.destroy(); -} -``` - -The adapter needs a sandbox session with an exposed port. The caller ends the -harness session and sandbox separately. +See the [Codex Harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/codex) for more information. diff --git a/packages/harness-cursor/README.md b/packages/harness-cursor/README.md index 6170b3ac318c..81213c3b7f87 100644 --- a/packages/harness-cursor/README.md +++ b/packages/harness-cursor/README.md @@ -2,14 +2,14 @@ The **[@ai-sdk/harness-cursor](https://www.npmjs.com/package/@ai-sdk/harness-cursor)** package adapts [Cursor CLI](https://cursor.com/cli) to the AI SDK harness abstraction through the Agent Client Protocol (ACP). +-> **Note**: This package is experimental. + ## Setup ```bash -npm install @ai-sdk/harness @ai-sdk/harness-cursor @ai-sdk/sandbox-vercel +npm i @ai-sdk/harness-cursor @ai-sdk/harness @ai-sdk/sandbox-vercel ``` -Create a Cursor user API key and set `CURSOR_API_KEY`, or pass it directly with `createCursor({ auth: { CURSOR_API_KEY: token } })`. The key authenticates Cursor CLI in the sandbox regardless of how Cursor is configured to authenticate to the model provider. - ## Usage ```ts @@ -40,8 +40,4 @@ try { } ``` -The adapter installs Cursor CLI inside the sandbox with Cursor's official installer. The sandbox must provide network access and at least one exposed TCP port. - -Cursor controls model-provider authentication in its own settings. For AI Gateway, configure Cursor's OpenAI API key with an AI Gateway key and set **Override OpenAI Base URL** to `https://ai-gateway.vercel.sh/cursor/v1`. The `auth` setting accepts the shared ACP modes `auto`, `direct`, and `ai-gateway`; explicit `direct` and `ai-gateway` values emit a configuration reminder, while `auto` does not. The setting cannot change Cursor's account configuration. - -See the [Cursor harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/cursor) for settings, tools, and limitations. +See the [Cursor Harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/cursor) for more information. diff --git a/packages/harness-deepagents/README.md b/packages/harness-deepagents/README.md index 55b59b41d1d1..122ddda77679 100644 --- a/packages/harness-deepagents/README.md +++ b/packages/harness-deepagents/README.md @@ -1,32 +1,17 @@ -# @ai-sdk/harness-deepagents +# Deep Agents Harness A [HarnessV1](../harness) adapter that runs [Deep Agents](https://github.com/langchain-ai/deepagentsjs) (LangChain's LangGraph-based agent harness) as a coding-agent runtime inside an AI SDK sandbox. -This is a **bridge-backed** harness: the Deep Agents runtime runs inside the -sandbox via a Node bridge (`node bridge.mjs`) built on the shared -`@ai-sdk/harness/bridge` runtime, while the host adapter drives turns over a -WebSocket. - -> **Status: happy-path validated.** The host adapter (`doStart` + session: -> `doPromptTurn`/`doStop`/`doDestroy`) and the Node bridge (driving the -> `deepagents` npm package via `createDeepAgent` + `streamEvents`) are validated -> end-to-end against a live Vercel Sandbox: text generation, streaming, -> multi-turn memory, and host-executed tools all work. Turn continuation, -> suspend/detach, cross-process resume, and built-in tool approvals throw -> `HarnessCapabilityUnsupportedError` and are follow-ups. +-> **Note**: This package is experimental. ## Setup ```bash -pnpm add @ai-sdk/harness-deepagents @ai-sdk/harness +npm i @ai-sdk/harness-deepagents @ai-sdk/harness @ai-sdk/sandbox-vercel ``` -The harness installs the -bridge's Node dependencies (the `deepagents` package and LangChain) into its -bootstrap directory via `pnpm` at startup. - ## Usage ```ts @@ -53,29 +38,4 @@ try { } ``` -## Auth - -Deep Agents uses the Anthropic client directly or through AI Gateway. With no -mode configured, the adapter prefers ambient AI Gateway credentials and falls -back to ambient Anthropic credentials. Pass an authentication environment to -use programmatically resolved credentials without reading `process.env`: - -```ts -const agent = new HarnessAgent({ - harness: createDeepAgents({ - auth: { ANTHROPIC_API_KEY: token }, - }), - model: 'anthropic/claude-sonnet-4.5', -}); -``` - -## Built-in tools - -| Common name | Native (LangGraph) tool | -| ----------- | ----------------------- | -| `read` | `read_file` | -| `write` | `write_file` | -| `bash` | `shell` | -| `grep` | `search` | - -See the [harness docs](https://ai-sdk.dev/docs) for broader concepts. +See the [Deep Agents Harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/deepagents) for more information. diff --git a/packages/harness-fx/README.md b/packages/harness-fx/README.md index 9bf01943b273..62e65e5928ee 100644 --- a/packages/harness-fx/README.md +++ b/packages/harness-fx/README.md @@ -2,10 +2,12 @@ The **[@ai-sdk/harness-fx](https://www.npmjs.com/package/@ai-sdk/harness-fx)** package adapts [fx](https://fx.sh) to the AI SDK harness abstraction using [libfx](https://www.npmjs.com/package/libfx). The runtime runs on the host, while built-in filesystem and shell tools operate exclusively on the sandbox. +-> **Note**: This package is experimental. + ## Setup ```bash -npm install @ai-sdk/harness @ai-sdk/harness-fx @ai-sdk/sandbox-vercel +npm i @ai-sdk/harness-fx @ai-sdk/harness @ai-sdk/sandbox-vercel ``` ## Usage @@ -37,8 +39,4 @@ try { } ``` -No fx executable or bridge is installed inside the sandbox, and no exposed sandbox port is required. Model requests run on the host. - -fx uses Vercel AI Gateway when `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` is available. Otherwise it discovers subscription credentials in this order: fx Codex, fx Grok, native Codex, then native Grok. Use `createFx({ auth: 'direct' })` to prefer subscriptions while retaining Gateway fallback, or `auth: 'ai-gateway'` to use Gateway only. - -See the [fx harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/fx) for settings, tools, and limitations. +See the [fx Harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/fx) for more information. diff --git a/packages/harness-github-copilot/README.md b/packages/harness-github-copilot/README.md index 6e2513f9473e..ee32da4ce286 100644 --- a/packages/harness-github-copilot/README.md +++ b/packages/harness-github-copilot/README.md @@ -2,10 +2,12 @@ The **[@ai-sdk/harness-github-copilot](https://www.npmjs.com/package/@ai-sdk/harness-github-copilot)** package runs GitHub Copilot CLI through its Agent Client Protocol server and the AI SDK harness abstraction. +-> **Note**: This package is experimental. + ## Setup ```bash -npm install @ai-sdk/harness @ai-sdk/harness-github-copilot @ai-sdk/sandbox-vercel +npm i @ai-sdk/harness-github-copilot @ai-sdk/harness @ai-sdk/sandbox-vercel ``` ## Usage @@ -38,8 +40,4 @@ try { } ``` -The adapter uses `@ai-sdk/harness-acp`, which installs the pinned GitHub Copilot CLI inside the sandbox. The sandbox must provide network access and at least one exposed TCP port. - -Set one of `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` for direct authentication. Without one of these variables, direct authentication reads the GitHub Copilot CLI login from the host's native credential store or plaintext fallback. If neither contains a token and the host has `gh` on `PATH`, the adapter reads `gh auth token` without modifying either credential store. Set `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` to use AI Gateway instead, or pass an isolated authentication environment with `createGitHubCopilot({ auth: { AI_GATEWAY_API_KEY: token } })`. - -See the [GitHub Copilot harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/github-copilot) for authentication security, settings, tools, and lifecycle support. +See the [GitHub Copilot Harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/github-copilot) for more information. diff --git a/packages/harness-grok-build/README.md b/packages/harness-grok-build/README.md index 1d914c3dc543..1b5a4e07c7f8 100644 --- a/packages/harness-grok-build/README.md +++ b/packages/harness-grok-build/README.md @@ -2,10 +2,12 @@ The **[@ai-sdk/harness-grok-build](https://www.npmjs.com/package/@ai-sdk/harness-grok-build)** package adapts [Grok Build](https://x.ai/cli) to the AI SDK harness abstraction through the Agent Client Protocol (ACP). +-> **Note**: This package is experimental. + ## Setup ```bash -npm install @ai-sdk/harness @ai-sdk/harness-grok-build @ai-sdk/sandbox-vercel +npm i @ai-sdk/harness-grok-build @ai-sdk/harness @ai-sdk/sandbox-vercel ``` ## Usage @@ -38,8 +40,4 @@ try { } ``` -The adapter uses `@ai-sdk/harness-acp`, which installs the pinned Grok Build CLI inside the sandbox. The sandbox must provide network access and at least one exposed TCP port. - -Set `XAI_API_KEY` for direct authentication. Set `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` to use AI Gateway instead, or pass an isolated authentication environment with `createGrokBuild({ auth: { AI_GATEWAY_API_KEY: token } })`. - -See the [Grok Build harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/grok-build) for settings, tools, and limitations. +See the [Grok Build Harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/grok-build) for more information. diff --git a/packages/harness-opencode/README.md b/packages/harness-opencode/README.md index eeae08f084cb..c11a7e52e7df 100644 --- a/packages/harness-opencode/README.md +++ b/packages/harness-opencode/README.md @@ -3,11 +3,15 @@ The OpenCode harness connects `HarnessAgent` to OpenCode through a sandboxed bridge. -## Native OpenCode configuration +-> **Note**: This package is experimental. -Use `openCodeConfig` to pass native OpenCode settings that do not have a -dedicated adapter option. For example, OpenCode supports selecting a model for -an individual agent: +## Setup + +```bash +npm i @ai-sdk/harness @ai-sdk/harness-opencode @ai-sdk/sandbox-vercel +``` + +## Usage ```ts import { createOpenCode } from '@ai-sdk/harness-opencode'; @@ -23,19 +27,4 @@ const adapter = createOpenCode({ }); ``` -Adapter-managed settings take precedence when the same key is present in -`openCodeConfig`. Agent-local `permission` and deprecated `tools` settings are -ignored so they cannot bypass harness permissions or built-in tool filtering. - -## Compaction events - -Native automatic and manual compaction emit a `compaction` stream part on -completion. Internal summary text is available on that part, rather than -streamed as assistant answer text. Summary model usage is preserved. - -With `includeRawChunks` enabled, `opencode.compaction` raw events expose -`messageId` and `status` (`started` or `failed`). Successful completion uses -the normalized `compaction` part, whose `harnessMetadata.opencode.messageId` -identifies the same operation. - -See the AI SDK documentation for usage. +See the [OpenCode harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/opencode) for more information. diff --git a/packages/harness-pi/README.md b/packages/harness-pi/README.md index f51599feb2df..b24144d79774 100644 --- a/packages/harness-pi/README.md +++ b/packages/harness-pi/README.md @@ -2,10 +2,12 @@ `HarnessV1` adapter backed by [`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent). Pi runs in the host Node.js process and uses the sandbox as a remote filesystem + shell — no bridge process is installed inside the sandbox. +-> **Note**: This package is experimental. + ## Setup ```bash -npm i @ai-sdk/harness-pi @ai-sdk/harness @ai-sdk/sandbox-vercel +npm i ai @ai-sdk/harness-pi @ai-sdk/harness @ai-sdk/sandbox-vercel zod ``` ## Usage @@ -52,10 +54,4 @@ try { } ``` -Pi has no in-sandbox bridge, so the supplied session does not need exposed ports. Its built-in tools operate on the sandbox from the host process. - -## Authentication - -The default `auto` authentication mode uses `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` when available and otherwise falls back to provider credentials such as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`. Use `createPi({ auth: 'ai-gateway' })` or `createPi({ auth: 'anthropic' })` to select a mode explicitly, or pass an isolated authentication environment with `createPi({ auth: { ANTHROPIC_API_KEY: token } })`. - -See the [Pi harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/pi) for authentication options, model configuration, tools, skills, MCP, and session lifecycle details. +See the [Pi Harness documentation](https://ai-sdk.dev/providers/ai-sdk-harnesses/pi) for more information. diff --git a/packages/harness/README.md b/packages/harness/README.md index 5c24c08c24d3..ea56f59c9052 100644 --- a/packages/harness/README.md +++ b/packages/harness/README.md @@ -1,13 +1,13 @@ # AI SDK - Harness Specification and Agent -_This package is **experimental**._ - `HarnessAgent` implementation plus the underlying harness specification, including an expanded network session sandbox interface to support harness sandbox needs. +-> **Note**: This package is experimental. + ## Setup ```bash -npm i ai zod @ai-sdk/harness @ai-sdk/harness-claude-code @ai-sdk/sandbox-vercel +npm i ai @ai-sdk/harness @ai-sdk/harness-claude-code @ai-sdk/sandbox-vercel zod ``` ## Usage @@ -84,24 +84,4 @@ try { } ``` -Set `output` on `HarnessAgent` to require the same typed, schema-backed output -on every turn. `generate()` exposes the validated value as `result.output`, and -`stream()` additionally exposes `partialOutputStream`; the JSON also remains on -the normal text and stream surfaces. - -```ts -import { Output } from 'ai'; - -const agent = new HarnessAgent({ - harness: claudeCode, - output: Output.object({ - schema: z.object({ answer: z.string() }), - }), -}); -``` - -## Documentation - -- [Detailed usage documentation](https://ai-sdk.dev/docs/ai-sdk-harnesses) -- [Harness abstraction architecture](https://github.com/vercel/ai/blob/main/architecture/harness-abstraction.md) -- [Sandbox abstraction architecture](https://github.com/vercel/ai/blob/main/architecture/sandbox-abstraction.md) +See the [Harness Specification and Agent documentation](https://ai-sdk.dev/docs/ai-sdk-harnesses) for more information. diff --git a/packages/heygen/README.md b/packages/heygen/README.md index a5f3e761158e..5c6432199ad8 100644 --- a/packages/heygen/README.md +++ b/packages/heygen/README.md @@ -4,12 +4,10 @@ The **[HeyGen provider](https://ai-sdk.dev/providers/ai-sdk-providers/heygen)** ## Setup -```sh -npm install @ai-sdk/heygen +```bash +npm i ai @ai-sdk/heygen ``` -Set the `HEYGEN_API_KEY` environment variable or pass `apiKey` to `createHeyGen`. - ## Usage ```ts @@ -25,6 +23,4 @@ const { videos } = await generateVideo({ }); ``` -The provider implements asynchronous submission and status retrieval. The AI SDK handles polling when you call `generateVideo`. - -See the [provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/heygen) and [HeyGen API documentation](https://developers.heygen.com/docs/models/heygen-video) for supported inputs and options. +See the [HeyGen Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/heygen) for more information. diff --git a/packages/huggingface/README.md b/packages/huggingface/README.md index c2c2ab42adca..9fd13e1018b5 100644 --- a/packages/huggingface/README.md +++ b/packages/huggingface/README.md @@ -6,10 +6,8 @@ The **[Hugging Face Inference Providers](https://huggingface.co/docs/inference-p ## Setup -The Hugging Face provider is available in the `@ai-sdk/huggingface` module. You can install it with: - ```bash -npm i @ai-sdk/huggingface +npm i ai @ai-sdk/huggingface ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `huggingface` from `@ai-sdk/huggingface`: - -```ts -import { huggingface } from '@ai-sdk/huggingface'; -``` - -## Example +## Usage ```ts import { huggingface } from '@ai-sdk/huggingface'; @@ -40,6 +30,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Hugging Face provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/huggingface)** for more information. +See the [Hugging Face Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/huggingface) for more information. diff --git a/packages/hume/README.md b/packages/hume/README.md index 3e13ebf3fc3a..e1f748287879 100644 --- a/packages/hume/README.md +++ b/packages/hume/README.md @@ -7,10 +7,8 @@ contains support for the Hume API. ## Setup -The Hume provider is available in the `@ai-sdk/hume` module. You can install it with - ```bash -npm i @ai-sdk/hume +npm i ai @ai-sdk/hume ``` ## Skill for Coding Agents @@ -21,15 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `hume` from `@ai-sdk/hume`: - -```ts -import { hume } from '@ai-sdk/hume'; -``` - -## Example +## Usage ```ts import { hume } from '@ai-sdk/hume'; @@ -41,6 +31,4 @@ const result = await generateSpeech({ }); ``` -## Documentation - -Please check out the **[Hume provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/hume)** for more information. +See the [Hume Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/hume) for more information. diff --git a/packages/klingai/README.md b/packages/klingai/README.md index 33cc2841f3de..da03c29876cf 100644 --- a/packages/klingai/README.md +++ b/packages/klingai/README.md @@ -6,10 +6,8 @@ The **Kling AI provider** for the [AI SDK](https://ai-sdk.dev/docs) contains vid ## Setup -The Kling AI provider is available in the `@ai-sdk/klingai` module. You can install it with: - ```bash -npm i @ai-sdk/klingai +npm i ai @ai-sdk/klingai ``` ## Skill for Coding Agents @@ -20,25 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `klingai` from `@ai-sdk/klingai`: - -```ts -import { klingai } from '@ai-sdk/klingai'; -``` - -## Video Models - -This provider currently supports three video generation modes: text-to-video, image-to-video, and motion control. - -> **Note:** Not all options are supported by every model version and mode combination. See the [KlingAI Capability Map](https://app.klingai.com/global/dev/document-api/apiReference/model/skillsMap) for detailed compatibility. - -### Text-to-Video - -Generate video from a text prompt. - -Available models: `kling-v1-t2v`, `kling-v1.6-t2v`, `kling-v2-master-t2v`, `kling-v2.1-master-t2v`, `kling-v2.5-turbo-t2v`, `kling-v2.6-t2v`, `kling-v3.0-t2v` +## Usage ```ts import { klingai } from '@ai-sdk/klingai'; @@ -57,126 +37,4 @@ const { videos } = await experimental_generateVideo({ }); ``` -### Image-to-Video - -Generate video from a start frame image, with optional end frame control. - -Available models: `kling-v1-i2v`, `kling-v1.5-i2v`, `kling-v1.6-i2v`, `kling-v2-master-i2v`, `kling-v2.1-i2v`, `kling-v2.1-master-i2v`, `kling-v2.5-turbo-i2v`, `kling-v2.6-i2v`, `kling-v3.0-i2v` - -```ts -import { klingai } from '@ai-sdk/klingai'; -import { experimental_generateVideo } from 'ai'; - -const { videos } = await experimental_generateVideo({ - model: klingai.video('kling-v3.0-i2v'), - prompt: { - image: 'https://example.com/start-frame.png', - text: 'The cat slowly turns its head and blinks', - }, - duration: 5, - providerOptions: { - klingai: { - // Pro mode required for start+end frame control - mode: 'pro', - // Optional: end frame image - imageTail: 'https://example.com/end-frame.png', - }, - }, -}); -``` - -### Motion Control - -Generate video using a reference motion video. - -Available models: `kling-v2.6-motion-control`, `kling-v3.0-motion-control` - -```ts -import { klingai } from '@ai-sdk/klingai'; -import { experimental_generateVideo } from 'ai'; - -const { videos } = await experimental_generateVideo({ - model: klingai.video('kling-v3.0-motion-control'), - prompt: { - image: 'https://example.com/character.png', - text: 'The character performs a smooth dance move', - }, - providerOptions: { - klingai: { - videoUrl: 'https://example.com/reference-motion.mp4', - characterOrientation: 'image', - mode: 'std', - }, - }, -}); -``` - -## Provider Options - -Use `providerOptions.klingai` to configure video generation. Options vary by mode: - -| Option | T2V | I2V | Motion Control | Description | -| ---------------------- | ----------------- | ----------------- | ----------------- | ------------------------------- | -| `mode` | `'std'` / `'pro'` | `'std'` / `'pro'` | `'std'` / `'pro'` | Generation quality mode | -| `negativePrompt` | Yes | Yes | — | What to avoid (max 2500 chars) | -| `sound` | V2.6+ pro only | V2.6+ pro only | — | `'on'` / `'off'` for audio | -| `cfgScale` | Yes (V1.x) | Yes (V1.x) | — | Prompt adherence [0, 1] | -| `cameraControl` | Yes | Yes | — | Camera movement presets | -| `imageTail` | — | Pro mode | — | End frame image (URL or base64) | -| `staticMask` | — | Yes | — | Static brush mask | -| `dynamicMasks` | — | Yes | — | Dynamic brush configs | -| `videoUrl` | — | — | Required | Reference motion video URL | -| `characterOrientation` | — | — | Required | `'image'` or `'video'` | -| `keepOriginalSound` | — | — | Yes | `'yes'` / `'no'` | -| `watermarkEnabled` | — | — | Yes | Enable watermark | -| `pollIntervalMs` | Yes | Yes | Yes | Poll interval (default: 5000ms) | -| `pollTimeoutMs` | Yes | Yes | Yes | Max wait (default: 600000ms) | - -See the [KlingAI Capability Map](https://app.klingai.com/global/dev/document-api/apiReference/model/skillsMap) for which features each model version supports. - -## Authentication - -Kling AI uses API key authentication. Create a key in the [Kling AI developer console](https://kling.ai/dev/api-key) and set the following environment variable: - -``` -KLINGAI_API_KEY=your-api-key -``` - -Or pass it directly: - -```ts -import { createKlingAI } from '@ai-sdk/klingai'; - -const klingai = createKlingAI({ - apiKey: 'your-api-key', -}); -``` - -### Legacy access key / secret key - -Kling AI's earlier access key / secret key pair is still supported. The provider uses it to sign a short-lived JWT for each request: - -``` -KLINGAI_ACCESS_KEY=your-access-key -KLINGAI_SECRET_KEY=your-secret-key -``` - -```ts -import { createKlingAI } from '@ai-sdk/klingai'; - -const klingai = createKlingAI({ - accessKey: 'your-access-key', - secretKey: 'your-secret-key', -}); -``` - -Credentials are resolved in this order, with explicit settings taking precedence over environment variables: - -1. The `apiKey` setting -2. The `accessKey` and `secretKey` settings -3. The `KLINGAI_API_KEY` environment variable -4. The `KLINGAI_ACCESS_KEY` and `KLINGAI_SECRET_KEY` environment variables - -## Documentation - -Please check out the [Kling AI API documentation](https://app.klingai.com/global/dev/document-api/quickStart/productIntroduction/overview) for more information. +See the [Kling AI Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/klingai) for more information. diff --git a/packages/langchain/README.md b/packages/langchain/README.md index eea287fa1cf0..f6674a2b9f08 100644 --- a/packages/langchain/README.md +++ b/packages/langchain/README.md @@ -2,42 +2,14 @@ The **[AI SDK](https://ai-sdk.dev)** LangChain adapter provides seamless integration between [LangChain](https://langchain.com/) and the AI SDK, enabling you to use LangChain agents and graphs with AI SDK UI components. -## Installation +## Setup ```bash -npm install @ai-sdk/langchain @langchain/core +npm i ai @ai-sdk/langchain @langchain/core ``` -> **Note:** `@langchain/core` is a required peer dependency. - -## Features - -- Convert AI SDK `UIMessage` to LangChain `BaseMessage` format -- Transform LangChain/LangGraph streams to AI SDK `UIMessageStream` -- `ChatTransport` implementation for LangSmith deployments -- Full support for text, tool calls, and tool results -- Custom data streaming with typed events (`data-{type}`) - ## Usage -### Converting Messages - -Use `toBaseMessages` to convert AI SDK messages to LangChain format: - -```ts -import { toBaseMessages } from '@ai-sdk/langchain'; - -// Convert UI messages to LangChain format -const langchainMessages = await toBaseMessages(uiMessages); - -// Use with any LangChain model -const response = await model.invoke(langchainMessages); -``` - -### Streaming from LangGraph - -Use `toUIMessageStream` to convert LangGraph streams to AI SDK format: - ```ts import { toBaseMessages, toUIMessageStream } from '@ai-sdk/langchain'; import { createUIMessageStreamResponse } from 'ai'; @@ -56,250 +28,4 @@ return createUIMessageStreamResponse({ }); ``` -Use the `tools` stream mode when you want to stream LangGraph tool progress. The adapter converts `on_tool_event` events to preliminary tool output (`preliminary: true`) and the final `on_tool_end` event to final tool output. - -### Streaming with Callbacks - -Use callbacks to access the final LangGraph state, handle errors, or detect aborts: - -```ts -const langchainStream = await graph.stream( - { messages: langchainMessages }, - { streamMode: ['values', 'messages'] }, -); - -return createUIMessageStreamResponse({ - stream: toUIMessageStream(langchainStream, { - onFinish: async finalState => { - if (finalState) { - await saveConversation(finalState.messages); - await sendAnalytics(finalState); - } - }, - onError: error => console.error('Stream failed:', error), - onAbort: () => console.log('Client disconnected'), - }), -}); -``` - -### Streaming with `streamEvents` - -You can also use `toUIMessageStream` with `streamEvents()` for more granular event handling: - -```ts -import { toBaseMessages, toUIMessageStream } from '@ai-sdk/langchain'; -import { createUIMessageStreamResponse } from 'ai'; - -// Using streamEvents with an agent -const langchainMessages = await toBaseMessages(uiMessages); -const streamEvents = agent.streamEvents( - { messages: langchainMessages }, - { version: 'v2' }, -); - -// Convert to UI message stream response -return createUIMessageStreamResponse({ - stream: toUIMessageStream(streamEvents), -}); -``` - -The adapter automatically detects the stream type and handles: - -- `on_chat_model_stream` events for text streaming -- `on_tool_start` and `on_tool_end` events for tool calls -- Reasoning content from contentBlocks - -### Custom Data Streaming - -LangChain tools can emit custom data events using `config.writer()`. The adapter converts these to typed `data-{type}` parts: - -```ts -import { tool, type ToolRuntime } from 'langchain'; - -const analyzeDataTool = tool( - async ({ query }, config: ToolRuntime) => { - // Emit progress updates - becomes 'data-progress' in the UI - config.writer?.({ - type: 'progress', - id: 'analysis-1', // Include 'id' to persist in message.parts - step: 'fetching', - message: 'Fetching data...', - progress: 50, - }); - - // ... perform analysis ... - - // Emit status update - becomes 'data-status' in the UI - config.writer?.({ - type: 'status', - id: 'analysis-1-status', - status: 'complete', - message: 'Analysis finished', - }); - - return 'Analysis complete'; - }, - { - name: 'analyze_data', - description: 'Analyze data with progress updates', - schema: z.object({ query: z.string() }), - }, -); -``` - -Enable the `custom` stream mode to receive these events: - -```ts -const stream = await graph.stream( - { messages: langchainMessages }, - { streamMode: ['values', 'messages', 'custom'] }, -); -``` - -**Custom data behavior:** - -- Data with an `id` field is **persistent** (added to `message.parts` for rendering) -- Data without an `id` is **transient** (only delivered via the `onData` callback) -- The `type` field determines the event name: `{ type: 'progress' }` → `data-progress` - -### LangSmith Deployment Transport - -Use `LangSmithDeploymentTransport` with the AI SDK `useChat` hook to connect directly to a LangGraph deployment from the browser: - -```tsx -import { useChat } from '@ai-sdk/react'; -import { LangSmithDeploymentTransport } from '@ai-sdk/langchain'; -import { useMemo } from 'react'; - -function Chat() { - const transport = useMemo( - () => - new LangSmithDeploymentTransport({ - url: 'https://your-deployment.us.langgraph.app', - apiKey: process.env.LANGSMITH_API_KEY, - }), - [], - ); - - const { messages, input, handleInputChange, handleSubmit } = useChat({ - transport, - }); - - return ( -
- {messages.map(m => ( -
{m.parts.map(part => part.text).join('')}
- ))} -
- - -
-
- ); -} -``` - -## API Reference - -### `toBaseMessages(messages)` - -Converts AI SDK `UIMessage` objects to LangChain `BaseMessage` objects. - -**Parameters:** - -- `messages`: `UIMessage[]` - Array of AI SDK UI messages - -**Returns:** `Promise` - -### `convertModelMessages(modelMessages)` - -Converts AI SDK `ModelMessage` objects to LangChain `BaseMessage` objects. - -**Parameters:** - -- `modelMessages`: `ModelMessage[]` - Array of model messages - -**Returns:** `BaseMessage[]` - -### `toUIMessageStream(stream, options?)` - -Converts a LangChain/LangGraph stream to an AI SDK `UIMessageStream`. - -**Parameters:** - -- `stream`: `AsyncIterable | ReadableStream` - A stream from LangChain `model.stream()`, LangGraph `graph.stream()`, or `streamEvents()` -- `options?`: `ToUIMessageStreamOptions` - Optional lifecycle controls and callbacks: - - `sendStart` - Whether to emit the outer `start` chunk (defaults to `true`) - - `sendFinish` - Whether to emit the outer `finish` chunk (defaults to `true`) - - `onStart()` - Called when stream initializes - - `onToken(token)` - Called for each token - - `onText(text)` - Called for each text chunk - - `onFinal(text)` - Called with aggregated text (on success, error, or abort) - - `onFinish(state)` - Called on success with LangGraph state (or `undefined` for other streams) - - `onError(error)` - Called when stream errors - - `onAbort()` - Called when stream is aborted - -**Returns:** `ReadableStream` - -When composing the adapter output into a stream that owns the message -lifecycle, set `sendStart` and `sendFinish` to `false`: - -```ts -const stream = createUIMessageStream({ - async execute({ writer }) { - writer.write({ type: 'start' }); - - const reader = toUIMessageStream(langchainStream, { - sendStart: false, - sendFinish: false, - }).getReader(); - - while (true) { - const { done, value: chunk } = await reader.read(); - if (done) break; - writer.write(chunk); - } - - writer.write({ type: 'finish' }); - }, -}); -``` - -Only the outer lifecycle chunks are omitted. Text, reasoning, tool, data, and -step chunks are still emitted. - -**Supported stream types:** - -- **Model streams** - Direct `AIMessageChunk` streams from `model.stream()` -- **LangGraph streams** - Streams with `streamMode: ['values', 'messages']`, or `['values', 'messages', 'tools']` for tool progress -- **streamEvents** - Event streams from `agent.streamEvents()` or `model.streamEvents()` - -**Supported LangGraph stream events:** - -- `messages` - Streaming message chunks (text, tool calls) -- `values` - State updates that finalize pending message chunks -- `tools` - Tool progress events (`on_tool_event` emits preliminary tool output with `preliminary: true`, final `on_tool_end` emits final output) -- `custom` - Custom data events (emitted as `data-{type}` chunks) - -**Supported streamEvents events:** - -- `on_chat_model_stream` - Token streaming from chat models -- `on_tool_start` - Tool execution start -- `on_tool_end` - Tool execution end with output - -### `LangSmithDeploymentTransport` - -A `ChatTransport` implementation for LangSmith/LangGraph deployments. - -**Constructor Parameters:** - -- `options`: `LangSmithDeploymentTransportOptions` - Configuration for the RemoteGraph connection - - `url`: `string` - LangSmith deployment URL or local server URL - - `apiKey?`: `string` - API key for authentication (optional for local development) - - `graphId?`: `string` - The ID of the graph to connect to (defaults to `'agent'`) - -**Implements:** `ChatTransport` - -## Documentation - -Please check out the [AI SDK documentation](https://ai-sdk.dev) for more information. +See the [LangChain Adapter documentation](https://ai-sdk.dev/providers/adapters/langchain) for more information. diff --git a/packages/llamaindex/README.md b/packages/llamaindex/README.md index e811a16ee7db..ed2c0efeeb8d 100644 --- a/packages/llamaindex/README.md +++ b/packages/llamaindex/README.md @@ -1,3 +1,37 @@ # AI SDK - LlamaIndex Adapter This package contains a LlamaIndex adapter for the AI SDK. + +## Setup + +```bash +npm i ai @ai-sdk/llamaindex llamaindex +``` + +## Usage + +```tsx +import { OpenAI, SimpleChatEngine } from 'llamaindex'; +import { toUIMessageStream } from '@ai-sdk/llamaindex'; +import { createUIMessageStreamResponse } from 'ai'; + +export const maxDuration = 60; + +export async function POST(req: Request) { + const { prompt } = await req.json(); + + const llm = new OpenAI({ model: 'gpt-6-astra' }); + const chatEngine = new SimpleChatEngine({ llm }); + + const stream = await chatEngine.chat({ + message: prompt, + stream: true, + }); + + return createUIMessageStreamResponse({ + stream: toUIMessageStream(stream), + }); +} +``` + +See the [LlamaIndex documentation](https://ai-sdk.dev/providers/adapters/llamaindex) for more information. diff --git a/packages/luma/README.md b/packages/luma/README.md index 2a786ca23e88..4ff2bcdb0b4d 100644 --- a/packages/luma/README.md +++ b/packages/luma/README.md @@ -2,26 +2,12 @@ The **Luma provider** for the [AI SDK](https://ai-sdk.dev/docs) contains support for Luma AI's state-of-the-art image generation models - Photon and Photon Flash. -## About Luma Photon Models - -Luma Photon and Photon Flash are groundbreaking image generation models that deliver: - -- Ultra-high quality image generation -- 10x higher cost efficiency compared to similar models -- Superior prompt understanding and adherence -- Unique character consistency capabilities from single reference images -- Multi-image reference support for precise style matching - -For more detailed information about the Luma models and their capabilities, please visit [Luma AI](https://lumalabs.ai/). - > **Deploying to Vercel?** With Vercel's AI Gateway you can access Luma (and hundreds of models from other providers) — no additional packages, API keys, or extra cost. [Get started with AI Gateway](https://vercel.com/ai-gateway). ## Setup -The Luma provider is available in the `@ai-sdk/luma` module. You can install it with: - ```bash -npm i @ai-sdk/luma +npm i ai @ai-sdk/luma ``` ## Skill for Coding Agents @@ -32,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `luma` from `@ai-sdk/luma`: - -```ts -import { luma } from '@ai-sdk/luma'; -``` - -## Image Generation Example +## Usage ```ts import { luma } from '@ai-sdk/luma'; @@ -57,6 +35,4 @@ fs.writeFileSync(filename, image.uint8Array); console.log(`Image saved to ${filename}`); ``` -## Documentation - -Please check out the **[Luma provider](https://ai-sdk.dev/providers/ai-sdk-providers/luma)** for more information. +See the [Luma Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/luma) for more information. diff --git a/packages/mcp/README.md b/packages/mcp/README.md index 00c95040c2f9..069f7681162a 100644 --- a/packages/mcp/README.md +++ b/packages/mcp/README.md @@ -6,10 +6,8 @@ tools with AI SDK functions like `generateText` and `streamText`. ## Setup -The MCP client is available in the `@ai-sdk/mcp` module. You can install it with - ```bash -npm i @ai-sdk/mcp ai zod +npm i ai @ai-sdk/mcp ``` ## Skill for Coding Agents @@ -23,9 +21,6 @@ npx skills add vercel/ai ## Usage -Create an MCP client with `createMCPClient()`, fetch the server tools with -`mcpClient.tools()`, and pass them to an AI SDK call: - ```ts import { createMCPClient } from '@ai-sdk/mcp'; import { generateText, isStepCount } from 'ai'; @@ -56,143 +51,4 @@ try { } ``` -The client converts MCP tool definitions into AI SDK tools, so model calls can -use them through the standard `tools` option. - -## Experimental webhook events - -Use `list`, `subscribe`, `refresh`, and `unsubscribe` through -`client.experimental_events` on the same `createMCPClient` instance. Configure -`experimental_events: { store }` with private durable storage shared with -`experimental_createMCPEventWebhook`, which you mount at your callback URL. - -Subscription creation persists `delivery.url` and the generated signing secret -before contacting the server, enabling signed callback verification during the -subscribe request. The receiver verifies raw request bytes and checks event -envelopes before invoking your handler. Optional callbacks let your application -validate filters and event data. Agent execution and durable deduplication -remain application concerns; closing the client does not unsubscribe. - -See the [MCP Events guide](https://ai-sdk.dev/docs/ai-sdk-core/mcp-events) and the -[local server/client example](../../examples/mcp/src/events/README.md). - -## Protocol versions - -The client supports legacy MCP protocol versions through the `initialize` -handshake and MCP `2026-07-28` through stateless protocol discovery. The -built-in stdio transport probes with `server/discover` and falls back to the -legacy handshake when connected to an older server. - -Custom transports can opt into the same negotiation by setting -`supportsProtocolVersionDiscovery` to `true`. Modern requests include the -protocol version, client capabilities, and client information in `_meta`. - -For streaming responses, close the MCP client when the stream finishes: - -```ts -import { createMCPClient } from '@ai-sdk/mcp'; -import { streamText } from 'ai'; - -const mcpClient = await createMCPClient({ - transport: { - type: 'http', - url: 'https://your-server.com/mcp', - }, -}); - -const result = streamText({ - model: 'openai/gpt-6-astra', - tools: await mcpClient.tools(), - prompt: 'Use the available tools to answer the user question.', - onEnd: async () => { - await mcpClient.close(); - }, -}); - -for await (const textPart of result.textStream) { - process.stdout.write(textPart); -} -``` - -## Transports - -HTTP is recommended for production deployments: - -Session persistence applies only to legacy MCP protocol versions. MCP -`2026-07-28` is stateless and does not use session ids or cached initialize -results. - -```ts -import { createMCPClient } from '@ai-sdk/mcp'; - -const savedSession = await loadMcpSession(); -let currentSessionId = savedSession?.sessionId; - -const mcpClient = await createMCPClient({ - transport: { - type: 'http', - url: 'https://your-server.com/mcp', - initialSessionId: savedSession?.sessionId, - initialProtocolVersion: savedSession?.initializeResult.protocolVersion, - terminateSessionOnClose: false, - onSessionIdChange: sessionId => { - currentSessionId = sessionId; - }, - onSessionExpired: sessionId => { - if (currentSessionId === sessionId) { - currentSessionId = undefined; - void clearMcpSession(); - } - }, - }, - initialInitializeResult: savedSession?.initializeResult, -}); - -if (currentSessionId) { - await saveMcpSession({ - sessionId: currentSessionId, - initializeResult: mcpClient.initializeResult, - }); -} -``` - -SSE is also supported for MCP servers that use Server-Sent Events: - -```ts -const mcpClient = await createMCPClient({ - transport: { - type: 'sse', - url: 'https://your-server.com/sse', - }, -}); -``` - -For local MCP servers, you can use stdio transport from the `@ai-sdk/mcp/mcp-stdio` -subpath: - -```ts -import { createMCPClient } from '@ai-sdk/mcp'; -import { Experimental_StdioMCPTransport } from '@ai-sdk/mcp/mcp-stdio'; - -const mcpClient = await createMCPClient({ - transport: new Experimental_StdioMCPTransport({ - command: 'node', - args: ['server.js'], - }), -}); -``` - -## Documentation - -Please check out the -[AI SDK MCP documentation](https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools) for -more information. - -Managed backends can implement `Experimental_MCPEventAdapter` and configure -`experimental_events: { adapter }` instead of a store. Its `createAdapter()` -method receives `{ transport }` metadata (HTTP/SSE type and URL, or -`{ type: 'custom' }` for custom transports) and returns `Experimental_MCPEventOperations` -bound to the authorized account. Catalog discovery still -uses the authenticated MCP transport; subscribe/get/list/unsubscribe delegate -to the backend, which owns renewal and webhook delivery. Managed clients do not -expose `refresh()`. See the [managed subscription reference](https://ai-sdk.dev/docs/reference/ai-sdk-core/mcp-events#managed-subscriptions). +See the [Model Context Protocol Client documentation](https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools) for more information. diff --git a/packages/minimax/README.md b/packages/minimax/README.md index fe74ee8822a4..45359bb163c8 100644 --- a/packages/minimax/README.md +++ b/packages/minimax/README.md @@ -6,10 +6,8 @@ The **[MiniMax provider](https://ai-sdk.dev/providers/ai-sdk-providers/minimax)* ## Setup -The MiniMax provider is available in the `@ai-sdk/minimax` module. You can install it with - ```bash -npm i @ai-sdk/minimax +npm i ai @ai-sdk/minimax ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `minimax` from `@ai-sdk/minimax`: - -```ts -import { minimax } from '@ai-sdk/minimax'; -``` - -## Language Model Example +## Usage ```ts import { minimax } from '@ai-sdk/minimax'; @@ -40,37 +30,4 @@ const { text } = await generateText({ }); ``` -## Thinking Mode Example - -```ts -import { minimax } from '@ai-sdk/minimax'; -import { generateText } from 'ai'; - -const { text } = await generateText({ - model: minimax('minimax-m3'), - prompt: 'Solve this problem step by step: What is 15% of 240?', - providerOptions: { - minimax: { - thinking: { type: 'adaptive' }, - }, - }, -}); -``` - -## Video Generation Example - -```ts -import { minimax } from '@ai-sdk/minimax'; -import { experimental_generateVideo as generateVideo } from 'ai'; - -const { video } = await generateVideo({ - model: minimax.video('MiniMax-H3'), - prompt: 'A white kitten chases a butterfly across a sunlit garden.', - aspectRatio: '16:9', - duration: 5, -}); -``` - -## Documentation - -Please check out the **[MiniMax provider](https://ai-sdk.dev/providers/ai-sdk-providers/minimax)** for more information. +See the [MiniMax Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/minimax) for more information. diff --git a/packages/mistral/README.md b/packages/mistral/README.md index 53e6f05ae53a..44797bd08db5 100644 --- a/packages/mistral/README.md +++ b/packages/mistral/README.md @@ -6,10 +6,8 @@ The **[Mistral provider](https://ai-sdk.dev/providers/ai-sdk-providers/mistral)* ## Setup -The Mistral provider is available in the `@ai-sdk/mistral` module. You can install it with - ```bash -npm i @ai-sdk/mistral +npm i ai @ai-sdk/mistral ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `mistral` from `@ai-sdk/mistral`: - -```ts -import { mistral } from '@ai-sdk/mistral'; -``` - -## Example +## Usage ```ts import { mistral } from '@ai-sdk/mistral'; @@ -40,6 +30,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Mistral provider](https://ai-sdk.dev/providers/ai-sdk-providers/mistral)** for more information. +See the [Mistral Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/mistral) for more information. diff --git a/packages/moonshotai/README.md b/packages/moonshotai/README.md index 8fe540756131..4f6c8ea4ca7c 100644 --- a/packages/moonshotai/README.md +++ b/packages/moonshotai/README.md @@ -6,10 +6,8 @@ The **[Moonshot AI provider](https://ai-sdk.dev/providers/ai-sdk-providers/moons ## Setup -The Moonshot AI provider is available in the `@ai-sdk/moonshotai` module. You can install it with - ```bash -npm i @ai-sdk/moonshotai +npm i ai @ai-sdk/moonshotai ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `moonshotai` from `@ai-sdk/moonshotai`: - -```ts -import { moonshotai } from '@ai-sdk/moonshotai'; -``` - -## Language Model Example +## Usage ```ts import { moonshotai } from '@ai-sdk/moonshotai'; @@ -40,58 +30,4 @@ const { text } = await generateText({ }); ``` -## Reasoning Effort Example (Kimi K3) - -```ts -import { - moonshotai, - type MoonshotAILanguageModelOptions, -} from '@ai-sdk/moonshotai'; -import { generateText } from 'ai'; - -const { text, reasoningText } = await generateText({ - model: moonshotai('kimi-k3'), - prompt: 'Solve this problem step by step: What is 15% of 240?', - providerOptions: { - moonshotai: { - reasoningEffort: 'high', - } satisfies MoonshotAILanguageModelOptions, - }, -}); - -console.log(reasoningText); -console.log(text); -``` - -Kimi K2.6 supports thinking and non-thinking modes. Enable it with -`thinking: { type: 'enabled' }` or disable it with -`thinking: { type: 'disabled' }`. - -Kimi K2.7 Code always has thinking enabled and uses Preserved Thinking. Keep -reasoning history in multi-turn conversations: - -```ts -import { - moonshotai, - type MoonshotAILanguageModelOptions, -} from '@ai-sdk/moonshotai'; -import { generateText } from 'ai'; - -const { text, reasoningText } = await generateText({ - model: moonshotai('kimi-k2.7-code'), - prompt: 'Solve this problem step by step: What is 15% of 240?', - providerOptions: { - moonshotai: { - thinking: { type: 'enabled' }, - reasoningHistory: 'preserved', - } satisfies MoonshotAILanguageModelOptions, - }, -}); - -console.log(reasoningText); -console.log(text); -``` - -## Documentation - -Please check out the **[Moonshot AI provider](https://ai-sdk.dev/providers/ai-sdk-providers/moonshotai)** for more information. +See the [Moonshot AI Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/moonshotai) for more information. diff --git a/packages/open-responses/README.md b/packages/open-responses/README.md index 0938c1c765f7..b7e294fbf54f 100644 --- a/packages/open-responses/README.md +++ b/packages/open-responses/README.md @@ -5,10 +5,8 @@ contains language model support for [Open Responses](https://www.openresponses.o ## Setup -The Open Responses provider is available in the `@ai-sdk/open-responses` module. You can install it with - ```bash -npm i @ai-sdk/open-responses +npm i ai @ai-sdk/open-responses ``` ## Skill for Coding Agents @@ -19,22 +17,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -Create an Open Responses provider instance using `createOpenResponses`: - -```ts -import { createOpenResponses } from '@ai-sdk/open-responses'; - -const openResponses = createOpenResponses({ - name: 'aProvider', - url: 'http://localhost:1234/v1/responses', -}); -``` - -You can use this instance to access models served by any Open Responses compatible endpoint. - -## Example +## Usage ```ts import { createOpenResponses } from '@ai-sdk/open-responses'; @@ -52,6 +35,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Open Responses provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/open-responses)** for more information. +See the [Open Responses Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/open-responses) for more information. diff --git a/packages/openai-compatible/README.md b/packages/openai-compatible/README.md index 89c7080b5a89..3a167a9b9649 100644 --- a/packages/openai-compatible/README.md +++ b/packages/openai-compatible/README.md @@ -2,16 +2,12 @@ This package provides a foundation for implementing providers that expose an OpenAI-compatible API. -The primary [OpenAI provider](../openai/README.md) is more feature-rich, including OpenAI-specific experimental and legacy features. This package offers a lighter-weight alternative focused on core OpenAI-compatible functionality. - > **Deploying to Vercel?** With Vercel's AI Gateway you can access hundreds of models from any provider — no additional packages, API keys, or extra cost. [Get started with AI Gateway](https://vercel.com/ai-gateway). ## Setup -The provider is available in the `@ai-sdk/openai-compatible` module. You can install it with - ```bash -npm i @ai-sdk/openai-compatible +npm i ai @ai-sdk/openai-compatible ``` ## Skill for Coding Agents @@ -22,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the provider creation method `createOpenAICompatible` from `@ai-sdk/openai-compatible`: - -```ts -import { createOpenAICompatible } from '@ai-sdk/openai-compatible'; -``` - -## Example +## Usage ```ts import { createOpenAICompatible } from '@ai-sdk/openai-compatible'; @@ -46,65 +34,4 @@ const { text } = await generateText({ }); ``` -### Customizing headers - -You can further customize headers if desired. For example, here is an alternate implementation to pass along api key authentication: - -```ts -import { createOpenAICompatible } from '@ai-sdk/openai-compatible'; -import { generateText } from 'ai'; - -const { text } = await generateText({ - model: createOpenAICompatible({ - baseURL: 'https://api.example.com/v1', - name: 'example', - headers: { - Authorization: `Bearer ${process.env.MY_API_KEY}`, - }, - }).chatModel('meta-llama/Llama-3-70b-chat-hf'), - prompt: 'Write a vegetarian lasagna recipe for 4 people.', -}); -``` - -### Including model ids for auto-completion - -```ts -import { createOpenAICompatible } from '@ai-sdk/openai-compatible'; -import { generateText } from 'ai'; - -type ExampleChatModelIds = - | 'meta-llama/Llama-3-70b-chat-hf' - | 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo' - | (string & {}); - -type ExampleCompletionModelIds = - | 'codellama/CodeLlama-34b-Instruct-hf' - | 'Qwen/Qwen2.5-Coder-32B-Instruct' - | (string & {}); - -type ExampleEmbeddingModelIds = - | 'BAAI/bge-large-en-v1.5' - | 'bert-base-uncased' - | (string & {}); - -const model = createOpenAICompatible< - ExampleChatModelIds, - ExampleCompletionModelIds, - ExampleEmbeddingModelIds ->({ - baseURL: 'https://api.example.com/v1', - name: 'example', - apiKey: process.env.MY_API_KEY, -}); - -// Subsequent calls to e.g. `model.chatModel` will auto-complete the model id -// from the list of `ExampleChatModelIds` while still allowing free-form -// strings as well. - -const { text } = await generateText({ - model: model.chatModel('meta-llama/Llama-3-70b-chat-hf'), - prompt: 'Write a vegetarian lasagna recipe for 4 people.', -}); -``` - -For more examples, see the [OpenAI Compatible Providers](https://ai-sdk.dev/providers/openai-compatible-providers) documentation. +See the [OpenAI Compatible Provider documentation](https://ai-sdk.dev/providers/openai-compatible-providers) for more information. diff --git a/packages/openai/README.md b/packages/openai/README.md index 0dc4cde716bc..2595b6fa79d2 100644 --- a/packages/openai/README.md +++ b/packages/openai/README.md @@ -7,10 +7,8 @@ contains language model support for the OpenAI chat and completion APIs and embe ## Setup -The OpenAI provider is available in the `@ai-sdk/openai` module. You can install it with - ```bash -npm i @ai-sdk/openai +npm i ai @ai-sdk/openai ``` ## Skill for Coding Agents @@ -21,15 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `openai` from `@ai-sdk/openai`: - -```ts -import { openai } from '@ai-sdk/openai'; -``` - -## Example +## Usage ```ts import { openai } from '@ai-sdk/openai'; @@ -41,31 +31,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -### Experimental realtime models - -Use the same factory for OpenAI Realtime and Live models: - -```ts -openai.experimental_realtime('gpt-realtime'); -openai.experimental_realtime('gpt-live-1'); -openai.experimental_realtime('not-yet-released', { api: 'live' }); -``` - -Live supports browser WSS sessions through an application-owned relay and -`experimental_useRealtime`, with client delegation: your application owns the -agent and tools. Optional browser-direct WebRTC is also available. Start with the -[OpenAI provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/openai#realtime-models) -for connection settings, startup options, and event mapping. - -The [`experimental_useRealtime` reference](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-realtime#continuous-conversations) -covers the JSON/PCM16 relay runtime, capture/playback controls, and application-handled -client delegation, plus `api.session` WebRTC setup and server-owned data-channel -permissions. Microphone capture requires browser permission; the application handles -client delegation and submits context on either transport. The -[Realtime guide](https://ai-sdk.dev/docs/ai-sdk-core/realtime) covers legacy token-based, -turn-based sessions. - -Runtime and provider authors can consult the repository's -[realtime integration notes](../../architecture/realtime-provider-integration.md). +See the [OpenAI Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/openai) for more information. diff --git a/packages/otel/README.md b/packages/otel/README.md index 40c958f44113..564e452ebeee 100644 --- a/packages/otel/README.md +++ b/packages/otel/README.md @@ -6,11 +6,8 @@ OpenTelemetry setup. ## Setup -The OpenTelemetry integration is available in the `@ai-sdk/otel` module. You can -install it with - ```bash -npm i @ai-sdk/otel +npm i ai @ai-sdk/otel ``` ## Skill for Coding Agents @@ -24,9 +21,6 @@ npx skills add vercel/ai ## Usage -Register the telemetry integration once at application startup with -`registerTelemetry()`: - ```ts import { OpenTelemetry } from '@ai-sdk/otel'; import { registerTelemetry } from 'ai'; @@ -34,86 +28,4 @@ import { registerTelemetry } from 'ai'; registerTelemetry(new OpenTelemetry()); ``` -For Next.js applications, place this in `instrumentation.ts` alongside your -OpenTelemetry provider setup. For Node.js applications, register it at the top -level of your entry file. - -Once registered, AI SDK calls emit telemetry events by default: - -```ts -import { generateText } from 'ai'; - -const result = await generateText({ - model: 'openai/gpt-6-astra', - prompt: 'Write a vegetarian lasagna recipe for 4 people.', - telemetry: { - functionId: 'recipe-generator', - }, -}); -``` - -You can opt out for an individual call with `telemetry.isEnabled`: - -```ts -const result = await generateText({ - model: 'openai/gpt-6-astra', - prompt: 'Write a vegetarian lasagna recipe for 4 people.', - telemetry: { - isEnabled: false, - }, -}); -``` - -## OpenTelemetry - -`OpenTelemetry` is the recommended integration. It emits spans that follow the -[OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). - -You can pass a custom tracer when you want to use a specific `TracerProvider`: - -```ts -import { OpenTelemetry } from '@ai-sdk/otel'; -import { registerTelemetry } from 'ai'; - -registerTelemetry( - new OpenTelemetry({ - tracer: tracerProvider.getTracer('gen_ai'), - }), -); -``` - -You can also add custom attributes to spans with `enrichSpan`: - -```ts -import { OpenTelemetry } from '@ai-sdk/otel'; -import { registerTelemetry } from 'ai'; - -registerTelemetry( - new OpenTelemetry({ - enrichSpan: ({ spanType, operationId, callId }) => ({ - 'my_app.span_type': spanType, - 'my_app.operation_id': operationId, - 'my_app.call_id': callId, - }), - }), -); -``` - -## Legacy Telemetry - -`LegacyOpenTelemetry` emits the older AI SDK-specific span format with `ai.*` -attributes. Use it when an existing observability integration depends on the -legacy span shape: - -```ts -import { LegacyOpenTelemetry } from '@ai-sdk/otel'; -import { registerTelemetry } from 'ai'; - -registerTelemetry(new LegacyOpenTelemetry()); -``` - -## Documentation - -Please check out the -[AI SDK telemetry documentation](https://ai-sdk.dev/docs/ai-sdk-core/telemetry) -for more information. +See the [OpenTelemetry documentation](https://ai-sdk.dev/docs/ai-sdk-core/telemetry) for more information. diff --git a/packages/perplexity/README.md b/packages/perplexity/README.md index 864ba86b70bd..fcba5b60a049 100644 --- a/packages/perplexity/README.md +++ b/packages/perplexity/README.md @@ -3,23 +3,12 @@ The **[Perplexity provider](https://ai-sdk.dev/providers/ai-sdk-providers/perplexity)** for the [AI SDK](https://ai-sdk.dev/docs) contains language model support for Perplexity's Agent API, including web search, citations, function tools, and structured output. -## Features - -- Real-time web search grounding for accurate, up-to-date responses -- Agent API presets from `fast` through `xhigh` -- Direct access to supported third-party models through Perplexity -- Native tools for web search, URL fetching, code execution, finance, MCP, and connectors -- AI SDK function tools, structured output, reasoning streams, and multi-turn tool calls -- Native Choice, Score, and Boolean decisions with probability distributions and image input - > **Deploying to Vercel?** With Vercel's AI Gateway you can access Perplexity (and hundreds of models from other providers) — no additional packages, API keys, or extra cost. [Get started with AI Gateway](https://vercel.com/ai-gateway). ## Setup -The Perplexity provider is available in the `@ai-sdk/perplexity` module. You can install it with: - ```bash -npm i @ai-sdk/perplexity +npm i ai @ai-sdk/perplexity ``` ## Skill for Coding Agents @@ -30,15 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `perplexity` from `@ai-sdk/perplexity`: - -```ts -import { perplexity } from '@ai-sdk/perplexity'; -``` - -## Example +## Usage ```ts import { perplexity } from '@ai-sdk/perplexity'; @@ -50,40 +31,4 @@ const { text } = await generateText({ }); ``` -Version 5 is a breaking migration from Sonar Chat Completions to the Agent API. -Legacy Sonar model IDs and provider options are not mapped. Review the -[migration notes](https://ai-sdk.dev/providers/ai-sdk-providers/perplexity#migrating-from-v4-sonar-to-v5-agent-api) -before upgrading an existing application. - -Perplexity supports Sonar Chat Completions only until September 27, 2026. -Remaining on version 4 will not preserve language generation after that date. -Migrate unsupported Sonar features using the alternatives in the migration notes. - -## Decisions - -```ts -import { perplexity } from '@ai-sdk/perplexity'; -import { experimental_decide as decide } from 'ai'; - -const result = await decide({ - model: perplexity.decisionModel('pplx-decider-latest'), - state: 'I was charged twice.', - questions: { - team: { - type: 'choice', - criteria: { billing: 'Payments and refunds', support: 'Other requests' }, - }, - }, -}); - -console.log(result.answers.team.choice); -console.log(result.answers.team.probabilities); -``` - -See [decision model documentation](https://ai-sdk.dev/providers/ai-sdk-providers/perplexity#decision-models) -for optional instructions, structured criteria, single-level Score rubrics, -images, limits, and provider metadata. - -## Documentation - -Please check out the **[Perplexity provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/perplexity)** for more information. +See the [Perplexity Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/perplexity) for more information. diff --git a/packages/policy-opa/README.md b/packages/policy-opa/README.md index ae801d5559de..c5b36bee655e 100644 --- a/packages/policy-opa/README.md +++ b/packages/policy-opa/README.md @@ -1,49 +1,14 @@ -# @ai-sdk/policy-opa +# Policy-Based Tool Approvals Policy-as-code authorization for AI SDK tool calls, powered by [Open Policy Agent](https://www.openpolicyagent.org/). -Write your "what can this agent do?" rules in a `.rego` file. Plug them into `generateText` / `streamText` / `ToolLoopAgent` as a `toolApproval` configuration. The SDK enforces them at every tool call, with the same wire format used by built-in approvals (`tool-approval-request` / `tool-approval-response`). +## Setup -## Why - -`toolApproval` in `ai` already supports three outcomes: `approved`, `denied`, and `user-approval` (the human-in-the-loop case). What it does not give you is a place to author the rules that does not require a code deploy. Authorization is the kind of thing where you want a written, testable artifact reviewed by the right people, not a function buried in your agent's setup code. - -This package fills that gap. Rules live in `.rego`. They are evaluated by OPA (in-process via WASM, or out-of-process via HTTP) and the result is mapped to the SDK's `ToolApprovalStatus`. Nothing new on the wire; everything sits on top of the existing public `toolApproval` callback. - -## Install - -```sh -pnpm add @ai-sdk/policy-opa -# pick one (or both) of the OPA backends: -pnpm add @open-policy-agent/opa-wasm # in-process WASM evaluation -pnpm add @open-policy-agent/opa # HTTP client to a running OPA server +```bash +npm i ai @ai-sdk/policy-opa @ai-sdk/anthropic ``` -The OPA backends are optional peer dependencies. The package only loads the one you import. - -## How it works - -Without policy: - -``` -model → tool call → tool.execute → result back to model -``` - -With policy: - -``` -model - → tool call - → toolApproval evaluates ──┬──► approved → tool.execute → result back to model - ├──► denied → tool-approval-response (auto, with reason) → model sees the denial - └──► user-approval → tool-approval-request → wait for human - → tool-approval-response on resume - → tool.execute or denial -``` - -The policy is consulted **before** every tool dispatch. Auto-deny does not require a human; user-approval pauses the run until a human responds with a `tool-approval-response`. The model sees the denial as a structured result on its next step and can reason about it (for example, "I can't drop that table, let me try something else"). - -## Quick start +## Usage ```ts import { generateText } from 'ai'; @@ -70,569 +35,4 @@ const result = await generateText({ }); ``` -## Writing the Rego policy - -The adapter expects the policy to emit a decision object with one of three `decision` values. `reason` is optional and gets surfaced back to the model (for `deny`) or to the human approver (for `requires-approval`). A manual approval request exposes it as `reason` in core results and as `approval.requestReason` in UI messages. - -```rego -package agent.call - -# Default to "not-applicable" so unmatched calls fall through to whatever -# behavior toolApproval has configured for them. Use { decision: "deny" } if -# you want to default-deny instead. -default decision := { "decision": "not-applicable" } - -# Hard deny: pushes are never allowed automatically. -decision := { "decision": "deny", "reason": "pushes require human review" } { - input.tool.name == "git" - input.args.args[0] == "push" -} - -# Auto-allow: read-only git operations. -decision := { "decision": "allow" } { - input.tool.name == "git" - input.args.args[0] in {"status", "log", "diff", "show"} -} - -# Human-in-the-loop: kubectl by oncall during business hours. -decision := { "decision": "requires-approval", "reason": "kubectl by oncall" } { - input.tool.name == "kubectl" - input.runtimeContext.role == "sre-oncall" -} -``` - -The adapter also accepts the legacy boolean shape (`{ "allow": true | false, "reason": "..." }`) so existing rules migrate without rewriting. - -### Errors fail closed - -If the backend itself errors (OPA server unreachable, WASM fault, a misbuilt bundle that yields no result), `opaPolicy` returns `{ type: 'denied' }` with the underlying message as the reason. The error never rejects out of the `toolApproval` callback and never aborts the run. A backend outage blocks the affected tool call rather than silently letting it through. This matches `opaCapabilityMiddleware`, which also fails closed. - -Present but unrecognized policy results, such as an unknown `decision` value or a non-boolean legacy `allow` value, also fail closed with a denied result. - -This is distinct from a Rego rule that returns no matching decision: `null` or `undefined` normalizes to `not-applicable` ("no opinion"), which the SDK treats as allow. Use `default decision := { "decision": "deny" }` in your policy if you want unmatched calls to be denied too. - -### What the adapter passes as `input` - -By default, the OPA input shape is: - -```jsonc -{ - "tool": { "name": "git" }, - "args": { "args": ["push", "origin", "main"] }, - "messages": [ - /* model messages for this generation */ - ], - "runtimeContext": { - /* whatever you passed as runtimeContext */ - }, -} -``` - -Override the shape with `toInput`: - -```ts -opaPolicy({ - client, - path: 'agent/call/decision', - toInput: ({ toolCall, runtimeContext }) => ({ - action: toolCall.toolName, - principal: runtimeContext.role, - resource: toolCall.input, - }), -}); -``` - -### Testing the policy - -OPA ships its own test framework: - -```rego -# policy_test.rego -package agent.call - -test_push_denied { - decision.decision == "deny" with input as { - "tool": { "name": "git" }, - "args": { "args": ["push", "origin", "main"] } - } -} - -test_status_allowed { - decision.decision == "allow" with input as { - "tool": { "name": "git" }, - "args": { "args": ["status"] } - } -} -``` - -Run `opa test policy.rego policy_test.rego`. These tests run in CI without involving the SDK at all, which is the main practical reason policy-as-code beats policy-in-application-code. - -## Loading the policy - -### Option A: WASM (in-process) - -Compile the `.rego` to WASM ahead of time: - -```sh -opa build -t wasm -e 'agent/call/decision' -o bundle.tar.gz policy.rego -tar -xzf bundle.tar.gz /policy.wasm -``` - -Load it at startup: - -```ts -import { wasmPolicyClient, opaPolicy } from '@ai-sdk/policy-opa'; -import { readFile } from 'node:fs/promises'; - -const wasm = await readFile('./policy.wasm'); -const client = await wasmPolicyClient({ wasm }); - -const toolApproval = opaPolicy({ client, path: 'agent/call/decision' }); -``` - -No network call per decision. Good fit when you ship the policy with the app, or fetch it from object storage at startup. Hot-reloading means rebuilding the WASM and re-instantiating the client. - -### Option B: HTTP (running OPA server) - -Run OPA somewhere: - -```yaml -# docker-compose.yml -services: - opa: - image: openpolicyagent/opa:latest - command: ['run', '--server', '--addr', ':8181', '/policies'] - ports: ['8181:8181'] - volumes: ['./policies:/policies'] -``` - -Point the client at it: - -```ts -import { httpPolicyClient, opaPolicy } from '@ai-sdk/policy-opa'; - -const client = httpPolicyClient({ url: 'http://localhost:8181' }); -const toolApproval = opaPolicy({ client, path: 'agent/call/decision' }); -``` - -One HTTP round-trip per decision. Good fit when policies change frequently and you want hot-reload without redeploying the app, or when multiple services share one OPA. Headers can be supplied for Styra DAS / EOPA authentication: - -```ts -httpPolicyClient({ - url: 'https://opa.internal', - headers: { Authorization: `Bearer ${token}` }, -}); -``` - -## Transitive enforcement: composite tools - -`toolApproval` only fires when the model calls a tool directly. Anywhere your agent has a coarse "dispatcher" tool that can perform many fine-grained actions, the model can bypass a per-action rule by going through the dispatcher. Classic example: the agent has a granular `git` tool that's gated, plus a coarse `bash` tool that isn't. `bash 'git push'` skips the `git` rule. - -The fix lives inside the dispatcher's `toolApproval` entry, not inside the tool's `execute`. Parse the dispatcher input down to a `(name, args)` pair, then evaluate it against the same rule the direct tool uses. The granular rule fires whether the model called the granular tool directly or routed through the dispatcher. - -To avoid writing the matching logic twice (once for the direct tool, once for the dispatcher), define it once and reuse it. Two forms work; pick whichever is easier to maintain for your codebase. - -### Form A: shared TypeScript predicate - -The matching logic lives in TS. Both approvals call the same predicate, varying only in how they extract `(name, args)` from the tool input. No OPA round-trip needed for the shared check, but you lose the policy-as-code authoring story for the rule itself. - -```ts -function deniedForAction(name: string, args: string[]): string | undefined { - if (name === 'git' && args[0] === 'push') { - return 'pushes require human review'; - } - return undefined; -} - -const toolApproval = ({ toolCall }) => { - if (toolCall.toolName === 'bash') { - const [name, ...args] = ( - toolCall.input as { command: string } - ).command.split(/\s+/); - const reason = deniedForAction(name, args); - if (reason) return { type: 'denied', reason }; - } - if (toolCall.toolName === 'git') { - const args = (toolCall.input as { args: string[] }).args; - const reason = deniedForAction('git', args); - if (reason) return { type: 'denied', reason }; - } - return 'approved'; -}; - -await generateText({ model, tools: { git, bash }, toolApproval, prompt }); -``` - -### Form B: shared Rego helper rule - -The matching logic lives in Rego. Both approvals call `opaPolicy` with the same `path`, varying only in how their `toInput` derives the `(kind, args)` pair. You get the authoring story (rules live in `.rego`, tested with `opa test`, reviewed independently), at the cost of one OPA evaluation per call. - -```rego -package agent.action - -# Shared helper: classifies a logical action regardless of which tool surface -# it arrived on. The dispatcher's toInput is responsible for setting -# `input.kind` and `input.args` consistently. -deny_reason["pushes require human review"] { - input.kind == "git" - input.args[0] == "push" -} - -decision := { "decision": "deny", "reason": r } { - r := deny_reason[_] -} -``` - -```ts -import { generateText } from 'ai'; -import { opaPolicy, wasmPolicyClient } from '@ai-sdk/policy-opa'; - -const client = await wasmPolicyClient({ wasm }); - -const gitApproval = opaPolicy({ - client, - path: 'agent/action/decision', - toInput: ({ toolCall }) => ({ - kind: 'git', - args: (toolCall.input as { args: string[] }).args, - }), -}); - -const bashApproval = opaPolicy({ - client, - path: 'agent/action/decision', - toInput: ({ toolCall }) => { - const { command } = toolCall.input as { command: string }; - const [bin, ...rest] = command.split(/\s+/); - return { kind: bin, args: rest }; - }, -}); - -await generateText({ - model, - tools: { git, bash }, - toolApproval: { - git: gitApproval, - bash: bashApproval, - }, - prompt, -}); -``` - -The patterns below are all the same five lines: derive a logical `(kind, args)` from the dispatcher input, ask OPA, return the SDK status. What changes per domain is only the parsing. - -### SQL meta-tool - -```ts -const sqlApproval = opaPolicy({ - client, - path: 'agent/action/decision', - toInput: ({ toolCall }) => { - const sql = (toolCall.input as { sql: string }).sql; - const verb = sql.trim().split(/\s+/)[0]?.toLowerCase(); // select | insert | delete | drop - return { kind: `db.${verb}`, sql }; - }, -}); -``` - -Rules like `input.kind == "db.delete"` or `input.kind == "db.drop"` fire whether the model called those granular tools directly or routed a `DROP TABLE` through `db.query`. For finer matches you can parse the statement with a SQL AST library and emit the affected tables in the input shape. - -### HTTP dispatcher - -```ts -const httpApproval = opaPolicy({ - client, - path: 'agent/action/decision', - toInput: ({ toolCall }) => { - const { method, url } = toolCall.input as { method: string; url: string }; - const u = new URL(url); - return { - kind: `http.${method.toLowerCase()}`, - host: u.host, - path: u.pathname, - }; - }, -}); -``` - -Rules can now match by host (`input.host == "api.production.internal"`), by method (`input.kind == "http.delete"`), or by both. - -### MCP proxy - -When an agent talks to an MCP server via a single `mcp.invoke` meta-tool, the server's entire surface arrives as one giant `*`-shaped capability. Narrow it back down inside the proxy's `toolApproval`: - -```ts -const mcpApproval = opaPolicy({ - client, - path: 'agent/action/decision', - toInput: ({ toolCall }) => { - const { name, input } = toolCall.input as { name: string; input: unknown }; - return { kind: `mcp.${name}`, args: input }; - }, -}); -``` - -A direct alternative is `wrapMcpTools` (below), which expands the MCP surface into per-tool entries so each one gets its own rule lookup; pick whichever model fits the way you discover and dispatch. - -### Browser dispatcher - -```ts -const browserApproval = opaPolicy({ - client, - path: 'agent/action/decision', - toInput: ({ toolCall }) => { - const { action, target } = toolCall.input as { - action: 'click' | 'type' | 'navigate'; - target: string; - }; - return { kind: `browser.${action}`, target }; - }, -}); -``` - -### Shell tool: gating git subcommands - -A `bash` tool (such as [vercel-labs/bash-tool](https://github.com/vercel-labs/bash-tool), input `{ command }`) can run any git operation, so the model could route a `git clone` or `git push` through it and skip a granular `git` rule. Gate it by parsing the command down to a git subcommand and deciding on that — and **deny anything you cannot reduce to a single clean git invocation**. Bash is adversarial to parse, so "can't prove it's safe" means "deny". - -```ts -// Returns the git invocation, or null if `command` is not a single clean git -// command. Shell metacharacters (&& || ; | redirects, subshells, substitution) -// return null so the policy fails closed. -function parseGitInvocation(command: string) { - if (/[;&|<>`$(){}\\\n]/.test(command)) return null; - const tokens = command.trim().split(/\s+/); - if (tokens[0] !== 'git' || tokens.length < 2) return null; - const [, subcommand, ...args] = tokens; - return { subcommand, args }; -} - -const bashApproval = opaPolicy({ - client, - path: 'agent/action/decision', - toInput: ({ toolCall }) => { - const { command } = toolCall.input as { command: string }; - const git = parseGitInvocation(command); - // Unparseable / non-git → kind:'bash' → the policy default-denies it. - return git - ? { kind: 'git', subcommand: git.subcommand, args: git.args } - : { kind: 'bash', command }; - }, -}); -``` - -The matching Rego allows only read-only git and denies the rest by default: - -```rego -package agent.action - -import rego.v1 - -# Subcommands that are read-only in every form. -git_read_only := {"status", "log", "diff", "show"} - -# Default deny covers clone, push, pull, fetch, reset, and every kind:"bash" -# the parser refused to vouch for. -default decision := {"decision": "deny", "reason": "command not permitted by policy"} - -decision := {"decision": "allow"} if { - input.kind == "git" - git_read_only[input.subcommand] -} - -decision := {"decision": "deny", "reason": msg} if { - input.kind == "git" - not git_read_only[input.subcommand] - msg := sprintf("git %s is not permitted (read-only git only)", [input.subcommand]) -} -``` - -Note the allowlist is the four subcommands that are read-only in _every_ form. `git branch` and `git remote` are deliberately left out: `git branch -D` deletes and `git remote update` fetches, so a subcommand-level allowlist is too coarse for them — they need an additional listing-form check on their args. The [`examples/git-in-bash`](./examples/git-in-bash) policy shows that check in full. - -A granular `git` tool shares the exact same rule, varying only in how it derives the action: - -```ts -const gitApproval = opaPolicy({ - client, - path: 'agent/action/decision', - toInput: ({ toolCall }) => { - const args = (toolCall.input as { args: string[] }).args; - return { kind: 'git', subcommand: args[0], args: args.slice(1) }; - }, -}); -``` - -So `git status` is allowed on both surfaces, `git clone …` is denied on both, and `cd /tmp && git clone …` (a compound bash command) is denied because the parser refuses it. A complete, runnable version — `policy.rego`, `policy_test.rego` (run with `opa test`), the parser and its tests, and a `generateText` demo — lives in [`examples/git-in-bash`](./examples/git-in-bash). For a stricter parser, swap the regex for a shell-aware tokenizer (e.g. `shell-quote`). - -### The honest limitation - -This approach gates dispatch at the model's call boundary: the agent asks to run `bash 'git push'`, the policy sees `{ kind: 'git', args: ['push'] }`, the call is denied before `bash.execute` is ever invoked. What it does **not** defend against is a tool that, once approved, performs additional side effects beyond what its input describes. If `bash.execute` runs `command` and then _also_ sends a side-channel HTTP request, no policy at the call boundary can stop it. - -The framework's job here is to give you one obvious place to write per-action authorization for the cases this design covers. For stronger guarantees against arbitrary side effects, run untrusted execution in an out-of-band sandbox (Vercel Sandbox, Firecracker, containers) and treat the sandbox boundary, not the tool boundary, as the trust frontier. - -## Optional policy: allow-all when no policy is configured - -Most apps load the policy from one source (a WASM bundle, a remote OPA server) and only want enforcement when that source is available. In local development, in CI, in a brand-new environment, you probably want the agent to just work without a policy file present. - -`optionalOpaPolicy` makes this case a one-liner: pass `client: undefined` and the helper returns `undefined`, which is the same as not passing `toolApproval` at all (the SDK approves every tool call). - -```ts -import { readFile } from 'node:fs/promises'; -import { optionalOpaPolicy, wasmPolicyClient } from '@ai-sdk/policy-opa'; - -const wasm = process.env.POLICY_WASM_PATH - ? await readFile(process.env.POLICY_WASM_PATH) - : undefined; - -const client = wasm ? await wasmPolicyClient({ wasm }) : undefined; - -const toolApproval = optionalOpaPolicy({ - client, - path: 'agent/call/decision', -}); - -await generateText({ model, tools, toolApproval, prompt }); -``` - -Behavior: - -- `POLICY_WASM_PATH` unset ➜ `client` is `undefined` ➜ `toolApproval` is `undefined` ➜ SDK allows all tool calls. The OPA modules are never loaded; lazy imports stay lazy. -- `POLICY_WASM_PATH` set ➜ policy loads, enforcement is on. - -A symmetric option exists for the HTTP backend: gate `httpPolicyClient({ url })` on whether `OPA_URL` is set. - -If you want stricter behavior (refuse to start without a policy), construct `opaPolicy` directly and let the missing-bytes case throw at startup. The "optional" framing is only for environments where you've intentionally decided absence means allow-all. - -## Rolling out a new policy safely: shadow mode - -Don't ship a new policy straight to enforce. The first version of any policy almost certainly denies things you didn't mean to deny, and you find out by breaking real agent runs. The fix is the same pattern Cloudflare uses for new rules and GitHub uses for new code-scanning checks: run the policy in **shadow mode** for a while, capture what it _would_ have decided, inspect, fix, then graduate. - -`shadow(approval, opts)` wraps any `ToolApprovalConfiguration`. The wrapped policy is evaluated normally and the decision is reported via `onDecision`, but the SDK is told the call is approved regardless of what the policy said. - -```ts -import { opaPolicy, shadow, wasmPolicyClient } from '@ai-sdk/policy-opa'; - -const client = await wasmPolicyClient({ wasm }); - -const toolApproval = shadow( - opaPolicy({ client, path: 'agent/call/decision' }), - { - enforce: process.env.ENFORCE_POLICY === 'true', - onDecision: event => { - logger.info('policy.decision', { - tool: event.toolCall.toolName, - decision: event.decision.type, - reason: event.decision.reason, - enforced: event.enforced, - wouldBlock: event.decision.type === 'denied', - }); - }, - }, -); - -await generateText({ model, tools, toolApproval, prompt }); -``` - -### Recommended rollout - -1. Write the policy. Test it locally with `opa test`. -2. Wrap it in `shadow(...)` with `enforce: false` (the default) and an `onDecision` callback wired to your normal log / metrics pipeline. -3. Run for a while in your real environment. Inspect events where `decision.type === 'denied'` or `'user-approval'`: these are the calls the policy _would_ have changed. -4. Fix anything wrong with the policy. Iterate from step 2. -5. When the only `denied` / `user-approval` events are ones you actually want, flip `enforce: true`. The policy is now load-bearing. - -Each event carries both the policy's verdict (`decision`) and what the SDK actually acted on (`effective`). In shadow mode they disagree whenever the policy returned anything other than approved; in enforce mode they always agree. Compare them in your dashboard to spot drift. - -### Telemetry semantics - -`onDecision` is fired **fire-and-forget**: a slow or throwing logger does not block tool execution and cannot break enforcement. Errors thrown from the callback are swallowed. The contract is "enforcement first, observability second." - -If you want the opposite (enforcement waits for the audit log to commit), call your logger from inside the underlying `toolApproval` instead of through `shadow`. - -## Defense in depth: capability scoping at the model boundary - -`toolApproval` enforces policy when the model **tries to call** a tool. `opaCapabilityMiddleware` enforces it earlier, before the model is even told the tool exists. This is defense in depth: if a bug or regression lets something slip through the call-time gate, the middleware still prevents the model from seeing the disallowed tool in its first place. - -```ts -import { wrapLanguageModel } from 'ai'; -import { wasmPolicyClient, opaCapabilityMiddleware } from '@ai-sdk/policy-opa'; - -const client = await wasmPolicyClient({ wasm }); - -const wrappedModel = wrapLanguageModel({ - model: anthropic('claude-sonnet-5-5'), - middleware: opaCapabilityMiddleware({ - client, - path: 'agent/tools/allowed', - }), -}); - -await generateText({ model: wrappedModel, tools, toolApproval, prompt }); -``` - -The Rego rule at `path` returns either a `string[]` of allowed tool names or `{ tools: string[] }`. Function tools are matched by `name`; provider tools are matched by either their dotted `id` (`.`) or their bare `name`, so an allowlist authored with the plain name keeps them. Anything not in the allowlist gets dropped before the model sees the list. - -Two non-obvious benefits beyond the security one: - -- **Token savings.** The model doesn't read descriptions for tools it cannot call. -- **Better jailbreak rejection.** When the model is steered toward a denied tool, it responds with "I don't have access to that" rather than producing a tool call that gets blocked by `toolApproval`, which reads as friendlier in chat UIs. - -### Failure mode - -On a malformed OPA response or an evaluator error, the middleware **fails closed**: `params.tools` is set to `undefined`, so the model is told it has no tools available at all. Misconfiguration should not silently widen the agent's capability surface. If you want fail-open behavior, write the policy fallback in Rego (e.g., a default rule that returns the full tool list) rather than in the middleware. - -## Scoping a discovered tool surface - -When tools come from somewhere external (MCP discovery, a plugin registry, a remote agent catalog) you do not get to write per-tool rules ahead of time. You don't know which tools the server will expose until runtime. The risk: any tool you forgot to write a rule for is silently allowed. - -`wrapMcpTools` closes that gap by making the resulting `toolApproval` configuration **total** over the discovered surface. Any tool the supplied approval does not match falls through to a configurable default: - -```ts -import { opaPolicy, wasmPolicyClient, wrapMcpTools } from '@ai-sdk/policy-opa'; - -const discovered = await mcpClient.tools(); -const client = await wasmPolicyClient({ wasm }); - -const { tools, toolApproval } = wrapMcpTools( - discovered, - opaPolicy({ client, path: 'agent/call/decision' }), - { default: 'user-approval' }, // anything OPA does not match needs a human -); - -await generateText({ model, tools, toolApproval, prompt }); -``` - -Three useful defaults: - -- `'user-approval'` (the default): uncovered tools require a human. Right choice when you trust the discovery source but want a safety net for tools you forgot about. -- `'denied'`: uncovered tools are blocked. Right choice for hard allowlist mode: the OPA policy enumerates what's allowed; everything else is rejected before the model can call it. -- `'approved'`: uncovered tools are allowed. Right choice only when the discovery source is fully trusted (rare; usually the wrong call for MCP). - -Despite the name, the helper works on any `Record`, not just MCP-discovered tools. - -## API - -Everything is exported from the package root, `@ai-sdk/policy-opa`. - -### Engine-neutral core - -- `shadow(approval, opts?)`: wrap any `ToolApprovalConfiguration` so the policy is evaluated and reported via `onDecision`, but the SDK acts as if every call was approved. Flip `opts.enforce: true` to graduate to real enforcement. Recommended starting point for any new policy. -- `wrapMcpTools(tools, approval, opts?)`: bundle a discovered tool set with a fallback approval policy so the resulting `toolApproval` configuration is total over the discovered surface. `opts.default` controls what happens to tools the supplied approval does not match (`'user-approval'` by default; use `'denied'` for hard allowlist mode). -- `PolicyClient`: interface implemented by the OPA backends. Use directly if you want to plug in a non-OPA engine. -- Helper types: `PolicyDecision`, `WrappedMcpTools`, `PolicyDecisionEvent`. - -### OPA backend and adapters - -- `wasmPolicyClient({ wasm, data? })`: async; loads a compiled OPA WASM bundle in-process. Optional `data` is passed to `setData` if the bundle exposes it. -- `httpPolicyClient({ url, headers? })`: sync; constructs a client against a running OPA server. -- `opaPolicy({ client, path, toInput? })`: returns a `ToolApprovalConfiguration` you pass to `generateText` / `streamText` / `ToolLoopAgent`. Fails closed (denies) if the backend errors. -- `optionalOpaPolicy({ client, path, toInput? })`: like `opaPolicy` but returns `undefined` when `client` is `undefined`, for environments where the policy file is optional and absence means allow-all. -- `opaCapabilityMiddleware({ client, path, toInput? })`: returns a `LanguageModelV4Middleware` that narrows `params.tools` to an OPA-supplied allowlist before the model sees them. Fails closed on malformed responses. -- `normalizeOpaDecision(result)`: exposed for users who want to call OPA themselves and just need the result normalization. - -## Versioning - -This package follows the AI SDK's release cadence. `peerDependencies` pins `ai` to the workspace version; the OPA backends are versioned independently. - -## License - -Apache-2.0. +See the [Policy-Based Tool Approvals documentation](https://ai-sdk.dev/docs/agents/policy-tool-approvals) for more information. diff --git a/packages/prodia/README.md b/packages/prodia/README.md index 73a5471868cf..bdef38de98f7 100644 --- a/packages/prodia/README.md +++ b/packages/prodia/README.md @@ -6,10 +6,8 @@ The **[Prodia provider](https://ai-sdk.dev/providers/ai-sdk-providers/prodia)** ## Setup -The Prodia provider is available in the `@ai-sdk/prodia` module. You can install it with - ```bash -pnpm add @ai-sdk/prodia +npm i ai @ai-sdk/prodia ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `prodia` from `@ai-sdk/prodia`: - -```ts -import { prodia } from '@ai-sdk/prodia'; -``` - -## Image Generation Example +## Usage ```ts import fs from 'node:fs'; @@ -45,40 +35,4 @@ fs.writeFileSync(filename, image.uint8Array); console.log(`Image saved to ${filename}`); ``` -## Additional Options - -If you want to pass additional inputs to the model besides the prompt, use the `providerOptions.prodia` property: - -```ts -import { prodia, type ProdiaImageProviderOptions } from '@ai-sdk/prodia'; -import { generateImage } from 'ai'; - -const { image } = await generateImage({ - model: prodia.image('inference.flux-fast.schnell.txt2img.v2'), - prompt: 'A cat wearing an intricate robe', - providerOptions: { - prodia: { - width: 1024, - height: 1024, - steps: 4, - } satisfies ProdiaImageProviderOptions, - }, -}); -``` - -## Configuring Base URL - -By default, the provider uses `https://inference.prodia.com/v2`. You can override this if needed: - -```ts -import { createProdia } from '@ai-sdk/prodia'; - -const prodia = createProdia({ - baseURL: 'https://inference.prodia.com/v2', - apiKey: process.env.PRODIA_TOKEN, -}); -``` - -## Documentation - -See the [Prodia provider](https://ai-sdk.dev/providers/ai-sdk-providers/prodia) for more information. +See the [Prodia Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/prodia) for more information. diff --git a/packages/quiverai/README.md b/packages/quiverai/README.md index 486a494e7506..9479a2f73965 100644 --- a/packages/quiverai/README.md +++ b/packages/quiverai/README.md @@ -6,10 +6,8 @@ The **QuiverAI provider** for the [AI SDK](https://ai-sdk.dev/docs) adds Arrow l ## Setup -The QuiverAI provider is available in the `@ai-sdk/quiverai` module. You can install it with: - ```bash -npm i @ai-sdk/quiverai +npm i ai @ai-sdk/quiverai ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `quiverai` from `@ai-sdk/quiverai`: - -```ts -import { quiverai } from '@ai-sdk/quiverai'; -``` - -## Image Generation Example +## Usage ```ts import { quiverai } from '@ai-sdk/quiverai'; @@ -45,20 +35,4 @@ fs.writeFileSync(filename, image.uint8Array); console.log(`Image saved to ${filename}`); ``` -## Text Generation Example - -```ts -import { quiverai } from '@ai-sdk/quiverai'; -import { generateText } from 'ai'; - -const { text } = await generateText({ - model: quiverai('arrow-2'), - prompt: 'Design a simple compass icon and explain the visual choices.', -}); - -console.log(text); -``` - -## Documentation - -Please check out the **[QuiverAI provider](https://ai-sdk.dev/providers/ai-sdk-providers/quiverai)** for more information. +See the [QuiverAI Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/quiverai) for more information. diff --git a/packages/react/README.md b/packages/react/README.md index 798ffc26822c..0dca1d7fdd00 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -2,6 +2,62 @@ [React](https://react.dev/) UI components for the [AI SDK](https://ai-sdk.dev/docs): -- [`useChat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) hook -- [`useCompletion`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-completion) hook -- [`useObject`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-object) hook +## Setup + +```bash +npm i ai @ai-sdk/react +``` + +## Usage + +```tsx +'use client'; + +import { useChat } from '@ai-sdk/react'; +import { DefaultChatTransport } from 'ai'; +import { useState } from 'react'; + +export default function Page() { + const { messages, sendMessage, status } = useChat({ + transport: new DefaultChatTransport({ + api: '/api/chat', + }), + }); + const [input, setInput] = useState(''); + + return ( + <> + {messages.map(message => ( +
+ {message.role === 'user' ? 'User: ' : 'AI: '} + {message.parts.map((part, index) => + part.type === 'text' ? {part.text} : null, + )} +
+ ))} + +
{ + e.preventDefault(); + if (input.trim()) { + sendMessage({ text: input }); + setInput(''); + } + }} + > + setInput(e.target.value)} + disabled={status !== 'ready'} + placeholder="Say something..." + /> + +
+ + ); +} +``` + +See the [React documentation](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot) for more information. diff --git a/packages/replicate/README.md b/packages/replicate/README.md index 66bef18a4a8a..170a59a2b5f5 100644 --- a/packages/replicate/README.md +++ b/packages/replicate/README.md @@ -6,10 +6,8 @@ The **[Replicate provider](https://ai-sdk.dev/providers/ai-sdk-providers/replica ## Setup -The Replicate provider is available in the `@ai-sdk/replicate` module. You can install it with - ```bash -npm i @ai-sdk/replicate +npm i ai @ai-sdk/replicate ``` ## Skill for Coding Agents @@ -36,21 +34,4 @@ fs.writeFileSync(filename, image.uint8Array); console.log(`Image saved to ${filename}`); ``` -If you want to pass additional inputs to the model besides the prompt, use the `providerOptions.replicate` property: - -```ts -const { image } = await generateImage({ - model: replicate.image('recraft-ai/recraft-v3'), - prompt: 'The Loch Ness Monster getting a manicure', - size: '1365x1024', - providerOptions: { - replicate: { - style: 'realistic_image', - }, - }, -}); -``` - -## Documentation - -Please check out the **[Replicate provider](https://ai-sdk.dev/providers/ai-sdk-providers/replicate)** for more information. +See the [Replicate Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/replicate) for more information. diff --git a/packages/revai/README.md b/packages/revai/README.md index 58e703b22821..0b7f4a699c9d 100644 --- a/packages/revai/README.md +++ b/packages/revai/README.md @@ -7,10 +7,8 @@ contains language model support for the Rev.ai transcription API. ## Setup -The Rev.ai provider is available in the `@ai-sdk/revai` module. You can install it with - ```bash -npm i @ai-sdk/revai +npm i ai @ai-sdk/revai ``` ## Skill for Coding Agents @@ -21,15 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `revai` from `@ai-sdk/revai`: - -```ts -import { revai } from '@ai-sdk/revai'; -``` - -## Example +## Usage ```ts import { revai } from '@ai-sdk/revai'; @@ -43,6 +33,4 @@ const { text } = await transcribe({ }); ``` -## Documentation - -Please check out the **[Rev.ai provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/revai)** for more information. +See the [Rev.ai Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/revai) for more information. diff --git a/packages/rsc/README.md b/packages/rsc/README.md index eeed2f536ed2..1abdd4bfb5c2 100644 --- a/packages/rsc/README.md +++ b/packages/rsc/README.md @@ -1,3 +1,31 @@ # AI SDK: React Server Components [React Server Components](https://react.dev/reference/rsc/server-components) for the [AI SDK](https://ai-sdk.dev/docs): + +## Setup + +```bash +npm i @ai-sdk/rsc +``` + +## Usage + +```tsx +'use server'; + +import { createStreamableUI } from '@ai-sdk/rsc'; + +export async function getWeather() { + const weatherUI = createStreamableUI(); + + weatherUI.update(
Loading...
); + + setTimeout(() => { + weatherUI.done(
It's a sunny day!
); + }, 1000); + + return weatherUI.value; +} +``` + +See the [React Server Components documentation](https://ai-sdk.dev/docs/ai-sdk-rsc/overview) for more information. diff --git a/packages/sandbox-just-bash/README.md b/packages/sandbox-just-bash/README.md index e6457ccc0bf8..6300133800f8 100644 --- a/packages/sandbox-just-bash/README.md +++ b/packages/sandbox-just-bash/README.md @@ -1,10 +1,8 @@ # AI SDK - just-bash Sandbox -_This package is **experimental**._ - Sandbox session implementation for [`just-bash`](https://github.com/vercel-labs/just-bash), an in-process JavaScript bash environment with a virtual filesystem. -`just-bash` sandboxes do not expose ports, so they cannot be used with features that require actual network sandboxes. +-> **Note**: This package is experimental. ## Setup @@ -14,8 +12,6 @@ npm i @ai-sdk/sandbox-just-bash ## Usage -Each creation produces a fresh in-memory sandbox and applies an optional harness template. - ```ts import { createJustBashNetworkSandboxSession } from '@ai-sdk/sandbox-just-bash'; @@ -33,8 +29,4 @@ console.log(stdout); // "hi" await networkSandboxSession.destroy(); ``` -### Use cases - -- Create a fresh in-memory session with `createJustBashNetworkSandboxSession()` and pass it to `HarnessAgent.createSession({ sandboxSession })`. An optional `sandboxId` only labels its wrapper and cannot enforce uniqueness. -- Take a network sandbox session's process-restricted subset with `networkSandboxSession.restricted()` and use it with AI SDK tools that accept `experimental_sandbox`. -- Adapt an existing native `Sandbox` with `createJustBashSandboxSessionFromNativeSandbox(nativeSandbox)` for AI SDK tools. `resumeJustBashNetworkSandboxSession()` reports that cross-process resume is unsupported. +Sandbox adapters are typically used in combination with [first-party tools](https://ai-sdk.dev/docs/ai-sdk-core/tools) or [the `HarnessAgent` layer](https://ai-sdk.dev/docs/ai-sdk-harnesses/harness-agent). See these docs for more information. diff --git a/packages/sandbox-vercel/README.md b/packages/sandbox-vercel/README.md index 9e72816f597f..bcf963165f5a 100644 --- a/packages/sandbox-vercel/README.md +++ b/packages/sandbox-vercel/README.md @@ -1,9 +1,9 @@ # AI SDK - Vercel Sandbox -_This package is **experimental**._ - Sandbox session implementation for [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox). +-> **Note**: This package is experimental. + ## Setup ```bash @@ -30,17 +30,4 @@ console.log(stdout); // "hi" await networkSandboxSession.destroy(); ``` -### Use cases - -- Create a network sandbox session with `createVercelNetworkSandboxSession()` and pass it to `HarnessAgent.createSession({ sandboxSession })`. For reusable snapshots, pass `template: await agent.getSandboxTemplate()` to the creator function. -- Set `sandboxId` to name a new sandbox, or persist the returned session's `id`. Creation never resumes an existing sandbox and a conflicting name fails; use `resumeVercelNetworkSandboxSession({ sandboxId })` to reattach. -- Take a network sandbox session's process-restricted subset with `networkSandboxSession.restricted()` and use it with AI SDK tools that accept `experimental_sandbox`. -- Adapt an existing native `Sandbox` with `createVercelSandboxSessionFromNativeSandbox(nativeSandbox)` and use it with AI SDK tools that accept `experimental_sandbox`. - -## Authentication - -Vercel Sandbox accepts `VERCEL_OIDC_TOKEN`, or explicit `token`, `teamId`, and `projectId` settings. For local OIDC authentication, link the application with `vercel link`, run `vercel env pull`, and load the generated `.env.local` before starting it. - -## Request transformations and credential brokering - -Vercel Sandbox supports outbound request transformations for use cases such as credential brokering. `setRequestTransformations()` replaces the managed rules, while `addRequestTransformations()` adds rules without replacing unrelated rules. +Sandbox adapters are typically used in combination with [first-party tools](https://ai-sdk.dev/docs/ai-sdk-core/tools) or [the `HarnessAgent` layer](https://ai-sdk.dev/docs/ai-sdk-harnesses/harness-agent). See these docs for more information. diff --git a/packages/svelte/README.md b/packages/svelte/README.md index 7a87fc60ecf6..2255c57986cf 100644 --- a/packages/svelte/README.md +++ b/packages/svelte/README.md @@ -2,8 +2,48 @@ [Svelte](https://svelte.dev/) UI components for the [AI SDK](https://ai-sdk.dev/docs): -- [`Chat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) -- [`Completion`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-completion) -- [`StructuredObject`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-object) +## Setup -For information on the few ways the Svelte APIs differ from the React ones, see [the docs](https://ai-sdk.dev/docs/getting-started/svelte#how-does-ai-sdksvelte-differ-from-ai-sdkreact) +```bash +npm i ai @ai-sdk/svelte +``` + +## Usage + +```svelte + + +
+
    + {#each chat.messages as message, messageIndex (messageIndex)} +
  • +
    {message.role}
    +
    + {#each message.parts as part, partIndex (partIndex)} + {#if part.type === 'text'} +
    {part.text}
    + {/if} + {/each} +
    +
    • + {/each} +
+
+ + +
+
+``` + +See the [Svelte documentation](https://ai-sdk.dev/docs/getting-started/svelte) for more information. diff --git a/packages/togetherai/README.md b/packages/togetherai/README.md index e39a5388bb49..a8801ed191bd 100644 --- a/packages/togetherai/README.md +++ b/packages/togetherai/README.md @@ -6,10 +6,8 @@ The **[Together.ai provider](https://ai-sdk.dev/providers/ai-sdk-providers/toget ## Setup -The Together.ai provider is available in the `@ai-sdk/togetherai` module. You can install it with - ```bash -npm i @ai-sdk/togetherai +npm i ai @ai-sdk/togetherai ``` ## Skill for Coding Agents @@ -20,15 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `togetherai` from `@ai-sdk/togetherai`: - -```ts -import { togetherai } from '@ai-sdk/togetherai'; -``` - -## Example +## Usage ```ts import { togetherai } from '@ai-sdk/togetherai'; @@ -40,6 +30,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[Together.ai provider](https://ai-sdk.dev/providers/ai-sdk-providers/togetherai)** for more information. +See the [Together.ai Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/togetherai) for more information. diff --git a/packages/tool-bash/README.md b/packages/tool-bash/README.md index 295221c2f675..c9f76ad0ffc2 100644 --- a/packages/tool-bash/README.md +++ b/packages/tool-bash/README.md @@ -2,23 +2,12 @@ A first-party, provider-independent bash tool for the [AI SDK](https://ai-sdk.dev/docs). -The `@ai-sdk/tool-bash` entry point provides a bash tool for any model supporting -function calling. Supply an `Experimental_SandboxSession` to choose where commands -run. Use `@ai-sdk/sandbox-just-bash` for an in-memory environment, -`@ai-sdk/sandbox-vercel` for Vercel Sandbox, or your own implementation. +## Setup -The tool has no direct dependency on either runtime. - -## Installation - -Install the tool and the sandbox adapter you want to use: - -```sh -pnpm add ai @ai-sdk/tool-bash @ai-sdk/sandbox-just-bash +```bash +npm i ai @ai-sdk/tool-bash @ai-sdk/sandbox-just-bash ``` -Requires Node.js 22.13 or newer. - ## Usage ```ts @@ -50,66 +39,4 @@ try { } ``` -`experimental_createBashTool()` returns the tool directly. Read generated files through the -supplied sandbox using `readTextFile({ path })`, which returns `null` if missing. -The just-bash adapter resolves relative read paths against its default directory. -When overriding `workingDirectory`, use absolute paths to read files there. - -The caller owns the sandbox lifecycle. Tools sharing a session share files. -Seed files through `sandbox.writeTextFile({ path, content })` before running the -tool. Commands use the sandbox's default working directory. Set -`workingDirectory` to an absolute path to override it; explicit directories are -created if needed. Without an override, creating the tool runs no setup commands. -Commands, networking, and persistence depend on the sandbox. - -## Vercel Sandbox - -Install `@ai-sdk/sandbox-vercel` and `@vercel/sandbox` to use an existing native -Vercel Sandbox. Wrap it with the adapter before passing it to the tool: - -```ts -import { createVercelSandboxSessionFromNativeSandbox } from '@ai-sdk/sandbox-vercel'; -import { experimental_createBashTool as createBashTool } from '@ai-sdk/tool-bash'; -import { Sandbox } from '@vercel/sandbox'; - -const nativeSandbox = await Sandbox.create(); - -try { - const sandbox = createVercelSandboxSessionFromNativeSandbox(nativeSandbox); - await sandbox.writeTextFile({ - path: 'notes.txt', - content: 'Hello from Vercel Sandbox', - }); - const bash = await createBashTool({ sandbox }); - - // Use bash with generateText, streamText, or ToolLoopAgent here. -} finally { - await nativeSandbox.stop(); -} -``` - -You can also create a managed session with -`createVercelNetworkSandboxSession()` from `@ai-sdk/sandbox-vercel` and pass -`session.restricted()`. For an existing native just-bash `Sandbox`, use -`createJustBashSandboxSessionFromNativeSandbox()` from `@ai-sdk/sandbox-just-bash`. -Raw runtime instances need their respective adapters; a custom -`Experimental_SandboxSession` can be passed directly. - -Pass `maxOutputLength` to limit characters retained from each output stream -(default: 30,000). Cancellation is forwarded to the supplied session. - -Pass `timeout` to set a timeout in milliseconds for each command execution: - -```ts -const bash = await createBashTool({ sandbox, timeout: 10_000 }); -``` - -The value must be an integer from `1` to `2147483647`. There is no tool-level -timeout by default. Each execution gets a fresh timeout; initialization and -waiting for the model or approval are excluded. The timeout is combined with -the caller's abort signal, and the sandbox must honor cancellation. The -sandbox's result or error is passed through (just-bash returns exit code `124` -when a running command is cancelled). - -See the [Bash Tool documentation](https://ai-sdk.dev/docs/ai-sdk-core/tools#bash-tool) -for options and file handling. +See the [Bash Tool documentation](https://ai-sdk.dev/docs/ai-sdk-core/tools#bash-tool) for more information. diff --git a/packages/tool-web-fetch/README.md b/packages/tool-web-fetch/README.md index 244845f57553..caf40809cc4e 100644 --- a/packages/tool-web-fetch/README.md +++ b/packages/tool-web-fetch/README.md @@ -2,19 +2,12 @@ A first-party, provider-independent web fetch tool for the [AI SDK](https://ai-sdk.dev/docs). -The `@ai-sdk/tool-web-fetch` entry point provides a web fetch tool for any model -supporting function calling. The model calls it with a URL and receives the -page content: HTML pages are converted to markdown with the main content -extracted, and text formats such as markdown, JSON, and XML are returned as is. +## Setup -## Installation - -```sh -pnpm add ai @ai-sdk/tool-web-fetch +```bash +npm i ai @ai-sdk/tool-web-fetch ``` -Requires Node.js 22.13 or newer. - ## Usage ```ts @@ -31,43 +24,4 @@ const result = await generateText({ console.log(result.text); ``` -The model calls the tool with `{ url, offset? }`. Long content is truncated to -`maxLength` characters, and the model can continue reading with `offset`. -Failures such as HTTP errors, blocked URLs, or unsupported content types are -returned as results, so the model can recover. - -Requests prefer markdown (`Accept: text/markdown`) and fall back to converting -HTML with [defuddle](https://github.com/kepano/defuddle). JavaScript is not -executed, so pages that render their content in the browser may return little -or no content. - -## Security - -The tool makes GET requests without cookies or credentials. Every request and -redirect is checked against private and reserved addresses, and on Node.js -resolved DNS addresses are validated at connect time. On other runtimes, only -the URL is validated; restrict network egress at the platform level. - -Use `allowedDomains` or `blockedDomains` to restrict which sites can be -fetched. Set `requireUrlInUserMessage` to only fetch URLs that appear in user -messages, which prevents the model from fetching URLs it constructed itself, -for example to exfiltrate data in a query string. Links found in tool results, -such as search results or fetched pages, cannot be followed in this mode. - -Fetched content is untrusted and can contain prompt injections. - -## Options - -| Option | Default | Description | -| ------------------------- | ---------------- | -------------------------------------------------------------------------------------------------- | -| `allowedDomains` | none | Only fetch from these domains and their subdomains. Cannot be combined with `blockedDomains`. | -| `blockedDomains` | none | Never fetch from these domains or their subdomains. | -| `requireUrlInUserMessage` | `false` | Only fetch URLs that appear in user messages. | -| `maxLength` | `50000` | Maximum characters returned per call. | -| `maxBytes` | 10 MiB | Maximum response size in bytes. | -| `timeout` | `30000` | Timeout in milliseconds for fetching each URL, including redirects. | -| `fetch` | DNS-pinned fetch | Custom fetch implementation, e.g. for a proxy. It must validate resolved addresses itself. | -| `defuddleOptions` | none | Options for the HTML content extractor, e.g. `contentSelector` to choose the main content element. | - -See the [Web Fetch Tool documentation](https://ai-sdk.dev/docs/ai-sdk-core/tools#web-fetch-tool) -for details. +See the [Web Fetch Tool documentation](https://ai-sdk.dev/docs/ai-sdk-core/tools#web-fetch-tool) for more information. diff --git a/packages/topaz/README.md b/packages/topaz/README.md index 9a670545c40f..558f1a6eb92b 100644 --- a/packages/topaz/README.md +++ b/packages/topaz/README.md @@ -2,16 +2,12 @@ The **Topaz Labs provider** for the [AI SDK](https://ai-sdk.dev/docs) contains image and video model support for the [Topaz Labs API](https://developer.topazlabs.com). -Topaz models **enhance media you supply**. They upscale, denoise, sharpen and restore an existing image or video, and do not generate media from a text prompt. - > **Deploying to Vercel?** With Vercel's AI Gateway you can access Topaz Labs (and hundreds of models from other providers) — no additional packages, API keys, or extra cost. [Get started with AI Gateway](https://vercel.com/ai-gateway). ## Setup -The Topaz Labs provider is available in the `@ai-sdk/topaz` module. You can install it with: - ```bash -npm i @ai-sdk/topaz +npm i ai @ai-sdk/topaz ``` ## Skill for Coding Agents @@ -22,17 +18,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `topaz` from `@ai-sdk/topaz`: - -```ts -import { topaz } from '@ai-sdk/topaz'; -``` - -The default instance reads the API key from the `TOPAZ_API_KEY` environment variable. Use `createTopaz({ apiKey })` to pass it explicitly. See [API Key Setup](https://developer.topazlabs.com/getting-started/api-key-setup) to create a key. - -## Image Enhancement Example +## Usage ```ts import { topaz } from '@ai-sdk/topaz'; @@ -47,22 +33,4 @@ const { image } = await generateImage({ }); ``` -## Video Enhancement Example - -`generateVideo` requires a prompt, so pass an empty one. `resolution` sets the output resolution. Starlight models also need the input video's properties in the `source` provider option: - -```ts -import { topaz } from '@ai-sdk/topaz'; -import { experimental_generateVideo as generateVideo } from 'ai'; - -const { videos } = await generateVideo({ - model: topaz.video('proteus'), - prompt: '', - inputReferences: ['https://example.com/clip.mp4'], - resolution: '3840x2160', -}); -``` - -## Documentation - -Please check out the **[Topaz Labs provider](https://ai-sdk.dev/providers/ai-sdk-providers/topaz)** for more information. +See the [Topaz Labs Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/topaz) for more information. diff --git a/packages/tui/README.md b/packages/tui/README.md index 346691ddbdac..78ae47e93e2a 100644 --- a/packages/tui/README.md +++ b/packages/tui/README.md @@ -1,16 +1,14 @@ -# @ai-sdk/tui +# AI SDK TUI Run local or remote AI SDK agents in a terminal UI. `@ai-sdk/tui` provides a full-screen interface with streaming output, tool cards, approvals, markdown rendering, scrollback, and a pinned prompt. -## Install +## Setup ```bash -npm install @ai-sdk/tui ai -pnpm add @ai-sdk/tui ai -bun add @ai-sdk/tui ai +npm i ai @ai-sdk/tui @ai-sdk/openai zod ``` ## Usage @@ -49,47 +47,4 @@ await runAgentTUI({ }); ``` -To connect to a remote agent, pass a `ChatTransport` instead: - -```ts -import { runAgentTUI } from '@ai-sdk/tui'; -import { DefaultChatTransport } from 'ai'; - -await runAgentTUI({ - title: 'Remote Agent', - transport: new DefaultChatTransport({ api: 'https://example.com/api/chat' }), -}); -``` - -## Controls - -- `Enter`: submit prompt -- `y` / `n`: approve or reject tool calls -- `Up` / `Down`: scroll transcript -- `PageUp` / `PageDown`: scroll transcript by a full page -- `Ctrl+L`: repaint -- `Esc` / `Ctrl+C`: exit - -## API - -```ts -await runAgentTUI({ - agent, - title: 'My Agent', - tools: 'collapsed', - reasoning: 'hidden', - responseStatistics: 'outputTokenCount', - sandbox, -}); -``` - -Settings: - -- `agent`: AI SDK agent to run. Provide either `agent` or `transport`. -- `transport`: AI SDK chat transport used to communicate with a remote agent. - Provide either `agent` or `transport`. -- `title`: optional title shown in the terminal UI. -- `tools`: tool call rendering mode. Use `"full"` to show tool input and output, `"collapsed"` to show only tool cards, `"auto-collapsed"` to show the latest tool expanded until another visible section appears, or `"hidden"` to omit tool calls. Defaults to `"auto-collapsed"`. -- `reasoning`: reasoning rendering mode. Use `"full"` to show reasoning, `"collapsed"` to show only reasoning cards, `"auto-collapsed"` to show the latest reasoning expanded until another visible section appears, or `"hidden"` to omit reasoning. Defaults to `"auto-collapsed"`. -- `responseStatistics`: response header statistic. Use `"outputTokensPerSecond"` to show output token throughput or `"outputTokenCount"` to show output token count. Defaults to `"outputTokensPerSecond"`. -- `sandbox`: optional sandbox session forwarded to every agent call as `experimental_sandbox` for tool descriptions and tool execution. Only available with `agent`. +See the [AI SDK TUI documentation](https://ai-sdk.dev/docs/agents/terminal-ui) for more information. diff --git a/packages/typesafe-ai/README.md b/packages/typesafe-ai/README.md index bc623038bdc7..624c977db205 100644 --- a/packages/typesafe-ai/README.md +++ b/packages/typesafe-ai/README.md @@ -6,11 +6,11 @@ questions using TypeSafe's System One models. ## Setup -```sh -pnpm add @ai-sdk/typesafe-ai ai +```bash +npm i ai @ai-sdk/typesafe-ai ``` -Set `TYPESAFE_AI_API_KEY`, then pass a decision model instance: +## Usage ```ts import { typeSafeAi } from '@ai-sdk/typesafe-ai'; @@ -35,28 +35,4 @@ const result = await experimental_decide({ console.log(result.answers); ``` -Decision is experimental. The package exports `typeSafeAi`, `createTypeSafeAi`, -`TypeSafeAiProviderSettings`, `TypeSafeAiProvider`, -`Experimental_TypeSafeAiDecisionModelId`, and `VERSION`. - -## Configuration - -`createTypeSafeAi({ apiKey, baseURL, headers, fetch })` supports an explicit key, -custom headers, a custom fetch implementation, and a base URL. The base URL -defaults to `TYPESAFE_AI_BASE_URL`, then `https://api.typesafe.ai/v1`. An -explicit `baseURL` takes precedence over the environment variable. The default -key comes from `TYPESAFE_AI_API_KEY`. Language, embedding, and image model -factories are unsupported. - -All questions are sent in one request against shared state. Choice supports up to -255 options; Score supports 2–10 ordered levels; Boolean maps to TypeSafe's Noul -primitive. Instructions and descriptions accept structured JSON. No -provider-specific options are currently defined. - -Native distributions and scores are preserved. TypeSafe returns rounded values; -`result.rounding` declares two decimal places so core can validate rounding error -without changing the numbers. TypeSafe confidence is separate from probability: -find it at `result.providerMetadata.typesafe.confidence[questionId]`. - -See the [provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/typesafe-ai) -and [TypeSafe API reference](https://docs.typesafe.ai/api). +See the [TypeSafe Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/typesafe-ai) for more information. diff --git a/packages/valibot/README.md b/packages/valibot/README.md index 4d533cdff87a..b57938cc010f 100644 --- a/packages/valibot/README.md +++ b/packages/valibot/README.md @@ -2,16 +2,13 @@ Allows you to use [Valibot](https://valibot.dev/) schemas with AI SDK. -The `valibotSchema` function supports both validation and JSON schema conversion -for Valibot schemas. - ## Setup ```bash -npm install @ai-sdk/valibot +npm i ai @ai-sdk/valibot @ai-sdk/anthropic valibot ``` -## Example +## Usage ```ts import { anthropic } from '@ai-sdk/anthropic'; @@ -40,3 +37,5 @@ const result = await generateText({ prompt: 'Generate a lasagna recipe.', }); ``` + +See the [Valibot Schema Support documentation](https://ai-sdk.dev/docs/reference/ai-sdk-core/valibot-schema) for more information. diff --git a/packages/voyage/README.md b/packages/voyage/README.md index 9ee27d02df8d..d1aa8bbdd62d 100644 --- a/packages/voyage/README.md +++ b/packages/voyage/README.md @@ -4,10 +4,8 @@ The **[Voyage AI provider](https://ai-sdk.dev/providers/ai-sdk-providers/voyage) ## Setup -The Voyage AI provider is available in the `@ai-sdk/voyage` module. You can install it with - ```bash -npm i @ai-sdk/voyage +npm i ai @ai-sdk/voyage ``` ## Skill for Coding Agents @@ -18,15 +16,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `voyage` from `@ai-sdk/voyage`: - -```ts -import { voyage } from '@ai-sdk/voyage'; -``` - -## Example +## Usage ```ts import { voyage } from '@ai-sdk/voyage'; @@ -41,6 +31,4 @@ const { embeddings } = await embedMany({ }); ``` -## Documentation - -Please check out the **[Voyage AI provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/voyage)** for more information. +See the [Voyage AI Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/voyage) for more information. diff --git a/packages/vue/README.md b/packages/vue/README.md index 0518806ca08c..a8a98b5258bb 100644 --- a/packages/vue/README.md +++ b/packages/vue/README.md @@ -2,6 +2,46 @@ [Vue.js](https://vuejs.org/) UI components for the [AI SDK](https://ai-sdk.dev/docs): -- [`useChat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) composable -- [`useCompletion`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-completion) composable -- [`useObject`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-object) composable +## Setup + +```bash +npm i ai @ai-sdk/vue +``` + +## Usage + +```typescript + + + +``` + +See the [Vue.js documentation](https://ai-sdk.dev/docs/getting-started/nuxt) for more information. diff --git a/packages/workflow-harness/README.md b/packages/workflow-harness/README.md index 55ca81b87925..85837a1d3f79 100644 --- a/packages/workflow-harness/README.md +++ b/packages/workflow-harness/README.md @@ -1,109 +1,16 @@ -# @ai-sdk/workflow-harness +# Workflow Harness Run an AI SDK `HarnessAgent` (Claude Code, Codex, Pi) as a **durable workflow** using the [Workflow DevKit](https://www.npmjs.com/package/workflow). A turn can be divided into time slices or semantic agent steps. -Time slices let a long agent turn survive a Fluid Compute function recycle -(~800s). Semantic steps let a workflow persist after each agent step, typically -by configuring the agent with `stopWhen: isStepCount(1)`. At either boundary the -agent is frozen non-destructively and a serializable state object is persisted -as the durable step return value. +## Setup -This package ships plain helpers + a serializable state machine; you own the -thin `'use workflow'` / `'use step'` wrappers (the Workflow DevKit compiles -those directives in your app). - -Keep the Workflow DevKit entrypoints separate from the agent definition. The -workflow module should import only workflow-safe code plus step modules. The -step module should dynamically import the agent inside the `'use step'` body so -the agent, sandbox adapter, and other Node-heavy dependencies stay out of the -compiled workflow bundle. - -`agent.ts`: - -```ts -import { HarnessAgent } from '@ai-sdk/harness/agent'; -import { claudeCode } from '@ai-sdk/harness-claude-code'; - -export const agent = new HarnessAgent({ harness: claudeCode }); -``` - -`time-slice-step.ts`: - -```ts -import { - runHarnessAgentTimeSlice, - type HarnessWorkflowState, -} from '@ai-sdk/workflow-harness'; - -export async function timeSliceStep( - state: HarnessWorkflowState, -): Promise { - 'use step'; - - const { agent } = await import('./agent'); - const { - createVercelNetworkSandboxSession, - resumeVercelNetworkSandboxSession, - } = await import('@ai-sdk/sandbox-vercel'); - const sandboxId = `harness-${state.sessionId}`; - const sandboxSession = - state.resumeFrom == null && state.continueFrom == null - ? await createVercelNetworkSandboxSession({ - sandboxId, - runtime: 'node24', - ports: [4000], - template: await agent.getSandboxTemplate(), - }) - : await resumeVercelNetworkSandboxSession({ sandboxId }); - - return runHarnessAgentTimeSlice({ agent, state, sandboxSession }); -} -``` - -`workflow.ts`: - -```ts -import { - createHarnessWorkflowState, - finalizeHarnessWorkflow, - type HarnessWorkflowInput, -} from '@ai-sdk/workflow-harness'; -import { timeSliceStep } from './time-slice-step'; - -export async function timeSliceWorkflow(input: { - prompt: HarnessWorkflowInput['prompt']; - sessionId: string; -}) { - 'use workflow'; - - let state = createHarnessWorkflowState(input); - do { - state = await timeSliceStep(state); - } while (state.status === 'ready_for_next_step'); - return finalizeHarnessWorkflow(state); -} -``` - -For a semantic stepped workflow, configure the agent with -`stopWhen: isStepCount(1)`, call `runHarnessAgentStep()` from the step module, -and continue while the status is `ready_for_next_step`: - -`stepped-agent.ts`: - -```ts -import { HarnessAgent } from '@ai-sdk/harness/agent'; -import { claudeCode } from '@ai-sdk/harness-claude-code'; -import { isStepCount } from 'ai'; - -export const steppedAgent = new HarnessAgent({ - harness: claudeCode, - stopWhen: isStepCount(1), -}); +```bash +npm i ai @ai-sdk/workflow-harness workflow @ai-sdk/harness @ai-sdk/harness-claude-code @ai-sdk/sandbox-vercel zod ``` -`stepped-agent-step.ts`: +## Usage ```ts import { @@ -136,42 +43,4 @@ export async function agentStep( } ``` -`stepped-workflow.ts`: - -```ts -import { - createHarnessWorkflowState, - finalizeHarnessWorkflow, - type HarnessWorkflowInput, -} from '@ai-sdk/workflow-harness'; -import { agentStep } from './stepped-agent-step'; - -export async function agentWorkflow( - input: Pick, -) { - 'use workflow'; - - let state = createHarnessWorkflowState(input); - do { - state = await agentStep(state); - } while (state.status === 'ready_for_next_step'); - return finalizeHarnessWorkflow(state); -} -``` - -`route.ts` (Next.js example): - -```ts -import { start } from 'workflow/api'; -import { timeSliceWorkflow } from './workflow'; - -export async function POST(request: Request) { - const body = (await request.json()) as { - prompt: string; - sessionId: string; - }; - const run = await start(timeSliceWorkflow, [body]); - - return new Response(run.readable); -} -``` +See the [Workflow Utilities documentation](https://ai-sdk.dev/docs/ai-sdk-harnesses/workflow-utilities) for more information. diff --git a/packages/workflow/README.md b/packages/workflow/README.md index c8f5a379903f..dae71ddb3e21 100644 --- a/packages/workflow/README.md +++ b/packages/workflow/README.md @@ -1,11 +1,11 @@ -# @ai-sdk/workflow +# Workflow WorkflowAgent is a class for building durable AI agents that can maintain state across workflow steps, call tools, and handle interruptions gracefully. -## Installation +## Setup ```bash -npm install @ai-sdk/workflow ai workflow@5 +npm i @ai-sdk/workflow zod ai workflow@5 ``` ## Usage @@ -42,46 +42,4 @@ console.log('Final messages:', result.messages); console.log('Steps:', result.steps); ``` -### Durable video generation - -`experimental_generateVideo` starts asynchronous video generation, suspends the -workflow until a provider webhook arrives, and returns the provider's video -data without downloading hosted URLs. - -```typescript -import { experimental_generateVideo as generateVideo } from '@ai-sdk/workflow/video'; - -export async function videoWorkflow(prompt: string) { - 'use workflow'; - - const result = await generateVideo({ - model: 'klingai/kling-v3.0-t2v', - prompt, - }); - - return result.videos; -} -``` - -The workflow can persist, copy, or process each returned video URL in a -separate step without serializing the video bytes through the workflow. - -## Features - -- **Streaming Support**: Stream responses in real-time -- **Tool Calling**: Execute tools dynamically during conversation -- **Context Management**: Pass context between steps -- **Error Handling**: Robust error handling with callbacks -- **Structured Output**: Parse structured outputs from LLM responses -- **Step Callbacks**: Hook into each step of the agent loop -- **Provider-Executed Tools**: Support for provider-executed tools -- **Abort Support**: Cancel operations with AbortSignal -- **Durable Video Generation**: Suspend on video webhooks without polling or automatically downloading hosted videos - -## API - -See the [AI SDK documentation](https://ai-sdk.dev/docs) for full API details. - -## License - -Apache-2.0 +See the [Workflow documentation](https://ai-sdk.dev/docs/agents/workflow-agent) for more information. diff --git a/packages/xai/README.md b/packages/xai/README.md index 7b6b005daf18..5acf8d1425d6 100644 --- a/packages/xai/README.md +++ b/packages/xai/README.md @@ -7,10 +7,8 @@ contains language model support for the xAI chat and completion APIs. ## Setup -The xAI Grok provider is available in the `@ai-sdk/xai` module. You can install it with - ```bash -npm i @ai-sdk/xai +npm i ai @ai-sdk/xai ``` ## Skill for Coding Agents @@ -21,15 +19,7 @@ If you use coding agents such as Claude Code or Cursor, we highly recommend addi npx skills add vercel/ai ``` -## Provider Instance - -You can import the default provider instance `xai` from `@ai-sdk/xai`: - -```ts -import { xai } from '@ai-sdk/xai'; -``` - -## Example +## Usage ```ts import { xai } from '@ai-sdk/xai'; @@ -41,6 +31,4 @@ const { text } = await generateText({ }); ``` -## Documentation - -Please check out the **[xAI Grok provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/xai)** for more information. +See the [xAI Grok Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/xai) for more information. diff --git a/packages/zai/README.md b/packages/zai/README.md index 424748dfdfc1..a6b42270704c 100644 --- a/packages/zai/README.md +++ b/packages/zai/README.md @@ -6,31 +6,11 @@ The **Z.AI provider** for the [AI SDK](https://ai-sdk.dev/docs) contains languag ## Setup -Install the Z.AI provider with: - ```bash -npm i @ai-sdk/zai -``` - -## Provider Instance - -Import the default provider instance from `@ai-sdk/zai`: - -```ts -import { zai } from '@ai-sdk/zai'; -``` - -The provider reads the API key from `ZAI_API_KEY` by default. To configure it explicitly, use `createZai`: - -```ts -import { createZai } from '@ai-sdk/zai'; - -const zai = createZai({ - apiKey: process.env.ZAI_API_KEY, -}); +npm i ai @ai-sdk/zai ``` -## Language Models +## Usage ```ts import { zai } from '@ai-sdk/zai'; @@ -44,4 +24,4 @@ const { text } = await generateText({ console.log(text); ``` -The provider supports streaming, reasoning, function tools, JSON object output, and URL-based image and video input on compatible GLM models. +See the [Z.AI Provider documentation](https://ai-sdk.dev/providers/ai-sdk-providers/zai) for more information. From b6ef4d11ae4e7d2b6a69f52eb801ed0873f1bd0d Mon Sep 17 00:00:00 2001 From: Felix Arntz Date: Fri, 23 Oct 2026 16:53:26 -0500 Subject: [PATCH 2/6] include basic content in provider and provider-utils README.md, though these are exceptions to the general format --- packages/provider-utils/README.md | 4 ++++ packages/provider/README.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/packages/provider-utils/README.md b/packages/provider-utils/README.md index f7ee1685f40d..2eefc7f02d07 100644 --- a/packages/provider-utils/README.md +++ b/packages/provider-utils/README.md @@ -1 +1,5 @@ # AI SDK - Provider Implementation Utilities + +Provides shared utility functions and types for the internal implementations of AI SDK Core (`ai`) and provider adapter packages. Applications rarely need to depend on this package directly. + +See the [AI SDK documentation](https://ai-sdk.dev/docs) for more information. diff --git a/packages/provider/README.md b/packages/provider/README.md index 0e858d8757f7..d7950412046e 100644 --- a/packages/provider/README.md +++ b/packages/provider/README.md @@ -1 +1,5 @@ # AI SDK - Provider Language Model Specification + +Defines the interfaces and specifications that provider adapters implement to work with AI SDK Core (`ai`). It is primarily an internal dependency of AI SDK Core and provider adapter packages; applications rarely need to depend on it directly. + +See the [AI SDK documentation](https://ai-sdk.dev/docs) for more information. From 1f66b8e79c8a899acafc6d5ffd76807acc464dcf Mon Sep 17 00:00:00 2001 From: Felix Arntz Date: Fri, 23 Oct 2026 17:05:28 -0500 Subject: [PATCH 3/6] define README.md conventions in a skill --- skills/edit-package-readme/SKILL.md | 60 +++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 skills/edit-package-readme/SKILL.md diff --git a/skills/edit-package-readme/SKILL.md b/skills/edit-package-readme/SKILL.md new file mode 100644 index 000000000000..72dce51837e9 --- /dev/null +++ b/skills/edit-package-readme/SKILL.md @@ -0,0 +1,60 @@ +--- +name: edit-package-readme +description: Create or edit package README.md files in the AI SDK monorepo. +metadata: + internal: true +--- + +# Package READMEs + +Keep `README.md` files minimal; they must not contain documentation beyond simple starting points. Detailed documentation belongs exclusively in `content/` and lives under `https://ai-sdk.dev/docs`. + +Every package `README.md` file must contain the following, in the given order: + +1. H1 (`#`) with a descriptive package title, not its npm identifier. +2. A 1–2 sentence description. +3. Optional note about compatibility, AI Gateway, or experimental nature. Consult similar packages and match their formatting; if in doubt, do not add one. +4. `## Setup`: only one fenced, one-line `npm i` command, including necessary related packages. +5. `## Usage`: only one fenced, basic getting-started code example (TypeScript or a framework component with TypeScript). +6. A suitable docs link using `See the [ documentation]() for more information.` If none clearly fits, use 1–2 related docs links with custom phrasing. + +You must not include anything else in the readme. Any additional documentation belongs in `content/`. + +## Template + +Omit the optional note when it does not apply. + +````markdown +# + +A brief description of the package. + +-> **Note**: + +## Setup + +```bash +npm i +``` + +## Usage + +```ts +import { example } from ''; + +await example(); +``` + +See the [ documentation](https://ai-sdk.dev/...) for more information. +```` + +## Exceptions + +These packages have special-case `README.md` files and do not follow this format: + +- `ai` +- `codemod` +- `provider-utils` +- `provider` + +Never consult these files for which `README.md` conventions to follow. From 30f8fcb0830a421d982b2aa5b0874033570528be Mon Sep 17 00:00:00 2001 From: Felix Arntz Date: Fri, 23 Oct 2026 17:06:33 -0500 Subject: [PATCH 4/6] changeset --- .changeset/tall-houses-relax.md | 84 +++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 .changeset/tall-houses-relax.md diff --git a/.changeset/tall-houses-relax.md b/.changeset/tall-houses-relax.md new file mode 100644 index 000000000000..c9f3bc318379 --- /dev/null +++ b/.changeset/tall-houses-relax.md @@ -0,0 +1,84 @@ +--- +"@ai-sdk/harness-github-copilot": patch +"@ai-sdk/harness-claude-code": patch +"@ai-sdk/harness-deepagents": patch +"@ai-sdk/harness-grok-build": patch +"@ai-sdk/black-forest-labs": patch +"@ai-sdk/openai-compatible": patch +"@ai-sdk/sandbox-just-bash": patch +"@ai-sdk/harness-opencode": patch +"@ai-sdk/workflow-harness": patch +"@ai-sdk/amazon-bedrock": patch +"@ai-sdk/harness-cursor": patch +"@ai-sdk/open-responses": patch +"@ai-sdk/provider-utils": patch +"@ai-sdk/sandbox-vercel": patch +"@ai-sdk/tool-web-fetch": patch +"@ai-sdk/anthropic-aws": patch +"@ai-sdk/google-vertex": patch +"@ai-sdk/harness-cline": patch +"@ai-sdk/harness-codex": patch +"@ai-sdk/harness-acp": patch +"@ai-sdk/huggingface": patch +"@ai-sdk/typesafe-ai": patch +"@ai-sdk/assemblyai": patch +"@ai-sdk/elevenlabs": patch +"@ai-sdk/fish-audio": patch +"@ai-sdk/harness-fx": patch +"@ai-sdk/harness-pi": patch +"@ai-sdk/llamaindex": patch +"@ai-sdk/moonshotai": patch +"@ai-sdk/perplexity": patch +"@ai-sdk/policy-opa": patch +"@ai-sdk/togetherai": patch +"@ai-sdk/anthropic": patch +"@ai-sdk/bytedance": patch +"@ai-sdk/code-mode": patch +"@ai-sdk/deepinfra": patch +"@ai-sdk/fireworks": patch +"@ai-sdk/langchain": patch +"@ai-sdk/replicate": patch +"@ai-sdk/tool-bash": patch +"@ai-sdk/cartesia": patch +"@ai-sdk/cerebras": patch +"@ai-sdk/deepgram": patch +"@ai-sdk/deepseek": patch +"@ai-sdk/devtools": patch +"@ai-sdk/gmicloud": patch +"@ai-sdk/provider": patch +"@ai-sdk/quiverai": patch +"@ai-sdk/workflow": patch +"@ai-sdk/alibaba": patch +"@ai-sdk/baseten": patch +"@ai-sdk/gateway": patch +"@ai-sdk/harness": patch +"@ai-sdk/klingai": patch +"@ai-sdk/minimax": patch +"@ai-sdk/mistral": patch +"@ai-sdk/valibot": patch +"@ai-sdk/cohere": patch +"@ai-sdk/gladia": patch +"@ai-sdk/google": patch +"@ai-sdk/heygen": patch +"@ai-sdk/openai": patch +"@ai-sdk/prodia": patch +"@ai-sdk/svelte": patch +"@ai-sdk/voyage": patch +"@ai-sdk/azure": patch +"@ai-sdk/react": patch +"@ai-sdk/revai": patch +"@ai-sdk/topaz": patch +"@ai-sdk/groq": patch +"@ai-sdk/hume": patch +"@ai-sdk/luma": patch +"@ai-sdk/otel": patch +"@ai-sdk/fal": patch +"@ai-sdk/mcp": patch +"@ai-sdk/rsc": patch +"@ai-sdk/tui": patch +"@ai-sdk/vue": patch +"@ai-sdk/xai": patch +"@ai-sdk/zai": patch +--- + +chore: update `README.md` for consistent format and to avoid duplication From daab4b1e68f4355de57c5ed297fd623fcb9b2d0c Mon Sep 17 00:00:00 2001 From: Felix Arntz Date: Fri, 23 Oct 2026 17:07:41 -0500 Subject: [PATCH 5/6] update changeset --- .changeset/tall-houses-relax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/tall-houses-relax.md b/.changeset/tall-houses-relax.md index c9f3bc318379..830e47e8eee8 100644 --- a/.changeset/tall-houses-relax.md +++ b/.changeset/tall-houses-relax.md @@ -81,4 +81,4 @@ "@ai-sdk/zai": patch --- -chore: update `README.md` for consistent format and to avoid duplication +chore(docs): update `README.md` for consistent format and to avoid duplication From d43e9efd1b6ac849811d43368a859a59895ff781 Mon Sep 17 00:00:00 2001 From: Felix Arntz Date: Fri, 23 Oct 2026 17:19:08 -0500 Subject: [PATCH 6/6] address PR feedback --- packages/policy-opa/README.md | 2 +- packages/workflow-harness/README.md | 8 +++++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/policy-opa/README.md b/packages/policy-opa/README.md index c5b36bee655e..5bbe48fcc881 100644 --- a/packages/policy-opa/README.md +++ b/packages/policy-opa/README.md @@ -5,7 +5,7 @@ Policy-as-code authorization for AI SDK tool calls, powered by [Open Policy Agen ## Setup ```bash -npm i ai @ai-sdk/policy-opa @ai-sdk/anthropic +npm i ai @ai-sdk/policy-opa @ai-sdk/anthropic @open-policy-agent/opa-wasm ``` ## Usage diff --git a/packages/workflow-harness/README.md b/packages/workflow-harness/README.md index 85837a1d3f79..e34f5ab66643 100644 --- a/packages/workflow-harness/README.md +++ b/packages/workflow-harness/README.md @@ -23,11 +23,17 @@ export async function agentStep( ): Promise { 'use step'; - const { steppedAgent } = await import('./stepped-agent'); + const { HarnessAgent } = await import('@ai-sdk/harness/agent'); + const { claudeCode } = await import('@ai-sdk/harness-claude-code'); + const { isStepCount } = await import('ai'); const { createVercelNetworkSandboxSession, resumeVercelNetworkSandboxSession, } = await import('@ai-sdk/sandbox-vercel'); + const steppedAgent = new HarnessAgent({ + harness: claudeCode, + stopWhen: isStepCount(1), + }); const sandboxId = `harness-${state.sessionId}`; const sandboxSession = state.resumeFrom == null && state.continueFrom == null