December 27, 2025 Aixgo Team

Aixgo v0.2.2: Public Interfaces for Library-Style Integration

Introducing the public agent package: build custom agents and integrate Aixgo into existing Go applications with minimal dependencies.

Aixgo v0.2.2 features the new public agent package that enables library-style integration of Aixgo into existing Go applications. This release also includes streaming reliability improvements for the VertexAI provider.

Introducing the Public Agent Package

The agent package is a standalone, minimal-dependency package that exports core interfaces for building custom agents without requiring the full Aixgo framework.

Why This Matters

Until now, using Aixgo meant adopting the full framework. Many teams have existing Go services where they want to add agent-based functionality without a major architectural change.

The public agent package provides:

Minimal Dependencies: Only requires github.com/google/uuid
Clean Interfaces: Agent, Message, and Runtime are all you need
Zero Framework Lock-in: Use what you need, add more later
Production Ready: LocalRuntime implementation for single-process deployments

Quick Example

package main

import (
    "context"
    "fmt"
    "github.com/aixgo-dev/aixgo/agent"
)

type AnalyzerAgent struct {
    name  string
    ready bool
}

func NewAnalyzerAgent(name string) *AnalyzerAgent {
    return &AnalyzerAgent{name: name}
}

func (a *AnalyzerAgent) Name() string { return a.name }
func (a *AnalyzerAgent) Role() string { return "analyzer" }
func (a *AnalyzerAgent) Ready() bool  { return a.ready }

func (a *AnalyzerAgent) Start(ctx context.Context) error {
    a.ready = true
    <-ctx.Done()
    return nil
}

func (a *AnalyzerAgent) Execute(ctx context.Context, input *agent.Message) (*agent.Message, error) {
    var req struct {
        Text string `json:"text"`
    }
    input.UnmarshalPayload(&req)

    return agent.NewMessage("result", map[string]interface{}{
        "length": len(req.Text),
        "status": "analyzed",
    }), nil
}

func (a *AnalyzerAgent) Stop(ctx context.Context) error {
    a.ready = false
    return nil
}

func main() {
    ctx := context.Background()
    rt := agent.NewLocalRuntime()

    rt.Register(NewAnalyzerAgent("analyzer"))
    go rt.Start(ctx)

    input := agent.NewMessage("analyze", map[string]string{"text": "Hello, Aixgo!"})
    response, _ := rt.Call(ctx, "analyzer", input)

    var result map[string]interface{}
    response.UnmarshalPayload(&result)
    fmt.Printf("Result: %v\n", result)

    rt.Stop(ctx)
}

Core Interfaces

Agent Interface

type Agent interface {
    Name() string
    Role() string
    Start(ctx context.Context) error
    Execute(ctx context.Context, input *Message) (*Message, error)
    Stop(ctx context.Context) error
    Ready() bool
}

Runtime Interface

type Runtime interface {
    Register(agent Agent) error
    Call(ctx context.Context, target string, input *Message) (*Message, error)
    CallParallel(ctx context.Context, targets []string, input *Message) (map[string]*Message, map[string]error)
    Send(target string, msg *Message) error
    // ... and more
}

Message Struct

msg := agent.NewMessage("request", payload).
    WithMetadata("correlation_id", "req-123").
    WithMetadata("user_id", "user-456")

When to Use Public Interfaces

Scenario	Recommended Approach
New standalone AI application	Full Aixgo framework
Adding agents to existing microservice	Public agent package
Custom runtime implementation	Public agent package
Need built-in ReAct, Classifier agents	Full Aixgo framework
Minimal dependency footprint required	Public agent package

Integration Patterns

The public package excels at integrating into existing services:

type AgentService struct {
    runtime agent.Runtime
}

func (s *AgentService) HandleRequest(w http.ResponseWriter, r *http.Request) {
    input := agent.NewMessage("process", requestBody).
        WithMetadata("request_id", r.Header.Get("X-Request-ID"))

    response, err := s.runtime.Call(r.Context(), "processor", input)
    // Handle response...
}

VertexAI Streaming Improvements

v0.2.2 continues our focus on production reliability with improvements to the VertexAI provider’s streaming implementation.

What’s Fixed

Cancellable Context: Stream cleanup now properly respects context cancellation
Priority Error Checking: Prevents race conditions in error handling
Improved Close(): Timeout-based channel draining ensures clean shutdown
Goroutine Leak Prevention: Properly terminates goroutines when streams are interrupted

Installation

# Full framework
go get github.com/aixgo-dev/aixgo@v0.2.2

# Just the public interfaces
go get github.com/aixgo-dev/aixgo/agent@v0.2.2

Documentation

Using Public Interfaces Guide: Complete guide to library-style integration
Package README: Detailed API reference in the repository
Integration Examples: Real-world patterns for embedding agents

What’s Next

Additional Public Interfaces: Expanding exportable components based on feedback
Runtime Implementations: Exploring distributed runtime options
Enhanced Testing Utilities: Mocks and test helpers for agent development

Get Involved

GitHub Issues: Report bugs or request features
Discussions: Share your use cases
Contributing: Contribution guide

Get started with library-style agent integration today:

go get github.com/aixgo-dev/aixgo/agent@v0.2.2

release public-api integration library