agent

Documentation

Overview

Package agent runs a general-purpose agent loop on top of the llm layer: stream an assistant turn, execute any tool calls it requests, feed the results back, and repeat until the model produces a final answer (or a limit is hit).

The loop mechanism (loop) is separate from the stateful coordinator (Agent): the loop reaches steering and follow-up messages only through hooks, and the Agent wires those hooks to its message queues. This keeps the loop independent of how queued messages are stored, and is what lets Steer/FollowUp be called from another goroutine while a run is in flight.

Index

• type Agent
  • func New(cfg Config) *Agent
  • func (a *Agent) ClearQueues()
  • func (a *Agent) Continue(ctx context.Context) <-chan Event
  • func (a *Agent) FollowUp(message llm.Message)
  • func (a *Agent) Run(ctx context.Context, prompt string) <-chan Event
  • func (a *Agent) Steer(message llm.Message)
• type Config
• type Event
• type EventType
• type Result
• type Tool

Types

type Agent

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

Agent is the stateful coordinator: it owns the transcript and the steering and follow-up queues, and drives the loop. Run and Continue are not safe to call concurrently with each other; Steer and FollowUp are safe to call at any time.

func New

func New(cfg Config) *Agent

New builds an Agent from its config.

func (*Agent) ClearQueues

func (a *Agent) ClearQueues()

ClearQueues removes all queued steering and follow-up messages.

func (*Agent) Continue

func (a *Agent) Continue(ctx context.Context) <-chan Event

Continue resumes from the current transcript without a new prompt, draining any queued steering or follow-up messages. The last transcript message must be a user or tool result message, or the provider will reject the request.

func (*Agent) FollowUp

func (a *Agent) FollowUp(message llm.Message)

FollowUp queues a message to run after the agent would otherwise stop.

func (*Agent) Run

func (a *Agent) Run(ctx context.Context, prompt string) <-chan Event

Run streams the agent loop for a new prompt. Events flow on the returned channel, which closes when the run ends. To stop early, cancel ctx and keep draining the channel until it closes.

func (*Agent) Steer

func (a *Agent) Steer(message llm.Message)

Steer queues a message to inject after the current turn's tools finish.

type Config

type Config struct {
	Client       *llm.Client
	Model        llm.Model
	Options      llm.StreamOptions
	SystemPrompt string
	Tools        []Tool
	// MaxTurns bounds the loop. Zero uses a default.
	MaxTurns int
}

Config configures an Agent.

type Event

type Event struct {
	Type EventType

	// Message is set for message_* events and turn_end (the assistant message).
	Message llm.Message
	// LLMEvent is the underlying stream event, set for message_update.
	LLMEvent *llm.Event

	// ToolCallID, ToolName, Args, Result, IsError are set for tool_execution_* events.
	ToolCallID string
	ToolName   string
	Args       map[string]any
	Result     *Result
	IsError    bool

	// ToolResults holds the tool result messages for a turn_end event.
	ToolResults []llm.Message
	// Messages holds this run's new messages for an agent_end event.
	Messages []llm.Message
}

Event is a single agent loop update. Only the fields relevant to Type are set.

type EventType

type EventType string

EventType identifies an agent loop update. Agent events wrap the lower-level llm stream events: a message_update carries the underlying llm.Event.

const (
	// EventAgentStart marks the beginning of a run.
	EventAgentStart EventType = "agent_start"
	// EventAgentEnd marks the end of a run. Messages holds this run's new messages.
	EventAgentEnd EventType = "agent_end"
	// EventTurnStart marks the beginning of a turn (one assistant response plus its tool calls).
	EventTurnStart EventType = "turn_start"
	// EventTurnEnd marks the end of a turn. Message is the assistant message; ToolResults are its results.
	EventTurnEnd EventType = "turn_end"
	// EventMessageStart marks a message (user, assistant, or tool result) entering the transcript.
	EventMessageStart EventType = "message_start"
	// EventMessageUpdate carries a streaming update for the current assistant message.
	// LLMEvent holds the underlying llm stream event.
	EventMessageUpdate EventType = "message_update"
	// EventMessageEnd marks a completed message.
	EventMessageEnd EventType = "message_end"
	// EventToolStart marks the start of a tool execution.
	EventToolStart EventType = "tool_execution_start"
	// EventToolEnd marks the end of a tool execution.
	EventToolEnd EventType = "tool_execution_end"
)

type Result

type Result struct {
	// Content is the text/image returned to the model as the tool result.
	Content []llm.ToolResultContent
	// Details is arbitrary structured data for logs or UI rendering.
	Details any
	// Terminate hints that the agent should stop after the current tool batch.
	// The loop only stops early when every tool result in the batch sets it.
	Terminate bool
}

Result is what a tool returns to the agent loop.

type Tool

type Tool interface {
	Definition() llm.ToolDefinition
	Execute(ctx context.Context, arguments map[string]any) (Result, error)
}

Tool is a model-facing tool definition plus its executor.

Execute should return an error on failure rather than encoding the failure in Content; the loop turns the error into an error tool result so the model can recover. It must honor ctx cancellation.