agent

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package agent 提供 Agent Registry 与 Turn/Step 双循环执行器。

对齐上游:packages/core/agent + agent-loop

设计要点:

  • Agent 通过 Inbox 双队列(turn 队列)接收 Run/Followup 输入;
  • 后台 worker 串行处理 turn(单 Turn 串行保证):turn/start → claim → pre-step → 多 Step → turn-stopping → turn/end;
  • 每个 Step:step/start → 派生 → agent/request → llm/stream → assistant/chunk* → 若含工具调用则经 M23 四级流水线执行 → step/end;
  • step/tool 错误 → agent/error 写入日志,turn 以 interrupted 关闭;
  • pending turn 超过队列容量 → ErrTurnQueueFull(reject)。

本文件对应任务 M18:Agent Cancel 原因分类(5 类)。

对齐上游:packages/core/agent/Agent.ts

Cancel 的取消原因通过 turn-stopping 事件记录为 "cancel:<cause>"; 上层读取日志时用 ExtractCancelCause 还原分类,turn/end 以 aborted 关闭。

本文件复刻官方 packages/core/agent/src/consumed-work.ts。

它回答 Turn/Step 词汇单独回答不了的问题:一份 agent 日志到底结算了哪些被消费的工作? 只看 turn/end 会把"在首个 step 前就中止的 turn"和"被拒绝/空 claim 产生的平衡 no-op turn" 混为一谈——要么把半途而废的工作误记为完成,要么冤枉每个 no-op。

缺失的事实来自收件箱自身的记录:Inbox 每次变更都带 removedCount,取消会标 outcome='canceled',据此区分"一个 claim 了输入的 turn"与"工作未运行即被丢弃"。

Package agent 的 Inbox 收件箱实现。

对齐官方 packages/core/agent/src/inbox.ts。

Inbox 是 Agent 拥有的两个有序待处理消息列表的增量投影:

  • next-turn:等待各个 turn 的提示
  • next-step:等待下一个 step 边界的输入

本文件对应任务 M33:Agent Initiator 上下文(安全归因)。

对齐上游:packages/core/agent initiator module

设计要点:

  • withInitiator 在 context 中注入当前发起操作的 Agent 身份 + 操作名;
  • requireInitiator 在无 withInitiator 包裹的调用点返回 Unauthorized 结构化错误 (不允许静默放行,阻断"匿名发起"的安全隐患);
  • withoutInitiator 显式清除 initiator(进入不受控区域时隔离身份)。

本文件复刻官方 packages/core/agent/src/model-selection.ts 的核心语义。

官方用两个 waterfall(system-prompt/assemble、agent/request)把"可变的模型选择" 耦合到 prompt 装配与请求路由:prompt 装配前快照所选模型,请求时应用该快照, 从而一次并发切换只在后续 step 生效,不会把"装配面"与"请求面"撕裂成两个模型。

omnix 的 sysprompt 是同步 Assembler(非 Cordis 异步事件),因此这里不照搬事件 接线,而是把 current/assembled 双快照固化为一个并发安全的小状态机,由 Agent 在 同步装配/请求的对应位置显式调用 Capture / Apply。

Package agent 的配置与运行时类型。

对齐官方 packages/core/agent/src/runtime-types.ts 和 types.ts。

本文件对应任务 M34:agent/request-error 重试瀑布。

对齐上游:packages/core/agent-loop request-error waterfall

设计要点:

  • RequestErrorAction{kind} 只有两种:'retry'(显式重试通道)与 'abort'(终止);
  • request-error waterfall 复用 M02 waterfall 洋葱链:各中间件按序判定动作,可短路; 未命中任何中间件时落到 TerminalRetryDecision 兜底;
  • 与 S15(LLM Retry)协同:S15 在 LLM 层做一次退避重试并写 llm/retry 事件;若仍失败 (达 max 上抛),进入本 request-error 瀑布决定 retry 或 abort;
  • 超过 max 次重试 → abort,并以 error 关闭当前 turn(写 agent/error 事件)。

Index

Constants

This section is empty.

Variables

View Source
var ErrDisposed = errors.New("agent: disposed")

ErrTurnQueueFull 表示 pending turn 队列已满(拒绝新的 Run/Followup)。

View Source
var ErrTurnQueueFull = errors.New("agent: turn queue full, reject pending turn")

Functions

func RecordCancel

