goaisdk

README

go-ai-sdk

An idiomatic Go port of the Vercel AI SDK: a single, provider-agnostic API for generating text, streaming text, generating structured objects, calling tools, computing embeddings, and generating images/speech/transcriptions across 39 providers — OpenAI, Anthropic, Google (Gemini), Groq, xAI, DeepSeek, Together, Fireworks, Cerebras, Perplexity, Moonshot, Qwen, MiniMax, DeepInfra, Hugging Face, Baseten, LM Studio, NVIDIA NIM, Vercel AI Gateway, Mistral, Cohere, Voyage, Mixedbread, Azure OpenAI, Vertex AI, Amazon Bedrock, ElevenLabs, fal, Replicate, Luma, Deepgram, LMNT, Hume, AssemblyAI, Gladia, Rev.ai, Cartesia, Prodia, and Black Forest Labs — with the same concepts and naming as the TypeScript original, expressed in native Go (context.Context, iter.Seq, generics, typed errors) rather than mirrored line-for-line.

Status: v0.2. The public API has reached full parity with the AI SDK 6 core (see the migration guide's AI SDK 6 delta for the feature-by-feature record, and the v6 parity final audit for the closing have-list). It's implemented and tested end-to-end (unit tests plus a shared provider-conformance suite), but it is young: expect rough edges, and expect the API to move before a 1.0. Coming from the TypeScript SDK? Start with Migrating from the Vercel AI SDK.

v0.2.0 breaking change: ai.Telemetry.OnSpanStart gained a leading ctx context.Context parameter, and ai.SpanInfo gained CorrelationID — a one-line signature update for any hand-rolled Telemetry implementation. See CHANGELOG.md.

Install

go get github.com/azrtydxb/go-ai-sdk

Requires Go 1.26+. The OpenTelemetry bridge is a separate module (kept out of the root so the core SDK stays dependency-free) — go get it only if you want it:

go get github.com/azrtydxb/go-ai-sdk/contrib/otel

Quickstart

package main

import (
	"context"
	"fmt"

	"github.com/azrtydxb/go-ai-sdk/ai"
	"github.com/azrtydxb/go-ai-sdk/providers/anthropic"
)

func main() {
	model := anthropic.New().Model("claude-sonnet-5") // reads ANTHROPIC_API_KEY

	result, err := ai.GenerateText(context.Background(), ai.GenerateTextOpts{
		Model:  model,
		Prompt: "Why is the sky blue? Answer in one sentence.",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(result.Text)
}

Streaming looks the same shape, with the result's parts consumed as a Go iterator instead of a collected string:

import "github.com/azrtydxb/go-ai-sdk/provider"

stream, err := ai.StreamText(context.Background(), ai.GenerateTextOpts{
	Model:  model,
	Prompt: "Count from one to five.",
})
if err != nil {
	panic(err)
}
defer stream.Close()

for part := range stream.Parts() {
	if delta, ok := part.(provider.TextDelta); ok {
		fmt.Print(delta.Text)
	}
}
if err := stream.Err(); err != nil {
	panic(err)
}

That's the whole surface for the two most common calls — everything else (tool calling, structured output, embeddings, media, streaming internals, middleware, MCP, telemetry, provider-specific options) is one guide away in docs/, starting at Getting started. Complete, runnable, env-guarded examples covering text, streaming, tools, structured output, embeddings, images, speech, transcription, and MCP — including the multi-step tool-calling loop and ai.GenerateObject[T] — live in examples/, each compiled by CI.

Features

• Text generation — ai.GenerateText/ai.StreamText, with an automatic multi-step tool-calling loop (StopWhen, PrepareStep, OnStepFinish) and conversation continuation. Lifecycle callbacks (OnModelCallStart/OnModelCallEnd, OnToolExecutionStart/ OnToolExecutionEnd) bracket each underlying model request and tool execution. See Generating text.
• Tool calling — typed tools via ai.NewTool[Args] with a reflection-derived JSON Schema, ActiveTools, RepairToolCall, and a typed error taxonomy, plus ai.WithToolStrict()/ai.WithToolInputExamples (provider-enforced strict schemas and example payloads, folded into tool descriptions for providers without native support via ai.AddToolInputExamplesMiddleware) and per-tool input-streaming lifecycle hooks (ai.WithToolInputCallbacks). See Tools.
• Structured timeouts — GenerateTextOpts.Timeout{Total, Step, Chunk} bounds a whole run, each step, and stream-chunk staleness independently, surfacing an SDK-imposed bound as a typed *ai.TimeoutError, distinct from the caller's own context.Context being canceled (still OnAbort/ the plain ctx error, exactly as before). See Generating text § Timeout.
• Tool-execution approvals — ai.RequireApproval/ai.ApprovalRequirer gate a tool call on an inline decision (ApproveToolCall) or a suspend-then-resume flow (PendingApprovals/Approvals), with denials surfaced as a typed *ai.ToolApprovalDeniedError tool result. See Tools § Approvals for tool execution.
• RuntimeContext — an arbitrary application-value bag (GenerateTextOpts.RuntimeContext, ai.RuntimeContextFrom(ctx)) threaded into every tool call, approval check, and inline approval decision for a run. See Tools § RuntimeContext.
• Agents — agent.Agent bundles a model, instructions, tools, and loop options for repeated runs (Generate/Stream), and agent.AsTool exposes one agent as a tool for another to delegate to. See Agents.
• Code Mode — codemode.Tool wraps a set of tools into a single run_code tool the model writes short programs against, executed by a caller-supplied Sandbox (the SDK ships no runtime). See Code Mode.
• Structured output — ai.GenerateObject[T]/ai.StreamObject[T], native-JSON where a provider supports it and forced-tool-call mode otherwise. See Structured output.
• Output modes on GenerateText — GenerateTextOpts.Output (OutputObject[T], OutputArray[T], OutputChoice, OutputJSON) decodes a GenerateText call's final text into a typed value, extracted via ai.OutputAs[T], without a separate GenerateObject call (GenerateText-only for now; StreamText returns a typed error if Output is set). See Generating text § Output modes.
• Streaming — a StreamPart sequence (iter.Seq) covering text, tool calls, reasoning, and sources uniformly, plus ai.SmoothStream for steady-cadence UI rendering. See Streaming.
• Reasoning/thinking — surfaced uniformly as ReasoningPart/ ReasoningDelta/ReasoningEnd across every provider that supports it, and requestable uniformly too: GenerateTextOpts.Reasoning maps a single Effort/BudgetTokens option onto each provider's native reasoning knob (reasoning_effort, thinking, thinkingConfig, or additionalModelRequestFields.thinking). See Reasoning.
• Embeddings — ai.Embed/ai.EmbedMany with automatic batching and ai.CosineSimilarity. See Embeddings.
• Reranking — ai.Rerank ranks documents by relevance to a query via provider.RerankingModel (Cohere, Voyage, Mixedbread). See Embeddings § Reranking.
• Media — image generation, video generation, speech synthesis, transcription (including live streaming transcription), and audio translation, all behind the same provider-agnostic pattern where one exists. See Media.
• Video generation — ai.GenerateVideo/provider.VideoModel, Luma (Dream Machine, async poll), fal, and Replicate (both synchronous). See Media § GenerateVideo.
• Streaming transcription — ai.StreamTranscribe/ provider.StreamingTranscriptionModel, a live bidirectional session over a stdlib-only WebSocket client (internal/websocket); Deepgram and OpenAI (Realtime API, transcription mode) implement it. See Media § StreamTranscribe.
• Audio translation — ai.Translate/provider.TranslationModel (English-only output, regardless of source language), OpenAI only. See Media § Translate.
• Realtime voice session — (*openai.Provider).RealtimeSession, a live bidirectional voice/text conversation over OpenAI's Realtime API; OpenAI-only, no generic provider interface. See Media § Realtime voice session.
• Files and skills — ai.UploadFile/ai.DeleteFile/ provider.FileStore (OpenAI, Anthropic), referenced from a prompt via provider.FilePart.FileID; Anthropic's Skills API ((*anthropic.Provider).UploadSkill) is a distinct, Anthropic-only capability. See Media § Files & skills.
• Middleware and registry — compose behavior onto any provider.LanguageModel (ExtractReasoningMiddleware, SimulateStreamingMiddleware, DefaultSettingsMiddleware, TelemetryMiddleware) and resolve "provider:model" strings via ai.Registry. See Middleware and registry.
• Provider options — a raw-wire-key escape hatch (ProviderOptions/ProviderMetadata) for provider-specific request parameters that don't have a dedicated field. See Provider options.
• Errors and retries — every model call goes through a shared retry wrapper with typed, errors.As-able failure modes. See Errors and retries.
• Telemetry — a minimal, dependency-free span-reporting seam (ai.Telemetry/ai.TelemetryMiddleware) in the root module, plus a ready-to-use OpenTelemetry bridge — contrib/otel, a separate Go module (so the root stays zero-dependency) emitting real GenAI-semconv spans (gen_ai.operation.name, gen_ai.system, gen_ai.request.model, gen_ai.usage.*, gen_ai.response.finish_reasons). See Telemetry and contrib/otel/README.md.
• MCP (Model Context Protocol) — an MCP client (stdio and Streamable HTTP transports) that adapts a server's tools straight into ai.Tool, plus resources, resource templates, prompts, argument completions, and server-initiated elicitation (stdio only — Streamable HTTP has no server→client channel to receive it on), and token-provider auth with transient retry on the HTTP transport. See MCP.

Documentation

• Getting started — install, first call, env vars, streaming quickstart
• Core guides: Generating text · Tools · Structured output · Agents · Code Mode · Embeddings · Media · Streaming · Reasoning · Middleware and registry · Provider options · Errors and retries · Telemetry · MCP
• Providers: overview and capability matrix, plus one page per vendor under docs/providers/
• Reference: Troubleshooting · Migrating from the Vercel AI SDK · Architecture
• docs/README.md is the full index of the tree above.

Provider and capability matrix

All 39 supported providers, by capability (✅ = supported · — = not exposed by this package · ⚠ = supported with a caveat, see that provider's page in docs/providers/):

Provider	Chat & streaming	Tool calling	Structured output	Embeddings	Reranking	Images	Video	Speech (TTS)	Transcription (STT)
OpenAI	✅	✅	✅ native	✅	—	✅	—	✅	✅ ⚠ live
Azure OpenAI	✅	✅	✅ native	✅	—	—	—	—	—
Groq	✅	✅	✅ native	—	—	—	—	—	✅
xAI	✅	✅	✅ native	—	—	✅ ⚠	—	—	—
DeepSeek	✅	✅	⚠ json_object-only	—	—	—	—	—	—
Cerebras	✅	✅	✅ native	—	—	—	—	—	—
Together	✅	✅	✅ native	✅	—	—	—	—	—
Fireworks	✅	✅	✅ native	✅	—	—	—	—	—
Perplexity	✅	⚠ no live tools	✅ native	—	—	—	—	—	—
Moonshot	✅	✅	✅ native	—	—	—	—	—	—
Qwen	✅	✅	✅ native	✅	—	—	—	—	—
MiniMax	✅	✅	✅ native	—	—	—	—	—	—
DeepInfra	✅	✅	✅ native	✅	—	—	—	—	—
Hugging Face	✅	✅	⚠ tool-mode	—	—	—	—	—	—
Baseten	✅	✅	✅ native	✅	—	—	—	—	—
LM Studio	✅	✅	✅ native	✅	—	—	—	—	—
NVIDIA NIM	✅	✅	✅ native	✅	—	—	—	—	—
Vercel AI Gateway	✅	✅	⚠ tool-mode	✅	—	—	—	—	—
Mistral	✅	✅	⚠ schema dropped	✅	—	—	—	—	—
Cohere	✅	✅	✅ native	✅	✅	—	—	—	—
Voyage	—	—	—	✅	✅	—	—	—	—
Mixedbread	—	—	—	—	✅	—	—	—	—
ElevenLabs	—	—	—	—	—	—	—	✅	✅
Anthropic	✅	✅	⚠ tool-mode	—	—	—	—	—	—
Google	✅	✅	✅ native	✅	—	✅	—	—	—
Vertex AI	✅	✅	✅ native	✅	—	✅	—	—	—
Amazon Bedrock	✅	✅	⚠ tool-mode	✅	—	—	—	—	—
fal	—	—	—	—	—	✅	✅	—	—
Replicate	—	—	—	—	—	✅	✅	—	—
Luma	—	—	—	—	—	✅	✅	—	—
Deepgram	—	—	—	—	—	—	—	—	✅ ⚠ live
LMNT	—	—	—	—	—	—	—	✅	—
Hume	—	—	—	—	—	—	—	✅	—
AssemblyAI	—	—	—	—	—	—	—	—	✅
Gladia	—	—	—	—	—	—	—	—	✅
Rev.ai	—	—	—	—	—	—	—	—	✅
Cartesia	—	—	—	—	—	—	—	✅	—
Prodia	—	—	—	—	—	✅	—	—	—
Black Forest Labs	—	—	—	—	—	✅	—	—	—

"Native" structured output means schema-constrained JSON directly via native JSON mode; "tool-mode" (Anthropic, Bedrock, Hugging Face, Vercel AI Gateway) uses an automatically injected, forced tool call instead — the same GenerateObject[T] call works identically either way. Rerank is ai.Rerank/provider.RerankingModel — see Embeddings § Reranking. StreamTranscribe (Deepgram, OpenAI, live/bidirectional) and Translate (OpenAI-only) are not ai.Registry/capability-matrix columns above — see Media for both, plus RealtimeSession (OpenAI-only) and FileStore (OpenAI, Anthropic), also outside the registry.

This is the full capability matrix from docs/providers/README.md, which also carries the exact wording of every ⚠ caveat above and links to each provider's own page for the full detail.

Provider coverage

Providers	Notes
OpenAI, Anthropic, Google (Gemini)	Three distinct wire formats prove the abstraction
Groq, xAI, DeepSeek, Together, Fireworks, Cerebras, Perplexity, Moonshot, Qwen, MiniMax, DeepInfra, Hugging Face, Baseten, LM Studio, NVIDIA NIM, Vercel AI Gateway	Thin presets over the OpenAI-compatible base
Mistral, Cohere, Voyage, Mixedbread	Own APIs, full provider implementations (Voyage: embeddings + reranking; Mixedbread: reranking only)
Azure OpenAI, Vertex AI, Amazon Bedrock	Platform auth: Azure (API-key preset over the OpenAI-compatible base), Vertex AI (Google service-account/ADC auth), Bedrock (AWS SigV4 request signing)
ElevenLabs, fal, Replicate, Luma, Deepgram, LMNT, Hume, AssemblyAI, Gladia, Rev.ai, Cartesia, Prodia, Black Forest Labs; image/speech/transcription for OpenAI, Google/Vertex, xAI, Groq	Media-only or media-layered providers, all behind the same ImageModel/SpeechModel/TranscriptionModel interfaces

A handful of AI SDK 6 providers remain unimplemented — planned per the v6 parity roadmap.

See CHANGELOG.md for the full release history, and the design spec for architecture, package layout, and the full decisions log.

Contributing

See docs/architecture.md for how the SDK is laid out — the three-package-layer split, the OpenAI/Gemini "compat base" pattern most providers build on, the StreamResponse disciplines every streaming implementation follows, and step-by-step checklists for adding a new provider or a new capability.

License

Apache License 2.0.

Documentation

Overview

Package goaisdk is the module root of go-ai-sdk, an idiomatic Go port of the Vercel AI SDK: one provider-agnostic API for text generation, streaming, structured output, tool calling, embeddings, and image/speech/transcription across 39 providers.

This root package contains no code — it exists to orient you. Start with github.com/azrtydxb/go-ai-sdk/ai.

Layout

The module is layered, and you generally import exactly two packages: ai for the calls, and one providers/* package to name a model.

• ai — the high-level API. GenerateText, StreamText, GenerateObject[T], Embed/EmbedMany, GenerateImage/Speech/Video, Transcribe, plus tools, middleware, telemetry, and the retry/error model. Provider-agnostic: it reaches into no providers/* package.
• provider — the interfaces every provider implements (LanguageModel, EmbeddingModel, ImageModel, …) and the wire types they exchange (Message, ContentPart, StreamPart, Response, Usage). Implement these to add a provider; import them to write middleware.
• providers/* — one package per provider (anthropic, openai, google, bedrock, …), each returning models that satisfy provider's interfaces.
• agent — a reusable model+instructions+tools bundle over ai's loop, and sub-agent delegation via AsTool.
• mcp — a Model Context Protocol client, exposing an MCP server's tools as ai.Tool values via mcp.Tools.
• codemode — executing model-authored code against your tools.
• ai/aitest, provider/providertest — test doubles and a shared provider conformance suite.

The OpenTelemetry bridge lives in a separate module, github.com/azrtydxb/go-ai-sdk/contrib/otel, so the core SDK stays dependency-free.

Quickstart

model := anthropic.New().Model("claude-sonnet-5")

result, err := ai.GenerateText(ctx, ai.GenerateTextOpts{
	Model:  model,
	Prompt: "Why is the sky blue? Answer in one sentence.",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(result.Text)

Swapping providers means changing only the Model line. See the runnable examples on ai for streaming, structured output, and tool calling.

Documentation

The docs/ directory in the repository holds the full guide set: getting-started.md, architecture.md (how ai, provider, and providers/* relate), core/ (one guide per capability), providers/ (one per provider), mcp.md, troubleshooting.md, and migrating-from-vercel-ai-sdk.md for anyone arriving from the TypeScript SDK.