Quickstart
Run a real agent turn with an LLM in under 20 lines.
The smallest real agent: an AgentSession with an LLM that answers one prompt.
This runs with just an API key — no audio or transport yet, so you can confirm
the core loop before wiring a voice pipeline.
Prerequisites
- Go 1.26+ and the SDK installed (Installation).
OPENAI_API_KEYset in your environment.
Run one turn
Build the session and agent. Models are named with "provider/model" strings;
importing a provider plugin registers it (the blank openai import below), so
"openai/gpt-4o" resolves — the key comes from OPENAI_API_KEY.
package main
import (
"context"
"fmt"
"log"
"time"
"github.com/webdeveloperben/agents-go/agents"
// Registers the OpenAI provider so "openai/..." specs resolve.
_ "github.com/webdeveloperben/agents-go/plugins/openai"
)
func main() {
session, err := agents.NewSession(agents.Config{
LLM: "openai/gpt-4o",
})
if err != nil {
log.Fatal(err)
}
defer func() { _ = session.Close(context.Background()) }()
agent := agents.MustNewAgent(agents.AgentOptions{
Instructions: "You are a concise assistant. Answer in one sentence.",
})Start the session on the agent and run a turn. Run appends the user input,
generates the reply, and returns a RunResult.
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := session.Start(ctx, agents.StartOptions{Agent: agent}); err != nil {
log.Fatal(err)
}
result, err := session.Run(ctx, agents.RunOptions{
UserInput: "What is agents-go in one line?",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(result.FinalOutput())
}"provider/model" strings are a convenience that resolves through the imported
plugins. You can always pass a concrete model instead — Config{LLM: openai.NewLLM(openai.LLMOptions{Model: "gpt-4o", Temperature: ...})} — when you
need full provider options. See Connect a provider.
Verify
OPENAI_API_KEY=sk-... go run .You should see a one-sentence reply printed. The LLM lives on the Agent, so a handoff can switch models without recreating the session.
This is a text-only turn — no microphone, speaker, or transport. To make it a voice agent, add STT/TTS/VAD models and bind the session to a transport's audio I/O; see Build a voice agent.
NewX returns (value, error); the MustNewX variants (like
MustNewAgentSession) panic instead. The Must forms keep setup code and
examples terse — use the error-returning forms where you want to handle failure.
Next
- How a turn flows — what
Runactually does. - Agents, sessions & tasks — the objects you just used.