go-agent

Go Agent

A reusable AI agent framework for Go implementing the observe → decide → act → update loop pattern for LLM-based task execution.

Overview

go-agent provides a clean, production-ready foundation for building AI agents with tool use capabilities in Go. It features:

• 🏗️ Hexagonal Architecture — Clean separation of domain logic and infrastructure
• 🔄 Agent Loop Pattern — Observe → Decide → Act → Update cycle for autonomous task execution
• 📡 Event-Driven — Observable task lifecycle via domain events
• 🧠 Memory System — Long-term context storage with text search and embedding-based semantic search
• 🛡️ Resilience Patterns — Breaker, debounce, retry, throttle, and timeout
• 🔧 Tool Use — Extensible tool system with type-safe definitions

Works with any OpenAI-compatible API (LM Studio, Ollama, OpenAI, vLLM, etc.).

Table of Contents

• Architecture
• CLI Usage
• Configuration
• Contributing
• Creating Custom Tools
• Docker
• Features
• Installation
• License
• Project Structure
• Quick Start
• Testing

Installation

go get github.com/andygeiss/go-agent

Requirements: Go 1.25.5+

Quick Start

Run the CLI Demo

# Clone the repository
git clone https://github.com/andygeiss/go-agent.git
cd go-agent

# Start LM Studio (or any OpenAI-compatible server) on localhost:1234

# Run the CLI
go run ./cmd/cli -model <your-model-name>

Use as a Library

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/andygeiss/cloud-native-utils/messaging"
    "github.com/andygeiss/go-agent/internal/adapters/outbound"
    "github.com/andygeiss/go-agent/internal/domain/agent"
    "github.com/andygeiss/go-agent/internal/domain/tooling"
)

func main() {
    // Create infrastructure
    dispatcher := messaging.NewExternalDispatcher()
    llmClient := outbound.NewOpenAIClient("http://localhost:1234", "your-model")
    toolExecutor := outbound.NewToolExecutor()
    publisher := outbound.NewEventPublisher(dispatcher)
    memoryStore := outbound.NewMemoryStore()

    // Register tools
    idGen := func() string { return fmt.Sprintf("note-%d", time.Now().UnixNano()) }
    memoryToolSvc := tooling.NewMemoryToolService(memoryStore, idGen)
    memoryGetTool := tooling.NewMemoryGetTool(memoryToolSvc)
    toolExecutor.RegisterTool(string(memoryGetTool.ID), memoryGetTool.Func)
    toolExecutor.RegisterToolDefinition(memoryGetTool.Definition)

    // Create agent
    ag := agent.NewAgent("my-agent", "You are a helpful assistant.",
        agent.WithMaxIterations(10),
        agent.WithMaxMessages(50),
    )

    // Create task service and run
    taskService := agent.NewTaskService(llmClient, toolExecutor, publisher)
    task := agent.NewTask("task-1", "chat", "What do you remember about my preferences?")
    
    result, _ := taskService.RunTask(context.Background(), &ag, task)
    println(result.Output)
}

Architecture

The project follows hexagonal architecture (ports and adapters) with domain-driven design:

┌─────────────────────────────────────────────────────────────────┐
│                         cmd/cli                                 │
│                    (Application Entry)                          │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                     internal/domain                             │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ agent/        Core aggregate, task service, types           ││
│  │ chatting/     Use cases: SendMessage, ClearConversation     ││
│  │ indexing/     Use cases: Scan, ChangedSince, DiffSnapshots  ││
│  │ memorizing/   Use cases: WriteNote, SearchNotes             ││
│  │ tooling/      Tool implementations                          ││
│  │ openai/       OpenAI API types (request, response, tool)    ││
│  └─────────────────────────────────────────────────────────────┘│
└──────────────────────────────┬──────────────────────────────────┘
                               │ depends on interfaces (ports)
┌──────────────────────────────▼──────────────────────────────────┐
│                    internal/adapters                            │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ inbound/         FSWalker (file system traversal)           ││
│  │ outbound/        LLMClient, ToolExecutor, EventPublisher,   ││
│  │                  MemoryStore, IndexStore implementations    ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

Agent Loop

The core agent implements an iterative loop:

1. Observe — Receive user input, build message context
2. Decide — Call LLM with messages and available tools
3. Act — Execute any tool calls requested by the LLM
4. Update — Add results to conversation, check termination
5. Repeat — Continue until task completes or max iterations reached

For detailed architecture documentation, see CONTEXT.md.

Features

Built-in Tools (alphabetically sorted)

Typed Memory System

Memory notes are categorized by source type for schema-aware storage and retrieval:

The memory_search tool supports filtering by source_types and min_importance, enabling precise retrieval of relevant context.

Helper constructors for schema-aware note creation:

// Create typed notes with appropriate defaults
note := agent.NewDecisionNote("note-1", "Use PostgreSQL", "database", "architecture")
note := agent.NewRequirementNote("note-2", "Must support 1000 concurrent users")
note := agent.NewExperimentNote("note-3", "Caching improves latency", "50% reduction")

