bubo

README

🦉 Bubo: A Framework for Building AI Agents

Bubo is a Go framework for creating and orchestrating AI agents, with first-class support for OpenAI's GPT models and function calling capabilities.

🌟 Overview

Bubo provides a robust foundation for building AI agents that can:

• Execute tools and functions
• Handle streaming responses
• Process multi-modal inputs (text, images, audio)
• Manage complex conversation threads
• Run parallel tool executions

✨ Key Features

• 🛠 Flexible Agent System

  • Define custom agents with specific tools and capabilities
  • Configure model parameters and instructions
  • Support for parallel tool execution

• 🔌 OpenAI Integration

  • First-class support for OpenAI's chat models
  • Streaming support for real-time responses
  • Function calling capabilities
  • Multi-modal content handling (text, images, audio)

• 📝 Rich Message Handling

  • Support for various message types (user, assistant, tool calls)
  • Structured content parts for different media types
  • Thread management for complex conversations

• 🔧 Tool System

  • Define custom tools with JSON schema validation
  • Support for parallel tool execution
  • Structured tool responses and error handling

• 📊 Observability

  • Detailed logging with zerolog integration
  • Stream events for real-time monitoring
  • Error tracking and handling

🚀 Getting Started

package main

import (
  "github.com/casualjim/bubo"
  "github.com/openai/openai-go"
)

func main() {
  // Create a new agent
  agent := bubo.NewAgent(
    "my-agent",
    string(openai.ChatModelGPT4),
    "Your agent instructions here",
  )

  // Add tools
  agent.AddTool(bubo.AgentToolDefinition{
    Name: "my-tool",
    Function: &bubo.FunctionDefinition{
      // Define your tool's schema and behavior
    },
  })

  // Configure parallel tool execution
  agent.EnableParallelToolCalls()
}

📦 Installation

go get github.com/casualjim/bubo

🛠 Requirements

• Go 1.23.3 or higher
• OpenAI API key for AI capabilities

📝 License

This project is licensed under the terms specified in the LICENSE file.

Documentation

Index

• Variables
• func WithToolParameters(parameters ...string) opts.Option[AgentToolDefinition]
• type Agent
• type AgentToolDefinition
  • func AgentTool(f any, options ...AgentToolOption) (AgentToolDefinition, error)
  • func MustAgentTool(f any, options ...AgentToolOption) AgentToolDefinition
• type AgentToolOption
• type DefaultAgent
  • func NewAgent(name string, model Model, instructions string) *DefaultAgent
  • func (a *DefaultAgent) AddTool(f1 AgentToolDefinition, frest ...AgentToolDefinition)
  • func (a *DefaultAgent) DisableParallelToolCalls()
  • func (a *DefaultAgent) EnableParallelToolCalls()
  • func (a *DefaultAgent) Instructions() string
  • func (a *DefaultAgent) Model() Model
  • func (a *DefaultAgent) Name() string
  • func (a *DefaultAgent) ParallelToolCalls() bool
  • func (a *DefaultAgent) RenderInstructions(cv types.ContextVars) (string, error)
  • func (a *DefaultAgent) SetToolChoice(toolChoice string)
  • func (a *DefaultAgent) ToolChoice() string
  • func (a *DefaultAgent) Tools() []AgentToolDefinition
  • func (a *DefaultAgent) WithParallelToolCalls() *DefaultAgent
  • func (a *DefaultAgent) WithTool(f1 AgentToolDefinition, frest ...AgentToolDefinition) *DefaultAgent
  • func (a *DefaultAgent) WithToolChoice(toolChoice string) *DefaultAgent
  • func (a *DefaultAgent) WithoutParallelToolCalls() *DefaultAgent
• type Model

Variables

var WithToolDescription = opts.ForName[AgentToolDefinition, string]("Description")

WithToolDescription returns a function that sets the description of an agent function. It takes a string parameter 'description' and returns a function that modifies the 'Description' field of the provided 'agentFunctionOptions' struct.

var WithToolName = opts.ForName[AgentToolDefinition, string]("Name")

WithToolName returns a function that sets the Name field of agentFunctionOptions to the provided name. This can be used to configure an agent function with a specific name.

Parameters:

• name: A string representing the name to be assigned.

Returns:

• A function that takes a pointer to agentFunctionOptions and sets its Name field.

Functions

func WithToolParameters

func WithToolParameters(parameters ...string) opts.Option[AgentToolDefinition]

WithToolParameters returns a function that sets the Parameters field of agentFunctionOptions to a map where each parameter is assigned a key in the format "paramN", where N is the index of the parameter in the input slice.

Parameters:

parameters - a variadic string slice containing the parameters to be set.

Returns:

A function that takes a pointer to agentFunctionOptions and sets its Parameters field.

Types

type Agent

