agent

Documentation

Index

• Constants
• Variables
• func Preview(tool string, input map[string]any) string
• type Agent
  • func New(cfg Config) *Agent
  • func (a *Agent) Backend() (string, string)
  • 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) SetBackend(provider llm.Provider, model string, compactor compact.Compactor) error
  • func (a *Agent) SetEventHandler(fn func(Event))
  • func (a *Agent) SetModel(model string)
  • func (a *Agent) SetUsage(usage llm.Usage)
  • func (a *Agent) Steer(text string) bool
  • func (a *Agent) Transcript() []llm.Message
  • func (a *Agent) Usage() llm.Usage
• type ApprovalRequest
• type Config
• type Event
• type EventKind
• type ToolCallRef

Constants

const DefaultMaxParallelTools = 8

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) Backend

func (a *Agent) Backend() (string, string)

Backend returns a consistent provider/model pair for display and session persistence.

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) SetBackend

func (a *Agent) SetBackend(provider llm.Provider, model string, compactor compact.Compactor) error

SetBackend changes the provider, model, and compactor as one unit. Callers switch only between turns, but the lock also keeps diagnostic readers and race-enabled tests from observing a half-switched backend.

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) SetUsage

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

func (*Agent) Steer

func (a *Agent) Steer(text string) bool

Steer adds a user instruction to the active turn. The loop consumes it only after the current provider response and any requested tools have completed, preserving tool_use/tool_result pairing in the transcript.

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
	MaxParallelTools 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
	ToolUseID string
	GroupID   string
	GroupSize int
	GroupPos  int
	Calls     []ToolCallRef
	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"
	EventAssistantCommentary EventKind = "assistant_commentary"
	EventParallelStart       EventKind = "parallel_start"
	EventToolCall            EventKind = "tool_call"
	EventToolResult          EventKind = "tool_result"
	EventSteeringApplied     EventKind = "steering_applied"
	EventDone                EventKind = "done"
	EventError               EventKind = "error"
	EventMaxTurnsReached     EventKind = "max_turns_reached"
)

type ToolCallRef

type ToolCallRef struct {
	ID   string
	Name string
	Args map[string]any
}

ToolCallRef is the ordered, immutable summary announced before a parallel group starts. IDs are provider tool-use IDs and are opaque to consumers.