Models

Models are reached only through interfaces in the stt, tts, llm, and vad packages. Concrete implementations come from provider plugins. The stt, tts, and vad interfaces each expose a Capabilities() struct so the runtime can adapt (the LLM does not).

All four share Label(), Model(), Provider(), a Metrics(ctx) channel, and Close(). Prewarm() is on the STT/LLM/TTS interfaces for providers that can warm connections ahead of first use — a plugin implements it; you don't call it.

llm.LLM

type LLM interface {
    Label() string
    Model() string
    Provider() string
    Chat(ctx context.Context, opts ChatOptions, conn model.APIConnectOptions) LLMStream
    ErrorEvents(ctx context.Context) <-chan LLMError
    Metrics(ctx context.Context) <-chan LLMMetrics
    Prewarm()
    Close() error
}

Chat returns a stream the runtime reads for text chunks and tool calls. Context is passed as an llm.ChatContext (the shared session history).

stt.STT

type STT interface {
    // ... Label/Model/Provider ...
    Capabilities() STTCapabilities
    Recognize(ctx, frames []*audio.AudioFrame, conn) (*SpeechEvent, error)  // one-shot
    Stream(ctx, conn) SpeechStream                                           // streaming
    ErrorEvents(ctx) <-chan STTError
    Metrics(ctx) <-chan STTMetrics
    Prewarm()
}

Recognize is one-shot over a complete buffer; Stream is push-frames / read-events for realtime transcription. Capabilities reports whether streaming is supported.

tts.TTS

type TTS interface {
    // ... Label/Model/Provider ...
    Capabilities() TTSCapabilities
    SampleRate() int
    NumChannels() int
    Synthesize(ctx, text string, conn) ChunkedStream  // one-shot
    Stream(ctx) SynthesizeStream                       // streaming
    // ... ErrorEvents / Metrics / Prewarm / Close ...
}

SampleRate / NumChannels describe the output audio the transport receives.

vad.VAD

type VAD interface {
    // ... Label/Model/Provider ...
    Capabilities() VADCapabilities
    MinSilenceDuration() *float64
    Stream(ctx) VADStream // push frames, read speech/silence events
    Metrics(ctx) <-chan VADMetrics
    Close() error
}

The VAD stream drives endpointing and barge-in detection — see Turn detection & interruption.

Model-spec strings (modelspec)

The modelspec package resolves "provider/model[:variant]" strings to these interfaces, so agents.Config fields can be strings. Providers self-register in their plugin's init (the database/sql driver pattern), so importing the plugin is enough:

import _ "github.com/webdeveloperben/agents-go/plugins/openai"

llm, err := modelspec.ResolveLLM("openai/gpt-4o")
// ResolveSTT, ResolveTTS, ResolveVAD likewise

The variant after : is provider-defined — a language for STT (deepgram/nova-3:en), a voice for TTS (openai/tts-1:alloy). A provider supports a capability by implementing that factory interface (modelspec.LLMFactory / STTFactory / TTSFactory / VADFactory). Keys come from the provider's env default — the registry holds factories, never credentials. Use the typed constructors for explicit options.

Setting models

Set on the session (default) or per-agent (override). The runtime resolves the agent's model when set, else the session's — see AgentSession.EffectiveModels().

Related

• Models & providers — the guide with worked examples.