Help us shape the future of Go! Take the 2026 Go Developer Survey

callbacks

package
v0.21.168 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 16, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package callbacks provides implementations of the assistant and tool callback interfaces for tracing, logging and per-run accounting.

A handler is attached with assistants.WithCallback and receives every assistant, LLM and tool event. The handler is propagated into nested assistants invoked through assistants.AssistantTool, so one handler observes a whole multi-agent run.

Handlers are invoked from the parallel tool-call goroutines, so every implementation must be safe for concurrent use. All handlers in this package lock internally.

Handlers

  • Noop does nothing; use it as an embedded base for custom handlers, or with WithProgress for progress reporting only.
  • Printer writes a human-readable trace to an io.Writer.
  • PackageLogger emits structured xlog key/value entries.
  • Fanout forwards every event to several handlers.
  • Scratchpad accumulates a transcript and RunStats per run.

Example: trace a run to stdout 

agent := assistants.NewAssistant[Answer](fac, sysPrompt,
    assistants.WithCallback(callbacks.NewPrinter(os.Stdout, callbacks.ModeVerbose)),
)

Example: collect a per-run report 

pad := callbacks.NewScratchpad(callbacks.ModeVerbose)
agent := assistants.NewAssistant[Answer](fac, sysPrompt,
    assistants.WithCallback(pad))

pad.StartRun(ctx) // requires a chatmodel.ChatContext on ctx
_, err := agent.Run(ctx, input, &out)
stats, transcript := pad.EndRun(ctx)

Scratchpad accumulates token usage at the LLM-call boundary rather than in OnAssistantEnd, because Response.Usage is already the aggregated subtree total and would otherwise be counted twice for nested assistants.

Index

Constants

This section is empty.

Variables

View Source 
var TimeNowFn = time.Now

TimeNowFn is the clock used for run timing. Override it in tests for deterministic durations.

Functions

func IsTimeout added in v0.14.89 

func IsTimeout(err error) bool

IsTimeout returns true for timeout error

Types

type Fanout 

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

Fanout is a callback handler that forwards the events to multiple callbacks.

func NewFanout 

func NewFanout(callbacks ...assistants.Callback) *Fanout

NewFanout returns a handler that forwards every event to the given handlers.

func (*Fanout) Add 

func (l *Fanout) Add(callback assistants.Callback)

Add appends another handler to receive events. Not safe to call concurrently with event delivery.

func (*Fanout) OnAssistantEnd 

func (l *Fanout) OnAssistantEnd(ctx context.Context, assistant assistants.IAssistant, input string, resp *assistants.Response, messageHistory llms.Messages)

func (*Fanout) OnAssistantError 

func (l *Fanout) OnAssistantError(ctx context.Context, assistant assistants.IAssistant, input string, err error, messages []llms.Message)

func (*Fanout) OnAssistantLLMCallEnd added in v0.10.61 

func (l *Fanout) OnAssistantLLMCallEnd(ctx context.Context, agent assistants.IAssistant, llm llms.Model, resp *llms.ContentResponse)

func (*Fanout) OnAssistantLLMCallStart added in v0.10.61 

func (l *Fanout) OnAssistantLLMCallStart(ctx context.Context, agent assistants.IAssistant, llm llms.Model, payload []llms.Message)

func (*Fanout) OnAssistantLLMParseError 

func (l *Fanout) OnAssistantLLMParseError(ctx context.Context, a assistants.IAssistant, input string, response string, err error)

func (*Fanout) OnAssistantStart 

func (l *Fanout) OnAssistantStart(ctx context.Context, assistant assistants.IAssistant, input string)

func (*Fanout) OnToolEnd 

func (l *Fanout) OnToolEnd(ctx context.Context, tool tools.ITool, assistantName, input string, output string)

func (*Fanout) OnToolError 

func (l *Fanout) OnToolError(ctx context.Context, tool tools.ITool, assistantName, input string, err error)

func (*Fanout) OnToolNotFound 

func (l *Fanout) OnToolNotFound(ctx context.Context, agent assistants.IAssistant, tool string)

func (*Fanout) OnToolStart 

func (l *Fanout) OnToolStart(ctx context.Context, tool tools.ITool, assistantName, input string)

type Mode 

type Mode int

Mode defines the mode for callback printing 

const (
	// ModeDefault is the default mode for callback printing
	ModeDefault Mode = iota
	// ModeVerbose is the verbose mode for callback printing
	ModeVerbose
)

type Noop 

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

Noop does nothing.

func NewNoop 

func NewNoop() *Noop

NewNoop returns a handler that ignores every event. Embed *Noop in a custom handler to implement only the events you care about, or use WithProgress for progress reporting without tracing.

func (*Noop) OnAssistantEnd 

func (l *Noop) OnAssistantEnd(ctx context.Context, assistant assistants.IAssistant, input string, resp *assistants.Response, messageHistory llms.Messages)