func RecordCancel(sl *session.SessionLog, cause CancelCause) error

RecordCancel 记录一次取消原因(写入 turn-stopping 事件)。

func RecordRequestError

func RecordRequestError(log *session.SessionLog, err error)

RecordRequestError 把一次请求错误写入会话日志(agent/error 事件),供审计。 log 可为 nil(此时跳过)。

func ShouldRetryError

func ShouldRetryError(err error) bool

ShouldRetryError 复用 llm 分类:仅 overload / rate-limit 可重试。

func WithInitiator

func WithInitiator(ctx context.Context, agentID brand.SessionID, op string) context.Context

WithInitiator 返回携带 initiator 的 context。

func WithoutInitiator

func WithoutInitiator(ctx context.Context) context.Context

WithoutInitiator 返回不携带任何 initiator 的 context(身份隔离)。

Types

type Agent

type Agent struct {
	// ID 会话 ID(复用 SessionLog 的 ID)。
	ID brand.SessionID
	// contains filtered or unexported fields
}

Agent 是代理执行器。

func NewAgent

func NewAgent(id brand.SessionID, log *session.SessionLog, sys *sysprompt.Assembler, pipeline *tools.Pipeline, adapter llm.LLMAdapter, options ...AgentOptions) *Agent

NewAgent 创建代理。 adapter 可为 nil(测试时由 Start 前的 mock 注入)。 options 可为 nil(使用默认配置)。

func (*Agent) Cancel

func (a *Agent) Cancel(cause CancelCause)

Cancel aborts the active turn and discards queued work unless KeepInbox is set.

func (*Agent) CancelWithOptions

func (a *Agent) CancelWithOptions(cause CancelCause, opts CancelOptions)

func (*Agent) Dispose

func (a *Agent) Dispose()

Dispose permanently closes the agent and cancels active and pending work. Tool and adapter implementations must honor context cancellation.

func (*Agent) Followup

func (a *Agent) Followup(input string) error

Followup queues a subsequent turn.

func (*Agent) Inbox

func (a *Agent) Inbox() *Inbox

Inbox 返回 Agent 的收件箱(待处理消息双队列)。

func (*Agent) Log

func (a *Agent) Log() *session.SessionLog

Log 返回事件溯源日志(供测试/上层读取派生状态)。

func (*Agent) Options

func (a *Agent) Options() AgentOptions

Options 返回 Agent 的配置(只读)。

func (*Agent) Run

func (a *Agent) Run(input string) error

Run queues a new turn. WhenIdle waits for all accepted work.

func (*Agent) SetRunContext

func (a *Agent) SetRunContext(parent context.Context, timeout time.Duration)

SetRunContext 绑定本次运行的上游 ctx(H01):可取消父 ctx + 可选超时预算。 timeout<=0 uses DefaultTimeout, or only parent cancellation when both are zero.

func (*Agent) SetToolProvider

func (a *Agent) SetToolProvider(fn func(name string) *tools.Tool)

SetToolProvider 注入工具解析函数。

func (*Agent) Status

func (a *Agent) Status() AgentStatus

Status 返回当前生命周期状态(idle/running)。

func (*Agent) WhenIdle

func (a *Agent) WhenIdle(ctx context.Context) error

WhenIdle 等待 Agent 活动达到静止。 如果当前已经是 idle,立即返回。

type AgentOptions

type AgentOptions struct {
	// Provider 路由名称(调用时必须有已注册的适配器)。
	// 为空时使用适配器的默认 provider。
	Provider string `json:"provider,omitempty"`

	// Model 是由选定 provider 适配器解释的模型 ID。
	// 为空时使用适配器的默认模型。
	Model string `json:"model,omitempty"`

	// ReasoningEffort 是适配器拥有的推理努力级别(provider/model 相关)。
	// 为空时使用适配器的默认设置。
	ReasoningEffort string `json:"reasoningEffort,omitempty"`

	// MaxTokens 是每次对话模型请求的最大输出 token 数。
	// 为 0 时使用适配器的默认限制。
	MaxTokens int `json:"maxTokens,omitempty"`

	// DefaultTimeout 是每次运行的默认超时(0 表示无超时)。
	DefaultTimeout time.Duration `json:"defaultTimeout,omitempty"`
}

AgentOptions 是 Agent 的创建配置(对齐官方 AgentOptions)。

