GAI

Requirements

• Go 1.26.9 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"
  "io"
  "log"
  "os"

  "github.com/lace-ai/gai/agent"
  "github.com/lace-ai/gai/ai"
  "github.com/lace-ai/gai/ai/openai"
  "github.com/lace-ai/gai/modelinput"
)

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
  }
  if closer, ok := model.(io.Closer); ok {
    defer func() {
      if err := closer.Close(); err != nil {
        log.Printf("close model: %v", err)
      }
    }()
  }

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

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

  for event := range workflow.RunEvents(ctx) {
    switch event.Type {
    case agent.EventOutput:
      if event.Output != nil && event.Output.Kind == agent.OutputText {
        fmt.Print(event.Output.Text)
      }
    }
  }

  fmt.Println()
  _, err = workflow.Wait()
  return err
}

Use Workflow.Run(ctx) when only the final result is needed. Use Workflow.RunEvents(ctx) for ordered streaming and call Wait after draining the channel. Both APIs execute the same middleware-aware pipeline. 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.

loop.Loop.Run exposes low-level loop.Event values. Workflow.RunEvents exposes higher-level agent.Event values covering visible output, primary and middleware stages, and one final workflow outcome. Workflow results contain copied loop.Iteration snapshots. Prompt-only tool rendering accepts modelinput.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) (string, error)
}

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

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,
) (string, error) {
  var args struct {
    OrderID string `json:"order_id"`
  }
  if err := loop.DecodeToolArgs(req, &args); err != nil {
    return "", err
  }
  return `{"status":"in_transit"}`, nil
}

Use loop.NewTool(name, description, params, handler) to wrap a handler without a custom struct. A non-nil handler error becomes a tool failure the model can read. ToolResultProcessor can transform results before they reach the conversation, events, or loop telemetry.

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. Tools registered with ToolOptions.Terminal complete the primary loop without another model generation. A terminal registration can set AllowNonTerminalCalls to execute mixed batches normally and continue instead.

Use ToolExecution to set concurrency and default handler deadlines, and loop.WithToolOptions for per-tool traits, serial execution, timeouts, or a shared guard. ToolPolicy authorizes before admission; ToolApprovalResolver handles in-process approval. ToolResultProcessor transforms output before it reaches events, conversation history, and loop telemetry. These settings are available on both loop.Loop and agent.Definition, with per-run agent overrides. See tool execution and migration for examples, terminal presentation batches, defaults, approval semantics, ordering, and cancellation guarantees.

Use RunInput.Execution to override an agent's defaults for one run. Omitted fields inherit from Definition.

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

Ordered workflow events

RunEvents exposes the workflow's ordered, middleware-aware event stream:

for event := range workflow.RunEvents(ctx) {
  switch event.Type {
  case agent.EventAttemptStart:
    // A generation attempt began.
  case agent.EventOutput:
    // Every EventOutput is externally visible, independent of Source.Index.
    render(event.Output)
  case agent.EventRetry:
    // Roll back output associated with event.AttemptID.
  case agent.EventIterationDone:
    // One model/tool iteration completed.
  case agent.EventStageStart, agent.EventStageFinish:
    // Observe primary and middleware-agent lifecycle.
  case agent.EventDone:
    // The complete workflow finished successfully.
  case agent.EventError, agent.EventCanceled:
    // Handle terminal failure or cancellation.
  }
}

result, err := workflow.Wait()

For non-streaming use, result, err := workflow.Run(ctx) starts and internally drains that same pipeline. Wait is repeatable and concurrency-safe; Result returns a non-blocking defensive snapshot.

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 accepted stage output after the upstream output.
• ReplaceOutput replaces the visible output with accepted stage output after a successful stage.

Nested attempt and tool lifecycle events stream while an agent-middleware stage runs. Nested EventOutput does not: PreserveOutput suppresses it, while AppendOutput and ReplaceOutput buffer it until the nested run completes and retry/discard outcomes determine which output is accepted. Consequently, a nested attempt's EventIterationDone precedes its accepted EventOutput; that output is emitted before the middleware EventStageFinish.

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
modelinput/              Prompt construction, rendering, structured input, and messages
modelinput/history/      Persisted history selection and optional summarization
modelinput/tooldefinitions/  Prompt-only tool definitions
context/                 Deprecated compatibility packages for the former paths
loop/                    Ordered model/tool execution and tool helpers
observability/langfuse/  Optional Langfuse OpenTelemetry exporter setup
testutil/                Mocks and helpers used by tests