aixgo

aixgo

Production-grade AI agent framework for Go. Build secure, scalable multi-agent systems without Python dependencies.

Documentation | Quick Start | Examples | Contributing

Features

Core Architecture

• Single Binary Deployment: Ship AI agents in <10MB binaries with zero runtime dependencies
• Type-Safe Agent Architecture: Compile-time error detection with Go's type system
• Seamless Scaling: Start local with Go channels, scale to distributed with gRPC—no code changes
• Runtime Systems: Local (in-process) and Distributed (gRPC) runtimes with identical APIs

Agent Orchestration

• Multi-Pattern Orchestration: 13 production-proven patterns (Supervisor, Sequential, Parallel, Router, Swarm, Hierarchical, RAG, Reflection, Ensemble, Classifier, Aggregation, Planning, MapReduce)
• Intelligent Routing: Router pattern for cost optimization (25-50% savings)
• Parallel Execution: 3-4× speedup for independent tasks
• RAG Pattern: Retrieval-Augmented Generation with vector store integration
• Quality Improvement: Reflection and Ensemble patterns for higher accuracy

Agent Types

• ReAct Agents: Reasoning and acting with LLM integration and tool calling
• Classifier Agents: AI-powered content classification with confidence scoring
• Aggregator Agents: Multi-agent synthesis with consensus, weighted, semantic, and hierarchical strategies
• Planner Agents: Task decomposition and planning
• Producer/Logger Agents: Data generation and logging

LLM & AI Integration

• Multi-Provider Support: OpenAI, Anthropic (Claude), xAI (Grok), Google (Gemini), HuggingFace
• Pydantic AI-Style Validation Retry: Automatic retry with validation errors for 40-70% improved structured output reliability
• MCP Integration: Model Context Protocol for tool calling (local, gRPC, multi-server)
• Vector Stores: Firestore, in-memory (Qdrant, pgvector, ChromaDB planned)
• Embeddings: OpenAI, HuggingFace models for semantic memory
• Semantic Memory: Long-term knowledge storage with vector search

Observability & Production

• Automatic Cost Tracking: Every LLM call tracked with token and cost metrics
• OpenTelemetry Integration: Distributed tracing and monitoring
• Langfuse Support: LLM-specific observability and analytics
• Health Checks: Liveness, readiness, and detailed health endpoints
• Prometheus Metrics: HTTP, gRPC, agent, and system metrics

Quick Start

Installation

go get github.com/aixgo-dev/aixgo

Setup

Before running your agents, you need to configure API keys for LLM providers. Create a .env file in your project root (or set environment variables):

# Copy the example environment file
cp .env.example .env

# Edit .env and add your API keys
# Required: At least one of these API keys
export OPENAI_API_KEY=sk-...        # For GPT models
export XAI_API_KEY=xai-...          # For Grok models
export ANTHROPIC_API_KEY=sk-ant-... # For Claude models (optional)
export HUGGINGFACE_API_KEY=hf_...  # For HuggingFace models (optional)

The framework will automatically detect the appropriate API key based on your model name:

