agency

README

Agency: The Go Way to AI

Library designed for developers eager to explore the potential of Large Language Models (LLMs) and other generative AI through a clean, effective, and Go-idiomatic approach.

Welcome to the agency! 🕵️‍♂️

💻 Quick Start

Install package:

go get github.com/neurocult/agency

Chat example:

package main

import (
	"bufio"
	"context"
	"fmt"
	"os"

	_ "github.com/joho/godotenv/autoload"

	"github.com/neurocult/agency"
	"github.com/neurocult/agency/providers/openai"
)

func main() {
	assistant := openai.
		New(openai.Params{Key: os.Getenv("OPENAI_API_KEY")}).
		TextToText(openai.TextToTextParams{Model: "gpt-4o-mini"}).
		SetPrompt("You are helpful assistant.")

	messages := []agency.Message{}
	reader := bufio.NewReader(os.Stdin)
	ctx := context.Background()

	for {
		fmt.Print("User: ")

		text, err := reader.ReadString('\n')
		if err != nil {
			panic(err)
		}

		input := agency.UserMessage(text)
		answer, err := assistant.SetMessages(messages).Execute(ctx, input)
		if err != nil {
			panic(err)
		}

		fmt.Println("Assistant: ", answer)

		messages = append(messages, input, answer)
	}
}

That's it!

See examples to find out more complex usecases including RAGs and multimodal operations.

🚀 Features

✨ Pure Go: fast and lightweight, statically typed, no need to mess with Python or JavaScript

✨ Write clean code and follow clean architecture by separating business logic from concrete implementations

✨ Easily create custom operations by implementing simple interface

✨ Compose operations together into processes with the ability to observe each step via interceptors

✨ OpenAI API bindings (can be used for any openai-compatable API: text to text (completion), text to image, text to speech, speech to text

🤔 Why need Agency?

At the heart of Agency is the ambition to empower users to build autonomous agents. While perfect for all range of generative AI applications, from chat interfaces to complex data analysis, our library's ultimate goal is to simplify the creation of autonomous AI systems. Whether you're building individual assistant or coordinating agent swarms, Agency provides the tools and flexibility needed to bring these advanced concepts to life with ease and efficiency.

In the generative AI landscape, Go-based libraries are rare. The most notable is LangChainGo, a Go port of the Python LangChain. However, translating Python to Go can be clunky and may not fit well with Go's idiomatic style. Plus, some question LangChain's design, even in Python. This situation reveals a clear need for an idiomatic Go alternative.

Our goal is to fill this gap with a Go-centric library that emphasizes clean, simple code and avoids unnecessary complexities. Agency is designed with a small, robust core, easy to extend and perfectly suited to Go's strengths in static typing and performance. It's our answer to the lack of Go-native solutions in generative AI.

Tutorial

• Part 1 (Russian translation)

🛣 Roadmap

In the next versions:

• Support for external function calls
• Metadata (tokens used, audio duration, etc)
• More provider-adapters, not only openai
• Image to text operations
• Powerful API for autonomous agents
• Tagging and JSON output parser

Documentation

Index

• type BaseMessage
  • func NewJsonMessage(role Role, content any) (BaseMessage, error)
  • func NewMessage(role Role, kind Kind, content []byte) BaseMessage
  • func NewTextMessage(role Role, content string) BaseMessage
  • func (bm BaseMessage) Content() []byte
  • func (bm BaseMessage) Kind() Kind
  • func (bm BaseMessage) Role() Role
• type Interceptor
• type Kind
• type Message
• type Operation
  • func NewOperation(handler OperationHandler) *Operation
  • func (p *Operation) Config() *OperationConfig
  • func (p *Operation) Execute(ctx context.Context, input Message) (Message, error)
  • func (p *Operation) SetMessages(msgs []Message) *Operation
  • func (p *Operation) SetPrompt(prompt string, args ...any) *Operation
• type OperationConfig
• type OperationHandler
• type Process
  • func NewProcess(operations ...*Operation) *Process
  • func (p *Process) Execute(ctx context.Context, input Message, interceptors ...Interceptor) (Message, error)
• type Role

Types

type BaseMessage

type BaseMessage struct {
	// contains filtered or unexported fields
}

func NewJsonMessage

func NewJsonMessage(role Role, content any) (BaseMessage, error)

NewJsonMessage marshals content and creates new `Message` with text kind and the specified `Role`

func NewMessage

func NewMessage(role Role, kind Kind, content []byte) BaseMessage

NewMessage creates new `Message` with the specified `Role` and `Kind`

func NewTextMessage

func NewTextMessage(role Role, content string) BaseMessage

NewTextMessage creates new `Message` with Text kind and the specified `Role`

func (BaseMessage) Content

func (bm BaseMessage) Content() []byte

func (BaseMessage) Kind

func (bm BaseMessage) Kind() Kind

func (BaseMessage) Role

func (bm BaseMessage) Role() Role

type Interceptor

type Interceptor func(in Message, out Message, cfg *OperationConfig)

Interceptor is a function that is called by Process after one operation finished but before next one is started.

type Kind

type Kind string

const (
	TextKind      Kind = "text"
	ImageKind     Kind = "image"
	VoiceKind     Kind = "voice"
	EmbeddingKind Kind = "embedding"
)

type Message

type Message interface {
	Role() Role
	Content() []byte
	Kind() Kind
}

type Operation

type Operation struct {
	// contains filtered or unexported fields
}

Operation is basic building block.

func NewOperation

func NewOperation(handler OperationHandler) *Operation

NewOperation allows to create an operation from a function.

func (*Operation) Config

func (p *Operation) Config() *OperationConfig

func (*Operation) Execute

func (p *Operation) Execute(ctx context.Context, input Message) (Message, error)

Execute executes operation handler with input message and current configuration.

func (*Operation) SetMessages

func (p *Operation) SetMessages(msgs []Message) *Operation

func (*Operation) SetPrompt

func (p *Operation) SetPrompt(prompt string, args ...any) *Operation

type OperationConfig

type OperationConfig struct {
	Prompt   string
	Messages []Message
}

OperationConfig represents abstract operation configuration for all possible models.

type OperationHandler

type OperationHandler func(context.Context, Message, *OperationConfig) (Message, error)

OperationHandler is a function that implements operation's logic. It could be thought of as an interface that providers must implement.

type Process

type Process struct {
	// contains filtered or unexported fields
}

Process is a chain of operations that can be executed in sequence.

func NewProcess

func NewProcess(operations ...*Operation) *Process

NewProcess creates a new Process with given operations.

func (*Process) Execute

func (p *Process) Execute(ctx context.Context, input Message, interceptors ...Interceptor) (Message, error)

Execute iterates over Process's operations and sequentially executes them. After first operation is executed it uses its output as an input to the second one and so on until the whole chain is finished. It also executes all given interceptors, if they are provided, so for every N operations and M interceptors it's N x M executions.

type Role

type Role string

const (
	UserRole      Role = "user"
	SystemRole    Role = "system"
	AssistantRole Role = "assistant"
	ToolRole      Role = "tool"
)