agent

Documentation

Index

• Constants
• func BuildSystemMessage(ctx context.Context, toolreg *tools.Registry, sysPrompt, toolsPrompt string) (llm.Message, []llm.ToolDefinition)
• func ConvertMCPToolsToLLMTools(tools []mcps.ToolDescriptor) []llm.ToolDefinition
• func StreamChat(ctx context.Context, loop *AgentLoop, messages []llm.Message, ...) (string, error)
• func ThisMoment() string
• type AgentLoop
  • func NewAgentLoop(cfg AgentLoopConfig, opts ...AgentLoopOption) *AgentLoop
  • func (al *AgentLoop) Run(ctx context.Context, messages []llm.Message, tools []llm.ToolDefinition) iter.Seq2[*llm.Event, error]
  • func (al *AgentLoop) RunNonStreaming(ctx context.Context, messages []llm.Message, tools []llm.ToolDefinition) (string, error)
• type AgentLoopConfig
• type AgentLoopOption
  • func WithMaxLoop(n int) AgentLoopOption
• type ChatExecutor
• type StreamCallbacks
• type ToolExecutor
  • func NewToolExecutor(toolreg *tools.Registry) *ToolExecutor
  • func (e *ToolExecutor) ExecuteToolCallLoop(ctx context.Context, messages []llm.Message, tools []llm.ToolDefinition, ...) (string, []llm.ToolCall, *llm.Usage, error)
  • func (e *ToolExecutor) ExecuteToolCalls(ctx context.Context, messages []llm.Message, toolCalls []llm.ToolCall, ...) ([]*llm.Event, []llm.Message, bool)

Constants

const (
	// DefaultSystemMsg is the fallback system prompt when no preset is configured.
	DefaultSystemMsg = "" /* 198-byte string literal not displayed */

	// DefaultToolsMsg is the fallback tool-usage prompt when no preset is configured.
	DefaultToolsMsg = "" /* 712-byte string literal not displayed */
)

Functions

func BuildSystemMessage

func BuildSystemMessage(ctx context.Context, toolreg *tools.Registry, sysPrompt, toolsPrompt string) (llm.Message, []llm.ToolDefinition)

BuildSystemMessage constructs a system message from the tool registry and prompts. Returns the system message and the resolved tool definitions.

func ConvertMCPToolsToLLMTools

func ConvertMCPToolsToLLMTools(tools []mcps.ToolDescriptor) []llm.ToolDefinition

ConvertMCPToolsToLLMTools converts MCP tool descriptors to LLM tool definitions.

func StreamChat

func StreamChat(ctx context.Context, loop *AgentLoop, messages []llm.Message, tools []llm.ToolDefinition, cb StreamCallbacks) (string, error)

StreamChat runs the agent loop in streaming mode, invoking callbacks for each delta and think event. Returns the full accumulated answer text.

func ThisMoment

func ThisMoment() string

ThisMoment returns a timestamp string in Chinese 时辰 format.

Types

type AgentLoop

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

AgentLoop encapsulates the full agent loop: LLM call + tool execution + iteration.

func NewAgentLoop

func NewAgentLoop(cfg AgentLoopConfig, opts ...AgentLoopOption) *AgentLoop

NewAgentLoop creates a new AgentLoop with the given config and options. Defaults MaxLoop to 5 when unset or <= 0.

func (*AgentLoop) Run

func (al *AgentLoop) Run(ctx context.Context, messages []llm.Message, tools []llm.ToolDefinition) iter.Seq2[*llm.Event, error]

Run executes the streaming agent loop, returning an iter.Seq2 that yields events from StreamChat and tool execution. The caller consumes events via `for event, err := range loop.Run(ctx, messages, tools)`.

The iterator runs synchronously within the caller's goroutine. It stops when:

• LLM returns no tool calls (final answer)
• all executed tools signal terminate=true
• maxLoop iterations are exceeded (yields error event)
• StreamChat returns an error (yields error event)
• the caller breaks out of the range loop

func (*AgentLoop) RunNonStreaming

func (al *AgentLoop) RunNonStreaming(ctx context.Context, messages []llm.Message, tools []llm.ToolDefinition) (string, error)

RunNonStreaming executes the non-streaming agent loop, returning the final answer string. It calls Chat, collects tool calls, executes tools, and loops until no tool calls remain or all tools signal terminate.

type AgentLoopConfig

type AgentLoopConfig struct {
	LLM      llm.Client    // LLM client for Chat and StreamChat
	ToolExec *ToolExecutor // tool executor (same package)
	MaxLoop  int           // safety net: max loop iterations, default 5
}

AgentLoopConfig holds configuration for AgentLoop.

type AgentLoopOption

type AgentLoopOption func(*AgentLoopConfig)

AgentLoopOption is a functional option for AgentLoopConfig.

func WithMaxLoop

func WithMaxLoop(n int) AgentLoopOption

WithMaxLoop sets the maximum number of loop iterations before safety-net termination.

type ChatExecutor

type ChatExecutor func(ctx context.Context, messages []llm.Message, tools []llm.ToolDefinition) (string, []llm.ToolCall, *llm.Usage, error)

ChatExecutor 定义聊天执行函数类型，支持流式/非流式

type StreamCallbacks

type StreamCallbacks struct {
	OnDelta func(delta string)
	OnThink func(think string)
}

StreamCallbacks holds callbacks for streaming agent responses.

type ToolExecutor

type ToolExecutor struct {

	// BeforeToolCall 在每个工具调用前执行。返回 block=true 时阻止工具执行，
	// reason 作为 error 内容写入 ToolResult。可选，nil 时跳过。
	BeforeToolCall func(ctx context.Context, name string, params map[string]any) (block bool, reason string)

	// AfterToolCall 在每个工具成功执行后调用，可修改 result。
	// 返回的 map 会替代原 result 用于后续格式化。可选，nil 时跳过。
	AfterToolCall func(ctx context.Context, name string, result map[string]any) map[string]any
	// contains filtered or unexported fields
}

ToolExecutor 封装工具调用循环逻辑

func NewToolExecutor

func NewToolExecutor(toolreg *tools.Registry) *ToolExecutor

NewToolExecutor 创建 ToolExecutor

func (*ToolExecutor) ExecuteToolCallLoop

func (e *ToolExecutor) ExecuteToolCallLoop(
	ctx context.Context,
	messages []llm.Message,
	tools []llm.ToolDefinition,
	exec ChatExecutor,
) (string, []llm.ToolCall, *llm.Usage, error)

ExecuteToolCallLoop 执行工具调用循环，直到无 tool calls

func (*ToolExecutor) ExecuteToolCalls

func (e *ToolExecutor) ExecuteToolCalls(ctx context.Context, messages []llm.Message, toolCalls []llm.ToolCall, think string) ([]*llm.Event, []llm.Message, bool)

ExecuteToolCalls 执行单轮工具调用（并发），返回事件列表、更新后的消息和 allTerminate。 allTerminate 在本次所有成功执行的 tool 都标记 terminate 时为 true。