agent

Documentation

Index

• type AgentErrored
  • func (AgentErrored) Kind() string
• type AgentFinished
  • func (AgentFinished) Kind() string
• type AgentStarted
  • func (AgentStarted) Kind() string
• type AssistantDelta
  • func (AssistantDelta) Kind() string
• type AssistantFinished
  • func (AssistantFinished) Kind() string
• type AssistantStarted
  • func (AssistantStarted) Kind() string
• type LoopEvent
• type Option
  • func WithHooks(hs *hooks.HookSet, meta hooks.HookMeta) Option
  • func WithInterrupt(ch <-chan struct{}) Option
  • func WithMaxTurns(n int) Option
  • func WithStreamOptions(opts ai.StreamOptions) Option
  • func WithSystem(s string) Option
  • func WithToolLifecycle(tl *ToolLifecycle) Option
• type Runner
  • func NewRunner(cfg RunnerConfig, opts ...Option) (*Runner, error)
  • func (r *Runner) Continue(ctx context.Context, messages []ai.Message, emit func(LoopEvent)) ([]ai.Message, error)
  • func (r *Runner) Run(ctx context.Context, messages []ai.Message, emit func(LoopEvent)) ([]ai.Message, error)
  • func (r *Runner) SetHookMeta(meta hooks.HookMeta)
• type RunnerConfig
• type ToolCallContext
• type ToolCallMutation
• type ToolFinished
  • func (ToolFinished) Kind() string
• type ToolFunc
  • func WrapTool(t tools.Tool) ToolFunc
• type ToolLifecycle
• type ToolResultContext
• type ToolResultMutation
• type ToolSet
  • func ToolSetFromRegistry(reg *tools.Registry) ToolSet
  • func ToolSetFromRegistryFiltered(reg *tools.Registry, names []string) (ToolSet, []tools.Definition, error)
• type ToolStarted
  • func (ToolStarted) Kind() string
• type TurnFinished
  • func (TurnFinished) Kind() string
• type TurnStarted
  • func (TurnStarted) Kind() string

Types

type AgentErrored

type AgentErrored struct {
	Err error
}

AgentErrored is emitted for terminal loop errors.

func (AgentErrored) Kind

func (AgentErrored) Kind() string

type AgentFinished

type AgentFinished struct{}

AgentFinished is emitted when loop completes.

func (AgentFinished) Kind

func (AgentFinished) Kind() string

type AgentStarted

type AgentStarted struct{}

AgentStarted is emitted when a loop begins.

func (AgentStarted) Kind

func (AgentStarted) Kind() string

type AssistantDelta

type AssistantDelta struct {
	Event   ai.AssistantEvent
	Message ai.AssistantMessage
}

AssistantDelta forwards an incremental provider event with the current partial message.

func (AssistantDelta) Kind

func (AssistantDelta) Kind() string

type AssistantFinished

type AssistantFinished struct {
	Message ai.AssistantMessage
}

AssistantFinished is emitted when the final assistant message is assembled.

func (AssistantFinished) Kind

func (AssistantFinished) Kind() string

type AssistantStarted

type AssistantStarted struct {
	Message ai.AssistantMessage
}

AssistantStarted is emitted when assistant streaming begins.

func (AssistantStarted) Kind

func (AssistantStarted) Kind() string

type LoopEvent

type LoopEvent interface {
	Kind() string
}

LoopEvent is the runtime event contract emitted by the agent loop.

type Option

type Option func(*Runner)

Option configures optional Runner fields.

func WithHooks

func WithHooks(hs *hooks.HookSet, meta hooks.HookMeta) Option

WithHooks sets the hook set and metadata for the loop.

func WithInterrupt

func WithInterrupt(ch <-chan struct{}) Option

WithInterrupt sets an interrupt channel to stop the loop.

func WithMaxTurns

func WithMaxTurns(n int) Option

WithMaxTurns sets the maximum number of loop turns.

func WithStreamOptions

func WithStreamOptions(opts ai.StreamOptions) Option

WithStreamOptions sets stream options (API key, base URL, etc.).

func WithSystem

func WithSystem(s string) Option

WithSystem sets the system prompt.

func WithToolLifecycle

func WithToolLifecycle(tl *ToolLifecycle) Option

