Skip to content
Back to search

goai

SkillWorks with Claude CodeGitHub

Go AI SDK, the Go way. One unified API across 21+ providers. Streaming, structured output, MCP support, stdlib only. Go AI SDK for AI applications inspired by Vercel AI SDK.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zendev-sh--goai/badge.svg)](/listings/zendev-sh--goai)

HTML

<a href="/listings/zendev-sh--goai"><img src="/api/listings/zendev-sh--goai/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

go get github.com/zendev-sh/goai@latest

Requires Go 1.25+.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 627 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # GoAI SDK - AI Agent Skill
  2. > Instructions for AI coding agents helping developers use the GoAI SDK.
  3. > Load this file when a user's project imports `github.com/zendev-sh/goai`.
  4. ## Overview
  5. GoAI is a Go SDK for AI applications. One unified API across 25+ LLM providers. Inspired by the Vercel AI SDK, adapted to Go idioms (generics, interfaces, channels).
  6. - **Package**: `github.com/zendev-sh/goai`
  7. - **Go version**: 1.25+
  8. - **Dependencies**: stdlib + `golang.org/x/oauth2` for Vertex AI. Optional `observability/otel` submodule adds OTel SDK (separate go.mod, not pulled unless imported).
  9. - **Docs**: https://goai.sh
  10. - **GoDoc**: https://pkg.go.dev/github.com/zendev-sh/goai
  11. ## Quick Reference
  12. ```
  13. go get github.com/zendev-sh/goai@latest
  14. ```
  15. ```go
  16. import (
  17. "github.com/zendev-sh/goai"
  18. "github.com/zendev-sh/goai/provider/openai" // or any provider
  19. )
  20. ```
  21. ## Core API
  22. ### 8 Top-Level Functions
  23. | Function | Purpose | Returns |
  24. | --------------------------------------------- | ------------------------------- | --------------------------- |
  25. | `goai.GenerateText(ctx, model, opts...)` | Non-streaming text generation | `(*TextResult, error)` |
  26. | `goai.StreamText(ctx, model, opts...)` | Streaming text via channels | `(*TextStream, error)` |
  27. | `goai.GenerateObject[T](ctx, model, opts...)` | Typed structured output (JSON) | `(*ObjectResult[T], error)` |
  28. | `goai.StreamObject[T](ctx, model, opts...)` | Streaming structured output | `(*ObjectStream[T], error)` |
  29. | `goai.Embed(ctx, model, text, opts...)` | Single text embedding | `(*EmbedResult, error)` |
  30. | `goai.EmbedMany(ctx, model, texts, opts...)` | Batch embeddings (auto-chunked) | `(*EmbedManyResult, error)` |
  31. | `goai.GenerateImage(ctx, model, imgOpts...)` | Image generation | `(*ImageResult, error)` |
  32. | `goai.GenerateVideo(ctx, model, vidOpts...)` | Video generation | `(*VideoResult, error)` |
  33. ### Model Constructors
  34. Each provider has `Chat()`, and optionally `Embedding()`, `Image()`, and `Video()`:
  35. ```go
  36. // Language models
  37. openai.Chat("gpt-4o")
  38. anthropic.Chat("claude-sonnet-4-20250514")
  39. google.Chat("gemini-2.5-flash")
  40. bedrock.Chat("anthropic.claude-sonnet-4-20250514-v1:0")
  41. azure.Chat("gpt-4o", azure.WithEndpoint("https://my-resource.openai.azure.com"))
  42. vertex.Chat("gemini-2.5-flash", vertex.WithProject("my-project"), vertex.WithLocation("us-central1"))
  43. groq.Chat("llama-3.3-70b-versatile")
  44. ollama.Chat("llama3.2")
  45. // Embedding models
  46. openai.Embedding("text-embedding-3-small")
  47. google.Embedding("text-embedding-004")
  48. cohere.Embedding("embed-english-v3.0")
  49. ollama.Embedding("nomic-embed-text")
  50. // Image models
  51. openai.Image("gpt-image-1")
  52. google.Image("imagen-4.0-generate-001")
  53. // Video models
  54. google.Video("veo-3.1-generate-preview")
  55. ```
  56. ### Auth - Auto-Resolved from Environment
  57. Providers auto-read API keys from env vars. No explicit config needed:
  58. | Provider | Env Var |
  59. | --------- | ------------------------------------------------------------ |
  60. | OpenAI | `OPENAI_API_KEY` |
  61. | Anthropic | `ANTHROPIC_API_KEY` |
  62. | Google | `GOOGLE_GENERATIVE_AI_API_KEY` or `GEMINI_API_KEY` |
  63. | Bedrock | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION` |
  64. | Azure | `AZURE_OPENAI_API_KEY` |
  65. | Vertex AI | Application Default Credentials (ADC) |
  66. | xAI | `XAI_API_KEY` |
  67. | Groq | `GROQ_API_KEY` |
  68. | Cohere | `COHERE_API_KEY` |
  69. | Mistral | `MISTRAL_API_KEY` |
  70. | DeepSeek | `DEEPSEEK_API_KEY` |
  71. Or set explicitly:
  72. ```go
  73. model := openai.Chat("gpt-4o", openai.WithAPIKey("sk-..."))
  74. ```
  75. Most providers support these options (Bedrock uses AWS credential options; Ollama requires no auth):
  76. ```go
  77. openai.WithAPIKey(key) // static API key
  78. openai.WithTokenSource(ts) // dynamic auth (OAuth, service accounts)
  79. openai.WithBaseURL(url) // override endpoint (Azure uses WithEndpoint)
  80. openai.WithHeaders(h) // custom HTTP headers
  81. openai.WithHTTPClient(c) // custom HTTP transport
  82. ```
  83. ---
  84. ## Patterns and Examples
  85. ### 1. Basic Text Generation
  86. ```go
  87. result, err := goai.GenerateText(ctx, openai.Chat("gpt-4o"),
  88. goai.WithSystem("You are a helpful assistant."),
  89. goai.WithPrompt("What is Go?"),
  90. )
  91. if err != nil {
  92. return err
  93. }
  94. fmt.Println(result.Text)
  95. ```
  96. ### 2. Streaming
  97. ```go
  98. stream, err := goai.StreamText(ctx, openai.Chat("gpt-4o"),
  99. goai.WithPrompt("Write a poem about Go."),
  100. )
  101. if err != nil {
  102. return err
  103. }
  104. // Option A: text-only channel
  105. for text := range stream.TextStream() {
  106. fmt.Print(text)
  107. }
  108. // Option B: raw chunks (mutually exclusive with TextStream)
  109. // for chunk := range stream.Stream() { ... }
  110. // Always available after streaming completes:
  111. result := stream.Result()
  112. fmt.Printf("\nTokens: %d in, %d out\n", result.TotalUsage.InputTokens, result.TotalUsage.OutputTokens)
  113. ```
  114. **Important**: `Stream()` and `TextStream()` are mutually exclusive. Only call one. `Result()` can always be called after either.
  115. ### 3. Structured Output (Generics)
  116. ```go
  117. type Recipe struct {
  118. Name string `json:"name" jsonschema:"description=Recipe name"`
  119. Ingredients []string `json:"ingredients"`
  120. Steps []string `json:"steps"`
  121. Difficulty string `json:"difficulty" jsonschema:"enum=easy|medium|hard"`
  122. }
  123. result, err := goai.GenerateObject[Recipe](ctx, openai.Chat("gpt-4o"),
  124. goai.WithPrompt("Chocolate chip cookies recipe"),
  125. )
  126. if err != nil {
  127. return err
  128. }
  129. fmt.Println(result.Object.Name) // typed access
  130. fmt.Println(result.Object.Difficulty) // "easy", "medium", or "hard"
  131. ```
  132. Schema is auto-generated from struct tags. Supported tags:
  133. - `json:"name"` - property name
  134. - `json:"-"` - exclude field
  135. - `jsonschema:"description=..."` - adds description
  136. - `jsonschema:"enum=a|b|c"` - restricts to enum values
  137. Supported types: string, bool, int/uint (all sizes), float32/64, slices, maps (string keys), structs (embedded structs flattened), pointers (nullable).
  138. ### 4. Streaming Structured Output
  139. ```go
  140. stream, err := goai.StreamObject[Recipe](ctx, model,
  141. goai.WithPrompt("Chocolate chip cookies recipe"),
  142. )
  143. if err != nil {
  144. return err
  145. }
  146. for partial := range stream.PartialObjectStream() {
  147. fmt.Printf("Name so far: %s\n", partial.Name)
  148. }
  149. result, err := stream.Result()
  150. // result.Object is the final validated Recipe
  151. ```
  152. ### 5. Tool Calling
  153. ```go
  154. weatherTool := goai.Tool{
  155. Name: "get_weather",
  156. Description: "Get weather for a city.",
  157. InputSchema: json.RawMessage(`{
  158. "type": "object",
  159. "properties": {
  160. "city": {"type": "string", "description": "City name"}
  161. },
  162. "required": ["city"]
  163. }`),
  164. Execute: func(ctx context.Context, input json.RawMessage) (string, error) {
  165. var params struct {
  166. City string `json:"city"`
  167. }
  168. if err := json.Unmarshal(input, &params); err != nil {
  169. return "", err
  170. }
  171. return fmt.Sprintf("72F and sunny in %s", params.City), nil
  172. },
  173. }
  174. result, err := goai.GenerateText(ctx, model,
  175. goai.WithPrompt("What's the weather in Tokyo?"),
  176. goai.WithTools(weatherTool),
  177. goai.WithMaxSteps(3), // enable auto tool loop
  178. )
  179. ```
  180. **Key rules:**
  181. - `WithMaxSteps(1)` (default) = no auto loop, tool calls returned in `result.ToolCalls`
  182. - `WithMaxSteps(n)` where n > 1 = auto loop: generate -> execute tools -> re-generate -> repeat
  183. - Tools without `Execute` are sent as definitions only (for manual handling)
  184. - Tool errors are passed back to the model as `"error: ..."` messages
  185. ### 6. Conversation History
  186. ```go
  187. result, err := goai.GenerateText(ctx, model,
  188. goai.WithSystem("You are a helpful assistant."),
  189. goai.WithMessages(
  190. goai.UserMessage("Hi, my name is Alice."),
  191. goai.AssistantMessage("Hello Alice! How can I help you?"),
  192. goai.UserMessage("What's my name?"),
  193. ),
  194. )
  195. ```
  196. Message builders:
  197. - `goai.SystemMessage(text)` - system message
  198. - `goai.UserMessage(text)` - user message
  199. - `goai.AssistantMessage(text)` - assistant message
  200. - `goai.ToolMessage(toolCallID, toolName, output)` - tool result
  201. ### 7. Embeddings
  202. ```go
  203. // Single embedding
  204. model := openai.Embedding("text-embedding-3-small")
  205. result, err := goai.Embed(ctx, model, "Hello world")
  206. fmt.Printf("Dimensions: %d\n", len(result.Embedding))
  207. // Batch embeddings (auto-chunked, parallel)
  208. results, err := goai.EmbedMany(ctx, model, []string{"text1", "text2", "text3"},
  209. goai.WithMaxParallelCalls(4),
  210. )
  211. ```
  212. ### 8. Image Generation
  213. ```go
  214. result, err := goai.GenerateImage(ctx, openai.Image("gpt-image-1"),
  215. goai.WithImagePrompt("A gopher writing Go code"),
  216. goai.WithImageSize("1024x1024"),
  217. goai.WithImageCount(1),
  218. )
  219. // result.Images[0].Data = raw bytes, result.Images[0].MediaType = "image/png"
  220. ```
  221. **Note**: `GenerateImage` uses `ImageOption` (not `Option`): `WithImagePrompt`, `WithImageCount`, `WithImageSize`, `WithAspectRatio`, `WithImageMaxRetries`, `WithImageTimeout`, `WithImageProviderOptions`.
  222. ### 9. Video Generation
  223. ```go
  224. result, err := goai.GenerateVideo(ctx, google.Video("veo-3.1-generate-preview"),
  225. goai.WithVideoPrompt("A gopher writing Go code"),
  226. goai.WithVideoAspectRatio("16:9"),
  227. goai.WithVideoDuration(8*time.Second),
  228. )
  229. // result.Video.Data = raw bytes, result.Video.MediaType = "video/mp4"
  230. ```
  231. Video generation handles asynchronous operation polling and authenticated downloads. Use `WithVideoImage` for image-to-video and `WithVideoPollTimeout` to bound long-running operations.
  232. ### 10. Provider-Defined Tools (Server-Side)
  233. Built-in tools executed by the provider, not your code:
  234. ```go
  235. // OpenAI web search
  236. result, err := goai.GenerateText(ctx, openai.Chat("gpt-4o"),
  237. goai.WithPrompt("Latest Go release?"),
  238. goai.WithTools(providerTool(openai.Tools.WebSearch())),
  239. )
  240. // Google Search grounding
  241. result, err := goai.GenerateText(ctx, google.Chat("gemini-2.5-flash"),
  242. goai.WithPrompt("Latest news about Go"),
  243. goai.WithTools(providerTool(google.Tools.GoogleSearch())),
  244. )
  245. // Anthropic code execution
  246. result, err := goai.GenerateText(ctx, anthropic.Chat("claude-sonnet-4-20250514"),
  247. goai.WithPrompt("Calculate fibonacci(10)"),
  248. goai.WithTools(providerTool(anthropic.Tools.CodeExecution())),
  249. )
  250. // Helper to convert provider.ToolDefinition → goai.Tool:
  251. func providerTool(td provider.ToolDefinition) goai.Tool {
  252. return goai.Tool{
  253. Name: td.Name, ProviderDefinedType: td.ProviderDefinedType,
  254. ProviderDefinedOptions: td.ProviderDefinedOptions,
  255. }
  256. }
  257. ```
  258. Available provider tools:
  259. - **OpenAI**: `WebSearch()`, `CodeInterpreter()`, `ImageGeneration()`, `FileSearch(opts...)`
  260. - **Anthropic**: `WebSearch()`, `WebFetch()`, `Computer(opts)`, `Bash()`, `TextEditor()`, `CodeExecution()`, `ToolSearchToolRegex()`, `ToolSearchToolBM25()` (+ versioned variants)
  261. - **Google**: `GoogleSearch()`, `URLContext()`, `CodeExecution()`, `ComputerUse(opts...)`, `FileSearch(opts...)`
  262. - **xAI**: `WebSearch()`, `XSearch()`
  263. - **Groq**: `BrowserSearch()`
  264. ### 11. Observability Hooks
  265. ```go
  266. result, err := goai.GenerateText(ctx, model,
  267. goai.WithPrompt("Hello"),
  268. goai.WithOnRequest(func(info goai.RequestInfo) {
  269. log.Printf("Calling %s with %d messages", info.Model, info.MessageCount)
  270. }),
  271. goai.WithOnResponse(func(info goai.ResponseInfo) {
  272. log.Printf("Response in %v, tokens: %d", info.Latency, info.Usage.TotalTokens)
  273. }),
  274. goai.WithOnStepFinish(func(step goai.StepResult) {
  275. log.Printf("Step %d: %s, tools: %d", step.Number, step.FinishReason, len(step.ToolCalls))
  276. }),
  277. goai.WithOnToolCall(func(info goai.ToolCallInfo) {
  278. log.Printf("Tool %s (step %d) took %v, input: %s", info.ToolName, info.Step, info.Duration, info.Input)
  279. }),
  280. )
  281. ```
  282. ---
  283. ## Complete Options Reference
  284. ### Core Options (type `goai.Option`)
  285. ```go
  286. goai.WithSystem(s string) // system prompt
  287. goai.WithPrompt(s string) // single user message (shorthand)
  288. goai.WithMessages(msgs ...provider.Message) // conversation history
  289. goai.WithPromptCaching(bool) // enable prompt caching
  290. goai.WithTools(tools ...goai.Tool) // available tools
  291. goai.WithMaxSteps(n int) // auto tool loop iterations (default: 1)
  292. goai.WithToolChoice(tc string) // "auto" | "none" | "required" | "<tool_name>"
  293. goai.WithMaxOutputTokens(n int) // response length limit
  294. goai.WithTemperature(t float64) // randomness (0.0 - 2.0)
  295. goai.WithTopP(p float64) // nucleus sampling
  296. goai.WithTopK(k int) // top-K sampling
  297. goai.WithFrequencyPenalty(p float64) // frequency penalty
  298. goai.WithPresencePenalty(p float64) // presence penalty
  299. goai.WithSeed(s int) // deterministic generation
  300. goai.WithStopSequences(seqs ...string) // stop sequences
  301. goai.WithMaxRetries(n int) // retry count (default: 2)
  302. goai.WithRetryObserver(fn RetryObserver) // observe retry attempts
  303. goai.WithTimeout(d time.Duration) // request timeout
  304. goai.WithHeaders(h map[string]string) // additional HTTP headers
  305. goai.WithProviderOptions(opts map[string]any) // provider-specific params
  306. goai.WithOnRequest(fn func(RequestInfo)) // before each API call
  307. goai.WithOnResponse(fn func(ResponseInfo)) // after each API call
  308. goai.WithOnStepFinish(fn func(StepResult)) // after each step
  309. goai.WithOnToolCallStart(fn func(ToolCallStartInfo)) // before each tool execution
  310. goai.WithOnToolCall(fn func(ToolCallInfo)) // after each tool execution
  311. goai.WithOnFinish(fn func(FinishInfo)) // after generation terminates
  312. goai.WithOnPanic(fn func(PanicInfo)) // observe recovered callback panics
  313. goai.WithOnBeforeStep(fn func(BeforeStepInfo) BeforeStepResult)
  314. goai.WithOnBeforeToolExecute(fn func(BeforeToolExecuteInfo) BeforeToolExecuteResult)
  315. goai.WithOnAfterToolExecute(fn func(AfterToolExecuteInfo) AfterToolExecuteResult)
  316. goai.WithExplicitSchema(schema json.RawMessage) // override auto-generated schema
  317. goai.WithSchemaName(name string) // schema name (default: "response")
  318. goai.WithMaxParallelCalls(n int) // EmbedMany parallelism (default: 4)
  319. goai.WithEmbeddingProviderOptions(opts map[string]any) // embedding-specific params
  320. ```
  321. ### Image Options (type `goai.ImageOption`)
  322. ```go
  323. goai.WithImagePrompt(prompt string) // text prompt
  324. goai.WithImageCount(n int) // number of images (default: 1)
  325. goai.WithImageSize(size string) // e.g. "1024x1024"
  326. goai.WithAspectRatio(ratio string) // e.g. "16:9"
  327. goai.WithImageMaxRetries(n int) // retries on 429/5xx
  328. goai.WithImageTimeout(d time.Duration) // overall timeout
  329. goai.WithImageProviderOptions(opts map[string]any) // provider-specific params
  330. ```
  331. ### Video Options (type `goai.VideoOption`)
  332. ```go
  333. goai.WithVideoPrompt(prompt string)
  334. goai.WithVideoImage(image provider.MediaData)
  335. goai.WithVideoCount(n int)
  336. goai.WithVideoAspectRatio(ratio string)
  337. goai.WithVideoResolution(resolution string)
  338. goai.WithVideoDuration(d time.Duration)
  339. goai.WithVideoFPS(fps int)
  340. goai.WithVideoSeed(seed int64)
  341. goai.WithVideoFrameImages(frames ...provider.VideoFrame)
  342. goai.WithVideoInputReferences(refs ...provider.MediaData)
  343. goai.WithVideoAudio(enabled bool)
  344. goai.WithVideoProviderOptions(opts map[string]any)
  345. goai.WithVideoMaxRetries(n int)
  346. goai.WithVideoTimeout(d time.Duration)
  347. goai.WithVideoPollInterval(d time.Duration)
  348. goai.WithVideoPollTimeout(d time.Duration)
  349. ```
  350. ---
  351. ## Result Types
  352. ### TextResult (from GenerateText / StreamText)
  353. ```go
  354. type TextResult struct {
  355. Text string // accumulated generated text
  356. Reasoning string // accumulated reasoning text
  357. ToolCalls []provider.ToolCall // tool calls from final step
  358. Steps []StepResult // per-step results
  359. TotalUsage provider.Usage // aggregated token usage
  360. FinishReason provider.FinishReason // "stop", "tool-calls", "length", etc.
  361. Response provider.ResponseMetadata // provider metadata (ID, Model)
  362. ProviderMetadata map[string]map[string]any // provider-specific response data
  363. Sources []provider.Source // citations/references
  364. StepsExhausted bool // whether MaxSteps was exhausted
  365. ResponseMessages []provider.Message // messages for the next turn
  366. }
  367. ```
  368. ### ObjectResult[T] (from GenerateObject / StreamObject)
  369. ```go
  370. type ObjectResult[T any] struct {
  371. Object T // the parsed typed object
  372. Usage provider.Usage // total token consumption across all steps
  373. FinishReason provider.FinishReason
  374. Response provider.ResponseMetadata
  375. ProviderMetadata map[string]map[string]any // provider-specific response data
  376. ResponseMessages []provider.Message // messages for the next turn
  377. Steps []StepResult // results from each generation step (multi-step tool loops)
  378. }
  379. ```
  380. ### EmbedResult / EmbedManyResult
  381. ```go
  382. type EmbedResult struct {
  383. Embedding []float64
  384. Usage provider.Usage
  385. ProviderMetadata map[string]map[string]any
  386. Response provider.ResponseMetadata
  387. }
  388. type EmbedManyResult struct {
  389. Embeddings [][]float64
  390. Usage provider.Usage
  391. ProviderMetadata map[string]map[string]any
  392. Response provider.ResponseMetadata
  393. }
  394. ```
  395. ### ImageResult
  396. ```go
  397. type ImageResult struct {
  398. Images []provider.ImageData
  399. ProviderMetadata map[string]map[string]any
  400. Usage provider.Usage
  401. Response provider.ResponseMetadata
  402. }
  403. ```
  404. ### VideoResult
  405. ```go
  406. type VideoResult struct {
  407. Video provider.VideoData
  408. Videos []provider.VideoData
  409. ProviderMetadata map[string]map[string]any
  410. Response provider.ResponseMetadata
  411. }
  412. ```
  413. ### provider.Usage
  414. ```go
  415. type Usage struct {
  416. InputTokens int
  417. OutputTokens int
  418. TotalTokens int
  419. ReasoningTokens int
  420. CacheReadTokens int
  421. CacheWriteTokens int
  422. }
  423. ```
  424. ---
  425. ## Error Handling
  426. ```go
  427. import "errors"
  428. result, err := goai.GenerateText(ctx, model, goai.WithPrompt("..."))
  429. if err != nil {
  430. var apiErr *goai.APIError
  431. var overflowErr *goai.ContextOverflowError
  432. if errors.As(err, &overflowErr) {
  433. // Prompt too long for context window - truncate messages and retry
  434. log.Printf("Context overflow: %s", overflowErr.Message)
  435. } else if errors.As(err, &apiErr) {
  436. log.Printf("API error %d: %s (retryable: %v)", apiErr.StatusCode, apiErr.Message, apiErr.IsRetryable)
  437. } else {
  438. log.Printf("Error: %v", err)
  439. }
  440. }
  441. ```
  442. **Always use `errors.As()`, never type assertion.**
  443. Built-in retry: transient errors (429, 5xx) are retried automatically up to `WithMaxRetries(2)` times with exponential backoff.
  444. ---
  445. ## TokenSource (Dynamic Auth)
  446. For OAuth, service accounts, or rotating credentials:
  447. ```go
  448. ts := provider.CachedTokenSource(func(ctx context.Context) (*provider.Token, error) {
  449. // Fetch token from your auth system
  450. token, err := myAuthClient.GetToken(ctx)
  451. if err != nil {
  452. return nil, err
  453. }
  454. return &provider.Token{
  455. Value: token.AccessToken,
  456. ExpiresAt: token.ExpiresAt,
  457. }, nil
  458. })
  459. model := openai.Chat("gpt-4o", openai.WithTokenSource(ts))
  460. ```
  461. - `provider.StaticToken(key)` - wraps a static string
  462. - `provider.CachedTokenSource(fetchFn)` - caches until expiry, thread-safe
  463. ---
  464. ## Supported Providers
  465. ### Tier 1 (dedicated implementations)
  466. | Provider | Import | Chat | Embed | Image | Provider Tools |
  467. | ------------- | -------------------- | ---- | ----- | ----- | -------------- |
  468. | OpenAI | `provider/openai` | Yes | Yes | Yes | 4 |
  469. | Anthropic | `provider/anthropic` | Yes | - | - | 14 |
  470. | Google Gemini | `provider/google` | Yes | Yes | Yes | 5 |
  471. | AWS Bedrock | `provider/bedrock` | Yes | Yes | - | - |
  472. | Azure OpenAI | `provider/azure` | Yes | - | Yes | - |
  473. | Vertex AI | `provider/vertex` | Yes | Yes | Yes | - |
  474. ### Tier 2
  475. | Provider | Import | Chat | Embed | Provider Tools |
  476. | ---------- | ------------------- | ---- | ----- | -------------- |
  477. | Cohere | `provider/cohere` | Yes | Yes | - |
  478. | Mistral | `provider/mistral` | Yes | - | - |
  479. | xAI (Grok) | `provider/xai` | Yes | - | 2 |
  480. | Groq | `provider/groq` | Yes | - | 1 |
  481. | DeepSeek | `provider/deepseek` | Yes | - | - |
  482. ### Tier 3 (OpenAI-compatible)
  483. Fireworks, Together, DeepInfra, OpenRouter, Perplexity, Cerebras
  484. ### Local
  485. | Provider | Import | Chat | Embed | Default URL |
  486. | -------- | ----------------- | ---- | ----- | -------------------- |
  487. | Ollama | `provider/ollama` | Yes | Yes | `http://localhost:11434` |
  488. | vLLM | `provider/vllm` | Yes | Yes | `localhost:8000/v1` |
  489. | RunPod | `provider/runpod` | Yes | - | `https://api.runpod.ai/v2/{endpointID}/openai/v1` |
  490. | Custom | `provider/compat` | Yes | Yes | user-defined |
  491. ---
  492. ## Common Mistakes to Avoid
  493. 1. **Don't use `WithPrompt` and `WithMessages` with user message together carelessly** - `WithPrompt("x")` is auto-wrapped as a `UserMessage` and prepended to `Messages`. Use one or the other for the initial user input.
  494. 2. **Don't call both `Stream()` and `TextStream()`** - they are mutually exclusive on `TextStream`. The second call returns a closed channel.
  495. 3. **Don't forget `WithMaxSteps` for tool loops** - default is 1 (no loop). Set `WithMaxSteps(n)` where n > 1 to enable automatic tool execution.
  496. 4. **Don't type-assert errors** - always use `errors.As(err, &target)`, never `err.(*goai.APIError)`.
  497. 5. **Don't mix option families** - text/object/embed functions use `Option`, `GenerateImage` uses `ImageOption`, and `GenerateVideo` uses `VideoOption`.
  498. 6. **Don't forget error handling on streaming** - always check the error from `StreamText`/`StreamObject` before consuming the stream.
  499. 7. **`Result()` on streams is blocking** - it waits for the entire stream to complete. Call it after consuming `TextStream()`/`Stream()`, or on its own if you don't need incremental output.
