Generation Generation — Go examples backed by real provider calls. go examples examples/generation src/examples/go/generation example Generation
ax
Go github.com/ax-llm/ax/packages/go
TypeScript Python Java C++ Go Rust

These Go examples are real runnable files. Edit the source file first; this page is rebuilt from the checked-in example and its metadata header.

Go Prompt-Cached Generation

Runs GPT-5.6 structured generation with stable OpenAI prompt-cache affinity.

Go 
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"
	"time"

	ax "github.com/ax-llm/ax/packages/go"
)

func openAIClient() *ax.OpenAICompatibleClient {
	apiKey := os.Getenv("OPENAI_API_KEY")
	if apiKey == "" {
		apiKey = os.Getenv("OPENAI_APIKEY")
	}
	if apiKey == "" {
		panic("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.")
	}
	model := os.Getenv("AX_OPENAI_MODEL")
	if model == "" {
		model = "gpt-5.6-luna"
	}
	return ax.NewOpenAICompatibleClient(map[string]ax.Value{"api_key": apiKey, "model": model, "model_config": ax.Object("temperature", 0)})
}

func printJSON(value ax.Value) {
	data, err := json.MarshalIndent(value, "", "  ")
	if err != nil {
		panic(err)
	}
	fmt.Println(string(data))
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()
	client := openAIClient()
	program := ax.NewAx("question:string -> answer:string", nil)
	output, err := program.Forward(ctx, client, map[string]ax.Value{"question": "In one sentence, explain Ax as a language-agnostic LLM programming library."}, map[string]ax.Value{"promptCacheKey": "ax-openai-example", "contextCache": ax.Object()})
	if err != nil {
		panic(err)
	}
	printJSON(output)
}

Go Model Catalog

Lists static models and named OpenAI-compatible profiles with portable thinking levels and service tiers.

Go 
package main

import (
	"fmt"

	ax "github.com/ax-llm/ax/packages/go"
)

func values(value ax.Value) []ax.Value {
	switch items := value.(type) {
	case []ax.Value:
		return items
	case *ax.AxArray:
		return items.Items
	default:
		panic(fmt.Sprintf("expected catalog array, got %T", value))
	}
}

func provider(catalog ax.Value, name string) map[string]ax.Value {
	for _, item := range values(catalog) {
		entry := item.(map[string]ax.Value)
		if entry["name"] == name {
			return entry
		}
	}
	panic("missing provider " + name)
}

func contains(items ax.Value, expected string) bool {
	for _, item := range values(items) {
		if item == expected {
			return true
		}
	}
	return false
}

func main() {
	catalog := ax.GetSupportedAIModels(map[string]ax.Value{})
	azure := provider(catalog, "azure-openai")
	openrouter := provider(catalog, "openrouter")
	azureCapabilities := azure["capabilities"].(map[string]ax.Value)
	openrouterCapabilities := openrouter["capabilities"].(map[string]ax.Value)

	if azure["isDynamic"] != true || len(values(azure["models"])) != 0 {
		panic("unexpected Azure profile")
	}
	if !contains(azureCapabilities["thinkingLevels"], "high") {
		panic("missing Azure thinking levels")
	}
	if !contains(azureCapabilities["serviceTiers"], "priority") {
		panic("missing Azure service tier")
	}
	if !contains(openrouterCapabilities["serviceTiers"], "flex") {
		panic("missing OpenRouter service tier")
	}

	fmt.Printf("%d providers; Azure and OpenRouter named profiles are available\n", len(values(catalog)))
}

Go Structured Extraction

Extracts structured fields and labels from support text with OpenAI.

Go 
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"
	"time"

	ax "github.com/ax-llm/ax/packages/go"
)


func openAIClient() *ax.OpenAICompatibleClient {
	apiKey := os.Getenv("OPENAI_API_KEY")
	if apiKey == "" { apiKey = os.Getenv("OPENAI_APIKEY") }
	if apiKey == "" { panic("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.") }
	model := os.Getenv("AX_OPENAI_MODEL")
	if model == "" { model = "gpt-5.4-mini" }
	return ax.NewOpenAICompatibleClient(map[string]ax.Value{"api_key": apiKey, "model": model, "model_config": ax.Object("temperature", 0)})
}

