core

Documentation

Overview

Package core 实现 loop 引擎：NewAgent 组装 Provider、Hook 与工具，

Run 驱动 "model → tool → model" 循环直到完成或终止。

Index

• Constants
• type Agent
  • func AgentFromContext(ctx context.Context) (*Agent, bool)
  • func NewAgent(p provider.ModelProvider, opts ...Option) *Agent
  • func (a *Agent) Fork(ctx context.Context, forkID string, seed []types.Message, tools []types.Tool, ...) (*types.LoopState, error)
  • 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 LoopParams
• type Option
  • func WithHooks(hooks ...hook.Hook) Option
  • func WithLoopParams(hp LoopParams) 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
  • func WithInputImages(images ...types.ImagePart) RunOption

Constants

const DefaultMaxIterations = 16

Types

type Agent

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

func AgentFromContext

func AgentFromContext(ctx context.Context) (*Agent, bool)

AgentFromContext 取回当前 Run 的 Agent。引擎在每次 Run 开始时把自身

注入 ctx——hook 需要复刻引擎能力时用它（如 task hook 的并行分身）， 无需在组装期反向持有 Agent 引用。

func NewAgent

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

NewAgent 组装 Agent。构建后只读是框架契约（并发 Run 共享安全、

Fork 浅拷贝复刻安全），全部定制经 Option 完成。

func (*Agent) Fork

func (a *Agent) Fork(ctx context.Context, forkID string, seed []types.Message, tools []types.Tool, input string) (*types.LoopState, error)

Fork 以"并行分身"语义运行一次子循环：复刻当前 Agent 的一切——provider /

model warp / 流式 / 超参 / 全部运行期 hook（审批、交互、摘要、持久化……）， 从 seed 消息快照 + input 继续，forkID 是子循环的身份标识。

Fork 是引擎的通用派生原语，不隶属任何扩展：ext/hook/task 是第一个 使用者，任何"以当前自我为模板跑隔离循环"的场景（评审、假设分支、 重跑验证……）都可复用。"复刻 Agent"只能在 core 内完成——startHooks / toolWarps / systemPrompt 是私有字段，扩展层无法从外部跳过组装期。

与 Run 的区别仅两处：

• startHooks 不重跑（置 nil）：它们是组装期 hook（skill 注 system、 mcp/task 注册工具），产物已在 seed 与传入工具中，重跑必重复注入； 运行期 hook（model/tool/loop/end）全部继承——分身与本体行为一致， 审批照拦、可问用户、session 照存。
• systemPrompt 置空、toolWarps 置 nil：seed 已含完整 system（含 skill 等动态注入内容），传入工具已含主循环 warp 壳，注入或包装都会重复。

单层保证：startHooks 不重跑，task 工具不会在子循环注册，且 task hook 对 ForkID 非空的子循环拒绝再次 fork（见 ext/hook/task）。

通过浅拷贝 Agent 实现复刻：Agent 构建后只读是框架契约，拷贝安全；并发 调用安全——每次调用在独立的局部拷贝上运行。已知限制：继承工具的 warp 壳持有主循环 emitter，壳内部事件（重试、降级）不带 forkID（引擎级事件 经子 state 发出，全部带标）。

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 LoopParams

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

LoopParams 是 loop 的运行参数（迭代上限、工具串行等）。

type Option

type Option func(*Agent)

Option 配置 Agent（组装期）。

func WithHooks

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

WithHooks 传入任意扩展（mcp、skill、异常捕获等），

每个扩展只需实现 hook 包中它关心的小接口。

func WithLoopParams

func WithLoopParams(hp LoopParams) Option

WithLoopParams 设置 loop 运行参数（迭代上限、工具串行等）。

func WithMaxIterations

func WithMaxIterations(n int) Option

WithMaxIterations 设置最大迭代次数。

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 / EventReasoningChunk 实时发出。

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

WithTools 注册静态工具（hook 运行时注入的工具另走 ToolRegistry.Register）。

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 不应重复带入。

func WithInputImages

func WithInputImages(images ...types.ImagePart) RunOption

WithInputImages 为本次输入附带多模态图片（挂 state，引擎组装 input

user 消息时携带；对齐 WithHistory 变参风格，空调用无效果）。