feat: add VercelModel adapter for Language Model Specification v3 providers

[awsarron]

Description

Adds VercelModel, an adapter that wraps any Language Model Specification v3 (LanguageModelV3) provider for use as a Strands model provider. This lets users bring models from the Vercel AI SDK ecosystem (e.g. @ai-sdk/amazon-bedrock, @ai-sdk/openai, @ai-sdk/anthropic, etc.) directly into Strands agents.

The adapter handles:

• Streaming text, reasoning, and tool use (both incremental tool-input-* and complete tool-call events)
• Message formatting: converts Strands messages (text, images, documents, video, tool use/results, reasoning) to the LanguageModelV3Prompt format
• Tool spec and tool choice mapping
• Usage/token tracking including cache read/write tokens
• Error classification: maps APICallError status codes and error message patterns to ModelThrottledError, ContextWindowOverflowError, and ModelError
• All LanguageModelV3CallOptions settings (temperature, topP, topK, penalties, stop sequences, seed) forwarded through config

Importable as a subpath export:

import { VercelModel } from '@strands-agents/sdk/vercel'

Usage:

OpenAI

import { Agent } from '@strands-agents/sdk'
import { VercelModel } from '@strands-agents/sdk/vercel'
import { openai } from '@ai-sdk/openai'

const agent = new Agent({
  model: new VercelModel(openai('gpt-4o')),
})

const result = await agent.invoke('Hello!')

Bedrock

import { Agent } from '@strands-agents/sdk'
import { VercelModel } from '@strands-agents/sdk/vercel'
import { bedrock } from '@ai-sdk/amazon-bedrock'

const agent = new Agent({
  model: new VercelModel(bedrock('us.anthropic.claude-sonnet-4-20250514-v1:0'), {
    temperature: 0.7,
  }),
})

const result = await agent.invoke('Hello!')

@ai-sdk/provider is added as an optional peer dependency since it crosses the API boundary (users construct LanguageModelV3 instances and pass them in).

Related Issues

#214
#540

Documentation PR

strands-agents/docs#689

Type of Change

New feature

Testing

• 710-line unit test suite covering text/reasoning/tool streaming, message formatting (user, assistant, system), tool spec/choice mapping, usage mapping, error classification, config forwarding, and edge cases
• Integration test fixtures added for VercelModel with both Bedrock and OpenAI backends

How have you tested the change?

• I ran npm run check

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Review Summary

Assessment: Request Changes

This is a well-implemented adapter that brings the Vercel AI SDK ecosystem to Strands. The code quality is good, tests are comprehensive (710 lines), and the dependency configuration correctly uses @ai-sdk/provider as an optional peer dependency per the DEPENDENCIES.md guidelines.

Required Changes

1. Documentation PR Required (Blocking)

The PR description's "Documentation PR" section shows TODO. Per the review guidelines, new features that add public API surface (like VercelModel) require a documentation PR. Please update this section with a link to https://github.com/strands-agents/docs/pull/... or a justification for why documentation is not needed.

2. API Review Label Missing

This PR introduces a new public class (VercelModel) that customers will frequently use to integrate Vercel AI SDK providers. Per the API Bar Raising guidelines, the PR should have the needs-api-review label. The PR description already contains good API documentation (usage example, configuration options), which is excellent preparation for API review.

Code Suggestions (Non-blocking)

• Tool call input handling: Consider normalizing tool-call input to string format for consistency with incremental tool-input-delta events (see inline comment)
• System prompt type guard: Minor readability improvement for the system prompt block filtering

The implementation follows existing model provider patterns well, and the test coverage is thorough. Looking forward to the documentation PR link!

[github-actions]

🔍 Code Review Summary

Assessment: Request Changes

This is a well-implemented adapter that brings the Vercel AI SDK ecosystem to Strands. The code quality is good, tests are comprehensive (710 lines), and the dependency configuration correctly uses @ai-sdk/provider as an optional peer dependency per the DEPENDENCIES.md guidelines.

---

⛔ Required Changes

1. Documentation PR Required (Blocking)

The PR description's "Documentation PR" section shows TODO. Per review guidelines, new features that add public API surface (like VercelModel) require a documentation PR linking to https://github.com/strands-agents/docs/pull/....

2. API Review Label Suggested

This PR introduces a new public class (VercelModel) that customers will frequently use. Per API Bar Raising guidelines, consider adding the needs-api-review label. The PR description already includes good API documentation (usage example, config options), which is excellent preparation.

---

💡 Code Suggestions (Non-blocking)

Tool call input handling (src/models/vercel-model.ts:265)

The tool-call input is passed directly to the delta event, but in incremental cases (tool-input-delta), input is treated as a concatenated string. Consider normalizing:

case 'tool-call':
  yield new ModelContentBlockDeltaEvent({
    type: 'modelContentBlockDeltaEvent',
    delta: { 
      type: 'toolUseInputDelta', 
      input: typeof part.input === 'string' ? part.input : JSON.stringify(part.input) 
    },
  })

This ensures streamAggregated (which expects JSON string input to parse) works correctly for both paths.

System prompt type filtering (src/models/vercel-model.ts:338)

Consider using a type guard instead of as unknown as for cleaner type safety:

const isTextBlock = (b: unknown): b is { text: string } =>
  typeof b === 'object' && b !== null && 'text' in b && typeof (b as {text?: unknown}).text === 'string'

---

✅ What's Good

• Follows existing model provider patterns well
• Comprehensive test coverage (text/reasoning/tool streaming, message formatting, error classification)
• Integration test fixtures for Bedrock and OpenAI backends
• Correct peer dependency configuration for @ai-sdk/provider
• Good TSDoc documentation on the class and config interface

Please address the documentation PR requirement and the review is ready to approve! 🚀

[github-actions]

Updated Review Status

Thanks for the updates! The PR description now includes excellent usage examples for both OpenAI and Bedrock backends. 👍

Remaining Blocking Item

The Documentation PR section still shows TODO. Since VercelModel is a new public API that users need to learn about to integrate Vercel AI SDK providers, a documentation PR is required before this can be approved.

Once you've created the documentation PR and linked it, the review is ready to approve!

[github-actions]

Review Check-in

I noticed some good updates to the PR:

✅ Cleaner Import Path: The module was renamed from vercel-model to vercel, giving users a cleaner import:

import { VercelModel } from '@strands-agents/sdk/vercel'

Status

Remaining Blocking Item: The Documentation PR section still shows TODO. Once the documentation PR is linked, this is ready to approve.

The implementation looks solid - comprehensive tests, follows existing patterns, and correct dependency configuration. 👍