Skip to main content

Go Quick Start

In this quickstart, you'll make a first text generation call, stream the response, give the model a tool, and wrap it all in a chat loop. Each step is a complete program you can run.

Prerequisites​

  • Go 1.26+ installed on your local development machine
  • An API key from a supported provider (OpenAI, Anthropic, Google, etc.)

If you haven't obtained your API key, sign up at your chosen provider's website.

Set up your application​

Create a new directory and initialize a Go module:

mkdir my-ai-app
cd my-ai-app
go mod init my-ai-app
go get github.com/digitallysavvy/go-ai
note

The Go AI SDK is a unified interface to large language models. You can change model and provider with a couple of lines of code. Learn more about available providers.

Set your API key​

The OpenAI provider reads OPENAI_API_KEY from the environment. Export it in the shell you will run the program from:

export OPENAI_API_KEY=sk-...

Other providers read their own variable, for example ANTHROPIC_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY.

If you prefer a .env file, Go does not load it on its own. Put OPENAI_API_KEY=sk-... in .env, install the loader with go get github.com/joho/godotenv, and add a blank import of its autoload package to main.go:

import _ "github.com/joho/godotenv/autoload"

The loader reads .env from the working directory when the program starts. Don't commit the file.

Generate text​

Create main.go:

package main

import (
"context"
"fmt"
"log"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/providers/openai"
)

func main() {
model, err := openai.New(openai.Config{}).LanguageModel(openai.ModelGPT6Astra)
if err != nil {
log.Fatal(err)
}

result, err := ai.GenerateText(context.Background(), ai.GenerateTextOptions{
Model: model,
Prompt: "Explain what a goroutine is in one sentence.",
})
if err != nil {
log.Fatal(err)
}

fmt.Println(result.Text)
}

Run it:

go run main.go

You should see one sentence about goroutines printed to your terminal. openai.ModelGPT6Astra is a constant for the model ID gpt-6-astra. Every provider package has constants like it in model_ids.go.

Stream the response​

ai.GenerateText waits for the whole answer. For a chat interface you want text as it arrives. Replace main.go with:

package main

import (
"context"
"fmt"
"log"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/provider"
"github.com/digitallysavvy/go-ai/pkg/providers/openai"
)

func main() {
model, err := openai.New(openai.Config{}).LanguageModel(openai.ModelGPT6Astra)
if err != nil {
log.Fatal(err)
}

stream, err := ai.StreamText(context.Background(), ai.StreamTextOptions{
Model: model,
Prompt: "Write a haiku about concurrency.",
})
if err != nil {
log.Fatal(err)
}

for chunk := range stream.Chunks() {
if chunk.Type == provider.ChunkTypeText {
fmt.Print(chunk.Text)
}
}
fmt.Println()

if err := stream.Err(); err != nil {
log.Fatal(err)
}
}

stream.Chunks() returns a channel of chunks. Text chunks carry the next piece of the answer. After the channel closes, stream.Err() reports any error that ended the stream early.

Switch providers​

To change providers, change the provider and model lines. The rest of your code stays the same.

Anthropic​

import "github.com/digitallysavvy/go-ai/pkg/providers/anthropic"

p := anthropic.New(anthropic.Config{
APIKey: os.Getenv("ANTHROPIC_API_KEY"),
})
model, err := p.LanguageModel(anthropic.ClaudeSonnet5_5)

Google​

import "github.com/digitallysavvy/go-ai/pkg/providers/google"

p := google.New(google.Config{
APIKey: os.Getenv("GOOGLE_GENERATIVE_AI_API_KEY"),
})
model, err := p.LanguageModel(google.ModelGemini31FlashLitePreview)

Add a tool​

Language models are poor at exact tasks like arithmetic and cannot see the outside world. Tools are Go functions the model can ask you to run. The SDK runs the function and sends the result back to the model.

This program gives the model a weather tool. StopWhen lets the model take several steps: call the tool, read the result, then answer.

package main

import (
"context"
"fmt"
"log"
"math/rand"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/provider/types"
"github.com/digitallysavvy/go-ai/pkg/providers/openai"
)

func main() {
model, err := openai.New(openai.Config{}).LanguageModel(openai.ModelGPT6Astra)
if err != nil {
log.Fatal(err)
}

weather := types.Tool{
Name: "getWeather",
Description: "Get the weather in a location (fahrenheit)",
Parameters: map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"location": map[string]interface{}{
"type": "string",
"description": "The location to get the weather for",
},
},
"required": []string{"location"},
},
Execute: func(ctx context.Context, params map[string]interface{}, opts types.ToolExecutionOptions) (interface{}, error) {
location, _ := params["location"].(string)
return map[string]interface{}{
"location": location,
"temperature": rand.Intn(59) + 32, // random 32-90°F
}, nil
},
}

result, err := ai.GenerateText(context.Background(), ai.GenerateTextOptions{
Model: model,
Prompt: "What's the weather in New York?",
Tools: []types.Tool{weather},
StopWhen: []ai.StopCondition{ai.IsStepCount(5)},
})
if err != nil {
log.Fatal(err)
}