WithToolLifecycle sets optional tool lifecycle hooks for the loop.

type Runner

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

Runner is a configured agent loop executor. It is safe for concurrent use. All configuration is set at construction time via RunnerConfig + options.

func NewRunner

func NewRunner(cfg RunnerConfig, opts ...Option) (*Runner, error)

NewRunner constructs a Runner with the given config and options.

func (*Runner) Continue

func (r *Runner) Continue(ctx context.Context, messages []ai.Message, emit func(LoopEvent)) ([]ai.Message, error)

Continue validates the history tail and resumes the agent loop.

func (*Runner) Run

func (r *Runner) Run(ctx context.Context, messages []ai.Message, emit func(LoopEvent)) ([]ai.Message, error)

Run executes the agent loop from scratch.

func (*Runner) SetHookMeta

func (r *Runner) SetHookMeta(meta hooks.HookMeta)

SetHookMeta updates the hook metadata (session/agent/user context). Safe to call between Run invocations; not safe during a Run.

type RunnerConfig

type RunnerConfig struct {
	Providers       providers.ProviderGetter
	Model           ai.Model
	Tools           ToolSet
	ToolDefinitions []ai.ToolDefinition
}

RunnerConfig holds the required fields for constructing a Runner.

type ToolCallContext

type ToolCallContext struct {
	SessionID  string
	Channel    string
	UserID     int64
	AgentID    string
	ToolName   string
	ToolCallID string
	Arguments  map[string]any
}

ToolCallContext describes one tool call before execution.

type ToolCallMutation

type ToolCallMutation struct {
	Arguments    map[string]any
	Block        bool
	BlockMessage string
}

ToolCallMutation describes how a pre-tool lifecycle hook changes execution.

type ToolFinished

type ToolFinished struct {
	Result ai.ToolResultMessage
}

ToolFinished is emitted when tool returns.

func (ToolFinished) Kind

func (ToolFinished) Kind() string

type ToolFunc

type ToolFunc func(ctx context.Context, call ai.ToolCall) (ai.TextContent, error)

ToolFunc executes one tool invocation.

func WrapTool

func WrapTool(t tools.Tool) ToolFunc

WrapTool adapts a single tools.Tool into a ToolFunc.

type ToolLifecycle

type ToolLifecycle struct {
	BeforeCall func(ctx context.Context, call ToolCallContext) (ToolCallMutation, error)
	AfterCall  func(ctx context.Context, result ToolResultContext) (ToolResultMutation, error)
}

ToolLifecycle carries optional tool-call lifecycle hooks for the agent loop.

type ToolResultContext

type ToolResultContext struct {
	SessionID  string
	Channel    string
	UserID     int64
	AgentID    string
	ToolName   string
	ToolCallID string
	Arguments  map[string]any
	Result     string
	IsError    bool
	Duration   time.Duration
}

ToolResultContext describes one completed tool call.

type ToolResultMutation

type ToolResultMutation struct {
	Result  *string
	IsError *bool
}

ToolResultMutation describes how a post-tool lifecycle hook changes the final result.

type ToolSet

type ToolSet map[string]ToolFunc

ToolSet maps tool names to handlers.

func ToolSetFromRegistry

func ToolSetFromRegistry(reg *tools.Registry) ToolSet

ToolSetFromRegistry builds a ToolSet from a tools.Registry. Every registered tool is included. The returned ToolSet dispatches calls through the registry's Execute method.

func ToolSetFromRegistryFiltered

func ToolSetFromRegistryFiltered(reg *tools.Registry, names []string) (ToolSet, []tools.Definition, error)

ToolSetFromRegistryFiltered builds a ToolSet including only the named tools. Returns the matching definitions and an error if any name is not found.

type ToolStarted

type ToolStarted struct {
	ToolCall ai.ToolCall
}

ToolStarted is emitted for each tool invocation.

func (ToolStarted) Kind

func (ToolStarted) Kind() string

type TurnFinished

type TurnFinished struct {
	Turn int
}

TurnFinished is emitted at the end of each loop turn.

func (TurnFinished) Kind

func (TurnFinished) Kind() string

type TurnStarted

type TurnStarted struct {
	Turn int
}

TurnStarted is emitted at the start of each loop turn.

func (TurnStarted) Kind

func (TurnStarted) Kind() string