README.md · README · 909 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="goai.png" alt="GoAI" width="400">
  3. </p>
  4. <h1 align="center">GoAI</h1>
  5. <p align="center"><em>AI SDK, the Go way.</em></p>
  6. <p align="center">Go SDK for building AI applications. One SDK, 25+ providers, MCP support.</p>
  7. <p align="center">
  8. <a href="bench/RESULTS.md"><img src="https://img.shields.io/badge/streaming-1.1x_faster-brightgreen" alt="Streaming"></a>
  9. <a href="bench/RESULTS.md"><img src="https://img.shields.io/badge/cold_start-24x_faster-brightgreen" alt="Cold Start"></a>
  10. <a href="bench/RESULTS.md"><img src="https://img.shields.io/badge/memory-3.1x_less-brightgreen" alt="Memory"></a>
  11. </p>
  12. <p align="center"><strong>1.1x faster streaming</strong>, <strong>24x faster cold start</strong>, <strong>3.1x less memory</strong> vs Vercel AI SDK (<a href="bench/RESULTS.md">benchmarks</a>)</p>
  13. <p align="center">
  14. <a href="https://goai.sh">Website</a> &middot;
  15. <a href="https://goai.sh/getting-started/installation">Docs</a> &middot;
  16. <a href="https://goai.sh/architecture">Architecture</a> &middot;
  17. <a href="https://goai.sh/providers/">Providers</a> &middot;
  18. <a href="https://goai.sh/examples">Examples</a> &middot;
  19. <a href="https://github.com/zendev-sh/zenflow">Orchestration (zenflow)</a>
  20. </p>
  21. ---
  22. Inspired by the [Vercel AI SDK](https://sdk.vercel.ai). The same clean abstractions, idiomatically adapted for Go with generics, interfaces, and functional options.
  23. ## Selected Releases
  24. > **v0.9.0** - Provider-neutral file upload and remote file references. `FileUploader` interface + `RemoteFileRef` for OpenAI (Files API), Anthropic (Files API), and Google Gemini (Files API). Compat providers map file parts to native OpenAI shapes. [Changelog →](https://github.com/zendev-sh/goai/releases)
  25. >
  26. > **v0.8.5** - New provider: [Requesty](https://goai.sh/providers/requesty) (OpenAI-compatible LLM gateway). Plus Anthropic native structured output, per-step `Reasoning`, and Gemini schema sanitization fixes. [Changelog →](https://github.com/zendev-sh/goai/releases)
  27. >
  28. > **v0.8.4** - `WithRetryObserver` callback for observing retry attempts, split tool-call stream metadata fix, and Anthropic `redacted_thinking` capture in streaming. [Changelog →](https://github.com/zendev-sh/goai/releases)
  29. >
  30. > **v0.8.3** - Native Ollama provider (`/api/chat` + `/api/embed`, think mode, no third-party SDK) and duplicate tool name detection. [Changelog →](https://github.com/zendev-sh/goai/releases)
  31. >
  32. > **v0.8.0** - MCP OAuth 2.1 + PKCE for remote servers, `NewTool[In]` typed constructor, and lifecycle hook panics surfaced as `*PanicError` via `WithOnPanic` (breaking). [Changelog →](https://github.com/zendev-sh/goai/releases)
  33. ## Features
  34. - **8 core functions**: `GenerateText`, `StreamText`, `GenerateObject[T]`, `StreamObject[T]`, `Embed`, `EmbedMany`, `GenerateImage`, `GenerateVideo`
  35. - **25+ providers**: OpenAI, Anthropic, Google, Bedrock, Azure, Vertex, Mistral, xAI, Groq, Cohere, DeepSeek, MiniMax, Fireworks, Together, DeepInfra, OpenRouter, Requesty, Perplexity, Cerebras, Ollama, vLLM, RunPod, Runcrate, Cloudflare Workers AI, FPT Smart Cloud, NVIDIA NIM, Heabsy, Opper, Cheaper Inference, CloudGPU, llama.cpp, + generic OpenAI-compatible
  36. - **Auto tool loop**: Define tools with `Execute` handlers, set `MaxSteps` for `GenerateText` and `StreamText`
  37. - **Structured output**: `GenerateObject[T]` auto-generates JSON Schema from Go types via reflection
  38. - **Streaming**: Real-time text and partial object streaming via channels
  39. - **Dynamic auth**: `TokenSource` interface for OAuth, rotating keys, cloud IAM, with `CachedTokenSource` for TTL-based caching
  40. - **Prompt caching**: Automatic cache control for supported providers (Anthropic, Bedrock, MiniMax)
  41. - **Citations/sources**: Grounding and inline citations from xAI, Perplexity, Google, OpenAI
  42. - **Web search**: Built-in web search tools for OpenAI, Anthropic, Google, Groq, xAI. Model decides when to search
  43. - **Code execution**: Server-side Python sandboxes via OpenAI, Anthropic, Google. No local setup
  44. - **Computer use**: Anthropic computer, bash, text editor tools for autonomous desktop interaction
  45. - **26 provider-defined tools**: Web fetch, file search, image generation, X search, and more - [full list](#provider-defined-tools)
  46. - **MCP client**: Connect to any MCP server (stdio, HTTP, SSE), auto-convert tools for use with GoAI
  47. - **Realtime voice** (experimental): Bidirectional audio sessions with interruption and automatic tool calls via Gemini Live, on the Gemini API or Vertex AI
  48. - **Observability**: Built-in Langfuse and OpenTelemetry (OTel) integrations for tracing generations, tools, and multi-step loops
  49. - **Multi-agent orchestration**: For declarative YAML workflows on top of GoAI, see [zenflow](https://github.com/zendev-sh/zenflow)
  50. - **10 lifecycle hooks**: Observability (`OnRequest`, `OnResponse`, `OnToolCallStart`, `OnToolCall`, `OnStepFinish`, `OnFinish`, `OnPanic`) and interceptor (`OnBeforeToolExecute`, `OnAfterToolExecute`, `OnBeforeStep`) hooks for permission gates, secret scanning, output transformation, and loop control
  51. - **Retry/backoff**: Automatic retry with exponential backoff on retryable HTTP errors (429/5xx)
  52. - **Minimal dependencies**: Core depends on `golang.org/x/oauth2` and `github.com/coder/websocket` (realtime sessions; no transitive dependencies) + one indirect (`cloud.google.com/go/compute/metadata`). Optional `observability/otel` and `observability/langfuse` submodules each use their own separate `go.mod`.
  53. ## Performance vs Vercel AI SDK
  54. | Metric | GoAI | Vercel AI SDK | Improvement |
  55. | -------------------- | ------ | ------------- | ----------- |
  56. | Streaming throughput | 1.46ms | 1.62ms | 1.1x faster |
  57. | Cold start | 569us | 13.9ms | 24x faster |
  58. | Memory (1 stream) | 220KB | 676KB | 3.1x less |
  59. | GenerateText | 56us | 79us | 1.4x faster |
  60. > Mock HTTP server, identical SSE fixtures, Apple M2. [Full report](bench/RESULTS.md)
  61. ## Install
  62. ```bash
  63. go get github.com/zendev-sh/goai@latest
  64. ```
  65. Requires Go 1.25+.
  66. ## Quick Start
  67. Most hosted providers auto-resolve API keys from environment variables. Local/custom providers may require explicit options:
  68. ```go
  69. package main
  70. import (
  71. "context"
  72. "fmt"
  73. "log"
  74. "github.com/zendev-sh/goai"
  75. "github.com/zendev-sh/goai/provider/openai"
  76. )
  77. func main() {
  78. // Reads OPENAI_API_KEY from environment automatically.
  79. model := openai.Chat("gpt-4o")
  80. result, err := goai.GenerateText(context.Background(), model,
  81. goai.WithPrompt("What is the capital of France?"),
  82. )
  83. if err != nil {
  84. log.Fatal(err)
  85. }
  86. fmt.Println(result.Text)
  87. }
  88. ```
  89. ## Streaming
  90. ```go
  91. ctx := context.Background()
  92. stream, err := goai.StreamText(ctx, model,
  93. goai.WithSystem("You are a helpful assistant."),
  94. goai.WithPrompt("Write a haiku about Go."),
  95. )
  96. if err != nil {
  97. log.Fatal(err)
  98. }
  99. for text := range stream.TextStream() {
  100. fmt.Print(text)
  101. }
  102. result := stream.Result()
  103. if err := stream.Err(); err != nil {
  104. log.Fatal(err)
  105. }
  106. fmt.Printf("\nTokens: %d in, %d out\n",
  107. result.TotalUsage.InputTokens, result.TotalUsage.OutputTokens)
  108. ```
  109. OpenAI Responses streams enforce a five-minute provider-event idle timeout.
  110. Configure this per model with `openai.WithResponsesStreamIdleTimeout`; pass `0`
  111. to explicitly disable the watchdog. Premature EOF and a bare `[DONE]` sentinel
  112. are rejected by default. Non-standard endpoints that require `[DONE]` can opt
  113. in explicitly with `openai.WithResponsesStreamDoneCompatibility(true)`; this
  114. option changes only terminal-sentinel handling and does not relax event schema
  115. validation. Every JSON data event must identify its type through either the JSON
  116. `type` property or the SSE `event:` field, and malformed recognized events
  117. terminate the stream. Endpoints should use SSE comments, not untyped data
  118. frames, for keepalives. Idle and protocol interruptions are exposed as typed
  119. `openai.StreamIdleTimeoutError` and `openai.StreamProtocolError` values.
  120. Streaming with tools:
  121. ```go
  122. import "github.com/zendev-sh/goai/provider"
  123. stream, err := goai.StreamText(ctx, model,
  124. goai.WithPrompt("What's the weather in Tokyo?"),
  125. goai.WithTools(weatherTool),
  126. goai.WithMaxSteps(5),
  127. )
  128. for chunk := range stream.Stream() {
  129. switch chunk.Type {
  130. case provider.ChunkText:
  131. fmt.Print(chunk.Text)
  132. case provider.ChunkStepFinish:
  133. fmt.Println("\n[step complete]")
  134. }
  135. }
  136. ```
  137. ## Structured Output
  138. Auto-generates JSON Schema from Go types. Works with OpenAI, Anthropic, and Google.
  139. ```go
  140. type Recipe struct {
  141. Name string `json:"name" jsonschema:"description=Recipe name"`
  142. Ingredients []string `json:"ingredients"`
  143. Steps []string `json:"steps"`
  144. Difficulty string `json:"difficulty" jsonschema:"enum=easy|medium|hard"`
  145. }
  146. result, err := goai.GenerateObject[Recipe](ctx, model,
  147. goai.WithPrompt("Give me a recipe for chocolate chip cookies"),
  148. )
  149. if err != nil {
  150. log.Fatal(err)
  151. }
  152. fmt.Printf("Recipe: %s (%s)\n", result.Object.Name, result.Object.Difficulty)
  153. ```
  154. Streaming partial objects:
  155. ```go
  156. stream, err := goai.StreamObject[Recipe](ctx, model,
  157. goai.WithPrompt("Give me a recipe for pancakes"),
  158. )
  159. if err != nil {
  160. log.Fatal(err)
  161. }
  162. for partial := range stream.PartialObjectStream() {
  163. fmt.Printf("\r%s (%d ingredients so far)", partial.Name, len(partial.Ingredients))
  164. }
  165. final, err := stream.Result()
  166. ```
  167. ## Tools
  168. Define a tool from a typed input struct with `goai.NewTool` - the JSON Schema is
  169. generated from the struct and arguments are unmarshaled for you. Set `MaxSteps`
  170. to enable the auto tool loop.
  171. ```go
  172. weatherTool := goai.NewTool("get_weather", "Get the current weather for a city.",
  173. func(ctx context.Context, args struct {
  174. City string `json:"city" jsonschema:"description=City name"`
  175. }) (string, error) {
  176. return fmt.Sprintf("22°C and sunny in %s", args.City), nil
  177. })
  178. result, err := goai.GenerateText(ctx, model,
  179. goai.WithPrompt("What's the weather in Tokyo?"),
  180. goai.WithTools(weatherTool),
  181. goai.WithMaxSteps(3),
  182. )
  183. if err != nil {
  184. log.Fatal(err)
  185. }
  186. fmt.Println(result.Text) // "It's 22°C and sunny in Tokyo."
  187. ```
  188. ## MCP (Model Context Protocol)
  189. Connect to any MCP server and use its tools with GoAI. Supports stdio, Streamable HTTP, and legacy SSE transports.
  190. ```go
  191. import "github.com/zendev-sh/goai/mcp"
  192. // Connect to any MCP server
  193. transport := mcp.NewStdioTransport("npx", []string{"-y", "@modelcontextprotocol/server-filesystem", "."})
  194. client := mcp.NewClient("my-app", "1.0", mcp.WithTransport(transport))
  195. _ = client.Connect(ctx)
  196. defer client.Close()
  197. // Use MCP tools with GoAI
  198. tools, _ := client.ListTools(ctx, nil)
  199. goaiTools := mcp.ConvertTools(client, tools.Tools)
  200. result, _ := goai.GenerateText(ctx, model,
  201. goai.WithTools(goaiTools...),
  202. goai.WithPrompt("List files in the current directory"),
  203. goai.WithMaxSteps(5),
  204. )
  205. ```
  206. For OAuth-protected remote servers, GoAI handles authorization-server discovery, dynamic client registration, PKCE, token refresh, and retry-on-401 natively — no external wrapper needed:
  207. ```go
  208. ts, _ := mcp.NewOAuthTokenSource(ctx, mcp.OAuthConfig{
  209. ServerURL: serverURL,
  210. RedirectURI: "http://127.0.0.1:8765/callback",
  211. Authorize: openBrowserAndAwaitRedirect, // returns the OAuth redirect URL
  212. })
  213. transport := mcp.NewHTTPTransport(serverURL, mcp.WithHTTPClient(mcp.NewOAuthHTTPClient(ts, nil)))
  214. client := mcp.NewClient("my-app", "1.0", mcp.WithTransport(transport))
  215. ```
  216. See [examples/mcp-tools](examples/mcp-tools/), [examples/mcp-oauth](examples/mcp-oauth/), and the [MCP documentation](https://goai.sh/concepts/mcp) for more.
  217. ## Companion Projects
  218. **[zenflow](https://github.com/zendev-sh/zenflow)** - multi-agent orchestration engine for Go. Declarative YAML workflows, typed inter-agent mailboxes, single static binary. Built on GoAI for the LLM layer; reach for it when one `MaxSteps` loop is no longer enough.
  219. ## Citations / Sources
  220. Providers that support grounding (Google, xAI, Perplexity) or inline citations (OpenAI) return sources:
  221. ```go
  222. result, err := goai.GenerateText(ctx, model,
  223. goai.WithPrompt("What were the major news events today?"),
  224. )
  225. if err != nil {
  226. log.Fatal(err)
  227. }
  228. if len(result.Sources) > 0 {
  229. for _, s := range result.Sources {
  230. fmt.Printf("[%s] %s - %s\n", s.Type, s.Title, s.URL)
  231. }
  232. }
  233. // Sources are also available per-step in multi-step tool loops.
  234. for _, step := range result.Steps {
  235. for _, s := range step.Sources {
  236. fmt.Printf(" Step source: %s\n", s.URL)
  237. }
  238. }
  239. ```
  240. ## Computer Use
  241. See [Provider-Defined Tools > Computer Use](#computer-use-1) and [examples/computer-use](examples/computer-use/) for Anthropic computer, bash, and text editor tools. Works with both Anthropic direct API and Bedrock.
  242. ## Embeddings
  243. ```go
  244. ctx := context.Background()
  245. model := openai.Embedding("text-embedding-3-small")
  246. // Single
  247. result, err := goai.Embed(ctx, model, "Hello world")
  248. if err != nil {
  249. log.Fatal(err)
  250. }
  251. fmt.Printf("Dimensions: %d\n", len(result.Embedding))
  252. // Batch (auto-chunked, parallel)
  253. many, err := goai.EmbedMany(ctx, model, []string{"foo", "bar", "baz"},
  254. goai.WithMaxParallelCalls(4),
  255. )
  256. if err != nil {
  257. log.Fatal(err)
  258. }
  259. ```
  260. ## Image Generation
  261. ```go
  262. ctx := context.Background()
  263. model := openai.Image("gpt-image-1")
  264. result, err := goai.GenerateImage(ctx, model,
  265. goai.WithImagePrompt("A sunset over mountains, oil painting style"),
  266. goai.WithImageSize("1024x1024"),
  267. )
  268. if err != nil {
  269. log.Fatal(err)
  270. }
  271. os.WriteFile("sunset.png", result.Images[0].Data, 0644)
  272. ```
  273. Also supported: Google Imagen (`google.Image("imagen-4.0-generate-001")`) and Vertex AI (`vertex.Image(...)`).
  274. ## Video Generation
  275. Google Veo video generation uses a long-running operation. GoAI starts the operation, polls until completion, and downloads the resulting video bytes.
  276. ```go
  277. ctx := context.Background()
  278. model := google.Video("veo-3.1-generate-preview")
  279. result, err := goai.GenerateVideo(ctx, model,
  280. goai.WithVideoPrompt("A paper plane taking flight at sunrise"),
  281. goai.WithVideoAspectRatio("16:9"),
  282. goai.WithVideoResolution("720p"),
  283. goai.WithVideoDuration(8*time.Second),
  284. goai.WithVideoAudio(true),
  285. )
  286. if err != nil {
  287. log.Fatal(err)
  288. }
  289. os.WriteFile("plane.mp4", result.Video.Data, 0644)
  290. ```
  291. Image-to-video is supported with `WithVideoImage`. First/last frames and image references are available through `WithVideoFrameImages` and `WithVideoInputReferences`.
  292. ## Realtime Voice
  293. Open a bidirectional voice session: stream audio in, play audio out, and let the model call tools mid-conversation. Experimental.
  294. ```go
  295. model := google.Live("gemini-3.8-live") // or vertex.Live(...) on Vertex AI
  296. session, err := goai.OpenRealtimeSession(ctx, model, goai.WithRealtimeTools(weatherTool))
  297. if err != nil {
  298. panic(err)
  299. }
  300. defer session.Close()
  301. go func() {
  302. for frame := range mic { // 16 kHz mono PCM16
  303. _ = session.InputAudio(ctx, frame)
  304. }
  305. }()
  306. for ev := range session.Events() {
  307. if ev.Type == provider.RealtimeOutputAudio {
  308. play(ev.Audio) // 24 kHz mono PCM16
  309. }
  310. }
  311. ```
  312. See [examples/realtime-voice](examples/realtime-voice/) and the [realtime documentation](https://goai.sh/concepts/realtime).
  313. ## Observability
  314. Built-in [Langfuse](https://langfuse.com) and [OpenTelemetry](https://opentelemetry.io) integrations. Ten lifecycle hooks cover the full generation pipeline -- observability providers use them to trace LLM calls, tool executions, panics, and multi-step agent loops:
  315. ```go
  316. import "github.com/zendev-sh/goai/observability/langfuse"
  317. // Credentials from env: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST
  318. result, err := goai.GenerateText(ctx, model,
  319. goai.WithPrompt("Hello"),
  320. goai.WithTools(weatherTool),
  321. goai.WithMaxSteps(5),
  322. langfuse.WithTracing(langfuse.TraceName("my-agent")),
  323. )
  324. ```
  325. Interceptor hooks let you control tool execution without modifying core code:
  326. ```go
  327. // Permission gate: block dangerous tools
  328. goai.WithOnBeforeToolExecute(func(info goai.BeforeToolExecuteInfo) goai.BeforeToolExecuteResult {
  329. if info.ToolName == "delete_file" {
  330. return goai.BeforeToolExecuteResult{Skip: true, Result: "Permission denied."}
  331. }
  332. return goai.BeforeToolExecuteResult{}
  333. }),
  334. // Detect max-steps exhaustion
  335. goai.WithOnFinish(func(info goai.FinishInfo) {
  336. if info.StepsExhausted {
  337. log.Printf("Loop exhausted after %d steps", info.TotalSteps)
  338. }
  339. }),
  340. ```
  341. See [examples/hooks](examples/hooks/), [examples/langfuse](examples/langfuse/), [examples/otel](examples/otel/), and the [observability docs](https://goai.sh/concepts/observability) for details.
  342. ## Providers
  343. Many providers auto-resolve credentials from environment variables. Others (for example `ollama`, `vllm`, `compat`) use explicit options:
  344. ```go
  345. // Auto-resolved: reads OPENAI_API_KEY from env
  346. model := openai.Chat("gpt-4o")
  347. // Explicit key (overrides env)
  348. model := openai.Chat("gpt-4o", openai.WithAPIKey("sk-..."))
  349. // Cloud IAM auth (Vertex, Bedrock)
  350. model := vertex.Chat("gemini-2.5-pro",
  351. vertex.WithProject("my-project"),
  352. vertex.WithLocation("us-central1"),
  353. )
  354. // AWS Bedrock (reads AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION from env)
  355. model := bedrock.Chat("anthropic.claude-sonnet-4-6-v1:0")
  356. // Local (Ollama, vLLM)
  357. model := ollama.Chat("llama3", ollama.WithBaseURL("http://localhost:11434"))
  358. result, err := goai.GenerateText(ctx, model, goai.WithPrompt("Hello"))
  359. ```
  360. ### Provider Table
  361. | Provider | Chat | Embed | Image | Auth | E2E | Import |
  362. | ---------- | ------------------------------------------------------------ | ---------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------- | ---- | --------------------- |
  363. | OpenAI | `gpt-4o`, `o3`, `codex-*` | `text-embedding-3-*` | `gpt-image-1` | `OPENAI_API_KEY`, `OPENAI_BASE_URL`, TokenSource | Full | `provider/openai` |
  364. | Anthropic | `claude-*` | - | - | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, TokenSource | Full | `provider/anthropic` |
  365. | Google | `gemini-*` | `text-embedding-004` | `imagen-*` | `GOOGLE_GENERATIVE_AI_API_KEY` / `GEMINI_API_KEY`, TokenSource | Full | `provider/google` |
  366. | Bedrock | `anthropic.*`, `meta.*` | `titan-embed-*`, `cohere.embed-*`, `nova-2-*`, `marengo-*` | - | AWS keys, `AWS_BEARER_TOKEN_BEDROCK`, `AWS_BEDROCK_BASE_URL` | Full | `provider/bedrock` |
  367. | Vertex | `gemini-*` | `text-embedding-004` | `imagen-*` | TokenSource, ADC, or `GOOGLE_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY` fallback | Unit | `provider/vertex` |
  368. | Azure | `gpt-4o`, `claude-*` | - | via Azure | `AZURE_OPENAI_API_KEY`, TokenSource | Full | `provider/azure` |
  369. | OpenRouter | various | - | - | `OPENROUTER_API_KEY`, TokenSource | Unit | `provider/openrouter` |
  370. | Mistral | `mistral-large`, `magistral-*` | - | - | `MISTRAL_API_KEY`, TokenSource | Full | `provider/mistral` |
  371. | Groq | `mixtral-*`, `llama-*` | - | - | `GROQ_API_KEY`, TokenSource | Full | `provider/groq` |
  372. | xAI | `grok-*` | - | - | `XAI_API_KEY`, TokenSource | Unit | `provider/xai` |
  373. | Cohere | `command-r-*` | `embed-*` | - | `COHERE_API_KEY`, TokenSource | Unit | `provider/cohere` |
  374. | DeepSeek | `deepseek-*` | - | - | `DEEPSEEK_API_KEY`, TokenSource | Unit | `provider/deepseek` |
  375. | MiniMax | `MiniMax-M2.7`, `MiniMax-M2.5`, `MiniMax-M2.1`, `MiniMax-M2` | - | - | `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, TokenSource | Full | `provider/minimax` |
  376. | Fireworks | various | - | - | `FIREWORKS_API_KEY`, TokenSource | Unit | `provider/fireworks` |
  377. | Together | various | - | - | `TOGETHER_AI_API_KEY` (or `TOGETHER_API_KEY`), TokenSource | Unit | `provider/together` |
  378. | DeepInfra | various | - | - | `DEEPINFRA_API_KEY`, TokenSource | Unit | `provider/deepinfra` |
  379. | Perplexity | `sonar-*` | - | - | `PERPLEXITY_API_KEY`, TokenSource | Unit | `provider/perplexity` |
  380. | Cerebras | `llama-*` | - | - | `CEREBRAS_API_KEY`, TokenSource | Unit | `provider/cerebras` |
  381. | Ollama | local models | local models | - | none | Unit | `provider/ollama` |
  382. | vLLM | local models | local models | - | Optional auth via `WithAPIKey` / `WithTokenSource` | Unit | `provider/vllm` |
  383. | RunPod | any vLLM model | - | - | `RUNPOD_API_KEY`, TokenSource | Unit | `provider/runpod` |
  384. | Runcrate | open models (e.g. `deepseek-ai/DeepSeek-V4.1-Flash`) | - | - | `RUNCRATE_API_KEY`, `RUNCRATE_BASE_URL`, TokenSource | Unit | `provider/runcrate` |
  385. | Cloudflare | `@cf/meta/*`, `@cf/openai/gpt-oss-*`, `@cf/qwen/*` | `@cf/baai/bge-*` | - | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_BASE_URL`, TokenSource | Unit | `provider/cloudflare` |
  386. | FPT Cloud | `Qwen3-*`, `Llama-*`, `gpt-oss-*`, `GLM-*`, `gemma-*` | `bge-*`, `gte-*`, `multilingual-e5-*` | - | `FPT_API_KEY`, `FPT_REGION` (`global`/`jp`), `FPT_BASE_URL`, TokenSource | Unit | `provider/fptcloud` |
  387. | NVIDIA NIM | `nvidia/llama-*`, `nvidia/nemotron-*` | `nvidia/nv-embed-*` | - | `NVIDIA_API_KEY`, `NVIDIA_BASE_URL`, TokenSource | Full | `provider/nvidia` |
  388. | llama.cpp | local models | local models | - | Optional auth via `WithAPIKey` / `WithTokenSource` | Unit | `provider/llamacpp` |
  389. | Requesty | `provider/model` (e.g. `openai/gpt-4o-mini`) | - | - | `REQUESTY_API_KEY`, `REQUESTY_BASE_URL`, TokenSource | Unit | `provider/requesty` |
  390. | Heabsy | open models (e.g. `qwen38`) | - | - | `HEABSY_API_KEY`, `HEABSY_BASE_URL`, TokenSource | Unit | `provider/heabsy` |
  391. | Opper | pool names (e.g. `claude-sonnet-4-6`) | - | - | `OPPER_API_KEY`, `OPPER_BASE_URL`, TokenSource | Unit | `provider/opper` |
  392. | Cheaper Inference | bare model IDs (e.g. `gpt-5.4-mini`) | - | - | `CHEAPER_INFERENCE_API_KEY`, `CHEAPER_INFERENCE_BASE_URL`, TokenSource | Unit | `provider/cheaperinference` |
  393. | CloudGPU | bare model IDs (e.g. `deepseek-v4.1-flash`) | - | - | `CLOUDGPU_API_KEY`, `CLOUDGPU_BASE_URL`, TokenSource | Unit | `provider/cloudgpu` |
  394. | Compat | any OpenAI-compatible | any | - | configurable | Unit | `provider/compat` |
  395. **E2E column**: "Full" = tested with real API calls. "Unit" = tested with mock HTTP servers (100% coverage).
  396. ### Tested Models
  397. <details>
  398. <summary><strong>E2E tested - 104 models across 8 providers</strong> (real API calls, click to expand)</summary>
  399. Last run: 2026-03-27. 104 models tested (generate + stream).
  400. | Provider | Models E2E tested (generate + stream) |
  401. | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  402. | Google (9) | `gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-2.5-pro` (stream), `gemini-3-flash-preview`, `gemini-3-pro-preview`, `gemini-3.1-pro-preview`, `gemini-2.0-flash`, `gemini-flash-latest`, `gemini-flash-lite-latest` |
  403. | Azure (21) | `claude-opus-4-6`, `claude-sonnet-4-6`, `DeepSeek-V3.2`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-5`, `gpt-5-codex`, `gpt-5-mini`, `gpt-5-pro`, `gpt-5.1`, `gpt-5.1-codex`, `gpt-5.1-codex-max`, `gpt-5.1-codex-mini`, `gpt-5.2`, `gpt-5.2-codex`, `gpt-5.3-codex`, `gpt-5.4`, `gpt-5.4-pro`, `Kimi-K2.5`, `model-router`, `o3` |
  404. | Bedrock (61) | **Anthropic**: `claude-sonnet-4-6`, `claude-sonnet-4-5`, `claude-sonnet-4`, `claude-opus-4-6-v1`, `claude-opus-4-5`, `claude-opus-4-1`, `claude-haiku-4-5`, `claude-3-5-sonnet`, `claude-3-5-haiku`, `claude-3-haiku` · **Amazon**: `nova-micro`, `nova-lite`, `nova-pro`, `nova-premier`, `nova-2-lite` · **Meta**: `llama4-scout`, `llama4-maverick`, `llama3-3-70b`, `llama3-2-{90,11,3,1}b`, `llama3-1-{70,8}b`, `llama3-{70,8}b` · **Mistral**: `mistral-large`, `mixtral-8x7b`, `mistral-7b`, `ministral-3-{14,8}b`, `voxtral-{mini,small}` · **Others**: `deepseek.v3`, `deepseek.r1`, `ai21.jamba-1-5-{mini,large}`, `cohere.command-r{-plus,}`, `google.gemma-3-{4,12,27}b`, `minimax.{m2,m2.1}`, `moonshotai.kimi-k2{-thinking,.5}`, `nvidia.nemotron-nano-{12,9}b`, `openai.gpt-oss-{120,20}b{,-safeguard}`, `qwen.qwen3-{32,235,coder-30,coder-480}b`, `qwen.qwen3-next-80b`, `writer.palmyra-{x4,x5}`, `zai.glm-4.7{,-flash}` |
  405. | Groq (2) | `llama-3.1-8b-instant`, `llama-3.3-70b-versatile` |
  406. | Mistral (5) | `mistral-small-latest`, `mistral-large-latest`, `devstral-small-2507`, `codestral-latest`, `magistral-medium-latest` |
  407. | Cerebras (1) | `llama3.1-8b` |
  408. | MiniMax (4) | `MiniMax-M2.7`, `MiniMax-M2.5`, `MiniMax-M2.1`, `MiniMax-M2` (generate + stream + tools + thinking) |
  409. | NVIDIA (1) | `meta/llama-3.3-70b-instruct` |
  410. </details>
  411. <details>
  412. <summary><strong>Unit tested</strong> (mock HTTP server, 100% coverage, click to expand)</summary>
  413. | Provider | Models in unit tests |
  414. | ---------- | -------------------------------------------------------------------------------------------------- |
  415. | OpenAI | `gpt-4o`, `o3`, `text-embedding-3-small`, `dall-e-3`, `gpt-image-1` |
  416. | Anthropic | `claude-sonnet-4-20250514`, `claude-sonnet-4-5-20241022`, `claude-sonnet-4-6-20260310` |
  417. | Google | `gemini-2.5-flash`, `gemini-2.5-flash-image`, `imagen-4.0-fast-generate-001`, `text-embedding-004` |
  418. | Bedrock | `us.anthropic.claude-sonnet-4-6`, `anthropic.claude-sonnet-4-20250514-v1:0`, `meta.llama3-70b` |
  419. | Azure | `gpt-4o`, `gpt-5.2-chat`, `dall-e-3`, `claude-sonnet-4-6` |
  420. | Vertex | `gemini-2.5-pro`, `imagen-3.0-generate-002`, `text-embedding-004` |
  421. | Cohere | `command-r-plus`, `command-a-reasoning`, `embed-v4.0` |
  422. | Mistral | `mistral-large-latest` |
  423. | Groq | `llama-3.3-70b-versatile` |
  424. | xAI | `grok-3` |
  425. | DeepSeek | `deepseek-chat` |
  426. | DeepInfra | `meta-llama/Llama-3.3-70B-Instruct` |
  427. | Fireworks | `accounts/fireworks/models/llama-v3p3-70b-instruct` |
  428. | OpenRouter | `anthropic/claude-sonnet-4` |
  429. | Perplexity | `sonar-pro` |
  430. | Together | `meta-llama/Llama-3.3-70B-Instruct-Turbo` |
  431. | Cerebras | `llama-3.3-70b` |
  432. | NVIDIA | `meta/llama-3.3-70b-instruct` |
  433. | Ollama | `llama3`, `llama3.2:1b`, `nomic-embed-text` |
  434. | vLLM | `meta-llama/Llama-3-8b` |
  435. | RunPod | `meta-llama/Llama-3.3-70B-Instruct` |
  436. | Cloudflare | `@cf/meta/llama-3.1-8b-instruct`, `@cf/baai/bge-base-en-v1.5` |
  437. | FPT Cloud | `Qwen3-32B` |
  438. </details>
  439. ### Custom / Self-Hosted
  440. Use the `compat` provider for any OpenAI-compatible endpoint:
  441. ```go
  442. model := compat.Chat("my-model",
  443. compat.WithBaseURL("https://my-api.example.com/v1"),
  444. compat.WithAPIKey("..."),
  445. )
  446. ```
  447. ### Dynamic Auth with TokenSource
  448. For OAuth, rotating keys, or cloud IAM:
  449. ```go
  450. ts := provider.CachedTokenSource(func(ctx context.Context) (*provider.Token, error) {
  451. tok, err := fetchOAuthToken(ctx)
  452. return &provider.Token{
  453. Value: tok.AccessToken,
  454. ExpiresAt: tok.Expiry,
  455. }, err
  456. })
  457. model := openai.Chat("gpt-4o", openai.WithTokenSource(ts))
  458. ```
  459. `CachedTokenSource` handles TTL-based caching (zero ExpiresAt = cache forever), thread-safe refresh without holding locks during network calls, and manual token invalidation via the `InvalidatingTokenSource` interface.
  460. ### AWS Bedrock
  461. Native Converse API with SigV4 signing (no AWS SDK dependency). Supports cross-region inference fallback, extended thinking, and image/document input:
  462. ```go
  463. model := bedrock.Chat("anthropic.claude-sonnet-4-6-v1:0",
  464. bedrock.WithRegion("us-west-2"),
  465. bedrock.WithReasoningConfig(bedrock.ReasoningConfig{
  466. Type: bedrock.ReasoningEnabled,
  467. BudgetTokens: 4096,
  468. }),
  469. )
  470. ```
  471. Auto-resolves `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` from environment. Cross-region fallback retries with `us.` prefix on model ID mismatch errors.
  472. ### Azure OpenAI
  473. Supports both OpenAI models (GPT, o-series) and Claude models (routed to Azure Anthropic endpoint automatically):
  474. ```go
  475. // OpenAI models
  476. model := azure.Chat("gpt-4o",
  477. azure.WithEndpoint("https://my-resource.openai.azure.com"),
  478. )
  479. // Claude models (auto-routed to Anthropic endpoint)
  480. model := azure.Chat("claude-sonnet-4-6",
  481. azure.WithEndpoint("https://my-resource.openai.azure.com"),
  482. )
  483. ```
  484. Auto-resolves `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT` (or `AZURE_RESOURCE_NAME`) from environment.
  485. ### Response Metadata
  486. Every result includes provider response metadata:
  487. ```go
  488. result, _ := goai.GenerateText(ctx, model, goai.WithPrompt("Hello"))
  489. fmt.Printf("Request ID: %s\n", result.Response.ID)
  490. fmt.Printf("Model used: %s\n", result.Response.Model)
  491. ```
  492. ## Options Reference
  493. ### Generation Options
  494. | Option | Description | Default |
  495. | ------------------------------- | ---------------------------------------- | ---------------- |
  496. | `WithSystem(s)` | System prompt | - |
  497. | `WithPrompt(s)` | Single user message | - |
  498. | `WithMessages(...)` | Conversation history | - |
  499. | `WithTools(...)` | Available tools | - |
  500. | `WithMaxOutputTokens(n)` | Response length limit | provider default |
  501. | `WithTemperature(t)` | Randomness (0.0-2.0) | provider default |
  502. | `WithTopP(p)` | Nucleus sampling | provider default |
  503. | `WithTopK(k)` | Top-K sampling | provider default |
  504. | `WithFrequencyPenalty(p)` | Frequency penalty | provider default |
  505. | `WithPresencePenalty(p)` | Presence penalty | provider default |
  506. | `WithSeed(s)` | Deterministic generation | - |
  507. | `WithStopSequences(...)` | Stop triggers | - |
  508. | `WithMaxSteps(n)` | Tool loop iterations | 1 (no loop) |
  509. | `WithSequentialToolExecution()` | Execute tools one at a time | parallel |
  510. | `WithMaxRetries(n)` | Retries on 429/5xx | 2 |
  511. | `WithTimeout(d)` | Overall timeout | none |
  512. | `WithHeaders(h)` | Per-request HTTP headers | - |
  513. | `WithProviderOptions(m)` | Provider-specific params | - |
  514. | `WithPromptCaching(b)` | Enable prompt caching | false |
  515. | `WithToolChoice(tc)` | "auto", "none", "required", or tool name | - |
  516. ### Lifecycle Hooks
  517. | Option | Description |
  518. | ----------------------------- | --------------------------------------------------------------- |
  519. | `WithOnRequest(fn)` | Called before each API call |
  520. | `WithOnResponse(fn)` | Called after each API call |
  521. | `WithOnToolCallStart(fn)` | Called before each tool execution begins |
  522. | `WithOnToolCall(fn)` | Called after each tool execution |
  523. | `WithOnStepFinish(fn)` | Called after each tool loop step |
  524. | `WithOnFinish(fn)` | Called once after all steps complete (carries `StepsExhausted`) |
  525. | `WithOnBeforeToolExecute(fn)` | Intercept before tool Execute -- can skip, override ctx/input |
  526. | `WithOnAfterToolExecute(fn)` | Intercept after tool Execute -- can modify output/error |
  527. | `WithOnBeforeStep(fn)` | Intercept before step 2+ -- can inject messages or stop loop |
  528. ### Structured Output Options
  529. | Option | Description |
  530. | ----------------------- | --------------------------------------------- |
  531. | `WithExplicitSchema(s)` | Override auto-generated JSON Schema |
  532. | `WithSchemaName(n)` | Schema name for provider (default "response") |
  533. ### Embedding Options
  534. | Option | Description | Default |
  535. | --------------------------------- | ------------------------- | ------- |
  536. | `WithMaxParallelCalls(n)` | Batch parallelism | 4 |
  537. | `WithEmbeddingProviderOptions(m)` | Embedding provider params | - |
  538. ### Image Options
  539. | Option | Description |
  540. | ----------------------------- | ------------------------------ |
  541. | `WithImagePrompt(s)` | Text description |
  542. | `WithImageCount(n)` | Number of images |
  543. | `WithImageSize(s)` | Dimensions (e.g., "1024x1024") |
  544. | `WithAspectRatio(s)` | Aspect ratio (e.g., "16:9") |
  545. | `WithImageMaxRetries(n)` | Retries on 429/5xx |
  546. | `WithImageTimeout(d)` | Overall timeout |
  547. | `WithImageProviderOptions(m)` | Image provider params |
  548. ## Error Handling
  549. GoAI generation and image APIs return typed errors for actionable failure modes (MCP client APIs return `*mcp.MCPError`):
  550. ```go
  551. result, err := goai.GenerateText(ctx, model, goai.WithPrompt("..."))
  552. if err != nil {
  553. var overflow *goai.ContextOverflowError
  554. var apiErr *goai.APIError
  555. switch {
  556. case errors.As(err, &overflow):
  557. // Prompt too long - truncate and retry
  558. case errors.As(err, &apiErr):
  559. if apiErr.IsRetryable {
  560. // 429 rate limit, 503 - already retried MaxRetries times
  561. }
  562. fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Message)
  563. // HTTP API errors include ResponseBody and ResponseHeaders for debugging
  564. default:
  565. // Network error, context cancelled, etc.
  566. }
  567. }
  568. ```
  569. Error types:
  570. | Type | Fields | When |
  571. | ---------------------- | ------------------------------------------------------------------------- | ----------------------------------- |
  572. | `APIError` | `StatusCode`, `Message`, `IsRetryable`, `ResponseBody`, `ResponseHeaders` | Non-2xx API responses |
  573. | `ContextOverflowError` | `Message`, `ResponseBody` | Prompt exceeds model context window |
  574. Retry behavior: automatic exponential backoff on retryable HTTP errors (429/5xx, plus OpenAI 404 propagation). `retry-after-ms` and `Retry-After` (both delay-seconds and HTTP-date) are respected. Retries apply to request-level failures (including initial stream connection), not mid-stream error events.
  575. ## Provider-Defined Tools
  576. Providers expose built-in tools that the model can invoke server-side. GoAI supports 26 provider-defined tools across 5 providers:
  577. | Provider | Tools | Import |
  578. | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
  579. | Anthropic | `Computer`, `Computer_20251124`, `Bash`, `TextEditor`, `TextEditor_20250728`, `WebSearch`, `WebSearch_20260209`, `WebSearch_20260318`, `WebFetch`, `CodeExecution`, `CodeExecution_20250522`, `CodeExecution_20250825`, `ToolSearchToolRegex`, `ToolSearchToolBM25` | `provider/anthropic` |
  580. | OpenAI | `WebSearch`, `CodeInterpreter`, `FileSearch`, `ImageGeneration` | `provider/openai` |
  581. | Google | `GoogleSearch`, `URLContext`, `CodeExecution`, `ComputerUse`, `FileSearch` | `provider/google` |
  582. | xAI | `WebSearch`, `XSearch` | `provider/xai` |
  583. | Groq | `BrowserSearch` | `provider/groq` |
  584. All tools follow the same pattern: create a definition with `<provider>.Tools.ToolName()` (e.g., `openai.Tools`, `anthropic.Tools`), then pass it as a `goai.Tool`:
  585. ```go
  586. // Example: def := openai.Tools.WebSearch(openai.WithSearchContextSize("medium"))
  587. def := <provider>.Tools.ToolName(options...)
  588. result, _ := goai.GenerateText(ctx, model,
  589. goai.WithTools(goai.Tool{
  590. Name: def.Name,
  591. ProviderDefinedType: def.ProviderDefinedType,
  592. ProviderDefinedOptions: def.ProviderDefinedOptions,
  593. }),
  594. )
  595. ```
  596. ### Web Search
  597. The model searches the web and returns grounded responses. Available from OpenAI, Anthropic, Google, and Groq.
  598. ```go
  599. // OpenAI (via Responses API) - also works via Azure
  600. def := openai.Tools.WebSearch(openai.WithSearchContextSize("medium"))
  601. // Anthropic (via Messages API) - also works via Bedrock
  602. def := anthropic.Tools.WebSearch(anthropic.WithMaxUses(5))
  603. // Google (grounding with Google Search) - returns Sources
  604. def := google.Tools.GoogleSearch()
  605. // result.Sources contains grounding URLs from Google Search
  606. // Groq (interactive browser search)
  607. def := groq.Tools.BrowserSearch()
  608. ```
  609. ### Code Execution
  610. The model writes and runs code in a sandboxed environment. Server-side, no local setup needed.
  611. ```go
  612. // OpenAI Code Interpreter - Python sandbox via Responses API
  613. def := openai.Tools.CodeInterpreter()
  614. // Anthropic Code Execution - Python sandbox via Messages API
  615. def := anthropic.Tools.CodeExecution() // v20260120, GA, no beta needed
  616. // Google Code Execution - Python sandbox via Gemini API
  617. def := google.Tools.CodeExecution()
  618. ```
  619. ### Web Fetch
  620. Claude fetches and processes content from specific URLs directly.
  621. ```go
  622. def := anthropic.Tools.WebFetch(
  623. anthropic.WithWebFetchMaxUses(3),
  624. anthropic.WithCitations(true),
  625. )
  626. ```
  627. ### File Search
  628. Semantic search over uploaded files in vector stores (OpenAI Responses API).
  629. ```go
  630. def := openai.Tools.FileSearch(
  631. openai.WithVectorStoreIDs("vs_abc123"),
  632. openai.WithMaxNumResults(5),
  633. )
  634. ```
  635. ### Image Generation
  636. LLM generates images inline during conversation (different from `goai.GenerateImage()` which calls the Images API directly).
  637. ```go
  638. def := openai.Tools.ImageGeneration(
  639. openai.WithImageQuality("low"),
  640. openai.WithImageSize("1024x1024"),
  641. )
  642. // On Azure, also set: azure.WithHeaders(map[string]string{
  643. // "x-ms-oai-image-generation-deployment": "gpt-image-1.5",
  644. // })
  645. ```
  646. ### Computer Use
  647. Anthropic computer, bash, and text editor tools for autonomous desktop interaction. Client-side execution required.
  648. ```go
  649. computerDef := anthropic.Tools.Computer(anthropic.ComputerToolOptions{
  650. DisplayWidthPx: 1920, DisplayHeightPx: 1080,
  651. })
  652. bashDef := anthropic.Tools.Bash()
  653. textEditorDef := anthropic.Tools.TextEditor()
  654. // Wrap each with an Execute handler for client-side execution
  655. ```
  656. ### URL Context
  657. Gemini fetches and processes web content from URLs in the prompt.
  658. ```go
  659. def := google.Tools.URLContext()
  660. ```
  661. See [examples/](examples/) for complete runnable examples of each tool.
  662. ## Examples
  663. See the [examples/](examples/) directory:
  664. - [chat](examples/chat/) - Non-streaming generation
  665. - [streaming](examples/streaming/) - Real-time text streaming
  666. - [streaming-tools](examples/streaming-tools/) - Streaming with multi-step tool loops
  667. - [structured](examples/structured/) - Structured output with Go generics
  668. - [tools](examples/tools/) - Single tool call
  669. - [agent-loop](examples/agent-loop/) - Multi-step agent with callbacks
  670. - [multi-turn](examples/multi-turn/) - Multi-turn conversation with ResponseMessages
  671. - [citations](examples/citations/) - Accessing sources and citations
  672. - [hooks](examples/hooks/) - Lifecycle hooks: permission gates, secret scanning, loop control, OnFinish
  673. - [langfuse](examples/langfuse/) - Langfuse tracing integration
  674. - [otel](examples/otel/) - OpenTelemetry tracing and metrics
  675. - [computer-use](examples/computer-use/) - Anthropic computer, bash, and text editor tools
  676. - [embedding](examples/embedding/) - Embeddings with similarity search
  677. - [web-search](examples/web-search/) - Web search across providers (OpenAI, Anthropic, Google)
  678. - [web-fetch](examples/web-fetch/) - Anthropic web fetch tool
  679. - [code-execution](examples/code-execution/) - Anthropic code execution tool
  680. - [code-interpreter](examples/code-interpreter/) - OpenAI code interpreter tool
  681. - [google-search](examples/google-search/) - Google Search grounding with Gemini
  682. - [google-code-execution](examples/google-code-execution/) - Google Gemini code execution tool
  683. - [file-search](examples/file-search/) - OpenAI file search tool
  684. - [image-generation](examples/image-generation/) - OpenAI image generation via Responses API
  685. - [mcp-tools](examples/mcp-tools/) - MCP tools with GoAI LLM integration
  686. - [mcp-filesystem](examples/mcp-filesystem/) - Filesystem MCP server via stdio
  687. - [mcp-github](examples/mcp-github/) - GitHub MCP server via stdio
  688. - [mcp-playwright](examples/mcp-playwright/) - Playwright MCP server for browser automation
  689. - [mcp-remote](examples/mcp-remote/) - MCP over Streamable HTTP transport
  690. - [mcp-sse](examples/mcp-sse/) - MCP over legacy SSE transport
  691. - [mcp-local](examples/mcp-local/) - MCP client basics (no LLM needed)
  692. ## Project Structure
  693. ```
  694. goai/ # Core SDK
  695. ├── provider/ # Provider interface + shared types
  696. │ ├── provider.go # LanguageModel, EmbeddingModel, ImageModel interfaces
  697. │ ├── types.go # Message, Part, Usage, StreamChunk, etc.
  698. │ ├── token.go # TokenSource, CachedTokenSource
  699. │ ├── openai/ # OpenAI (Chat Completions + Responses API)
  700. │ ├── anthropic/ # Anthropic (Messages API)
  701. │ ├── google/ # Google Gemini (REST API)
  702. │ ├── bedrock/ # AWS Bedrock (Converse API + SigV4 + EventStream)
  703. │ ├── vertex/ # Google Vertex AI (OpenAI-compat)
  704. │ ├── azure/ # Azure OpenAI
  705. │ ├── cohere/ # Cohere (Chat v2 + Embed)
  706. │ ├── minimax/ # MiniMax (Anthropic-compatible API)
  707. │ ├── compat/ # Generic OpenAI-compatible
  708. │ └── ... # 23 OpenAI-compatible provider implementation files
  709. ├── internal/
  710. │ ├── openaicompat/ # Shared codec for 23 OpenAI-compatible provider implementation files
  711. │ ├── gemini/ # Schema sanitization (Vertex, Google)
  712. │ ├── sse/ # SSE line parser
  713. │ └── httpc/ # HTTP utilities
  714. ├── examples/ # Usage examples
  715. └── bench/ # Performance benchmarks (GoAI vs Vercel AI SDK)
  716. ├── fixtures/ # Shared SSE test fixtures
  717. ├── go/ # Go benchmarks (go test -bench)
  718. ├── ts/ # TypeScript benchmarks (Bun + Tinybench)
  719. ├── collect.sh # Result aggregation → report
  720. └── Makefile # make bench-all
  721. ```
  722. ## Contributing
  723. See [CONTRIBUTING.md](CONTRIBUTING.md).
  724. ## License
  725. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.