react

README

react - Simple yet powerful agent framework for Go

• A ReAct agent is a class of AI agent that is capable of advanced tasks through tool calling.
• This package implements a version of a ReAct agent in Go, with a few extra features.

Features

• Backed by the power of jpf: The LLM handling is extremely robust and model-agnostic.
• Easy to create custom tools: To create a tool, you just need to implement a simple interface.
• Built-in dynamic skill retrieval: Named PromptFragment in this package, you can add skills to the agent and they will be intelligently injected into its context when relevant.
• Supports Streaming: You can inject callbacks for both streaming back the text of the final response, and streaming back messages as they are created.
• Clean message abstraction: The agent history is stored as a typed list of messages, differentiated by use. These only get converted into the API messages right before sending to the LLM.

Usage

• Create an agent and ask it a question:

agent := NewCraig(
    modelBuilder,
    WithCraigTools(tool1, tool2),
    WithCraigPersonality("You are an ai assistant"),
    WithCraigFragments(PromptFragment{
        Key: "time_tool",
        When: "The user asks the agent for the time or date",
        Content: "When asked for the time, the agent will respond in HH:MM 24hr format. When asked the date, DD/MM/YYYY.",
    }),
)

response, err := agent.Send("Whats the time")

• Stream the response back to the terminal

type printStreamer struct{}
func (*printStreamer) TrySendTextChunk(chunk string) {fmt.Print(chunk)}

response, err := agent.Send("Write 3 haikus", WithResponseStreamer(&printStreamer{}))
// The response will be printed to the terminal as the API streams it back

• Agents use model builders, which are the method of providing the agent with the llm to use

type ModelBuilder interface {
	AgentModelBuilder
	FragmentSelectorModelBuilder
}

type AgentModelBuilder interface {
	// Build a model for the agent.
	// A struct may be passed as the response type for a json schema, or it may be nil.
	// The stream callbacks may also be nil.
	BuildAgentModel(responseType any, onInitFinalStream func(), onDataFinalStream func(string)) jpf.Model
}

type FragmentSelectorModelBuilder interface {
	// Build a model for a fragment selector.
	// A struct may be passed as the response type for a json schema, or it may be nil.
	BuildFragmentSelectorModel(responseType any) jpf.Model
}

Documentation

Index

• Constants
• func EncodeMessages(w io.Writer, messages []Message) error
• func WithCraigFragments(frags ...PromptFragment) func(kw *craigKwargs)
• func WithCraigPersonality(personality string) func(kw *craigKwargs)
• func WithCraigTools(tools ...Tool) func(kw *craigKwargs)
• type Agent
  • func NewCraig(mb ModelBuilder, opts ...CraigOpt) Agent
  • func NewCraigFromSaved(mb ModelBuilder, messages []Message, opts ...CraigOpt) Agent
• type AgentMessage
• type AgentMode
• type AgentModelBuilder
• type AvailableToolDefinition
• type AvailableToolDefinitionsMessage
• type CraigOpt
• type FragmentSelector
  • func NewFragmentSelector(modelBuilder FragmentSelectorModelBuilder, dontRepeatN int) FragmentSelector
• type FragmentSelectorModelBuilder
• type Message
  • func DecodeMessages(r io.Reader) ([]Message, error)
• type MessageStreamer
• type ModeSwitchMessage
• type ModelBuilder
• type NotificationMessage
• type PromptFragment
  • func (f PromptFragment) IsConditional() bool
• type PromptFragmentMessage
• type SendMessageOpt
  • func WithMessageStreamer(streamer MessageStreamer) SendMessageOpt
  • func WithNotifications(notifications ...NotificationMessage) SendMessageOpt
  • func WithResponseStreamer(streamer TextStreamer) SendMessageOpt
• type SystemMessage
• type TextStreamer
• type Tool
• type ToolCall
• type ToolCallArg
• type ToolCallsMessage
• type ToolResponse
• type ToolResponseMessage
• type UserMessage

Constants

const (
	ModeCollectContext = iota
	ModeReasonAct
	ModeAnswerUser
)

Functions

func EncodeMessages

func EncodeMessages(w io.Writer, messages []Message) error

EncodeMessages into a json format on the writer.

func WithCraigFragments

func WithCraigFragments(frags ...PromptFragment) func(kw *craigKwargs)

func WithCraigPersonality

func WithCraigPersonality(personality string) func(kw *craigKwargs)

func WithCraigTools

func WithCraigTools(tools ...Tool) func(kw *craigKwargs)

Types

type Agent

type Agent interface {
	// Send a message to the agent, getting its response.
	// May pass parameters to stream back messages or the response.
	Send(msg string, opts ...SendMessageOpt) (string, error)
	// Fetch the entire history state of the agent.
	Messages() iter.Seq[Message]
}

Agent defines a Re-Act Agent.

func NewCraig