这些选项在 Agent 创建时固定,运行时不可变。Persona 属于 system-prompt 部分,不在此配置中。

type AgentStatus

type AgentStatus string

AgentStatus 是 Agent 的生命周期状态(对齐官方 AgentStatus)。

在每次状态转换时通过 agent/status 事件发出:

  • idle:没有驱动程序活动
  • running:当唤醒输入开始可取消的 pre-step 处理时开始, 持续到驱动程序耗尽、关闭或检查点 turns

Disposal 将 Agent 从其注册表中移除;它不是第三个可观察状态。

const (
	// StatusIdle 表示 Agent 当前空闲(没有活动的驱动程序)。
	StatusIdle AgentStatus = "idle"
	// StatusRunning 表示 Agent 正在运行(有活动的驱动程序)。
	StatusRunning AgentStatus = "running"
)

type CancelCause

type CancelCause string

CancelCause 是取消原因分类(M18:5 类)。

const (
	// CancelUser 用户主动取消。
	CancelUser CancelCause = "user"
	// CancelParent 父代理取消(subagent 场景)。
	CancelParent CancelCause = "parent"
	// CancelHook hook 因拒绝触发取消。
	CancelHook CancelCause = "hook"
	// CancelDisposed 代理被释放(dispose)导致的取消。
	CancelDisposed CancelCause = "disposed"
	// CancelLegacy 历史/兼容性取消路径。
	CancelLegacy CancelCause = "legacy"
)

取消原因枚举(与上游 Agent.Cancel 的 5 类对齐)。

func AllCancelCauses

func AllCancelCauses() []CancelCause

AllCancelCauses 返回全部 5 种取消原因(测试与校验用)。

func ExtractCancelCause

func ExtractCancelCause(events []session.SessionEvent) (CancelCause, bool)

ExtractCancelCause 从事件日志中提取最后一次取消原因分类。 返回 (cause, true) 表示存在取消记录;否则 (cause, false)。

type CancelOptions

type CancelOptions struct {
	// KeepInbox 保留排队和引导中的 inbox 项,而不是丢弃它们。
	// 活动的 turn 仍然被中止,但未开始和待处理的工作会保留供后续 turn 使用,
	// 并且不会记录 canceled inbox splice。
	KeepInbox bool `json:"keepInbox,omitempty"`
}

CancelOptions 是取消选项(对齐官方 CancelOptions)。

type ConsumedWork

type ConsumedWork struct {
	// End 是最后一个结算了已消费工作的已关闭 turn:它进入过模型 step,
	// 或 claim 了收件箱输入后失败/被中止/被拒绝。没有任何 turn 结算工作时为 nil。
	End *session.SessionEvent
	// DroppedUnrun 表示在上述 turn 之后,已被接受的工作在收件箱中被取消、从未运行。
	// 这是"任何 turn 都来不及打开就被取消的输入"唯一的账目——没有 turn/end 描述它。
	DroppedUnrun bool
}

ConsumedWork 是一份 agent 日志对其消费工作的结算。

func FoldConsumedWork

func FoldConsumedWork(events []session.SessionEvent) ConsumedWork

FoldConsumedWork 单遍折叠一份 agent 日志(或其拥有的后缀),得到已消费工作的结算。 每个输入都是日志本身,调用方无需在取消前采样实时状态,因此任何人发起的取消 (持有者的 teardown、祖先的中断、卸载中的插件)都得到一致读法。

type Inbox

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

Inbox 是持久化 Agent 收件箱事件的增量投影。

它维护两个列表:next-turn 和 next-step,并通过 splice 操作进行变更。

func NewInbox

func NewInbox(log *session.SessionLog, notifications InboxNotifications) *Inbox

NewInbox 创建一个新的 Inbox,并从会话日志中重放所有 agent/inbox/spliced 事件。

func (*Inbox) Claim

func (inbox *Inbox) Claim(log *session.SessionLog, target session.InboxTarget, turn uint64) []UserMessage

Claim 移除并返回为一个 step 提议的完整批次,并发布每条认领的消息。 持久化 splice 是纯删除。

target 表示此边界是否还消费一个排队的 turn。 turn 是将拥有该批次的 turn 编号。 返回 next-step 输入,后跟排队的 turn(如果请求)。

func (*Inbox) Clear

func (inbox *Inbox) Clear(log *session.SessionLog)