type Agent interface {
	// Name returns the agent's name
	Name() string

	// Model returns the agent's model
	Model() Model

	// Instructions returns the agent's instructions
	Instructions() string

	// Tools returns the agent's function definitions
	Tools() []AgentToolDefinition

	// ToolChoice returns the agent's tool choice
	ToolChoice() string

	// ParallelToolCalls returns whether the agent supports parallel tool calls
	ParallelToolCalls() bool

	// RenderInstructions renders the agent's instructions with the provided context variables.
	RenderInstructions(types.ContextVars) (string, error)
}

Agent represents an interface for an agent with various capabilities. It provides methods to retrieve the agent's name, model, instructions, function definitions, tool choice, and whether it supports parallel tool calls. available functions, tool choice, and whether parallel tool calls are supported.

type AgentToolDefinition

type AgentToolDefinition struct {
	Name        string
	Description string
	Parameters  map[string]string
	Function    any
}

AgentToolDefinition represents the definition of an agent function. It includes the function's name, description, parameters, and the function itself.

func AgentTool

func AgentTool(f any, options ...AgentToolOption) (AgentToolDefinition, error)

AgentTool creates an AgentToolDefinition from the provided function and options. The function is assigned to the Function field of the resulting AgentToolDefinition.

Parameters:

• f: The function to be assigned to the AgentToolDefinition.
• options: A variadic list of AgentToolOption to configure the AgentToolDefinition.

Returns:

An AgentToolDefinition with the provided function and applied options.

func MustAgentTool

func MustAgentTool(f any, options ...AgentToolOption) AgentToolDefinition

MustAgentTool wraps the AgentTool call and ensures that any error returned by AgentTool is handled by panicking. It takes a function `f` and a variadic number of AgentToolOption `options` as arguments, and returns an AgentToolDefinition. If AgentTool returns an error, MustAgentTool will panic.

Parameters:

• f: The function to be wrapped.
• options: A variadic number of options to configure the agent tool.

Returns:

• AgentToolDefinition: The definition of the agent tool.

type AgentToolOption

type AgentToolOption = opts.Option[AgentToolDefinition]

AgentToolOption is a type alias for a function that modifies the configuration options of an agent tool. It allows for flexible and customizable configuration of agent tools by applying various options.

type DefaultAgent

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

DefaultAgent represents an agent with specific attributes and capabilities. It includes the agent's name, model, instructions, function definitions, tool choice, and whether it supports parallel tool calls.

func NewAgent

func NewAgent(name string, model Model, instructions string) *DefaultAgent

NewAgent creates a new DefaultAgent with the provided parameters.

func (*DefaultAgent) AddTool

func (a *DefaultAgent) AddTool(f1 AgentToolDefinition, frest ...AgentToolDefinition)

AddTool adds a function definition to the agent.

func (*DefaultAgent) DisableParallelToolCalls

func (a *DefaultAgent) DisableParallelToolCalls()

DisableParallelToolCalls disables parallel tool calls for the agent.

func (*DefaultAgent) EnableParallelToolCalls

func (a *DefaultAgent) EnableParallelToolCalls()

EnableParallelToolCalls enables parallel tool calls for the agent.

func (*DefaultAgent) Instructions

func (a *DefaultAgent) Instructions() string

Instructions returns the agent's instructions.

func (*DefaultAgent) Model

func (a *DefaultAgent) Model() Model

Model returns the agent's model.

func (*DefaultAgent) Name

func (a *DefaultAgent) Name() string

Name returns the agent's name.

func (*DefaultAgent) ParallelToolCalls

func (a *DefaultAgent) ParallelToolCalls() bool

ParallelToolCalls returns whether the agent supports parallel tool calls.

func (*DefaultAgent) RenderInstructions

func (a *DefaultAgent) RenderInstructions(cv types.ContextVars) (string, error)

RenderInstructions renders the agent's instructions with the provided context variables.

func (*DefaultAgent) SetToolChoice

func (a *DefaultAgent) SetToolChoice(toolChoice string)

SetToolChoice sets the agent's tool choice.

func (*DefaultAgent) ToolChoice

func (a *DefaultAgent) ToolChoice() string

ToolChoice returns the agent's tool choice.

func (*DefaultAgent) Tools

func (a *DefaultAgent) Tools() []AgentToolDefinition

Tools returns the agent's function definitions.

func (*DefaultAgent) WithParallelToolCalls

func (a *DefaultAgent) WithParallelToolCalls() *DefaultAgent

WithParallelToolCalls enables parallel tool calls for the agent.

func (*DefaultAgent) WithTool

func (a *DefaultAgent) WithTool(f1 AgentToolDefinition, frest ...AgentToolDefinition) *DefaultAgent

WithTool adds a function definition to the agent.

func (*DefaultAgent) WithToolChoice

func (a *DefaultAgent) WithToolChoice(toolChoice string) *DefaultAgent

WithToolChoice sets the agent's tool choice.

func (*DefaultAgent) WithoutParallelToolCalls

func (a *DefaultAgent) WithoutParallelToolCalls() *DefaultAgent

WithoutParallelToolCalls disables parallel tool calls for the agent.

type Model

type Model interface {
	Name() string
	Provider() provider.Provider
}