func printJSON(value ax.Value) {
	data, err := json.MarshalIndent(value, "", "  ")
	if err != nil { panic(err) }
	fmt.Println(string(data))
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()
	client := openAIClient()
	program := ax.NewAx("ticket:string -> priority:class \"high, normal, low\", summary:string, labels:string[]", nil)
	output, err := program.Forward(ctx, client, map[string]ax.Value{"ticket": "Checkout has failed for enterprise customers since 09:00. Support wants a concise summary and tags."}, nil)
	if err != nil { panic(err) }
	printJSON(output)
}

Go Vertex MaaS Renewable Credentials

Calls a Vertex MaaS OpenAI-compatible endpoint with a fresh bearer token per request.

Go 
package main

import (
	"context"
	"fmt"
	"os"

	ax "github.com/ax-llm/ax/packages/go"
)

func required(name string) string {
	value := os.Getenv(name)
	if value == "" {
		panic("Set " + name + " to run this example.")
	}
	return value
}

func vertexCredentialProvider() ax.AxCredentialProvider {
	return ax.AxCredentialProviderFunc(
		func(_ context.Context, _ ax.AxCredentialRequest) (map[string]string, error) {
			// Replace this environment lookup with the host application's ADC token
			// source. Ax calls the hook again for every request attempt and retry.
			token := os.Getenv("GOOGLE_VERTEX_ACCESS_TOKEN")
			if token == "" {
				return nil, fmt.Errorf("set GOOGLE_VERTEX_ACCESS_TOKEN to run this example")
			}
			return map[string]string{"Authorization": "Bearer " + token}, nil
		},
	)
}

func main() {
	model := os.Getenv("AX_VERTEX_MODEL")
	if model == "" {
		model = "google/gemma-4-26b-a4b-it-maas"
	}
	client := ax.NewAI("vertex-ai", map[string]ax.Value{
		"api_url":             required("VERTEX_AI_API_URL"),
		"model":               model,
		"credential_provider": vertexCredentialProvider(),
	})
	out, err := client.Chat(context.Background(), map[string]ax.Value{
		"chat_prompt":     ax.Array(ax.Object("role", "user", "content", "Reply with the word ready.")),
		"response_format": ax.Object("type", "json_object"),
	}, nil)
	if err != nil {
		panic(err)
	}
	fmt.Println(out)
}

Go Signature Constraints

Builds native constrained fields and runs the signature with OpenAI.

Go 
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"
	"time"

	ax "github.com/ax-llm/ax/packages/go"
)

func openAIClient() *ax.OpenAICompatibleClient {
	apiKey := os.Getenv("OPENAI_API_KEY")
	if apiKey == "" {
		apiKey = os.Getenv("OPENAI_APIKEY")
	}
	if apiKey == "" {
		panic("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.")
	}
	model := os.Getenv("AX_OPENAI_MODEL")
	if model == "" {
		model = "gpt-5.4-mini"
	}
	return ax.NewOpenAICompatibleClient(map[string]ax.Value{
		"api_key":      apiKey,
		"model":        model,
		"model_config": ax.Object("temperature", 0),
	})
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()
	signature := ax.AxSignature{
		Description: "Extract a constrained restaurant booking",
		Inputs: []ax.Field{
			{
				Name: "requestText", Title: "Request Text", Description: "Booking request",
				Type: ax.FieldType{Name: "string", MinLength: 10, MaxLength: 500},
			},
			{
				Name: "contactEmail", Title: "Contact Email", Description: "Contact email",
				Type: ax.FieldType{Name: "string", Format: "email"},
			},
		},
		Outputs: []ax.Field{
			{
				Name: "partySize", Title: "Party Size", Description: "Guests",
				Type: ax.FieldType{Name: "number", Minimum: 1, Maximum: 12},
			},
			{
				Name: "bookingCode", Title: "Booking Code", Description: "Must look like ABC-1234",
				Type: ax.FieldType{
					Name: "string", Pattern: `^[A-Z]{3}-\d{4}$`,
					PatternDescription: "Three letters, a dash, and four digits",
				},
			},
		},
	}
	program := ax.NewAx("requestText:string -> partySize:number, bookingCode:string", nil)
	program.Signature = signature
	output, err := program.Forward(
		ctx,
		openAIClient(),
		map[string]ax.Value{
			"requestText":  "Book dinner for four people under the name Ada Lovelace.",
			"contactEmail": "ada@example.com",
		},
		nil,
	)
	if err != nil {
		panic(err)
	}
	data, err := json.MarshalIndent(output, "", "  ")
	if err != nil {
		panic(err)
	}
	fmt.Println(string(data))
}

Centralized Usage Observer