Programmatic search by type:

svc := memorizing.NewService(store)

// Search specific types
decisions, _ := svc.SearchDecisions(ctx, "database", 10)
requirements, _ := svc.SearchRequirements(ctx, "scalability", 10)

// Search with combined filters
opts := &agent.MemorySearchOptions{
    SourceTypes:   []agent.SourceType{agent.SourceTypeDecision},
    MinImportance: 4,
    Tags:          []string{"architecture"},
}
notes, _ := store.Search(ctx, "query", 10, opts)

Embedding-Based Semantic Search

Memory notes support vector embeddings for semantic similarity search using cosine similarity:

// Store a note with an embedding (embeddings generated by external model)
embedding := getEmbedding("Go is a statically typed language")  // your embedding function
note := agent.NewMemoryNote("note-1", agent.SourceTypeFact).
    WithRawContent("Go is a statically typed language").
    WithEmbedding(embedding)
_ = store.Write(ctx, note)

// Search with cosine similarity ranking
queryEmbedding := getEmbedding("programming languages")
results, _ := store.SearchWithEmbedding(ctx, "languages", queryEmbedding, 10, nil)

Key features:

• Embedding type — []float32 vector representation
• WithEmbedding() — Builder method to attach embedding to notes
• SearchWithEmbedding() — Ranks results by cosine similarity
• Falls back to importance-based sorting when no query embedding provided
• Supports common embedding dimensions (128, 512, 1536 for OpenAI ada-002)

Domain Events (alphabetically sorted)

Subscribe to task lifecycle events:

• agent.task.completed — Task finishes successfully
• agent.task.failed — Task terminates with error
• agent.task.started — Task begins execution
• agent.toolcall.executed — Tool call completes

Lifecycle Hooks (alphabetically sorted)

hooks := agent.NewHooks().
    WithAfterLLMCall(func(ctx context.Context, ag *agent.Agent, t *agent.Task) error {
        log.Println("LLM response received")
        return nil
    }).
    WithAfterTask(func(ctx context.Context, ag *agent.Agent, t *agent.Task) error {
        log.Println("Task finished:", t.Status)
        return nil
    }).
    WithAfterToolCall(func(ctx context.Context, ag *agent.Agent, tc *agent.ToolCall) error {
        log.Println("Tool executed:", tc.Name, "→", tc.Result)
        return nil
    }).
    WithBeforeLLMCall(func(ctx context.Context, ag *agent.Agent, t *agent.Task) error {
        log.Println("Calling LLM...")
        return nil
    }).
    WithBeforeTask(func(ctx context.Context, ag *agent.Agent, t *agent.Task) error {
        log.Println("Starting task:", t.Name)
        return nil
    }).
    WithBeforeToolCall(func(ctx context.Context, ag *agent.Agent, tc *agent.ToolCall) error {
        log.Println("Executing tool:", tc.Name)
        return nil
    })

taskService.WithHooks(hooks)

Resilience Patterns

The OpenAIClient includes configurable resilience (alphabetically sorted):

• Circuit Breaker: Opens after 5 consecutive failures (configurable)
• Debounce: Coalesces rapid calls (disabled by default)
• Retry: 3 attempts with 2s delay (configurable)
• Throttling: Rate limiting via token bucket (disabled by default)
• Timeout: HTTP (60s) and LLM call (120s) timeouts (configurable)

CLI Usage

go run ./cmd/cli [flags]

Commands (during chat, alphabetically sorted)

Flags (alphabetically sorted)

Creating Custom Tools

package tooling

import (
    "context"
    "github.com/andygeiss/go-agent/internal/domain/agent"
)

// Define the tool
func NewMyTool() agent.Tool {
    return agent.Tool{
        ID: "my_tool",
        Definition: agent.NewToolDefinition("my_tool", "Description of what it does").
            WithParameter("input", "The input parameter"),
        Func: MyToolFunc,
    }
}

// Implement the function
func MyToolFunc(ctx context.Context, arguments string) (string, error) {
    var args struct {
        Input string `json:"input"`
    }
    if err := agent.DecodeArgs(arguments, &args); err != nil {
        return "", err
    }
    
    // Your tool logic here
    return "result", nil
}

Register the tool:

myTool := tooling.NewMyTool()
executor.RegisterTool("my_tool", myTool.Func)
executor.RegisterToolDefinition(myTool.Definition)

Configuration

Agent Options (alphabetically sorted)

agent.NewAgent("id", "system prompt",
    agent.WithMaxIterations(20),      // Max loop iterations per task
    agent.WithMaxMessages(100),       // Message history limit (0 = unlimited)
    agent.WithMetadata(agent.Metadata{
        "model": "gpt-4",
        "user":  "alice",
    }),
)

LLM Client Options (alphabetically sorted)

