Build a voice agent
Wire a session to a transport and STT/LLM/TTS, and drive a turn.
This guide builds a working voice session end to end: a transport for audio I/O, the four models, an agent, and a running turn loop. It uses the console transport (PCM over stdin/stdout) so you can run it with no server — swap the transport later without touching agent code.
The entrypoint to the SDK is the AgentSession, not any one transport. The
session is transport-oblivious — console.Run here is just the lowest-friction
way to feed it audio. The same session code runs over WebSocket or WebRTC
(Transports), and a text-only agent needs no transport at all
(Quickstart).
Choose a transport
The console transport pipes signed-16-bit mono PCM in and out. It exposes
tr.Input() / tr.Output() audio seams that the session binds to. Everything
runs inside console.Run, which hands your Entrypoint a *console.Transport.
import "github.com/webdeveloperben/agents-go/transport/console"
console.Run(ctx, console.RunOptions{
Reader: os.Stdin,
Writer: os.Stdout,
Entrypoint: func(ctx context.Context, tr *console.Transport) error {
// build the session here (next steps)
return nil
},
})Create the session with models
An AgentSession binds the transport's audio to the four models. Config takes
model-spec strings; here we import plugins/fake so "fake/…" specs resolve and
the agent runs offline. Swap them for real specs like "openai/gpt-4o" (import
that plugin) when you're ready — see Models & providers.
import (
"github.com/webdeveloperben/agents-go/agents"
_ "github.com/webdeveloperben/agents-go/plugins/fake"
)
session := agents.MustNewSession(agents.Config{
STT: "fake/stt:hello",
VAD: "fake/vad",
LLM: "fake/llm",
TTS: "fake/tts",
Input: agents.SessionInput{Audio: tr.Input()},
Output: agents.SessionOutput{Audio: tr.Output()},
})
defer func() { _ = session.Close(ctx) }()Start with an agent
The agent is the persona. Start makes it the active agent and begins the turn
loop — from here the session listens, endpoints, generates, and speaks on its own.
agent := agents.MustNewAgent(agents.AgentOptions{
Instructions: "You are a brief, friendly assistant.",
})
if err := session.Start(ctx, agents.StartOptions{Agent: agent}); err != nil {
return err
}Run it
cat input.pcm | go run ./examples/console > output.pcmAudio in becomes agent audio out. The turn loop handles endpointing and barge-in for you — see Speech & the turn.
Going to production
- Swap the fakes for real models — Models & providers.
- Swap the console transport for WebRTC (
roomio) or Twilio — same session code, see Transports. - Give the agent things to do — Tools.
Related
- Quickstart — the smallest text-only version.
- Architecture — why the session is transport-oblivious.