Attributes every completed model call to a tenant, user, and request from one global observer.

Go 
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"
	"time"

	ax "github.com/ax-llm/ax/packages/go"
)

func main() {
	apiKey := os.Getenv("OPENAI_API_KEY")
	if apiKey == "" {
		apiKey = os.Getenv("OPENAI_APIKEY")
	}
	if apiKey == "" {
		panic("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.")
	}
	model := os.Getenv("AX_OPENAI_MODEL")
	if model == "" {
		model = "gpt-5.4-mini"
	}

	events := []ax.AxUsageEvent{}
	ax.SetUsageObserver(func(event ax.AxUsageEvent) {
		events = append(events, event)
	})
	defer ax.SetUsageObserver(nil)

	client := ax.NewOpenAICompatibleClient(map[string]ax.Value{
		"api_key": apiKey,
		"model":   model,
		"usageContext": ax.Object(
			"tenantId", "tenant-42",
			"feature", "support-chat",
			"attributes", ax.Object("environment", "example"),
		),
	})
	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()
	_, err := client.Chat(
		ctx,
		map[string]ax.Value{
			"chat_prompt": ax.Array(
				ax.Object("role", "user", "content", "Reply with one short greeting."),
			),
		},
		ax.Object(
			"usageContext",
			ax.Object("userId", "user-7", "requestId", fmt.Sprintf("request-%d", time.Now().UnixNano())),
		),
	)
	if err != nil {
		panic(err)
	}
	output, err := json.MarshalIndent(events, "", "  ")
	if err != nil {
		panic(err)
	}
	fmt.Println(string(output))
}

Go Incremental Provider Stream

Pulls OpenAI SSE events incrementally and closes the response body.

Go 
package main

import (
	"context"
	"fmt"
	"os"
	"time"

	ax "github.com/ax-llm/ax/packages/go"
)

func main() {
	apiKey := os.Getenv("OPENAI_API_KEY")
	if apiKey == "" {
		apiKey = os.Getenv("OPENAI_APIKEY")
	}
	if apiKey == "" {
		panic("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.")
	}
	model := os.Getenv("AX_OPENAI_MODEL")
	if model == "" {
		model = "gpt-5.6-luna"
	}
	client, ok := ax.NewAI("openai", map[string]ax.Value{"api_key": apiKey, "model": model}).(ax.StreamingAIClient)
	if !ok {
		panic("OpenAI provider does not expose incremental streaming")
	}
	started := time.Now()
	stream, err := client.StreamEvents(context.Background(), map[string]ax.Value{
		"chat_prompt": ax.Array(ax.Object("role", "user", "content", "Reply with exactly: streaming works")),
		"model_config": ax.Object("temperature", 1),
	}, nil)
	if err != nil {
		panic(err)
	}
	defer stream.Close()
	for stream.Next() {
		event := stream.Value().(map[string]ax.Value)
		var results []ax.Value
		switch value := event["results"].(type) {
		case *ax.AxArray:
			results = value.Items
		case []ax.Value:
			results = value
		}
		if len(results) == 0 {
			continue
		}
		result := results[0].(map[string]ax.Value)
		if content, ok := result["content"].(string); ok && content != "" {
			fmt.Printf("[%d ms] %s", time.Since(started).Milliseconds(), content)
		}
	}
	if err := stream.Err(); err != nil {
		panic(err)
	}
	fmt.Println()
}

Go Gemini Flex Inference

Sends latency-tolerant work through Gemini Flex and reports the applied tier.

Go 
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	ax "github.com/ax-llm/ax/packages/go"
)

func geminiAPIKey() string {
	value := os.Getenv("GOOGLE_API_KEY")
	if value == "" {
		value = os.Getenv("GOOGLE_APIKEY")
	}
	if value == "" {
		panic("Set GOOGLE_API_KEY or GOOGLE_APIKEY to run this example.")
	}
	return value
}

func main() {
	model := os.Getenv("AX_GEMINI_MODEL")
	if model == "" {
		model = "gemini-3.7-flash"
	}
	client := ax.NewAI("google-gemini", map[string]ax.Value{
		"api_key": geminiAPIKey(),
		"model":   model,
	})
	out, err := client.Chat(context.Background(), map[string]ax.Value{
		"chat_prompt": ax.Array(ax.Object(
			"role", "user",
			"content", "Explain in one sentence why batch evaluations save time.",
		)),
	}, map[string]ax.Value{"service_tier": "flex"})
	if err != nil {
		panic(err)
	}
	data, err := json.MarshalIndent(out, "", "  ")
	if err != nil {
		panic(err)
	}
	fmt.Println(string(data))
}

Go Contextual Generation

Answers from supplied context and returns compact citations with OpenAI.

Go 
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"
	"time"

	ax "github.com/ax-llm/ax/packages/go"
)


func openAIClient() *ax.OpenAICompatibleClient {
	apiKey := os.Getenv("OPENAI_API_KEY")
	if apiKey == "" { apiKey = os.Getenv("OPENAI_APIKEY") }
	if apiKey == "" { panic("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.") }
	model := os.Getenv("AX_OPENAI_MODEL")
	if model == "" { model = "gpt-5.4-mini" }
	return ax.NewOpenAICompatibleClient(map[string]ax.Value{"api_key": apiKey, "model": model, "model_config": ax.Object("temperature", 0)})
}

func printJSON(value ax.Value) {
	data, err := json.MarshalIndent(value, "", "  ")
	if err != nil { panic(err) }
	fmt.Println(string(data))
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()
	client := openAIClient()
	program := ax.NewAx("context:string, question:string -> answer:string, citations:string[]", nil)
	output, err := program.Forward(ctx, client, map[string]ax.Value{"context": "Ax uses signatures, ai(), ax(), agent(), flow(), and optimize().", "question": "How should a new developer think about Ax?"}, nil)
	if err != nil { panic(err) }
	printJSON(output)
}

Go Adaptive Provider Balancing

Routes equivalent chat traffic using shared reliability, latency, and cost statistics.

Go 
package main

import (
	"context"
	"fmt"
	"os"

	ax "github.com/ax-llm/ax/packages/go"
)

func main() {
	key := os.Getenv("OPENAI_API_KEY")
	if key == "" {
		key = os.Getenv("OPENAI_APIKEY")
	}
	if key == "" {
		panic("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.")
	}
	model := os.Getenv("AX_OPENAI_MODEL")
	if model == "" {
		model = "gpt-5.4-mini"
	}
	services := []ax.AxAIService{
		ax.NewOpenAICompatibleClient(map[string]ax.Value{"api_key": key, "model": model}),
		ax.NewOpenAICompatibleClient(map[string]ax.Value{"api_key": key, "model": model}),
	}

	store := ax.NewAxInMemoryBalancerStatsStore()
	routeKeys := []string{"openai-primary", "openai-backup"}
	events := []string{}
	strategy := &ax.AxBalancerAdaptiveStrategy{
		DeadlineMs: 6_000, BadOutcomeCost: 0.02,
		ExpectedTokens: map[string]ax.Value{"promptTokens": 1_200.0, "completionTokens": 300.0},
		Namespace:      "support-summary-v1", StatsStore: store,
		RouteKey: func(_ ax.AxAIService, index int) string { return routeKeys[index] },
		Slice: func(context map[string]ax.Value) string {
			if options, ok := context["options"].(map[string]ax.Value); ok && options["stream"] == true {
				return "streaming"
			}
			return "interactive"
		},
		OnRoutingEvent: func(event ax.AxBalancerRoutingEvent) { events = append(events, fmt.Sprint(event["type"])) },
	}
	balancer, err := ax.NewAxBalancerWithOptions(services, ax.AxBalancerOptions{Strategy: strategy})
	if err != nil {
		panic(err)
	}
	response, err := balancer.Chat(context.Background(), map[string]ax.Value{"model": model, "chat_prompt": ax.Array(ax.Object("role", "user", "content", "Summarize why shared routing state matters."))}, nil)
	if err != nil {
		panic(err)
	}
	fmt.Println(response)
	fmt.Println(events)
}

Portable Runtime Hooks

Applies global and forward-scoped rate limiting, tracing, and metrics to AxGen, AxAgent, and AxFlow.

Go 
package main

import (
	"context"
	"fmt"
	"os"
	"time"

	ax "github.com/ax-llm/ax/packages/go"
	axgoja "github.com/ax-llm/ax/packages/go/runtime/goja"
)

type logSpan struct{ name string }
func (s *logSpan) SetAttributes(map[string]ax.Value) {}
func (s *logSpan) AddEvent(name string, _ map[string]ax.Value) { fmt.Printf("[span:event] %s %s\n", s.name, name) }
func (s *logSpan) RecordException(err error) { fmt.Printf("[span:error] %s %v\n", s.name, err) }
func (s *logSpan) SetStatus(string, string) {}
func (s *logSpan) End() { fmt.Printf("[span:end] %s\n", s.name) }

type logTracer struct{}
func (logTracer) StartSpan(start ax.AxSpanStart) ax.AxSpan {
	fmt.Printf("[span:start] %s\n", start.Name)
	return &logSpan{name: start.Name}
}

type logInstrument struct{ name string }
func (i logInstrument) Add(value float64, _ map[string]ax.Value) { fmt.Printf("[metric] %s += %g\n", i.name, value) }
func (i logInstrument) Record(value float64, _ map[string]ax.Value) { fmt.Printf("[metric] %s = %g\n", i.name, value) }

type logMeter struct{}
func (logMeter) CreateCounter(name string, _ ax.AxMetricInstrumentOptions) ax.AxCounter { return logInstrument{name} }
func (logMeter) CreateHistogram(name string, _ ax.AxMetricInstrumentOptions) ax.AxHistogram { return logInstrument{name} }
func (logMeter) CreateGauge(name string, _ ax.AxMetricInstrumentOptions) ax.AxGauge { return logInstrument{name} }

func limiter(label string) ax.AxRateLimiter {
	return ax.AxRateLimiterFunc(func(next ax.AxRequestExecutor, info ax.AxRateLimitInfo) (ax.Value, error) {
		fmt.Printf("[limit:%s] %s %s/%s stream=%t\n", label, info.Operation, info.Provider, info.Model, info.Streaming)
		return next()
	})
}

func main() {
	apiKey := os.Getenv("OPENAI_API_KEY")
	if apiKey == "" { apiKey = os.Getenv("OPENAI_APIKEY") }
	if apiKey == "" { panic("Set OPENAI_API_KEY or OPENAI_APIKEY to run this example.") }
	model := os.Getenv("AX_OPENAI_MODEL")
	if model == "" { model = "gpt-5.4-mini" }
	client := ax.NewOpenAICompatibleClient(map[string]ax.Value{
		"api_key": apiKey, "model": model, "model_config": ax.Object("temperature", 0),
	})
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
	defer cancel()
	tracer, meter := logTracer{}, logMeter{}
	override := ax.AxRuntimeHooks{RateLimiter: limiter("forward"), Tracer: tracer, Meter: meter}

	ax.SetRateLimiter(limiter("global"))
	ax.SetTracer(tracer)
	ax.SetMeter(meter)
	defer func() { ax.SetRateLimiter(nil); ax.SetTracer(nil); ax.SetMeter(nil) }()

	direct := ax.NewAx("topic:string -> summary:string", nil)
	result, err := direct.Forward(ctx, client, map[string]ax.Value{"topic": "portable Ax runtime hooks"}, nil)
	if err != nil { panic(err) }
	fmt.Println(result)

	helper := ax.NewAgent("question:string -> answer:string", nil)
	result, err = helper.ForwardWithHooks(ctx, client, map[string]ax.Value{"question": "What does a rate limiter wrap?"}, map[string]ax.Value{"runtime": axgoja.NewRuntime(), "max_actor_steps": 12}, override)
	if err != nil { panic(err) }
	fmt.Println(result)

	workflow := ax.NewFlow(map[string]ax.Value{"id": "examples.runtimeHooks"}).
		Execute("outline", ax.NewAx("topic:string -> outline:string", nil), nil).
		Execute("polish", ax.NewAx("outline:string -> answer:string", nil), nil).
		Returns(map[string]ax.Value{"answer": "polish"})
	result, err = workflow.ForwardWithHooks(ctx, client, map[string]ax.Value{"topic": "Ax runtime hooks"}, nil, override)
	if err != nil { panic(err) }
	fmt.Println(result)
}
Docs
Start
Quick Start How Ax Fits Together Advanced Start FAQ
Agents
Overview Micro Agents Standard Agents Long-Horizon Agents Performance Internals
Examples
Overview Generation Agents Long-Horizon Agents Flows Audio MCP Optimization
Concepts
DSPy Signatures Tools MCP MCP Subscriptions Event Runtime Optimization Playbook LLMs Telemetry
Subsystems
ai() LLM Models ax() Generation s() Signatures agent() Agents flow() Workflows optimize() GEPA
Skills
Overview Quick Reference AI Audio Signatures Generation Flow Agent Agent RLM Memory & Skills Observability Agent Optimize Agent Context GEPA Refinement Playbook
API Docs
ai() API ax() API s() API agent() API flow() API optimize() API