func NewCraig(mb ModelBuilder, opts ...CraigOpt) Agent

Create a new CRAIG agent with the given tools.

func NewCraigFromSaved

func NewCraigFromSaved(mb ModelBuilder, messages []Message, opts ...CraigOpt) Agent

Create a new CRAIG agent from the given state (from a previous CRAIG agent). The tools provided should match the tools originally provided to NewCraig (in schema).

type AgentMessage

type AgentMessage struct {
	Content string
}

type AgentMode

type AgentMode uint8

type AgentModelBuilder

type AgentModelBuilder interface {
	// Build a model for the agent.
	// A struct may be passed as the response type for a json schema, or it may be nil.
	// The stream callbacks may also be nil.
	BuildAgentModel(responseType any, onInitFinalStream func(), onDataFinalStream func(string)) jpf.Model
}

type AvailableToolDefinition

type AvailableToolDefinition struct {
	Name        string
	Description []string
}

type AvailableToolDefinitionsMessage

type AvailableToolDefinitionsMessage struct {
	Tools []AvailableToolDefinition
}

type CraigOpt

type CraigOpt func(*craigKwargs)

type FragmentSelector

type FragmentSelector interface {
	// Select any relevant fragments that should be added tp the conversation.
	SelectFragments([]PromptFragment, []Message) ([]PromptFragment, error)
}

FragmentSelector defines an object that can choose relevant fragments to a conversation.

func NewFragmentSelector

func NewFragmentSelector(modelBuilder FragmentSelectorModelBuilder, dontRepeatN int) FragmentSelector

type FragmentSelectorModelBuilder

type FragmentSelectorModelBuilder interface {
	// Build a model for a fragment selector.
	// A struct may be passed as the response type for a json schema, or it may be nil.
	BuildFragmentSelectorModel(responseType any) jpf.Model
}

type Message

type Message interface {
	// contains filtered or unexported methods
}

Message is a sum type defining the structured data that can live in agent history.

func DecodeMessages

func DecodeMessages(r io.Reader) ([]Message, error)

DecodeMessages from the json format (from EncodeMessages) on the writer.

type MessageStreamer

type MessageStreamer interface {
	// Try to send a message, ignoring errors.
	TrySendMessage(msg Message)
}

MessageStreamer defines a callback interface that can be used to listen to new messages that the agent creates.

type ModeSwitchMessage

type ModeSwitchMessage struct {
	Mode AgentMode
}

type ModelBuilder

type ModelBuilder interface {
	AgentModelBuilder
	FragmentSelectorModelBuilder
}

type NotificationMessage

type NotificationMessage struct {
	Kind    string
	Content string
}

type PromptFragment

type PromptFragment struct {
	// A sensible snake_case key
	Key string
	// When should this be applied? If empty will always be applied.
	When string
	// The content that is not seen by the selector but is seen by the agent when chosen.
	Content string
}

func (PromptFragment) IsConditional

func (f PromptFragment) IsConditional() bool

type PromptFragmentMessage

type PromptFragmentMessage struct {
	Fragments []PromptFragment
}

type SendMessageOpt

type SendMessageOpt func(*streamers)

func WithMessageStreamer

func WithMessageStreamer(streamer MessageStreamer) SendMessageOpt

In addition to other message streamers, use the provided streamer.

func WithNotifications

func WithNotifications(notifications ...NotificationMessage) SendMessageOpt

func WithResponseStreamer

func WithResponseStreamer(streamer TextStreamer) SendMessageOpt

In addition to other response streamers, use the provided streamer.

type SystemMessage

type SystemMessage struct {
	Content string
}

type TextStreamer

type TextStreamer interface {
	// Try to send a response text chunk back, ignoring errors.
	TrySendTextChunk(chunk string)
}

TextStreamer defines a callback interface that can be used to listen to text being streamed back from the final agent response.

type Tool

type Tool interface {
	// The name of the tool to be used by the agent. Should probably be snake_case.
	Name() string
	// Describe the tool in short bullet points to the agent.
	// Includes which parameters to provide.
	// Parameters can be described as any json type.
	Description() []string
	// Call the tool, providing a formatted response or an error if the tool call failed.
	// The values of the args will be the direct result of json decoding the tool call args.
	Call(map[string]any) (string, error)
}

Tool is a runnable object that can be both described to and called by an agent.

type ToolCall

type ToolCall struct {
	ToolName string
	ToolArgs []ToolCallArg
}

type ToolCallArg

type ToolCallArg struct {
	ArgName  string
	ArgValue any
}

type ToolCallsMessage

type ToolCallsMessage struct {
	Reasoning string
	ToolCalls []ToolCall
}

type ToolResponse

type ToolResponse struct {
	Response string
}

type ToolResponseMessage

type ToolResponseMessage struct {
	Responses []ToolResponse
}

type UserMessage

type UserMessage struct {
	Content string
}