client := outbound.NewOpenAIClient(baseURL, model).
    WithCircuitBreaker(10).                     // Open after 10 failures
    WithDebounce(500 * time.Millisecond).       // Coalesce rapid calls
    WithHTTPClient(customClient).               // Custom HTTP client
    WithLLMTimeout(180 * time.Second).          // LLM call timeout
    WithLogger(slog.Default()).                 // Structured logging
    WithRetry(5, 3*time.Second).                // 5 attempts, 3s delay
    WithThrottle(100, 10, time.Second)          // tokens, refill, period

Task Service Options

taskService := agent.NewTaskService(llm, executor, publisher).
    WithHooks(hooks).                 // Lifecycle hooks
    WithParallelToolExecution()       // Enable parallel tool calls

Docker

Build

docker build -t go-agent .

Run with Docker Compose

# Create .env file with required variables
echo "APP_SHORTNAME=go-agent" > .env
echo "USER=$(whoami)" >> .env

# Start services
docker-compose up -d

Testing

# Run all tests (~2s)
go test ./...

# Run with coverage
go test -cover ./...

# Run integration tests (requires LM Studio or compatible server)
OPENAI_CHAT_MODEL="your-model" OPENAI_CHAT_URL="http://localhost:1234" \
  go test -tags=integration ./...

# Run all benchmarks (PGO profiling)
go test -bench=. ./cmd/cli/...

# Run specific benchmark categories
go test -bench=Memory ./cmd/cli/...           # Memory system benchmarks
go test -bench=FullStack ./cmd/cli/...        # End-to-end benchmarks
go test -bench=TaskService ./cmd/cli/...      # Task service benchmarks

# Run benchmarks with custom time
go test -bench=. -benchtime=1s ./cmd/cli/...

Integration Tests

Integration tests are guarded by the //go:build integration build tag and require:

• A running LM Studio (or compatible) server
• Environment variables: OPENAI_CHAT_MODEL, OPENAI_CHAT_URL, OPENAI_EMBED_MODEL, OPENAI_EMBED_URL

Without -tags=integration, these tests are excluded from the build.

### Benchmark Categories

The CLI benchmarks (`cmd/cli/main_test.go`) cover all domain contexts:

| Category | Description |
|----------|-------------|
| `Benchmark_FSWalker_*` | Real file system walking |
| `Benchmark_FullStack_*` | End-to-end agent with tools |
| `Benchmark_IndexingService_*` | Scan/ChangedSince/DiffSnapshots at 100/1000/10000 files |
| `Benchmark_IndexStore_*` | Snapshot save/get operations |
| `Benchmark_IndexToolService_*` | Tool-based indexing operations |
| `Benchmark_MemoryNote_*` | MemoryNote object creation/methods |
| `Benchmark_MemoryStore_*` | Raw store ops at 100/1000/10000 notes |
| `Benchmark_MemoryTools_*` | Tool-based memory operations |
| `Benchmark_MemorizingService_*` | Complete memory workflow |
| `Benchmark_*NoteUseCase` | Domain use case benchmarks |
| `Benchmark_NewFileInfo` | FileInfo object creation |
| `Benchmark_NewSnapshot` | Snapshot object creation |
| `Benchmark_SendMessageUseCase_*` | Chat use case execution |
| `Benchmark_Snapshot_*` | Snapshot method performance |
| `Benchmark_TaskService_*` | Task service with hooks/parallelism |

---

## Project Structure

go-agent/ ├── cmd/cli/ # CLI application ├── internal/ │ ├── adapters/ │ │ ├── inbound/ # Inbound adapters (data sources) │ │ │ └── file_walker.go # FileWalker → filesystem traversal │ │ └── outbound/ # Outbound adapters (infrastructure) │ │ ├── conversation_store.go # ConversationStore → resource.Access │ │ ├── encrypted_conversation_store.go # AES-GCM encrypted variant │ │ ├── event_publisher.go # EventPublisher → messaging.Dispatcher │ │ ├── index_store.go # IndexStore → resource.Access │ │ ├── memory_store.go # MemoryStore → resource.Access │ │ ├── openai_client.go # LLMClient → OpenAI-compatible API │ │ └── tool_executor.go # ToolExecutor → tool registry │ └── domain/ │ ├── agent/ # Core domain (Agent, Task, Message, Hooks, Events) │ ├── chatting/ # Chat use cases (SendMessage, ClearConversation, GetAgentStats) │ ├── indexing/ # File indexing (Scan, ChangedSince, DiffSnapshots) │ ├── memorizing/ # Memory use cases (WriteNote, GetNote, SearchNotes, DeleteNote) │ ├── openai/ # OpenAI API types (Request, Response, Tool) │ └── tooling/ # Tool implementations (memory, index) ├── AGENTS.md # AI agent definitions ├── CONTEXT.md # Architecture documentation ├── Dockerfile ├── docker-compose.yml ├── README.md # This file └── VENDOR.md # Vendor library documentation

---

## Contributing

1. Read [CONTEXT.md](CONTEXT.md) for architecture and conventions
2. Check [VENDOR.md](VENDOR.md) for approved vendor patterns
3. Follow the hexagonal architecture pattern
4. Add tests for new functionality
5. Run `go fmt ./...` and `go vet ./...` before committing

---

## License

[MIT License](LICENSE)