Documentation
¶
Index ¶
Constants ¶
const MaxToolRounds = limits.MaxToolRounds
MaxToolRounds is the maximum number of tool-call-execute-recall iterations before the runner gives up and returns whatever it has. This prevents infinite loops from models that keep requesting tools.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*ToolRunner)
Option configures a ToolRunner at construction time.
func WithMaxRounds ¶
WithMaxRounds overrides the default maximum number of tool-call rounds. Non-positive values fall back to llm.DefaultMaxToolTurns.
type ToolResult ¶
ToolResult holds the result of executing a single tool call.
type ToolRunResult ¶
type ToolRunResult struct {
// Stream is the live LLM response stream. Events are forwarded
// in real-time from the LLM, enabling token-by-token streaming.
// The caller should consume this stream (e.g. via StreamToPost).
// If the runner stopped because shouldExecute returned false,
// this stream DOES contain the unresolved tool calls.
Stream *llm.TextStreamResult
// ToolTurns records each intermediate tool round that was executed.
// Empty if the LLM returned text without any tool calls, or if
// shouldExecute returned false on the first round.
//
// NOTE: ToolTurns is populated asynchronously by the streaming
// goroutine. It is safe to read after the Stream has been fully
// consumed (channel happens-before guarantees this).
ToolTurns []ToolTurn
// FinalText is the assistant text from the round where the loop exited
// with no tool calls. Empty on stream error, unresolved tool calls, or a
// failed forced synthesis. Read after Stream is fully consumed.
FinalText string
}
ToolRunResult is the return value of Run(). It contains the final stream (no more tool calls) and all intermediate tool rounds.
type ToolRunner ¶
type ToolRunner struct {
// contains filtered or unexported fields
}
ToolRunner manages the call-execute-recall loop for LLM tool use. It calls the LLM, checks for tool calls in the stream, executes approved ones, appends results back to the request, and calls again.
func New ¶
func New(lm llm.LanguageModel, opts ...Option) *ToolRunner
New creates a ToolRunner bound to the given language model. Pass WithMaxRounds to override the default per-agent tool-call ceiling.
func (*ToolRunner) Run ¶
func (r *ToolRunner) Run( ctx context.Context, request llm.CompletionRequest, shouldExecute func(llm.ToolCall) bool, onToolTurns func([]ToolTurn), opts ...llm.LanguageModelOption, ) (*ToolRunResult, error)
Run calls the LLM and handles tool execution in a loop.
Events (text, reasoning, annotations, etc.) are forwarded in real-time to the returned stream, enabling token-by-token streaming to the client. Tool call events are buffered internally to detect and execute tools.
Parameters:
- request: The CompletionRequest to send to the LLM. The request's Context.Tools must contain the ToolStore with available tools.
- shouldExecute: Called for each tool call to decide whether to auto-execute it. If ANY tool call in a batch returns false, the entire batch is left unresolved and the runner returns.
- onToolTurns: Optional callback invoked with accumulated tool turns after all intermediate tool rounds complete, before the final text response starts streaming. May be nil.
- opts: Additional LanguageModelOption values (e.g. WithReasoningDisabled).
Returns:
- *ToolRunResult with the live stream and (asynchronously populated) tool turns.
- error if the initial LLM call fails. Errors from subsequent LLM calls (after tool execution) are delivered through the stream as EventTypeError.
type ToolTurn ¶
type ToolTurn struct {
// AssistantMessage is the accumulated text from the assistant response
// that contained tool calls.
AssistantMessage string
// AssistantToolCalls holds the tool calls from the assistant response.
AssistantToolCalls []llm.ToolCall
// AssistantReasoning holds the reasoning data from the assistant response.
AssistantReasoning llm.ReasoningData
// ToolResults holds the executed tool results, one per tool call.
// Includes both successful and errored results.
ToolResults []ToolResult
// TokensIn and TokensOut are the token counts for the LLM call
// that produced this round's assistant response.
TokensIn int64
TokensOut int64
}
ToolTurn represents one round of tool execution. Each round corresponds to one LLM call that returned tool_use blocks, followed by tool execution and the resulting tool_result blocks.
Source Files
Directories