# Go AI SDK

> Go toolkit for AI applications and agents: text and object generation, streaming, tools, MCP, agents and many model providers behind one interface. Port of the Vercel AI SDK (TypeScript).

- Module: `github.com/digitallysavvy/go-ai` (packages under `github.com/digitallysavvy/go-ai/pkg/...`)
- Install: `go get github.com/digitallysavvy/go-ai@latest`
- Go version: Go 1.26 or later
- Docs: https://goaisdk.com/docs; append `.md` to any page URL for markdown

## The six calls you will use most

```go
import (
    "github.com/digitallysavvy/go-ai/pkg/agent"
    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/provider/types"
    "github.com/digitallysavvy/go-ai/pkg/providers/anthropic"
    "github.com/digitallysavvy/go-ai/pkg/providers/openai"
    "github.com/digitallysavvy/go-ai/pkg/schema"
)

// 1. Provider and model. Take model IDs from the provider's constants.
prov := anthropic.New(anthropic.Config{APIKey: os.Getenv("ANTHROPIC_API_KEY")})
model, err := prov.LanguageModel(anthropic.ClaudeSonnet5_5)

// 2. Generate text.
res, err := ai.GenerateText(ctx, ai.GenerateTextOptions{Model: model, Prompt: "Hello"})
fmt.Println(res.Text)

// 3. Stream text. Use Chunks(); the stream is not an io.Reader.
stream, err := ai.StreamText(ctx, ai.StreamTextOptions{Model: model, Prompt: "Hello"})
for c := range stream.Chunks() { fmt.Print(c.Text) }
err = stream.Err()

// 4. Structured output into a struct.
err = ai.GenerateObjectInto(ctx, ai.GenerateObjectOptions{
    Model: model, Prompt: "A pancake recipe",
    Schema: schema.NewSimpleStructSchema(reflect.TypeOf(Recipe{})),
}, &recipe)

// 5. Tools and an agent loop. Set ToolApproval to gate a tool.
tool := types.Tool{
    Name: "weather", Description: "Current weather", ToolApproval: true,
    Parameters: map[string]interface{}{"type": "object"},
    Execute: func(ctx context.Context, in map[string]interface{}, o types.ToolExecutionOptions) (interface{}, error) {
        return "sunny", nil
    },
}
a := agent.NewToolLoopAgent(agent.AgentConfig{
    Model: model, Tools: []types.Tool{tool}, StopWhen: []ai.StopCondition{ai.StepCountIs(5)},
})
out, err := a.Execute(ctx, "Weather in Oslo?") // out.Text

// 6. Embeddings.
emb, err := openai.New(openai.Config{APIKey: os.Getenv("OPENAI_API_KEY")}).EmbeddingModel(openai.ModelTextEmbedding3Small)
er, err := ai.Embed(ctx, ai.EmbedOptions{Model: emb, Input: "hello"}) // er.Embedding
```

## Gotchas

- `LanguageModel(id)` returns `(model, error)`; check the error.
- Streams are `provider.TextStream` (`Next`, `Err`, `Close`) or `Chunks()`. They do not implement `io.Reader`.
- Provider option and metadata keys are camelCase, as in the TypeScript SDK.
- Use `ToolApproval` on a tool. `NeedsApproval` is deprecated.
- `GenerateText` and `StreamText` run one step unless you set `StopWhen` (for example `ai.StepCountIs(5)`). A tool-loop agent defaults to 20 steps.
- For a useChat endpoint, `ai.PipeUIMessageStreamToResponse` and `agent.PipeAgentUIStreamFromUIMessagesToResponse` set the status and stream headers on an `http.ResponseWriter`. Do not set them yourself.
- `OnStepFinish` has different signatures in `ai` and `agent`. Check the godoc.

## Where to read next

- [llms.txt](https://goaisdk.com/llms.txt): index with a "Start here" block
- [llms-core.txt](https://goaisdk.com/llms-core.txt): the core pages in one file
- [sitemap.md](https://goaisdk.com/sitemap.md): every page with type and summary
- [Quick start](https://goaisdk.com/docs/getting-started/golang.md)
- [Generating text](https://goaisdk.com/docs/ai-sdk-core/generating-text.md)
- [Structured data](https://goaisdk.com/docs/ai-sdk-core/generating-structured-data.md)
- [Tools and tool calling](https://goaisdk.com/docs/ai-sdk-core/tools-and-tool-calling.md)
- [Building agents](https://goaisdk.com/docs/agents/building-agents.md)
- [Use Go AI SDK with coding agents](https://goaisdk.com/docs/getting-started/using-go-ai-with-coding-agents.md)
- Reference app (useChat frontend, Go backend, approval-gated tool, harness): https://github.com/digitallysavvy/go-ai-demo