Documentation
¶
Overview ¶
Package engine drives the agent loop: send messages → consume the streamed response → execute requested tools → loop until the model stops on its own.
Two surfaces:
- Run executes one task to completion in a fresh conversation. Use this for `agent run` and other one-shot callers.
- Session keeps message history across calls. Use this for `agent chat` or any caller that needs multi-turn memory.
Index ¶
- func Run(ctx context.Context, cfg Config, task string) error
- type Config
- type Session
- func (s *Session) LastInputTokens() int
- func (s *Session) Messages() []llm.Message
- func (s *Session) Model() string
- func (s *Session) Reset()
- func (s *Session) RestoreMessages(msgs []llm.Message)
- func (s *Session) SetModel(p llm.Provider, model string)
- func (s *Session) SetUsage(u llm.Usage)
- func (s *Session) Step(ctx context.Context, task string) error
- func (s *Session) Truncate(maxExchanges int)
- func (s *Session) Usage() llm.Usage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
Provider llm.Provider
Model string
System string
Tools *tools.Registry
Temperature *float64
MaxTokens int
// MaxContextTokens is the model's context window size. When estimated
// input tokens exceed 80% of this, the session auto-compacts. Zero
// means use a conservative default (128K).
MaxContextTokens int
// ResponseSchema constrains the model to produce valid JSON matching
// this schema. Nil means unconstrained text output.
ResponseSchema json.RawMessage
// Out receives streamed assistant text. nil means discard.
Out io.Writer
// Status receives tool-call indicators ("→ shell ls", "← 12 lines").
// nil means discard. Typically wired to stderr.
Status io.Writer
// MaxTurns bounds the tool-use loop within a single Step. Zero uses
// defaultMaxTurns.
MaxTurns int
// ToolConfirm is called before executing any destructive tool.
// Return true to proceed, false to skip. Nil means auto-approve.
ToolConfirm func(ctx context.Context, toolName string, input json.RawMessage) (bool, error)
// ContinueConfirm is called when MaxTurns is reached. Return true
// to continue for another MaxTurns rounds, false to stop.
// Nil means stop immediately.
ContinueConfirm func(ctx context.Context, turns int) (bool, error)
}
Config configures a Run or Session. The zero value is not usable: Provider and Model must be set.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is a stateful, multi-turn conversation driver. Step appends a user turn and runs the engine loop; the resulting message history is retained on the Session and reused on subsequent Steps.
func NewSession ¶
NewSession constructs a Session. It validates required Config fields lazily on the first Step call (so a Session can be built before all dependencies are wired, e.g. in tests).
func (*Session) LastInputTokens ¶
LastInputTokens returns the input_tokens from the most recent provider call. This approximates the current context window consumption.
func (*Session) Messages ¶
Messages returns a snapshot of the rolling history. The outer slice and each Message's Content slice are fresh copies; the ContentBlock values themselves (and any contained byte slices) are shared, so callers shouldn't mutate field-level data either.
func (*Session) Reset ¶
func (s *Session) Reset()
Reset clears the conversation history. Tool registry and provider remain configured.
func (*Session) RestoreMessages ¶
RestoreMessages replaces the message history with saved messages. Used to resume a previous session from persistent storage.
func (*Session) SetModel ¶
SetModel hot-swaps the provider and model for subsequent Steps. Existing message history is preserved.
func (*Session) Step ¶
Step appends task as a user turn and runs the engine loop until the model stops naturally (or hits MaxTurns). The assistant's response streams to s.cfg.Out; full message turns are appended to the history.
func (*Session) Truncate ¶
Truncate keeps at most the last maxExchanges user-initiated exchanges. A user-initiated exchange begins at a user message containing only text blocks (i.e., not a tool_result-bearing follow-up). All messages from that point through the next exchange-start are retained as a unit, so an assistant turn's tool_use is never split from its matching tool_result. maxExchanges <= 0 is a no-op.
Source Files