Clear 持久化取消所有待处理输入,先清除 next-step 再清除 next-turn。

func (*Inbox) HasPending

func (inbox *Inbox) HasPending() bool

HasPending 返回任一待处理消息列表是否包含工作。

func (*Inbox) NextStep

func (inbox *Inbox) NextStep() []UserMessage

NextStep 返回等待下一个 step 边界的输入(只读)。

func (*Inbox) NextTurn

func (inbox *Inbox) NextTurn() []UserMessage

NextTurn 返回等待下一个 turn 的消息(只读)。

func (*Inbox) Push

func (inbox *Inbox) Push(log *session.SessionLog, target session.InboxTarget, message UserMessage)

Push 追加一条消息到指定列表的末尾,并持久化。

type InboxNotifications

type InboxNotifications struct {
	// Inserted 发布一条插入的消息。
	Inserted func(message UserMessage)
	// Discarded 发布一条丢弃的消息。
	Discarded func(message UserMessage)
	// Claimed 在其拥有的 turn 内发布一条认领的消息。
	Claimed func(message UserMessage, turn uint64)
}

InboxNotifications 是 Inbox 变更的实时通知。

type Initiator

type Initiator struct {
	// AgentID 发起操作的 Agent 会话 ID。
	AgentID brand.SessionID
	// Op 操作名(如 "Run" / "Followup" / "executeTool")。
	Op string
}

Initiator 描述一次操作的发起者。

func MustInitiator

func MustInitiator(ctx context.Context) *Initiator

MustInitiator 便捷版本:无 initiator 时 panic(用于内部已保证有 initiator 的调用点)。

func RequireInitiator

func RequireInitiator(ctx context.Context) (*Initiator, error)

RequireInitiator 取出 initiator;若不存在则返回 UnauthorizedInitiatorError。 用于所有需要"安全归因"的操作入口。

type ModelSelection

type ModelSelection struct {
	// Provider 已注册的提供方路由。
	Provider string
	// Model 提供方拥有的模型 id。
	Model string
	// ReasoningEffort 适配器拥有的推理努力;为空表示采用提供方/默认行为。
	ReasoningEffort string
}

ModelSelection 是为一次活跃 Agent 选定的完整 provider/model 及可选推理努力。

type ModelSelectionRef

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

ModelSelectionRef 是可变模型选择 + 为当前 step 捕获的快照。

func NewModelSelectionRef

func NewModelSelectionRef() *ModelSelectionRef

NewModelSelectionRef 创建空选择器。

func (*ModelSelectionRef) Apply

Apply 用当前 step 捕获的快照改写请求配置,对齐官方 agent/request 语义:

  • 没有捕获选择 → 原样返回(继承配置);
  • 有捕获 → 先清除继承的 reasoningEffort,再应用 provider/model; 捕获自带 effort 则写入,为空则保持清除(恢复所选模型的提供方/默认行为)。

func (*ModelSelectionRef) Assembled

func (r *ModelSelectionRef) Assembled() *ModelSelection

Assembled 返回当前 step 已捕获快照的拷贝。

func (*ModelSelectionRef) Capture

func (r *ModelSelectionRef) Capture() *ModelSelection

Capture 在一次 step 的 prompt 装配边界调用:把当前 current 冻结为 assembled, 返回该快照(即便 current 为 nil 也返回 nil,表示本 step 不指定模型)。

func (*ModelSelectionRef) Current

func (r *ModelSelectionRef) Current() *ModelSelection

Current 返回当前选择的拷贝。

func (*ModelSelectionRef) Select

func (r *ModelSelectionRef) Select(sel *ModelSelection)

Select 更新"下一步"要用的选择(可在运行期并发切换;nil 表示清除选择、用默认)。

type PreStepDecision

type PreStepDecision struct {
	// Kind 是决策类型:"reject" 或 "enter"。
	Kind string `json:"kind"`
	// Messages 是进入 step 时携带的用户消息(Kind=enter 时有效)。
	Messages []UserMessage `json:"messages,omitempty"`
	// StartsRequestSeries 表示在此 step 的已接纳消息之前启动一个不同的
	// model-message 系列(Kind=enter 时可选)。
	StartsRequestSeries bool `json:"startsRequestSeries,omitempty"`
}

PreStepDecision 是循环是否以及携带哪些消息进入提议的 step (对齐官方 PreStepDecision)。

func EnterPreStep

