agent

Documentation

Overview

Package agent implements the agent loop: prompt assembly, model calls, tool iteration, and reply.

Index

• Constants
• type Agent
  • func New(opts Options) (*Agent, error)
  • func (a *Agent) Cancel(sessionID string) bool
  • func (a *Agent) Handle(ctx context.Context, msg channel.Message) (string, error)
  • func (a *Agent) SetPersona(text string)
• type History
• type Options
• type Tools

Constants

const (
	ToolTraceFull    = "full"    // → name / ✓ timing · chars
	ToolTraceCompact = "compact" // Making Calls: ✓, ✗, ✓ (default)
	ToolTraceOff     = "off"     // hide tool activity
)

Tool-trace modes for user-visible progress (see TOOL_TRACE).

const AuthGuideURL = "https://github.com/shotah/ai-gantry/blob/main/docs/auth.md"

AuthGuideURL is linked from /auth replies when the operator needs the full guide.

const DefaultCoalesceSettle = 2 * time.Second

DefaultCoalesceSettle is how long to wait after the last inbound bubble before running one joined turn (interrupt + coalesce + settle).

Types

type Agent

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

Agent runs the prompt → model → (tools) → reply loop.

func New

func New(opts Options) (*Agent, error)

New creates an Agent. Completer and Sessions are required.

func (*Agent) Cancel

func (a *Agent) Cancel(sessionID string) bool

Cancel interrupts an in-flight turn for sessionID. Returns false when idle. Safe to call from another Handle (/cancel) while the turn is running.

func (*Agent) Handle

func (a *Agent) Handle(ctx context.Context, msg channel.Message) (string, error)

Handle is a channel.Handler: assemble prompt, call model (with tools), return reply.

func (*Agent) SetPersona

func (a *Agent) SetPersona(text string)

SetPersona replaces the system persona text (e.g. after SIGHUP reload). When memory is enabled, the persona-precedence note is appended.

type History

type History interface {
	Messages(ctx context.Context, sessionID string) ([]session.Message, error)
	Append(ctx context.Context, sessionID string, msgs ...session.Message) error
	Reset(ctx context.Context, sessionID string) error
	Stats(ctx context.Context, sessionID string) (messages int, estTokens int, err error)
	Summary(ctx context.Context, sessionID string) (string, error)
}

History is the session-backed conversation store used by the agent.

type Options

type Options struct {
	Persona       string
	Completer     provider.Completer
	Sessions      History
	Tools         Tools         // optional
	Memory        memory.Memory // optional; hydration + persona precedence note
	Model         string
	MaxToolIters  int
	StreamReplies bool // stream final text via channel.ReplyWriter when Completer is a Streamer
	// ToolTrace is full|compact|off. Empty defaults to compact.
	ToolTrace string
	Logger    *slog.Logger
	StartedAt time.Time
	// Location is the operator timezone for the per-turn temporal anchor (CRON_TZ).
	Location *time.Location
	TZName   string // IANA name for display (e.g. America/Los_Angeles)
	// CoalesceSettle waits this long after the last bubble before running a
	// joined turn (interrupt + coalesce). 0 disables. Production default is
	// DefaultCoalesceSettle via run config.
	CoalesceSettle time.Duration
	// SpinupNotice posts a "still working" line once a turn has gone this long
	// without model output. The first turn of the process posts immediately
	// instead of waiting. 0 disables both notices.
	SpinupNotice time.Duration
	// Consolidator is optional; /memstats reads last_run from it when set.
	Consolidator *memory.Consolidator
	// MCPManifest is the path to mcp.toml for /auth (chat OAuth). Empty disables /auth.
	MCPManifest string
}

Options configures the agent.

type Tools

type Tools interface {
	Tools() []provider.ToolDef
	Call(ctx context.Context, name string, arguments json.RawMessage) (string, error)
	ToolCount() int
}

Tools executes MCP (or other) tools during the agent loop.