agent

Documentation

Index

• Constants
• Variables
• func Preview(tool string, input map[string]any) string
• type Agent
  • func New(cfg Config) *Agent
  • func (a *Agent) Clear()
  • func (a *Agent) Model() string
  • func (a *Agent) ReplaceTranscript(messages []llm.Message)
  • func (a *Agent) RunTool(ctx context.Context, name string, input map[string]any) (string, bool)
  • func (a *Agent) Send(ctx context.Context, userText string) (string, error)
  • func (a *Agent) SendWith(ctx context.Context, userText string, imagePaths []string) (string, error)
  • func (a *Agent) SetApprover(fn func(context.Context, ApprovalRequest) (bool, error))
  • func (a *Agent) SetEventHandler(fn func(Event))
  • func (a *Agent) SetModel(model string)
  • func (a *Agent) SetPermissionMode(mode string) error
  • func (a *Agent) SetUsage(usage llm.Usage)
  • func (a *Agent) ToolSpecs() []llm.ToolSpec
  • func (a *Agent) Transcript() []llm.Message
  • func (a *Agent) Usage() llm.Usage
• type ApprovalRequest
• type Config
• type Event
• type EventKind

Constants

const DefaultMaxTurns = 500

DefaultMaxTurns is a high safety fuse for runaway tool loops, not a normal work budget. Coding tasks can legitimately need many model/tool cycles; the model should usually stop because it is done, not because Neo reached this.

Variables

var ErrMaxOutputTokens = errors.New("response truncated: model hit its max output tokens limit")

ErrMaxOutputTokens is returned when the model stops because it hit its output-token limit with no tool calls to continue on. Ending the turn (with the partial text) beats silently re-calling the provider until MaxTurns.

var ErrMaxTurns = errors.New("max turns reached")

Functions

func Preview

func Preview(tool string, input map[string]any) string

Types

type Agent

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

func New

func New(cfg Config) *Agent

func (*Agent) Clear

func (a *Agent) Clear()

func (*Agent) Model

func (a *Agent) Model() string

func (*Agent) ReplaceTranscript

func (a *Agent) ReplaceTranscript(messages []llm.Message)

func (*Agent) RunTool

func (a *Agent) RunTool(ctx context.Context, name string, input map[string]any) (string, bool)

RunTool runs a built-in tool directly through the same permission and approval path used for model-requested tool calls. It emits the normal tool call/result events, but does not mutate the LLM transcript.

func (*Agent) Send

func (a *Agent) Send(ctx context.Context, userText string) (string, error)

func (*Agent) SendWith

func (a *Agent) SendWith(ctx context.Context, userText string, imagePaths []string) (string, error)

SendWith sends a user turn that may carry image attachments alongside the text. Images are placed before the text block, which is how vision models expect a "here's an image, now my question" message to be ordered. Paths that can't be read are skipped with an inline note rather than aborting the turn — attachments are best-effort.

func (*Agent) SetApprover

func (a *Agent) SetApprover(fn func(context.Context, ApprovalRequest) (bool, error))

func (*Agent) SetEventHandler

func (a *Agent) SetEventHandler(fn func(Event))

SetEventHandler replaces the event callback. Useful when the consumer (e.g. a Bubble Tea program) isn't constructed until after the agent.

func (*Agent) SetModel

func (a *Agent) SetModel(model string)

func (*Agent) SetPermissionMode

func (a *Agent) SetPermissionMode(mode string) error

func (*Agent) SetUsage

func (a *Agent) SetUsage(usage llm.Usage)

func (*Agent) ToolSpecs

func (a *Agent) ToolSpecs() []llm.ToolSpec

func (*Agent) Transcript

func (a *Agent) Transcript() []llm.Message

func (*Agent) Usage

func (a *Agent) Usage() llm.Usage

type ApprovalRequest

type ApprovalRequest struct {
	ToolName string
	Args     map[string]any
	Reason   string
	Preview  string
}

type Config

type Config struct {
	Model string
	// System is the flattened system prompt. SystemBlocks, when set, carries the
	// same prompt as ordered segments so the provider can place cache breakpoints;
	// the loop passes both so providers can use whichever they support.
	System       string
	SystemBlocks []llm.SystemBlock
	Provider     llm.Provider
	Tools        *tools.Registry
	Policy       permission.Policy
	Compactor    compact.Compactor
	Approve      func(context.Context, ApprovalRequest) (bool, error)
	MaxTurns     int
	OnEvent      func(Event)
	Messages     []llm.Message
	Usage        llm.Usage
}

type Event

type Event struct {
	Kind     EventKind
	Text     string
	Name     string
	Args     map[string]any
	MaxTurns int
	IsError  bool // set on EventToolResult when the tool returned an error
	Err      error
}

type EventKind

type EventKind string

const (
	EventAssistantText   EventKind = "assistant_text"
	EventToolCall        EventKind = "tool_call"
	EventToolResult      EventKind = "tool_result"
	EventDone            EventKind = "done"
	EventError           EventKind = "error"
	EventMaxTurnsReached EventKind = "max_turns_reached"
)