func (*Noop) OnAssistantError 

func (l *Noop) OnAssistantError(ctx context.Context, assistant assistants.IAssistant, input string, err error, messageHistory llms.Messages)

func (*Noop) OnAssistantLLMCallEnd added in v0.10.61 

func (l *Noop) OnAssistantLLMCallEnd(ctx context.Context, agent assistants.IAssistant, llm llms.Model, resp *llms.ContentResponse)

func (*Noop) OnAssistantLLMCallStart added in v0.10.61 

func (l *Noop) OnAssistantLLMCallStart(ctx context.Context, agent assistants.IAssistant, llm llms.Model, payload []llms.Message)

func (*Noop) OnAssistantLLMParseError 

func (l *Noop) OnAssistantLLMParseError(ctx context.Context, a assistants.IAssistant, input string, response string, err error)

func (*Noop) OnAssistantStart 

func (l *Noop) OnAssistantStart(ctx context.Context, assistant assistants.IAssistant, input string)

func (*Noop) OnProgress added in v0.13.80 

func (l *Noop) OnProgress(ctx context.Context, agent assistants.IAssistant, title, message string)

func (*Noop) OnToolEnd 

func (l *Noop) OnToolEnd(ctx context.Context, tool tools.ITool, assistantName, input string, output string)

func (*Noop) OnToolError 

func (l *Noop) OnToolError(ctx context.Context, tool tools.ITool, assistantName, input string, err error)

func (*Noop) OnToolNotFound 

func (l *Noop) OnToolNotFound(ctx context.Context, agent assistants.IAssistant, tool string)

func (*Noop) OnToolStart 

func (l *Noop) OnToolStart(ctx context.Context, tool tools.ITool, assistantName, input string)

func (*Noop) WithProgress added in v0.13.81 

func (l *Noop) WithProgress(cb assistants.OnProgressFunc)

WithProgress installs a progress callback, so a Noop handler can report progress without tracing anything else.

type PackageLogger 

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

PackageLogger is a callback handler that prints to the logger.

func NewPackageLogger 

func NewPackageLogger(logger *xlog.PackageLogger) *PackageLogger

NewPackageLogger returns a handler that emits structured key/value log entries through the given package logger.

func (*PackageLogger) OnAssistantEnd 

func (l *PackageLogger) OnAssistantEnd(ctx context.Context, assistant assistants.IAssistant, input string, resp *assistants.Response, messageHistory llms.Messages)

func (*PackageLogger) OnAssistantError 

func (l *PackageLogger) OnAssistantError(ctx context.Context, assistant assistants.IAssistant, input string, err error, messageHistory llms.Messages)

func (*PackageLogger) OnAssistantLLMCallEnd added in v0.10.61 

func (l *PackageLogger) OnAssistantLLMCallEnd(ctx context.Context, agent assistants.IAssistant, llm llms.Model, resp *llms.ContentResponse)

func (*PackageLogger) OnAssistantLLMCallStart added in v0.10.61 

func (l *PackageLogger) OnAssistantLLMCallStart(ctx context.Context, agent assistants.IAssistant, llm llms.Model, payload []llms.Message)

func (*PackageLogger) OnAssistantLLMParseError 

func (l *PackageLogger) OnAssistantLLMParseError(ctx context.Context, assistant assistants.IAssistant, input string, response string, err error)

func (*PackageLogger) OnAssistantStart 

func (l *PackageLogger) OnAssistantStart(ctx context.Context, assistant assistants.IAssistant, input string)

func (*PackageLogger) OnToolEnd 

func (l *PackageLogger) OnToolEnd(ctx context.Context, tool tools.ITool, assistantName, input string, output string)

func (*PackageLogger) OnToolError 

func (l *PackageLogger) OnToolError(ctx context.Context, tool tools.ITool, assistantName, input string, err error)

func (*PackageLogger) OnToolNotFound 

func (l *PackageLogger) OnToolNotFound(ctx context.Context, agent assistants.IAssistant, tool string)

func (*PackageLogger) OnToolStart 

func (l *PackageLogger) OnToolStart(ctx context.Context, tool tools.ITool, assistantName, input string)

type Printer 

type Printer struct {
	Out  io.Writer
	Mode Mode
	// contains filtered or unexported fields
}

Printer is a callback handler that prints to the Writer.

func NewPrinter 

func NewPrinter(out io.Writer, mode Mode) *Printer

NewPrinter returns a handler that writes a human-readable trace to out. ModeVerbose adds full message payloads and assistant output.

func (*Printer) OnAssistantEnd 

func (l *Printer) OnAssistantEnd(ctx context.Context, assistant assistants.IAssistant, input string, resp *assistants.Response, messageHistory llms.Messages)

func (*Printer) OnAssistantError 

