Documentation
¶
Overview ¶
Package agent provides a tool-loop agent that orchestrates multi-step reasoning and tool execution.
It is a higher-level abstraction over core.StreamText that presents a simplified interface: callers provide a prompt string, tools, and configuration, and receive a channel of StreamEvent values that represent the streamed model output, tool calls, tool results, and step boundaries.
The agent owns the tool-loop lifecycle:
- It calls core.StreamText with the configured tools and options.
- It translates core.StreamPart events into StreamEvent values on the output channel.
- The underlying tool execution (calling Go functions and feeding results back) is handled by core — the agent concentrates on event translation and lifecycle management.
Usage:
a := &agent.Agent{
Provider: provider,
Model: "gpt-5.4",
System: "You are a helpful assistant.",
Tools: core.ToolSet{
"weather": core.NewTool("weather", "Get weather", schema, executeWeather),
},
MaxSteps: 5,
}
events, err := a.Run(ctx, "What is the weather in London?")
if err != nil {
log.Fatal(err)
}
for ev := range events {
switch ev.Type {
case agent.EventTextDelta:
fmt.Print(ev.TextDelta)
case agent.EventToolCall:
log.Printf("calling %s: %s", ev.ToolCall.ToolName, ev.ToolCall.Input)
case agent.EventToolResult:
log.Printf("result: %s", ev.ToolResult.Output)
case agent.EventFinish:
log.Printf("done: %s", ev.FinishReason)
}
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RunAgent ¶
func RunAgent(ctx context.Context, provider chat.Provider, prompt string, tools core.ToolSet, maxSteps int) (<-chan StreamEvent, error)
RunAgent orchestrates a multi-step agent run using the given provider, prompt, and tool set. It wraps core.StreamText and translates each core.StreamPart into a StreamEvent, emitting them on the returned channel.
core.StreamText handles the full tool loop internally — executing tools, feeding results back to the model, and respecting maxSteps for termination. RunAgent provides a simpler function-based API that avoids constructing an Agent struct.
The returned channel is unbuffered. The agent goroutine respects ctx cancellation — when ctx is cancelled, an EventAbort is emitted and the channel closes.
Types ¶
type Agent ¶
type Agent struct {
Provider chat.Provider `json:"-"`
Model string `json:"model,omitempty"`
System string `json:"system,omitempty"`
Tools core.ToolSet `json:"-"`
MaxSteps int `json:"max_steps,omitempty"`
Temperature float32 `json:"temperature,omitempty"`
MaxTokens int `json:"max_tokens,omitempty"`
// ProviderOptions carries provider-specific request options through to
// core.StreamText.
ProviderOptions map[string]any `json:"provider_options,omitempty"`
}
Agent orchestrates multi-step reasoning and tool execution by wrapping core.StreamText. Callers configure the agent and call Agent.Run to receive a channel of StreamEvent values.
func (*Agent) Run ¶
Run starts the agent with the given prompt and returns a channel of stream events. The agent goroutine drives core.StreamText, translates core.StreamPart events into StreamEvent values, and closes the channel when the run completes.
The returned channel is unbuffered. The agent goroutine respects ctx cancellation — when ctx is cancelled, an EventAbort is emitted and the channel closes.
type EventType ¶
type EventType string
EventType identifies the kind of a StreamEvent.
const ( EventTextDelta EventType = "text-delta" EventReasoningDelta EventType = "reasoning-delta" EventToolCall EventType = "tool-call" EventToolResult EventType = "tool-result" EventStartStep EventType = "step-start" EventFinishStep EventType = "finish-step" EventFinish EventType = "finish" EventError EventType = "error" EventAbort EventType = "abort" )
StreamEvent event type constants.
type StreamEvent ¶
type StreamEvent struct {
Type EventType `json:"type"`
TextDelta string `json:"text_delta,omitempty"`
ReasoningDelta string `json:"reasoning_delta,omitempty"`
ToolCall *core.ToolCall `json:"tool_call,omitempty"`
ToolResult *core.ToolResult `json:"tool_result,omitempty"`
StepResult *core.StepResult `json:"step_result,omitempty"`
Error error `json:"-"`
FinishReason core.FinishReason `json:"finish_reason,omitempty"`
TotalUsage *chat.Usage `json:"total_usage,omitempty"`
}
StreamEvent is a single event emitted during agent execution. Each event has a [Type] and at most one payload field populated — the payload depends on the [Type].
Source Files