🤖 AI SDK Dart
A Dart/Flutter SDK inspired by Vercel AI SDK — provider-agnostic APIs for text generation, streaming, structured output, tool use, embeddings, image generation, speech, and more.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
A Dart/Flutter SDK inspired by Vercel AI SDK — provider-agnostic APIs for text generation, streaming, structured output, tool use, embeddings, image generation, speech, and more.
Dart/Flutter port of Vercel AI SDK v6 — provider-agnostic text generation, streaming, structured output, tools, embeddings, image gen, speech, MCP, and Flutter UI controllers
AI SDK Dart brings Vercel AI SDK concepts to Dart and Flutter with Dart types, streams, and lifecycle primitives. Core workflows share a provider-neutral API; provider-specific capabilities remain explicit.
Version 3.0 was reviewed against Vercel AI SDK 7.0.111 / provider 4.0.17. See the v2-to-v3 migration guide for the full upgrade path and the contract comparison for the implementation-by-implementation audit.
instructions — the canonical top-level instruction, retained across
steps; system remains a deprecated fallback. System-role input messages
are rejected by default unless allowSystemInMessages: true.stream + callbacks — result.stream is now the exhaustive
typed event stream (the old provider-part stream moved to
providerStream); fullStream is a deprecated alias, not a second
producer. onStart, onStepStart, onToolExecutionStart,
onToolExecutionEnd, onStepEnd, and onEnd are the canonical lifecycle
callbacks (onFinish/onStepFinish remain fallbacks).finalStep — usage, content, toolCalls,
sources, and files aggregate every step; text, structured output,
reasoning, reasoningText, and finalStep describe the last step only.
responseMessages holds just the turns generated by that call — append it
once to your own history with result.responseMessages.map(ModelMessage.fromProvider).toolWithContext binds typed
application context to a tool executor without sending it to the provider;
approvalPolicy moves approval to the request/agent boundary; a restored
approval is bound to the exact call ID, arguments, and policy revision.
maxToolConcurrency admits more than one tool call at a time (serial by
default).CancellationToken
(abortSignal) reaches every adapter and closes real transport work.
TimeoutConfiguration distinguishes total/step/first-chunk/chunk/tool
deadlines for generateText, streamText, and ToolLoopAgent. Set
timeout: const TimeoutConfiguration(total: Duration(seconds: 30))
for a total deadline. Object, embedding, media, and reranking functions
accept Duration.BodyInclusionPolicy — request/response bodies and raw provider
chunks are omitted by default; opt in per call when an integration needs
to retain them.openai.responses(id) with hosted
tools (web search, file search, code interpreter, image generation, remote
MCP), plus Files and Batch lifecycle clients.reasoning option mapped to OpenAI reasoning
effort, Anthropic thinking and Gemini thinking budgets; signed reasoning is
replayed through responseMessages.DataContentProviderReference (namespace + ID) that an
unrelated provider must reject rather than reinterpret as a URL.ai_sdk_conversation (immutable persisted
snapshots + codec), ai_sdk_remote (trusted-backend UI-message-stream
transport), ai_sdk_json_schema (optional local schema validation before
decoding), and ai_sdk_telemetry (OTLP/HTTP metrics export) — see the
package table below. ai_sdk_realtime tracks the same contracts as an
unpublished preview.MCPProtocolMode.modern, host-owned auth
discovery (MCPAuthConfiguration/MCPAuthDiscovery), typed progress, and
explicit retryOnTransportFailure now that a lost tools/call reply is
no longer retried automatically by default.Model IDs remain open strings. The dated capability catalog
separates upstream catalog information from protocol fixtures and live
evidence; a model appearing in that catalog does not establish every SDK
feature works with that model. Live-provider qualification (real API
canaries, device audio for ai_sdk_realtime) is tracked separately and
remains in progress — see docs/provider-canaries.md.
Upgrading from 2.x or earlier? The 2.0 migration guide covers the V3→V4 provider-seam rename first; apply it before the 3.0 guide above.
examples/flutter_chat)examples/advanced_app)generateText — single-turn or multi-step text generation with full result envelopestreamText — real-time token streaming with typed event taxonomysmoothStream transform — configurable chunk-size smoothing; delayInMs option adds per-chunk delay for UX pacingmaxSteps, prepareStep, and stopConditionstimeout accepts TimeoutConfiguration for text generation, streaming, and agents; object, embedding, media, and reranking functions accept a total Duration deadlineonStart, onStepStart, onToolExecutionStart, onToolExecutionEnd, onStepEnd, onEnd (plus onChunk, onError, onAbort); deprecated onFinish/onStepFinish remain fallbacksOutput.object(schema) — parse model output into a typed Dart objectOutput.array(schema) — parse model output into a typed Dart listOutput.choice(options) — constrain output to a fixed set of string valuesOutput.json() — raw JSON without schema validationextractJsonMiddleware when a model needs code-fence normalizationtool<Input, Output>() — fully typed tool definitions with JSON schemadynamicTool() — tools with unknown input type for dynamic use casesauto, required, none, or specific toolneedsApprovalonInputStart, onInputDelta, onInputAvailable lifecycle hooksgenerateImage — image generation (gpt-image-1 / DALL·E via OpenAI)generateSpeech — text-to-speech audio synthesistranscribe — speech-to-text transcriptionembed() — single value embedding with usage trackingembedMany() — batch embedding for multiple values with configurable chunk sizecosineSimilarity() — built-in similarity computationwrapEmbeddingModel() — composable middleware pipeline for embedding modelswrapLanguageModel(model: ..., middleware: ...) — composable middleware pipelineextractReasoningMiddleware — strips <think> tags into ReasoningPartextractJsonMiddleware — strips ```json ``` fencessimulateStreamingMiddleware — converts non-streaming models to streamingdefaultSettingsMiddleware — applies default temperature/top-p/etc.addToolInputExamplesMiddleware — enriches tool descriptions with exampleswrapEmbeddingModel / wrapImageModel — the same composable middleware pattern for embedding and image modelscreateProviderRegistry — map provider aliases to model factoriescustomProvider() — lightweight on-the-fly provider construction without a full registry'provider:modelId' string at runtimeChatController — multi-turn streaming chat with message historyCompletionController — single-turn text completion with statusObjectStreamController — streaming typed JSON object updatesAiChatScaffold, message list/bubbles, composer,
streaming text, typing indicator, tool-call & approval cards, reasoning, citations, usage, and moreMCPClient — connect to MCP servers, discover tools, invoke themStreamableHttpClientTransport — MCP Streamable HTTP transport (2025-06-18) for remote serversStdioMCPTransport — stdio process transport (native platforms)dart:io is isolated behind conditional imports, so the client runs on Flutter webgenerateText/streamTextAiSdkError hierarchy — AiApiCallError, AiNoObjectGeneratedError, and AiRetryError for exhausted retryable failuresAiApiCallError carrying the
provider's message, type, code, statusCode, raw body, and an isRetryable flag,
consistently across every providerMockEmbeddingModelV2 testing utility for embedding model conformance
ai_sdk_providerandai_sdk_openai_compatibleare transitive dependencies — you do not need to add them directly.
dart pub add ai_sdk_dart ai_sdk_openai
import 'dart:io';
import 'package:ai_sdk_dart/ai_sdk_dart.dart';
import 'package:ai_sdk_openai/ai_sdk_openai.dart';
Future<void> main() async {
final apiKey = Platform.environment['OPENAI_API_KEY'];
if (apiKey == null || apiKey.isEmpty) {
throw StateError('Set OPENAI_API_KEY before running this example.');
}
final provider = OpenAIProvider(apiKey: apiKey);
try {
final result = await generateText(
model: provider('gpt-4.1-mini'),
prompt: 'Say hello from AI SDK Dart!',
);
print(result.text);
} finally {
provider.dispose();
}
}
For server and CLI apps, prefer reading credentials from your runtime
environment and passing apiKey: yourself, as shown above. The convenience
factories like openai('...'), anthropic('...'), and google('...') read
compile-time defines such as OPENAI_API_KEY, so they are best paired with
dart run --define=... or Flutter --dart-define=....
The optional v3 remote package sends application messages to your backend. The backend owns provider credentials, authorization, and tool execution. Use an application session token to authenticate the client.
import 'package:ai_sdk_conversation/ai_sdk_conversation.dart';
import 'package:ai_sdk_remote/ai_sdk_remote.dart';
Stream<Conversation> sendChatTurn({
required Uri endpoint,
required Conversation conversation,
required Future<String> Function() sessionToken,
}) async* {
final transport = RemoteConversationTransport(
endpoint: endpoint,
authHeaders: () async => {
'Authorization': 'Bearer ${await sessionToken()}',
},
);
try {
yield* transport.send(conversation);
} finally {
transport.dispose();
}
}
A Flutter StreamBuilder<Conversation> can render these snapshots. Cancelling
the subscription cancels its active request and runs the cleanup above. Store
snapshots with ConversationCodec; decoding a snapshot does not execute tools.
The backend must implement the pinned UI-message stream protocol. The reference backend and runnable Dart client demonstrate the request and response flow without provider credentials. The adapter does not retry or resume a disconnected turn automatically.
import 'dart:io';
final result = await streamText(
model: openai('gpt-4.1-mini'),
prompt: 'Count from 1 to 5.',
);
await for (final chunk in result.textStream) {
stdout.write(chunk);
}
final result = await generateText<Map<String, dynamic>>(
model: openai('gpt-4.1-mini'),
prompt: 'Return the capital and currency of Japan as JSON.',
output: Output.object(
schema: Schema<Map<String, dynamic>>(
jsonSchema: const {
'type': 'object',
'properties': {
'capital': {'type': 'string'},
'currency': {'type': 'string'},
},
},
fromJson: (json) => json,
),
),
);
print(result.output); // {capital: Tokyo, currency: JPY}
final result = await generateText(
model: openai('gpt-4.1-mini'),
prompt: 'What is the weather in Paris?',
maxSteps: 5,
tools: {
'getWeather': tool<Map<String, dynamic>, String>(
description: 'Get current weather for a city.',
inputSchema: Schema(
jsonSchema: const {
'type': 'object',
'properties': {'city': {'type': 'string'}},
},
fromJson: (json) => json,
),
execute: (input, _) async => 'Sunny, 18°C',
),
},
);
print(result.text);
try {
final result = await generateText(
model: openai('gpt-4.1-mini'),
prompt: 'Hello',
);
} on AiApiCallError catch (e) {
// Typed provider error — message, status, and retryability are all available.
print('${e.statusCode}: ${e.message} (retryable: ${e.isRetryable})');
}
dart pub add ai_sdk_dart ai_sdk_openai ai_sdk_flutter_ui
import 'package:ai_sdk_dart/ai_sdk_dart.dart';
import 'package:ai_sdk_openai/ai_sdk_openai.dart';
import 'package:ai_sdk_flutter_ui/ai_sdk_flutter_ui.dart';
final agent = ToolLoopAgent(
model: openai('gpt-4.1-mini'),
instructions: 'You are a helpful assistant.',
);
final chat = ChatController();
// In your widget — a complete chat surface:
AiChatScaffold(controller: chat, agent: agent);
Do not ship long-lived provider API keys inside distributed browser, mobile, or desktop clients. Use a trusted proxy or backend-minted short-lived credentials instead. The Flutter examples below use
--dart-definefor local development and smoke testing, not as a production secret-distribution strategy.
The ai_sdk_flutter_ui package provides three reactive controllers plus a library of 19 prebuilt,
themeable Material widgets — so you can wire up a full chat UI in a few lines, or drop down to the
controllers and render everything yourself.
import 'package:ai_sdk_dart/ai_sdk_dart.dart';
import 'package:ai_sdk_flutter_ui/ai_sdk_flutter_ui.dart';
import 'package:ai_sdk_openai/ai_sdk_openai.dart';
final agent = ToolLoopAgent(model: openai('gpt-4.1-mini'));
final chat = ChatController();
// A complete message list + composer, wired to the controller + agent:
AiChatScaffold(controller: chat, agent: agent);
Other widgets — ChatMessageList, ChatMessageBubble, ChatComposer, StreamingTextView,
TypingIndicator, ToolCallCard, ToolApprovalCard, ReasoningView, SourceCitations,
UsageView, PromptSuggestions, ObjectStreamView, and more — can be composed à la carte. They
read only the controllers' public state, so they work with any state-management approach.
final agent = ToolLoopAgent(model: openai('gpt-4.1-mini'));
final chat = ChatController();
// In your widget:
ListenableBuilder(
listenable: chat,
builder: (context, _) {
return Column(
children: [
for (final msg in chat.messages)
Text('${msg.role}: ${msg.content}'),
if (chat.isLoading) const CircularProgressIndicator(),
],
);
},
);
// Send a message:
await chat.sendMessage(agent: agent, text: 'What is the capital of France?');
final completion = CompletionController(
agent: ToolLoopAgent(model: openai('gpt-4.1-mini')),
);
await completion.complete('Write a haiku about Dart.');
print(completion.completion);
final controller = ObjectStreamController<Map<String, dynamic>>(
model: openai('gpt-4.1-mini'),
schema: Schema<Map<String, dynamic>>(
jsonSchema: const {'type': 'object'},
fromJson: (json) => json,
),
);
await controller.submit('Describe Japan as a JSON object.');
print(controller.value); // Partial updates arrive in real-time
Connect to any Model Context Protocol server and use its tools directly in your AI calls:
import 'package:ai_sdk_dart/ai_sdk_dart.dart';
import 'package:ai_sdk_mcp/ai_sdk_mcp.dart';
import 'package:ai_sdk_openai/ai_sdk_openai.dart';
final client = MCPClient(
transport: StreamableHttpClientTransport(
url: Uri.parse('http://localhost:3000/mcp'),
headers: {'Authorization': 'Bearer <short-lived-token>'},
),
);
await client.initialize();
final tools = await client.tools(); // Returns a ToolSet
final result = await generateText(
model: openai('gpt-4.1-mini'),
prompt: 'What files are in the project?',
tools: tools,
maxSteps: 5,
);
For stdio-based MCP servers (local processes):
final client = MCPClient(
transport: StdioMCPTransport(
command: 'npx',
args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/dir'],
),
);
StreamableHttpClientTransport speaks the MCP Streamable HTTP transport
(2025-06-18) against a single endpoint. It negotiates the protocol version
during initialize(), sends notifications/initialized, accepts JSON or SSE
responses to each POST, starts the optional GET SSE listener for
server-pushed notifications, reconnects that listener with Last-Event-ID, and
sends DELETE on shutdown when the server assigned Mcp-Session-Id. Put
required auth or routing headers in headers, but avoid embedding long-lived
secrets in shipped browser or mobile clients. The HTTP transport is web-safe —
dart:io is only pulled in by StdioMCPTransport on native platforms, behind
a conditional import — so the client also runs on Flutter web.
The client also has an explicit MCPProtocolMode.modern strategy for
protocol 2026-07-28, including per-request metadata, MRTR input-required
results, typed progress, and subscriptions/listen. MCP Tasks, cache-hint
interpretation, and arbitrary partial tool-output streams are outside the
current package surface; progress notifications do not represent partial
results.
generateText — full result envelope (text, steps, usage, reasoning, sources, files)streamText — complete event taxonomy (20 typed event types), onAbort callbackgenerateObject / structured output (object, array, choice, json) with native JSON schemaembed / embedMany + cosineSimilarity, wrapEmbeddingModelgenerateImage (OpenAI gpt-image-1 / DALL·E)generateSpeech (OpenAI TTS)transcribe (OpenAI Whisper)reranktimeout parameter on all core functionscustomProvider() for lightweight on-the-fly provider constructioncreateProviderRegistry) — 6 model categoriesAiApiCallError with status / type / code / body) across all providersContributions are welcome! Please open an issue first to discuss changes before submitting a PR.
fvm flutter pub get
make test
make analyze
Run make benchmark for the structured-stream throughput benchmark.
Or run a smaller set of pinned toolchain smoke checks directly:
fvm dart analyze .
fvm dart test packages/ai_sdk_dart/test/
fvm dart test packages/ai_sdk_openai/test/
fvm dart test packages/ai_sdk_anthropic/test/
fvm dart test packages/ai_sdk_google/test/
fvm flutter test examples/flutter_chat/
fvm flutter test examples/advanced_app/
CLI and server examples can read credentials from the process environment. The
repo make targets forward those values to the provider factories as
compile-time defines when needed:
OPENAI_API_KEY=sk-... make run-basic
OPENAI_API_KEY=sk-... make run-mcp
Equivalent direct Dart invocation:
OPENAI_API_KEY=sk-... \
fvm dart run --define=OPENAI_API_KEY=sk-... examples/basic/lib/main.dart
Flutter example apps are different: they read compile-time defines from
String.fromEnvironment, so pass keys with --dart-define:
cd examples/flutter_chat && fvm flutter run \
--dart-define=OPENAI_API_KEY=sk-...
cd examples/advanced_app && fvm flutter run \
--dart-define=OPENAI_API_KEY=sk-... \
--dart-define=ANTHROPIC_API_KEY=sk-ant-... \
--dart-define=GOOGLE_API_KEY=AIza...
The Flutter commands above compile the keys into the client app. Use them for local demos only. Production apps should call a trusted backend or fetch short-lived provider credentials instead of embedding long-lived secrets.
Managed with the Dart pub workspace and the repository Makefile:
fvm flutter pub get
make analyze
make test
See docs/v6-parity-matrix.md for a feature-by-feature parity matrix against Vercel AI SDK v6.
Dart/Flutter port of Vercel AI SDK v6 — provider-agnostic text generation, streaming, structured output, tools, embeddings, image gen, speech, MCP, and Flutter UI controllers
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Ai Sdk Dart 透過 stdio 在本機執行。
上次檢查時間:2026-10-27。 Dart/Flutter port of Vercel AI SDK v6 — provider-agnostic text generation, streaming, structured output, tools, embeddings, image gen, speech, MCP, and Flutter UI controllers