Go quickstart

Get up and running with Genkit in Go in under five minutes using Gemini models via the Google AI plugin.

This guide walks you through adding Genkit to a Go module, writing your first AI-powered function, and exploring it with the local Developer UI.

1. Get a Google AI API key

   Genkit’s Google AI plugin uses the Gemini API. Get a free API key from Google AI Studio.

   Set the key as an environment variable before running your app:

   export GEMINI_API_KEY="your-api-key"
   

   The googlegenai.GoogleAI plugin also accepts GOOGLE_API_KEY. You can pass the key directly in the plugin struct (&googlegenai.GoogleAI{APIKey: "..."}) but using an environment variable keeps credentials out of source control.

2. Add Genkit to your Go module

   Initialize a new module (or open an existing one), then fetch the Genkit packages:

   go mod init example.com/myapp
   go get github.com/firebase/genkit/go
   go get github.com/firebase/genkit/go/plugins/googlegenai
   

   Install the Genkit CLI to get the Developer UI:

   curl -sL cli.genkit.dev | bash
   
3. Write your first Genkit app

   Create main.go:

   package main
   
   import (
   	"context"
   	"fmt"
   	"log"
   
   	"github.com/firebase/genkit/go/ai"
   	"github.com/firebase/genkit/go/genkit"
   	"github.com/firebase/genkit/go/plugins/googlegenai"
   )
   
   func main() {
   	ctx := context.Background()
   
   	// Initialize Genkit with the Google AI plugin.
   	// The plugin reads GEMINI_API_KEY (or GOOGLE_API_KEY) from the environment.
   	g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}))
   
   	// Define a flow — a traced, deployable AI function.
   	jokeFlow := genkit.DefineFlow(g, "tellJoke",
   		func(ctx context.Context, topic string) (string, error) {
   			return genkit.GenerateText(ctx, g,
   				ai.WithModelName("googleai/gemini-2.5-flash"),
   				ai.WithPrompt("Tell me a short joke about %s.", topic),
   			)
   		},
   	)
   
   	joke, err := jokeFlow.Run(ctx, "software engineers")
   	if err != nil {
   		log.Fatalf("flow failed: %v", err)
   	}
   	fmt.Println(joke)
   }
   

   Run it directly:

   go run main.go
   
4. Explore with the Developer UI

   The Genkit CLI wraps your app with tracing and launches a local Developer UI where you can run flows interactively and inspect execution traces.

   genkit start -- go run main.go
   

   This starts your app, then opens the Developer UI at http://localhost:4000. From there you can:

   • Run the tellJoke flow with any input without restarting your app.
   • Inspect traces to see the full request and response sent to Gemini.
   • Compare models by switching between gemini-2.5-flash and gemini-2.5-pro in real time.

   Set the GENKIT_ENV=dev environment variable to keep the reflection API server running outside of genkit start, which is useful when iterating during development.

5. Add structured output (optional)

   genkit.GenerateData uses Go generics to return type-safe, unmarshaled structs:

   type Recipe struct {
   	Title       string   `json:"title"`
   	Ingredients []string `json:"ingredients"`
   	Steps       []string `json:"steps"`
   }
   
   recipeFlow := genkit.DefineFlow(g, "generateRecipe",
   	func(ctx context.Context, dish string) (*Recipe, error) {
   		recipe, _, err := genkit.GenerateData[Recipe](ctx, g,
   			ai.WithModelName("googleai/gemini-2.5-flash"),
   			ai.WithPrompt("Create a recipe for %s.", dish),
   		)
   		return recipe, err
   	},
   )
   
   recipe, err := recipeFlow.Run(ctx, "chocolate chip cookies")
   if err != nil {
   	log.Fatal(err)
   }
   fmt.Printf("%s — ingredients: %v\n", recipe.Title, recipe.Ingredients)
   
6. Expose flows as HTTP endpoints (optional)

   To serve your flows over HTTP, register them with the standard net/http mux:

   import (
   	"log"
   	"net/http"
   )
   
   mux := http.NewServeMux()
   for _, flow := range genkit.ListFlows(g) {
   	mux.HandleFunc("POST /"+flow.Name(), genkit.Handler(flow))
   }
   log.Fatal(http.ListenAndServe(":8080", mux))
   

   Then call the flow:

   curl -X POST http://localhost:8080/tellJoke \
     -H "Content-Type: application/json" \
     -d '{"data": "gophers"}'
   

   genkit.Handler returns a standard http.HandlerFunc, so it works with any Go HTTP framework (Gin, Echo, Chi, and others).

Next steps

Concepts: Flows

Learn how flows add observability, retries, and HTTP exposure to any AI function.

Concepts: Models

Understand model references, config options, multimodal inputs, and streaming.

Guides: Structured output

Return validated, type-safe structs from any model call using Go generics.

Guides: Streaming

Stream tokens to the client as they arrive using genkit.GenerateStream.

Guides: Agents

Build multi-step agentic workflows with genkit.DefineTool and looping.

Plugins: Google AI

Full reference for the googlegenai plugin including Vertex AI, Imagen, and embeddings.

Plugins overview

Browse all available plugins: Vertex AI, Ollama, Anthropic, and more.

Developer tools

Deep dive into the Genkit CLI and Developer UI.