func EnterPreStep(messages ...UserMessage) PreStepDecision

EnterPreStep 创建一个 enter 决策(携带指定消息进入 step)。

func RejectPreStep

func RejectPreStep() PreStepDecision

RejectPreStep 创建一个 reject 决策(不进入 step)。

type RequestConfig

type RequestConfig struct {
	Provider        string
	Model           string
	ReasoningEffort string
}

RequestConfig 是一次模型请求中与模型路由相关的可改字段。

type RequestErrorAction

type RequestErrorAction struct {
	// Kind 动作类型。
	Kind RequestErrorActionKind `json:"kind"`
	// Reason 决策原因(审计)。
	Reason string `json:"reason,omitempty"`
}

RequestErrorAction 是一次 request-error 的决策结果。

func ResolveRequestError

func ResolveRequestError(chain *RequestErrorWaterfall, p *RequestErrorPayload) RequestErrorAction

ResolveRequestError 运行 request-error 瀑布得到最终动作。

  • 若某个中间件写入了 p.Action 则直接返回;
  • 否则链放行到兜底:应用 TerminalRetryDecision。

func TerminalRetryDecision

func TerminalRetryDecision(p *RequestErrorPayload) RequestErrorAction

TerminalRetryDecision 是兜底终端决策: 错误可重试且未超过最大次数 → retry;否则 abort(并以 error 关闭 turn)。

type RequestErrorActionKind

type RequestErrorActionKind string

RequestErrorActionKind 是 request-error 处理动作类型。

const (
	ActionRetry RequestErrorActionKind = "retry"
	ActionAbort RequestErrorActionKind = "abort"
)

动作枚举:仅 retry 与 abort 两种。

type RequestErrorPayload

type RequestErrorPayload struct {
	// Err 触发请求错误的底层错误。
	Err error
	// RetryCount 已发生的重试次数。
	RetryCount int
	// MaxRetries 允许的最大重试次数。
	MaxRetries int
	// RetryableError 错误是否可重试(overload/rate-limit)。
	RetryableError bool
	// Action 由瀑布写入的最终动作。
	Action *RequestErrorAction
}

RequestErrorPayload 是 request-error 瀑布的共享载荷。

func NewRequestErrorPayload

func NewRequestErrorPayload(err error, retryCount, maxRetries int) *RequestErrorPayload

NewRequestErrorPayload 构造载荷并预计算可重试性。

type RequestErrorWaterfall

type RequestErrorWaterfall = waterfall.Chain[RequestErrorPayload]

RequestErrorWaterfall 是 request-error 处理瀑布(复用 M02 waterfall.Chain)。 中间件可通过写入 p.Action 并短路(不调用 next)终止链。

func NewRequestErrorWaterfall

func NewRequestErrorWaterfall(handlers ...waterfall.Handler[RequestErrorPayload]) *RequestErrorWaterfall

NewRequestErrorWaterfall 构建 request-error 瀑布链。

type SessionStartSource

type SessionStartSource string

SessionStartSource 是会话生命周期开始的原因 (对齐官方 SessionStartSource)。

  • startup:种子创建
  • resume:持久化加载
  • clear:清除后重新开始
  • compact:压缩后重新开始
const (
	// StartSourceStartup 表示种子创建。
	StartSourceStartup SessionStartSource = "startup"
	// StartSourceResume 表示持久化加载。
	StartSourceResume SessionStartSource = "resume"
	// StartSourceClear 表示清除后重新开始。
	StartSourceClear SessionStartSource = "clear"
	// StartSourceCompact 表示压缩后重新开始。
	StartSourceCompact SessionStartSource = "compact"
)

type UnauthorizedInitiatorError

type UnauthorizedInitiatorError struct {
	Op string
}

UnauthorizedInitiatorError 表示在无 initiator 包裹时调用了 requireInitiator。

func (*UnauthorizedInitiatorError) Error

Error 实现 error 接口。

type UserMessage

type UserMessage struct {
	// ID 是消息 ID。
	ID string `json:"id"`
	// Content 是消息内容。
	Content string `json:"content"`
	// Source 是消息来源("run" / "followup" / "inbox" 等)。
	Source string `json:"source,omitempty"`
	// CreatedAt 是创建时间。
	CreatedAt time.Time `json:"createdAt,omitempty"`
}

UserMessage 是用户消息(简化版,对齐官方 UserMessage)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL