GAI

Requirements

• Go 1.26.1 or newer
• Credentials for the model provider you use

Install the module in an existing application:

go get github.com/lace-ai/gai

Build a basic agent

This complete program streams a response from an OpenAI-backed agent:

package main

import (
  "context"
  "fmt"
  "log"
  "os"

  "github.com/lace-ai/gai/agent"
  "github.com/lace-ai/gai/ai/openai"
  gaictx "github.com/lace-ai/gai/context"
  "github.com/lace-ai/gai/loop"
  "github.com/lace-ai/gai/ai"
)

func main() {
  if err := run(context.Background()); err != nil {
    log.Fatal(err)
  }
}

func run(ctx context.Context) error {
  provider := openai.New(os.Getenv("OPENAI_API_KEY"), nil)

  model, err := provider.Model("gpt-4.1-mini")
  if err != nil {
    return err
  }
  defer func() {
    if err := model.Close(); err != nil {
      log.Printf("close model: %v", err)
    }
  }()

  assistant := agent.New(agent.Definition{
    Name:  "assistant",
    Model: model,
    Prompt: func(context.Context, agent.RunInput) (gaictx.PromptBuilder, error) {
      return gaictx.New(gaictx.Definition{
        SystemInstructions: []gaictx.Part{
          gaictx.NewTextPart("You are a concise, helpful assistant."),
        },
      }), nil
    },
  })

  workflow, err := assistant.NewRun(ctx, agent.RunInput{
    Prompt: gaictx.PromptInput{
      User: gaictx.NewTextContent("What is the capital of France?"),
    },
  })
  if err != nil {
    log.Fatal(err)
  }

  var runErr error
  for event := range workflow.RunEvents(ctx) {
    switch event.Type {
    case loop.EventToken:
      if event.Token != nil && event.Token.Type == ai.TokenTypeText {
        if event.Token.Text != "" {
          fmt.Print(event.Token.Text)
        } else {
          fmt.Print(event.Token.String())
        }
      }

    case loop.EventError, loop.EventCanceled:
      runErr = event.Err
    }
  }

  fmt.Println()
  return runErr
}

Workflow.RunEvents is the preferred API for a primary agent when event order matters. Each workflow is single-use; create a new workflow from the reusable agent definition for each request.

Package boundary

agent is the high-level API: it owns reusable definitions, per-run configuration, workflow lifecycle, middleware, and aggregate results. loop is the canonical low-level execution API and owns tools, tool responses and helpers, selection and transport, ordered events, and iterations. ai owns provider-neutral request, definition, and call types. Use agent for application workflows; use loop directly only when an application deliberately needs mutable execution control.

Workflow.RunEvents exposes the canonical loop.Event stream, while workflow results contain copied loop.Iteration snapshots. Prompt-only tool rendering accepts context.ToolSignature, so context packages do not require executable tools.

A tool has a typed schema and a Go function:

type Tool interface {
  Name() string
  Description() string
  Params() ai.ToolParameters
  Function(ctx context.Context, req *ai.ToolCall) *ToolResponse
}

Tool parameters are converted to JSON Schema for provider-native function calling. Models that do not support native tools can use GAI's text-protocol compatibility path.

func (t *LookupOrderTool) Params() ai.ToolParameters {
  return ai.ToolParameters{
    Strict: true,
    Properties: []ai.ToolParameter{
      {
        Name:        "order_id",
        Type:        ai.ToolParameterString,
        Description: "The order ID to look up.",
        Required:    true,
      },
    },
  }
}

func (t *LookupOrderTool) Function(
  ctx context.Context,
  req *ai.ToolCall,
) *loop.ToolResponse {
  var args struct {
    OrderID string `json:"order_id"`
  }
  if err := loop.DecodeToolArgs(req, &args); err != nil {
    return loop.NewToolError(err)
  }
  return loop.NewToolSuccess(`{"status":"in_transit"}`)
}

Attach tools to an agent definition:

support := agent.New(agent.Definition{
  Name:  "support",
  Model: model,
  Tools: []loop.Tool{lookupOrderTool},
  Prompt: supportPrompt,
})

The loop sends definitions to the model, executes requested calls, appends tool results to the conversation, and continues until the model commits a normal response or the iteration limit is reached.

For per-run tools, set RunInput.Execution.Tools:

• nil inherits Definition.Tools
• a non-nil slice replaces them
• an empty slice disables tools for that run

workflow, err := support.NewRun(ctx, agent.RunInput{
  Execution: agent.ExecutionConfig{
    Tools: []loop.Tool{lookupOrderToolForUser(userID)},
  },
})

Execution.ToolChoice and Execution.Reasoning can also be configured per run.

Ordered workflow events

RunEvents forwards the loop's event stream without splitting it into unrelated channels:

for event := range workflow.RunEvents(ctx) {
  switch event.Type {
  case loop.EventAttemptStart:
    // A generation attempt began.
  case loop.EventToken:
    // Stream visible text or inspect other token types.
  case loop.EventRetry:
    // Roll back output associated with event.AttemptID.
  case loop.EventIterationDone:
    // One model/tool iteration completed.
  case loop.EventDone:
    // The loop completed successfully.
  case loop.EventError, loop.EventCanceled:
    // Handle terminal failure or cancellation.
  }
}

Workflow.Run remains available for workflows that use post-processing middleware. It exposes compatibility token, status, and error channels; consumers must drain all three concurrently.

Workflow middleware

Middleware stages run after an upstream agent completes and are suited to tasks such as memory extraction, auditing, formatting, and evaluation.

agent.NewAgentMiddleware adapts another agent with one of three output policies:

• PreserveOutput keeps the upstream output and records the stage result.
• AppendOutput emits the stage output after the upstream output.
• ReplaceOutput replaces the visible output after a successful stage.

Use AgentMiddlewareConfig.MapInput to map a typed upstream WorkflowResult into the next agent's RunInput. Use MiddlewareFunc for transformations that do not need another model call.

Middleware is post-processing, not a supervisor or handoff runtime. Tool authorization and approval belong at the tool-execution boundary rather than in workflow middleware.

Package map

agent/                   Reusable agent definitions, workflows, middleware, and summary agents
ai/                      Provider-neutral requests, responses, tools, capabilities, and providers
context/                 Prompt construction, rendering, structured input, and messages
context/history/         Persisted history selection and optional summarization
loop/                    Ordered model/tool execution and tool helpers
observability/langfuse/  Optional Langfuse OpenTelemetry exporter setup
testutil/                Mocks and helpers used by tests