• grok-* or xai-* models use XAI_API_KEY
• gpt-* models use OPENAI_API_KEY
• claude-* models use ANTHROPIC_API_KEY
• HuggingFace models (e.g., meta-llama/*) use HUGGINGFACE_API_KEY

Your First Agent

Create a simple multi-agent system in under 5 minutes:

1. Create a configuration file (config/agents.yaml):

supervisor:
  name: coordinator
  model: gpt-4-turbo
  max_rounds: 10

agents:
  - name: data-producer
    role: producer
    interval: 1s
    outputs:
      - target: analyzer

  - name: analyzer
    role: react
    model: gpt-4-turbo
    prompt: |
      You are a data analyst. Analyze incoming data and provide insights.
    inputs:
      - source: data-producer
    outputs:
      - target: logger

  - name: logger
    role: logger
    inputs:
      - source: analyzer

2. Create your main.go:

package main

import (
    "github.com/aixgo-dev/aixgo"
    _ "github.com/aixgo-dev/aixgo/agents"
)

func main() {
    if err := aixgo.Run("config/agents.yaml"); err != nil {
        panic(err)
    }
}

3. Run your agent system:

go run main.go

That's it! You now have a running multi-agent system with producer, analyzer, and logger agents orchestrated by a supervisor.

Documentation & Resources

Comprehensive documentation, guides, and examples are available at aixgo.dev:

📚 Guides

• Core Concepts - Agent types, orchestration patterns, and architecture
• Multi-Agent Orchestration - Supervisor patterns and workflows
• Security Best Practices - Production security configurations
• Production Deployment - Docker, Kubernetes, and Cloud Run

🎯 Examples

Browse 29+ complete, production-ready configuration examples:

• Agent Types - Producer, ReAct, Logger, Classifier, Aggregator, Planner
  • Classifier Workflow - AI-powered ticket classification with confidence scoring
  • Aggregator Workflow - Multi-agent synthesis with consensus and semantic strategies
• LLM Providers - OpenAI, Anthropic, Gemini, Vertex AI, xAI, HuggingFace
• Structured Output - Type-safe LLM responses with validation
  • Pydantic-Style Validation - Automatic retry with validation errors for reliable structured data extraction
• MCP Integration - Local transport, gRPC, multi-server setups
• Security - Authentication, authorization, TLS configurations
• Orchestration - MapReduce, parallel, sequential, reflection patterns
• Use Cases - Complete end-to-end applications

🚀 Quick Links

• API Reference - Full Go package documentation
• Release Notes - Track feature development and roadmap
• GitHub Discussions - Ask questions and share ideas

Why Aixgo?

Production-First Design

Python AI frameworks excel at prototyping but struggle in production. Aixgo is built for systems that ship, scale, and stay running.

Use Cases

• Data Pipelines: Add AI enrichment to high-throughput ETL workflows
• API Services: Production AI endpoints with Go's performance characteristics
• Edge Deployment: Run AI agents on resource-constrained devices
• Multi-Agent Systems: Coordinate complex workflows with supervisor patterns
• Distributed Systems: Scale from single instance to multi-region with zero refactoring

Architecture

Aixgo implements a unified orchestration architecture supporting multiple patterns for building production AI agent systems.

Orchestration Patterns

13 production-proven patterns for different use cases:

• Supervisor: Centralized orchestration with specialized agent routing
• Sequential: Ordered pipeline execution (extract → transform → load)
• Parallel: Concurrent execution with 3-4× speedup
• Router: Intelligent routing for 25-50% cost optimization
• Swarm: Decentralized agent handoffs (inspired by OpenAI Swarm)
• Hierarchical: Multi-level delegation for complex workflows
• RAG: Retrieval-Augmented Generation with vector stores
• Reflection: Iterative refinement for quality improvement
• Ensemble: Multi-model voting for high-accuracy decisions

See docs/PATTERNS.md for detailed pattern catalog.

Agent Types

• ReAct: Reasoning + Acting agents powered by LLMs with tool calling
• Classifier: LLM-powered content classification with confidence scoring
• Aggregator: Multi-agent output synthesis using consensus, weighted, semantic, or hierarchical strategies
• Planner: Task decomposition and strategic planning
• Producer: Generates messages at configured intervals
• Logger: Consumes and logs messages from other agents

Runtime Systems

Agents communicate through a runtime abstraction layer:

• Local Runtime: Go channels for in-process communication (single binary deployment)
• Distributed Runtime: gRPC for multi-node orchestration (distributed deployment)
• Deployment Flexibility: Same code runs on both - deployment is just configuration

Agent Roles

Producer Agent

Generates periodic messages for downstream agents:

agents:
  - name: event-generator
    role: producer
    interval: 500ms
    outputs:
      - target: processor

ReAct Agent

LLM-powered agent with reasoning and tool calling:

agents:
  - name: analyst
    role: react
    model: gpt-4-turbo
    prompt: 'You are an expert data analyst.'
    tools:
      - name: query_database
        description: 'Query the database'
        input_schema:
          type: object
          properties:
            query: { type: string }
          required: [query]
    inputs:
      - source: event-generator
    outputs:
      - target: logger

Logger Agent

Consumes and logs messages:

agents:
  - name: audit-log
    role: logger
    inputs:
      - source: analyst

Classifier Agent

LLM-powered content classification with structured outputs and confidence scoring:

agents:
  - name: ticket-classifier
    role: classifier
    model: gpt-4-turbo
    inputs:
      - source: support-tickets
    outputs:
      - target: classified-tickets
    classifier_config:
      categories:
        - name: technical_issue
          description: "Issues requiring technical troubleshooting"
          keywords: ["error", "bug", "crash"]
        - name: billing_inquiry
          description: "Questions about payments or invoices"
          keywords: ["payment", "charge", "refund"]
      confidence_threshold: 0.7
      temperature: 0.3

Aggregator Agent

Synthesizes outputs from multiple agents using intelligent strategies:

agents:
  - name: research-synthesizer
    role: aggregator
    model: gpt-4-turbo
    inputs:
      - source: expert-1
      - source: expert-2
      - source: expert-3
    outputs:
      - target: final-report
    aggregator_config:
      aggregation_strategy: consensus  # or weighted, semantic, hierarchical, rag_based
      consensus_threshold: 0.75
      conflict_resolution: llm_mediated
      timeout_ms: 5000

Configuration

Aixgo uses YAML-based declarative configuration:

supervisor:
  name: string # Supervisor identifier
  model: string # LLM model to use
  max_rounds: int # Maximum execution rounds

agents:
  - name: string # Unique agent name
    role: string # producer | react | logger
    interval: duration # For producer agents
    model: string # For react agents
    prompt: string # System prompt for react agents
    tools: [] # Tool definitions for react agents
    inputs: [] # Input sources
    outputs: [] # Output targets

Observability

Aixgo includes built-in OpenTelemetry support for production observability:

• Distributed Tracing: Track messages across multi-agent workflows
• Structured Logging: Context-aware logs with trace correlation
• Metrics Export: Agent performance and health metrics
• Integration Ready: Works with Grafana, Datadog, Langfuse, and more

Development

Building from Source

git clone https://github.com/aixgo-dev/aixgo.git
cd aixgo
go build ./...

Running Tests

# Run all tests
go test ./...

# With race detection
go test -race ./...

# With coverage
go test -cover ./...

Project Structure

aixgo/
├── agents/           # Agent implementations (Producer, ReAct, Logger)
├── config/           # Example configurations
├── docs/             # Documentation
├── examples/         # Example applications
├── internal/
│   ├── agent/        # Agent core types and factory
│   ├── llm/          # LLM integration and validation
│   ├── observability/# OpenTelemetry integration
│   └── supervisor/   # Supervisor implementation
├── proto/            # Message protocol definitions
├── aixgo.go          # Main entry point and config loader
└── runtime.go        # Message runtime and communication layer

Roadmap

See our GitHub Project Board for the latest roadmap, feature development, and priorities.

Documentation

For comprehensive documentation, visit https://aixgo.dev.

Repository Documentation:

• Pattern Catalog - 13 orchestration patterns with examples
• Deployment Guide - Deploy to Cloud Run, Kubernetes, or local
• Observability Guide - OpenTelemetry and cost tracking
• Testing Guide - Testing strategies
• Contributing Guide - How to contribute
• API Reference - GoDoc documentation

Security

• Authentication Guide - Configure auth modes for different deployments
• Security Best Practices - Secure development guidelines
• Production Security Checklist - Pre-deployment requirements

Authentication Configuration

Aixgo supports flexible authentication modes for different deployment scenarios:

Quick Examples

Local Development (no auth):

environment: development
auth_mode: disabled

Cloud Run with IAP:

environment: production
auth_mode: delegated
delegated_auth:
  identity_header: X-Goog-Authenticated-User-Email
  iap:
    enabled: true

Self-hosted with API Keys:

environment: production
auth_mode: builtin
builtin_auth:
  method: api_key
  api_keys:
    source: environment
    env_prefix: AIXGO_API_KEY_

See Authentication Guide for complete documentation and examples/ for full configuration files.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Key areas we're looking for help:

• Additional agent implementations
• LLM provider integrations
• Documentation improvements
• Example applications
• Performance optimizations

License

MIT License - see LICENSE for details.

Community

• GitHub Discussions - Ask questions, share ideas
• Issues - Report bugs, request features

Why Go for AI Agents?

"Where Python prototypes go to die in production, Go agents ship and scale."

Python excels at AI research and prototyping. Go excels at production systems. Aixgo bridges the gap:

• Performance: Compiled binaries with true concurrency, no GIL
• Simplicity: Single binary deployment, no dependency management
• Security: Minimal attack surface, static linking, memory safety
• Scalability: Native support for distributed systems
• Maintainability: Type safety catches errors before production

Build AI agents that ship with the same performance, security, and operational simplicity as the rest of your Go stack.

Production-grade AI agents in pure Go.