fmt.Println(result.Text)
}

The tool returns a random temperature, so the answer changes on each run. Replace the body of Execute with a call to a real weather API when you are ready.

The pieces of a tool:

  1. Description helps the model decide when to use the tool.
  2. Parameters is a JSON Schema describing the input. Here it requires a location string.
  3. Execute runs your code and returns any JSON-serializable value.

Build a chat loop​

Now put the pieces together: a terminal chat that streams answers, keeps history, and can call the tool.

package main

import (
"bufio"
"context"
"fmt"
"log"
"math/rand"
"os"
"strings"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/provider"
"github.com/digitallysavvy/go-ai/pkg/provider/types"
"github.com/digitallysavvy/go-ai/pkg/providers/openai"
)

func main() {
ctx := context.Background()

model, err := openai.New(openai.Config{}).LanguageModel(openai.ModelGPT6Astra)
if err != nil {
log.Fatal(err)
}

tools := []types.Tool{
{
Name: "getWeather",
Description: "Get the weather in a location (fahrenheit)",
Parameters: map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"location": map[string]interface{}{
"type": "string",
"description": "The location to get the weather for",
},
},
"required": []string{"location"},
},
Execute: func(ctx context.Context, params map[string]interface{}, opts types.ToolExecutionOptions) (interface{}, error) {
location, _ := params["location"].(string)
return map[string]interface{}{
"location": location,
"temperature": rand.Intn(59) + 32,
}, nil
},
},
}

messages := []types.Message{}
reader := bufio.NewReader(os.Stdin)

fmt.Println("AI chat (type 'exit' to quit)")

for {
fmt.Print("You: ")
userInput, err := reader.ReadString('\n')
userInput = strings.TrimSpace(userInput)
if err != nil || userInput == "exit" {
break
}
if userInput == "" {
continue
}

messages = append(messages, types.Message{
Role: types.RoleUser,
Content: []types.ContentPart{types.TextContent{Text: userInput}},
})

stream, err := ai.StreamText(ctx, ai.StreamTextOptions{
Model: model,
Messages: messages,
Tools: tools,
StopWhen: []ai.StopCondition{ai.IsStepCount(5)},
})
if err != nil {
log.Printf("Error: %v\n", err)
messages = messages[:len(messages)-1]
continue
}

fmt.Print("\nAssistant: ")
var answer strings.Builder
for chunk := range stream.Chunks() {
if chunk.Type == provider.ChunkTypeText {
fmt.Print(chunk.Text)
answer.WriteString(chunk.Text)
}
}
fmt.Print("\n\n")

if err := stream.Err(); err != nil {
log.Printf("Stream error: %v\n", err)
messages = messages[:len(messages)-1]
continue
}

messages = append(messages, types.Message{
Role: types.RoleAssistant,
Content: []types.ContentPart{types.TextContent{Text: answer.String()}},
})
}
}

Run it with go run main.go and ask "What's the weather in New York in celsius?". The model calls getWeather, reads the result, converts it, and streams the answer.

What the loop does:

  1. Keeps history in the messages slice. Each turn appends the user message, then the assistant's answer.
  2. Streams each answer with ai.StreamText and prints text chunks as they arrive.
  3. Allows several steps with StopWhen, so tool calls resolve before the final answer.
  4. Rolls back the last user message if a call fails, so history stays consistent.

To add more tools, append them to the tools slice. A model can chain tools, for example one that fetches a temperature and one that converts it.

Where to Next?​

You've built an AI agent using the Go AI SDK! From here, you have several paths to explore:

  • Build a chat app - Serve a useChat frontend from Go, add tool approval and run coding agents, based on the Shipyard demo
  • Recipes - Short, complete programs for common tasks
  • Foundations - Learn about core concepts like providers, prompts, and streaming
  • AI SDK Core - Explore the complete API reference
  • Agents - Build more sophisticated autonomous agents
  • Advanced Topics - Learn about production patterns like caching, rate limiting, and backpressure
  • Examples - Check out more example applications

Production Tips​

When moving to production, consider:

  1. Error Handling - Implement proper error handling and retry logic
  2. Context Timeouts - Set appropriate timeouts for your use case
  3. Rate Limiting - Respect provider rate limits
  4. Monitoring - Add telemetry and logging
  5. Cost Management - Monitor token usage and implement caching

Example with timeout and better error handling:

import providererrors "github.com/digitallysavvy/go-ai/pkg/provider/errors"

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := ai.GenerateText(ctx, options)
if err != nil {
var rateLimitErr *providererrors.RateLimitError
var providerErr *providererrors.ProviderError
switch {
case errors.As(err, &rateLimitErr):
log.Printf("Rate limited: %v", rateLimitErr)
// Wait and retry, respecting rateLimitErr.RetryAfterSeconds if set
case errors.As(err, &providerErr):
log.Printf("Provider error (%d): %v", providerErr.StatusCode, providerErr)
// Retry on 5xx, fail fast on 4xx
case providererrors.IsValidationError(err):
log.Printf("Invalid input: %v", err)
// Fix the request
default:
log.Printf("Unknown error: %v", err)
}
return
}