func (l *Printer) OnAssistantError(ctx context.Context, assistant assistants.IAssistant, input string, err error, messages []llms.Message)

func (*Printer) OnAssistantLLMCallEnd added in v0.10.61 

func (l *Printer) OnAssistantLLMCallEnd(ctx context.Context, agent assistants.IAssistant, llm llms.Model, resp *llms.ContentResponse)

func (*Printer) OnAssistantLLMCallStart added in v0.10.61 

func (l *Printer) OnAssistantLLMCallStart(ctx context.Context, agent assistants.IAssistant, llm llms.Model, payload []llms.Message)

func (*Printer) OnAssistantLLMParseError 

func (l *Printer) OnAssistantLLMParseError(ctx context.Context, assistant assistants.IAssistant, input string, response string, err error)

func (*Printer) OnAssistantStart 

func (l *Printer) OnAssistantStart(ctx context.Context, assistant assistants.IAssistant, input string)

func (*Printer) OnToolEnd 

func (l *Printer) OnToolEnd(ctx context.Context, tool tools.ITool, assistantName, input string, output string)

func (*Printer) OnToolError 

func (l *Printer) OnToolError(ctx context.Context, tool tools.ITool, assistantName, input string, err error)

func (*Printer) OnToolNotFound 

func (l *Printer) OnToolNotFound(ctx context.Context, agent assistants.IAssistant, tool string)

func (*Printer) OnToolStart 

func (l *Printer) OnToolStart(ctx context.Context, tool tools.ITool, assistantName, input string)

type RunStats 

type RunStats struct {
	ChatID string
	RunID  string

	Duration                time.Duration
	TotalMessages           uint32
	Usage                   llms.UsageStats
	AssistantCalls          uint32
	AssistantCallsSucceeded uint32
	AssistantCallsFailed    uint32
	ToolsCalls              uint32
	ToolsCallsSucceeded     uint32
	ToolsCallsFailed        uint32
	ToolNotFound            uint32
}

RunStats summarizes one run: duration, token and byte usage, and the assistant and tool call counts, including failures and calls to tools that were not registered. Usage covers nested assistants as well.

type Scratchpad 

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

ScratchpadCallback is a callback handler that prints to the Writer.

func NewScratchpad 

func NewScratchpad(mode Mode) *Scratchpad

NewScratchpad returns a handler that accumulates a transcript and RunStats per run, keyed by chat ID. Bracket a run with StartRun and EndRun.

func (*Scratchpad) EndRun 

func (l *Scratchpad) EndRun(ctx context.Context) (*RunStats, []byte)

EndRun stops recording, appends the summary, and returns the stats and the transcript. Returns (nil, nil) when no run is active for the chat on ctx.

func (*Scratchpad) OnAssistantEnd 

func (l *Scratchpad) OnAssistantEnd(ctx context.Context, assistant assistants.IAssistant, input string, resp *assistants.Response, messageHistory llms.Messages)

func (*Scratchpad) OnAssistantError 

func (l *Scratchpad) OnAssistantError(ctx context.Context, assistant assistants.IAssistant, input string, err error, messageHistory llms.Messages)

func (*Scratchpad) OnAssistantLLMCallEnd added in v0.10.61 

func (l *Scratchpad) OnAssistantLLMCallEnd(ctx context.Context, agent assistants.IAssistant, llm llms.Model, resp *llms.ContentResponse)

func (*Scratchpad) OnAssistantLLMCallStart added in v0.10.61 

func (l *Scratchpad) OnAssistantLLMCallStart(ctx context.Context, agent assistants.IAssistant, llm llms.Model, payload []llms.Message)

func (*Scratchpad) OnAssistantLLMParseError 

func (l *Scratchpad) OnAssistantLLMParseError(ctx context.Context, assistant assistants.IAssistant, input string, response string, err error)

func (*Scratchpad) OnAssistantStart 

func (l *Scratchpad) OnAssistantStart(ctx context.Context, assistant assistants.IAssistant, input string)

func (*Scratchpad) OnToolEnd 

func (l *Scratchpad) OnToolEnd(ctx context.Context, tool tools.ITool, assistantName, input string, output string)

func (*Scratchpad) OnToolError 

func (l *Scratchpad) OnToolError(ctx context.Context, tool tools.ITool, assistantName, input string, err error)

func (*Scratchpad) OnToolNotFound 

func (l *Scratchpad) OnToolNotFound(ctx context.Context, agent assistants.IAssistant, tool string)

func (*Scratchpad) OnToolStart 

func (l *Scratchpad) OnToolStart(ctx context.Context, tool tools.ITool, assistantName, input string)

func (*Scratchpad) StartRun 

func (l *Scratchpad) StartRun(ctx context.Context)

StartRun begins recording for the chat on ctx. It is a no-op when ctx carries no chatmodel.ChatContext.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.