core

Documentation

Overview

Package core 实现 loop 引擎：NewAgent 组装 Provider、Hook 与工具， Run 驱动 "model → tool → model" 循环直到完成或终止。

Index

• Constants
• type Agent
  • func NewAgent(p provider.ModelProvider, opts ...Option) *Agent
  • func (a *Agent) Run(ctx context.Context, input string, runOpts ...RunOption) (state *types.LoopState, err error)
  • func (a *Agent) RunAsync(ctx context.Context, input string, runOpts ...RunOption) *RunHandle
• type HyperParams
• type Option
  • func WithHooks(hooks ...hook.Hook) Option
  • func WithHyperParams(hp HyperParams) Option
  • func WithMaxIterations(n int) Option
  • func WithModelWarp(warps ...warp.ModelHandler) Option
  • func WithOnEvent(fn event.OnEvent) Option
  • func WithStreaming(enabled bool) Option
  • func WithSystemPrompt(prompt string) Option
  • func WithToolWarp(warps ...warp.ToolHandler) Option
  • func WithTools(tools ...types.Tool) Option
• type RunHandle
  • func (h *RunHandle) Cancel()
  • func (h *RunHandle) Events() <-chan event.Event
  • func (h *RunHandle) Wait() (*types.LoopState, error)
• type RunOption
  • func WithHistory(messages ...types.Message) RunOption

Constants

const DefaultMaxIterations = 16

Types

type Agent

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

func NewAgent

func NewAgent(p provider.ModelProvider, opts ...Option) *Agent

func (*Agent) Run

func (a *Agent) Run(ctx context.Context, input string, runOpts ...RunOption) (state *types.LoopState, err error)

Run 驱动整个 loop：model ↔ tool 循环，直到模型不再发起 tool call、 达到 MaxIterations、hook 置 Stop 或出错。EndHook 无论成败都会执行。 消息序列构造顺序：system 提示词 → WithHistory 历史 → 本次 input， 随后 startHook 可继续注入（如 skill）。

func (*Agent) RunAsync

func (a *Agent) RunAsync(ctx context.Context, input string, runOpts ...RunOption) *RunHandle

RunAsync 以 goroutine 驱动 loop，返回异步句柄。 事件经 Events 通道给出（与 WithOnEvent 同一事件流，二选一即可）。

h := agent.RunAsync(ctx, "任务")
defer h.Cancel()
for e := range h.Events() { render(e) }
state, err := h.Wait()

type HyperParams

type HyperParams struct {
	// MaxIterations 最大迭代次数，0 取默认 16。
	MaxIterations int
	// SerialTools 串行执行工具调用（默认 false = 每个调用独立并发，
	// 调用数即并发数——并发数量不可配，需要限流在 tool warp 内实现）。
	SerialTools bool
}

HyperParams 是 Agent 的运行超参数。

type Option

type Option func(*Agent)

func WithHooks

func WithHooks(hooks ...hook.Hook) Option

WithHooks 传入任意扩展（mcp、skill、异常捕获等）， 每个扩展只需实现 hook 包中它关心的小接口。

func WithHyperParams

func WithHyperParams(hp HyperParams) Option

WithHyperParams 设置运行超参数（迭代上限、工具并发量等）。

func WithMaxIterations

func WithMaxIterations(n int) Option

func WithModelWarp

func WithModelWarp(warps ...warp.ModelHandler) Option

WithModelWarp 传入模型节点中间件（类型定义见 warp 包）。 组装延迟到每次 Run：引擎注入 per-Run 事件出口后才包装， 先注册的位于最外层，warp 实例 per-Run 独立。

func WithOnEvent

func WithOnEvent(fn event.OnEvent) Option

WithOnEvent 设置事件回调。 并发契约：工具并发执行时（含 tool warp 的事件），回调可能被多个 goroutine 同时调用——实现必须并发安全且快速返回； 需要免锁消费时用 RunAsync 的 Events 通道（channel 天然并发安全）。

func WithStreaming

func WithStreaming(enabled bool) Option

WithStreaming 启用后，Provider 若实现 StreamProvider 则走流式， chunk 通过 EventModelChunk 实时发出。

func WithSystemPrompt

func WithSystemPrompt(prompt string) Option

WithSystemPrompt 设置 agent 级系统提示词（人格、规则等）， 位于消息序列最前。会话级动态注入用 skill hook 或 WithHistory。

func WithToolWarp

func WithToolWarp(warps ...warp.ToolHandler) Option

WithToolWarp 传入工具节点中间件（引擎标准能力，类型定义见 warp 包）。 挂载在 ToolRegistry 上：静态注册（WithTools）与 hook 运行时注入的工具 都会被包装。先注册的位于最外层。

func WithTools

func WithTools(tools ...types.Tool) Option

type RunHandle

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

RunHandle 是 RunAsync 的异步句柄：Events 通道消费实时事件， Cancel 取消执行，Wait 获取最终结果。loop 结束后 Events 自动关闭。

func (*RunHandle) Cancel

func (h *RunHandle) Cancel()

Cancel 取消执行（幂等）。loop 在当前节点收尾后以 cancelled 停止。

func (*RunHandle) Events

func (h *RunHandle) Events() <-chan event.Event

Events 返回事件通道（缓冲 256）。注意：channel 满时 loop 会阻塞， 消费方应尽快消费；审计等场景不可丢弃事件。

func (*RunHandle) Wait

func (h *RunHandle) Wait() (*types.LoopState, error)

Wait 阻塞直到 loop 结束，返回最终状态。

type RunOption

type RunOption func(*types.LoopState)

RunOption 是单次 Run 的定制项。

func WithHistory

func WithHistory(messages ...types.Message) RunOption

WithHistory 携带历史对话消息（多轮会话延续）， 历史位于本次 input 之前、system 提示词之后。 system 消息会被过滤：它们是 agent 的属性（WithSystemPrompt、skill hook）， 每轮由引擎重新注入，历史快照中的 system 不应重复带入。