Go Agents

A library providing functional composition primitives for building AI-augmented applications in Go.

Overview

Go Agents offers type-safe building blocks for creating AI workflows using familiar Go patterns. The library focuses on functional composition, where AgentFunc[T, R] provides the same composability as Go's http.Handler, but for AI processing pipelines.

For project status and roadmap details, refer to PROJECT.md.

Key Features

• Functional Composition: Six composition patterns (Compose, Parallel, Chain, Retry, Fallback, Conditional)
• Type Safety: Go generics provide compile-time guarantees for agent workflows
• LLM Integration: HTTP-based integration tested with Ollama, designed for OpenAI-compatible APIs
• Multi-Agent Coordination: Hub-based message routing for agent communication
• Clean Architecture: Proper separation of concerns with unidirectional dependencies
• Standard Library: Uses only Go standard library and established patterns

Architecture

See .docs/architecture.md for comprehensive architectural documentation including package layers, design patterns, and implementation details.

Core Principles

1. Functional: Agents as composable functions with clear input/output types
2. Minimal: Essential primitives without framework overhead
3. Go Native: Standard library patterns and established Go idioms

Current Capabilities

• LLM Integration: Tested with Ollama, supports OpenAI-compatible endpoints
• Agent Lifecycle: Proper start/stop with graceful shutdown
• Resource Management: Context-aware operations with timeout handling
• Structured Logging: Built-in slog integration for observability

Examples

The examples/ directory contains working demonstrations of library capabilities:

Simple Agent

Basic agent creation, LLM integration, and conversation processing with beautiful console output. Shows agent lifecycle management and error handling.

Functional Composition

Demonstrates all six composition patterns (Compose, Parallel, Chain, Retry, Fallback, Conditional) with type-safe agent functions and comprehensive error handling.

Inter-Agent Communication

Multi-agent coordination using hub-based messaging. Shows request/response patterns, pub/sub communication, and distributed task processing with coordinator and worker agents.

Processor Pipeline

Agent Primitive Inversion pattern where processors orchestrate agents through middleware pipelines. Demonstrates logging processors, tool integration, and pipeline composition.

Profile Agent

Profile-driven agent configuration showing behavioral modification through runtime profile updates and multiple configuration sources.

Multi-Hub Coordination

Advanced multi-hub agent coordination patterns for complex distributed scenarios.

Each example includes detailed documentation and can be run independently. See examples/README.md for setup instructions.

Related Projects

• Model Context Protocol - Tool integration standard (planned integration)
• Agent2Agent Protocol - Inter-agent communication standard (planned integration)
• Ollama - Local LLM deployment platform (tested integration)