agentic-go

A lightweight, type-safe Go framework for building AI agents with tool use, structured output, and multi-agent orchestration.

Features

• Provider-agnostic -- pluggable Model interface with 9 built-in providers
• Type-safe tools -- generic tool builders with automatic JSON Schema generation from Go structs
• Structured output -- TypedAgent[DepsT, OutputT] returns validated typed results
• Streaming -- first-class streaming with channel-based event delivery
• Dependency injection -- typed dependencies passed to tool handlers via RunContext[DepsT]
• Multi-agent -- delegate tasks between agents with Handoff
• Deferred tools -- async execution with human-in-the-loop approval
• History processors -- truncation, sliding window, and LLM-based summarization
• Multi-modal -- images, audio, video, and document inputs
• MCP support -- use tools from Model Context Protocol servers
• Thinking tokens -- extended reasoning for Anthropic, OpenAI o-series, and Gemini
• Output validation -- struct tag validation with automatic retry

Installation

go get github.com/regularkevvv/agentic-go

Requires Go 1.25.4 or later.

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    agentic "github.com/regularkevvv/agentic-go"
    "github.com/regularkevvv/agentic-go/provider/openai"
)

func main() {
    model, _ := openai.New("gpt-4o")
    agent := agentic.NewAgent[agentic.NoDeps]("You are a helpful assistant.", model)

    result, err := agent.Run(context.Background(), "Hello!", nil)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Output)
}

Tools

Define tools with automatic schema inference from Go types:

type GetWeatherInput struct {
    _        struct{} `tool:"Look up the current weather for a city"`
    Location string   `json:"location" description:"City name"`
    Unit     string   `json:"unit,omitempty" enum:"celsius,fahrenheit"`
}

agentic.AddTool(agent, func(input GetWeatherInput) (WeatherOutput, error) {
    return WeatherOutput{Temperature: 24, Condition: "sunny"}, nil
})

Tools with dependencies:

agentic.AddToolWithDeps(agent, func(ctx agentic.RunContext[MyDeps], input QueryInput) (QueryOutput, error) {
    rows, _ := ctx.Deps.DB.QueryContext(ctx.Ctx, input.SQL)
    return QueryOutput{Rows: rows}, nil
})

Structured Output

type Summary struct {
    Title    string   `json:"title"    validate:"required"`
    Points   []string `json:"points"   validate:"required,min=1"`
}

agent := agentic.NewTypedAgent[agentic.NoDeps, Summary](
    "Summarize the input as structured data.",
    model,
    "Return a structured summary.",
)

result, _ := agent.Run(ctx, "Summarize Go's strengths.", nil)
fmt.Println(result.Output.Title)  // typed access

Providers

Provider	Import	Constructor
OpenAI	provider/openai	openai.New("gpt-4o")
Anthropic	provider/anthropic	anthropic.New("claude-sonnet-4-20250514")
Google Gemini	provider/gemini	gemini.New("gemini-2.0-flash")
Azure OpenAI	provider/azure	azure.New(endpoint, deployment, apiKey)
AWS Bedrock	provider/bedrock	bedrock.New("us.anthropic.claude-sonnet-4-20250514-v1:0")
Together AI	provider/together	together.New("meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo")
OpenRouter	provider/openrouter	openrouter.New("anthropic/claude-sonnet-4")
Ollama	provider/ollama	ollama.New("llama3.1")
Grok	provider/grok	grok.New("grok-3")

Implement the Model interface to add your own.

Agent-to-Agent

Delegate tasks to specialized sub-agents:

researcher := agentic.NewAgent[MyDeps]("You are a research assistant.", model)
writer := agentic.NewAgent[MyDeps]("You write clear reports.", model)

// Writer can delegate research tasks
writer.AddHandoff(agentic.NewHandoff("research", "Delegate research tasks", researcher))

Deferred Tools

Tools that require human approval before execution:

tool, handler, _ := agentic.DeferredToolWithApproval(
    "delete_record", "Delete a database record",
    func(ctx context.Context, input DeleteInput) (string, error) {
        return db.Delete(input.ID)
    },
    func(ctx context.Context, call agentic.ToolUse) (bool, error) {
        return promptUser("Approve deletion of %s?", call.Input["id"]), nil
    },
)

Streaming

stream, _ := agent.RunStream(ctx, "Tell me a story.", nil)
for event := range stream.Events {
    if event.Type == agentic.StreamEventTextDelta {
        fmt.Print(event.Delta)
    }
}

History Processors

Manage context window with built-in processors:

agent := agentic.NewAgent[agentic.NoDeps]("You are helpful.", model,
    agentic.WithHistoryProcessor[agentic.NoDeps](agentic.TruncateHistory(20)),
)

// Or chain multiple processors
agentic.WithHistoryProcessor[agentic.NoDeps](agentic.ChainProcessors(
    agentic.SlidingWindowHistory(4000, tokenCounter),
    agentic.TruncateHistory(50),
))

Project Layout

agentic-go/
  agent.go            # Core agent orchestration
  agent_options.go    # Configuration options
  stream.go           # Streaming support
  typed_agent.go      # TypedAgent for structured output
  handoff.go          # Agent-to-agent delegation
  deferred.go         # Async/deferred tools
  history_processor.go # Message history transforms
  tools/              # Tool builders, registry, toolsets
  provider/           # LLM provider implementations
  internal/core/      # Shared types (Message, Tool, Model, etc.)
  mcp/                # Model Context Protocol integration
  examples/           # Runnable example programs

Examples

cp .env.example .env   # fill in your API key
go run ./examples/basic
go run ./examples/tools
go run ./examples/structured

See examples/ for details.

Contributing

See CONTRIBUTING.md for development setup, testing, and PR guidelines.

License

MIT