Skip to content

API stability channels

Genkit follows semantic versioning guidelines for version updates. Everything in github.com/firebase/genkit/go except the packages listed below is stable, and takes breaking changes only in a major release.

Versioning

Section titled “Versioning”

Genkit Go is in the v1 series. The module path stays github.com/firebase/genkit/go for the whole series; a v2 would take a /v2 suffix, so a major bump can never break your build silently. The module requires Go 1.25 or later.

Running go get github.com/firebase/genkit/go records the dependency version in your go.mod. You can update to newer releases using go get -u. See the release notes for what changed between versions.

Preview APIs

Section titled “Preview APIs”

A few features ship ahead of that guarantee so you can build on them and send feedback while their shape is still settling. Preview is the name for this channel throughout the docs, and a page that carries a :::caution[Preview] admonition is in it. In code, the channel shows up two ways: the package suffix exp (or x), and the genkit.WithExperimental() opt-in. Each preview API may experience breaking changes in minor releases while its shape is stabilizing.

Throughout these docs genkitx is an import alias for github.com/firebase/genkit/go/genkit/exp, aix for github.com/firebase/genkit/go/ai/exp, and a2uix for github.com/firebase/genkit/go/plugins/a2ui/exp. All three packages declare themselves exp, so the aliases keep them apart.

  • Tools with a plain context.Context signature (github.com/firebase/genkit/go/ai/exp, .../ai/exp/tool, .../genkit/exp): genkitx.DefineTool and genkitx.DefineInterruptibleTool, whose functions take a context.Context rather than an *ai.ToolContext, and whose interrupt payload is a typed value rather than a metadata map. They complement the stable tool APIs rather than replacing them.
  • Agents (github.com/firebase/genkit/go/ai/exp, .../ai/exp/localstore, .../genkit/exp, .../plugins/middleware/exp): the agent constructors, session stores, HTTP route builders, and the multi-agent, background-delegation, and artifact middleware.
  • A2UI (github.com/firebase/genkit/go/plugins/a2ui/exp): the generative UI middleware that streams A2UI surfaces from a model to a browser.
  • Durable streaming (github.com/firebase/genkit/go/core/x/streaming, .../plugins/firebase/exp): the StreamManager API that lets a client reconnect to a stream by ID.

The genkit/exp constructors require opting in. Pass genkit.WithExperimental() to genkit.Init, or they panic with a message pointing back to that option.

Samples whose directory name ends in -exp are written against these APIs. basic-tools-exp and basic-tool-interrupts-exp are line-for-line rewrites of their stable twins, so a diff between the pair is the whole API difference.