agent

package
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Jul 4, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package agent 提供 AI Agent 的核心能力。

包含以下核心组件：

  • Agent — 定义 Agent 生命周期（Run / Stream / RunWithMessages）
  • Session — 内存会话管理，维护对话历史
  • ReActLoop — Reason-Act 迭代策略
  • ContextCompressor — 长对话自动压缩
  • AgentConfig — 配置参数
  • Option — Functional Options 配置模式

基本用法： 

ag := agent.NewAgent(client, agent.DefaultConfig())
result, err := ag.Run(ctx, "你好")

Index

Constants

This section is empty.

Variables

View Source 
var ErrHandoffCycleDetected = errors.New("handoff cycle detected: agent visited too many times")

ErrHandoffCycleDetected 表示检测到循环跳转。

当同一个 Agent 在跳转历史中被访问超过 2 次时触发， 通常意味着 Agent 之间形成了循环依赖。

View Source 
var ErrHandoffMaxHops = errors.New("handoff maximum hops exceeded")

ErrHandoffMaxHops 表示超过最大跳转次数限制。

当跳转链路长度超过 maxHandoffHops 时触发， 是防止 Agent 链路过长的兜底保护机制。

View Source 
var ErrMaxNestingTooLarge = errors.New("max nesting depth cannot exceed hard limit 10")

ErrMaxNestingTooLarge 配置的最大嵌套深度超过硬上限时返回的错误。

硬上限为 10 层，防止无限递归导致的资源耗尽。

View Source 
var ErrNestingDepthExceeded = errors.New("agent tool nesting depth exceeded")

ErrNestingDepthExceeded 嵌套深度超过最大限制时返回的哨兵错误。

当 Agent-as-Tool 调用层数超过配置的最大深度时，Execute 会包装此错误返回。

View Source 
var ErrSessionNotFound = errors.New("session not found")

ErrSessionNotFound 表示会话 ID 在 SessionStore 中不存在。

Functions

func CombineAbortSignals 

func CombineAbortSignals(signals ...<-chan struct{}) <-chan struct{}

CombineAbortSignals returns a channel that closes when ANY input signal fires.

func HandoffTool 

func HandoffTool(handoff Handoff, tracker *HandoffTracker, fromAgentID string) tool.Tool

HandoffTool 创建一个 Handoff 工具实例。

将 Handoff 配置包装为实现了 tool.Tool 接口的对象， 可直接注册到 Agent 的工具注册表中供 LLM 调用。

参数说明：

  • handoff: 跳转配置
  • tracker: 跳转追踪器，传 nil 则不追踪
  • fromAgentID: 发起跳转的源 Agent ID

返回：

  • tool.Tool: 可注册的工具实例

func NewAgentTool 

func NewAgentTool(name string, description string, ag Agent, opts ...AgentToolOption) tool.Tool

NewAgentTool 将 Agent 包装为 tool.Tool，使其可被父 Agent 作为工具调用。

这实现了 Agent-as-Tool 模式，支持嵌套调用（默认最大 3 层）。 子 Agent 使用自己的 Session，不与父 Agent 共享状态。

参数说明：

  • name - 工具名称，需唯一
  • description - 工具描述，供 AI 理解工具用途
  • ag - 被包装的子 Agent
  • opts - 可选配置（嵌套深度、摘要模式）

返回：

  • tool.Tool - 包装后的工具实例

Types

type AbortController 

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

AbortController manages cancellation signals with parent-child propagation.

When an AbortController is aborted, all of its descendants are also aborted. The Signal channel is closed when the controller is aborted and can be used with select statements to detect cancellation.

func NewAbortController 

func NewAbortController() *AbortController

NewAbortController creates a new AbortController that is not yet aborted.

func (*AbortController) Abort 

func (ac *AbortController) Abort(reason string)

Abort triggers cancellation with the provided reason.

func (*AbortController) Child 

func (ac *AbortController) Child() *AbortController

Child creates a child controller. When the parent aborts, all children abort.

If the parent is already aborted when Child is called, the child is aborted immediately before being returned.

func (*AbortController) IsAborted 

func (ac *AbortController) IsAborted() bool

IsAborted reports whether the controller has been aborted.

func (*AbortController) Reason 

func (ac *AbortController) Reason() string

Reason returns the abort reason, or an empty string if not aborted.

func (*AbortController) Signal 

func (ac *AbortController) Signal() <-chan struct{}

Signal returns a channel that is closed when the controller is aborted.

type Agent 

type Agent interface {
	// Run 执行一个 Agent 任务并返回最终结果。
	Run(ctx context.Context, input string) (*AgentResult, error)

	// Stream 执行一个 Agent 任务并通过 channel 返回事件。
	Stream(ctx context.Context, input string) (<-chan AgentEvent, error)

	// RunWithMessages 使用现有的消息历史执行。
	RunWithMessages(ctx context.Context, messages []bamboo.BambooMessage) (*AgentResult, error)

	// AddTool 向 Agent 注册一个工具。
	AddTool(t tool.Tool) error

	// SetSystemPrompt 更新系统提示词。
	SetSystemPrompt(prompt string)
}

Agent 是 AI Agent 的核心接口。

定义了 Agent 的完整生命周期，包括：

  • 任务执行（Run / Stream）
  • 历史消息复用（RunWithMessages）
  • 工具注册（AddTool）
  • 系统提示词配置（SetSystemPrompt）

func NewAgent 

func NewAgent(client bamboo.BambooClient, config AgentConfig) Agent

NewAgent 使用给定的客户端和配置创建一个新的 Agent。

如果 config.LoopStrategy 为 nil，则使用默认的 ReActLoop。

func NewAgentWithOptions 

func NewAgentWithOptions(client bamboo.BambooClient, opts ...Option) Agent

NewAgentWithOptions 使用函数式选项创建 Agent。

参数说明：

  • client - BM-SDK 客户端
  • opts - 可选的配置选项

返回：

  • Agent - 配置好的 Agent 实例

type AgentConfig 

type AgentConfig struct {
	// Model 是使用的模型名称。
	Model string

	// MaxTokens 是单次 AI 调用的最大 token 数。
	MaxTokens int64

	// Temperature 是 AI 生成的温度参数（0.0-1.0）。
	Temperature *float64

	// SystemPrompt 是系统提示词，用于设定 Agent 角色。
	SystemPrompt string

	// MaxIterations 是 ReAct 循环的最大迭代次数。
	MaxIterations int

	// LoopStrategy 是循环策略，nil 时使用默认 ReActLoop。
	LoopStrategy LoopStrategy

	// MaxContextTokens 是上下文的最大 token 数。
	MaxContextTokens int64

	// Compressor 是上下文压缩器，nil 时禁用压缩。
	Compressor ContextCompressor

	// Compressors 是压缩管道（Pipeline 模式）。
	// 与 Compressor 字段互斥：如果非空，优先使用 Pipeline 模式。
	Compressors []ContextCompressor

	// MaxConcurrentTools 是并发执行的最大工具数量。
	MaxConcurrentTools int

	// ThinkingConfig 是思考/推理配置，控制模型的推理行为。
	ThinkingConfig *bamboo.ThinkingConfig

	// SystemCacheControl 是 system prompt 的缓存控制标记（Anthropic prompt caching）。
	SystemCacheControl *provider.CacheControl

	// PromptCacheKey 是 OpenAI prompt cache 路由粘性键。
	PromptCacheKey string

	// MaxRecoveryAttempts 是 max_tokens 重试次数（默认 3）。
	MaxRecoveryAttempts int

	// Hooks 是 Agent 的钩子列表（可选，默认为空）。
	//
	// 注册的 Hook 会在 Agent 生命周期中的特定事件点被触发，
	// 可用于审计、拦截、输入变换等场景。nil 或空切片表示禁用 Hook，
	// 此时 HookRegistry 的 Execute 调用为零开销。
	Hooks []Hook

	// Deciders 是 Agent 的决策钩子列表（可选，默认为空）。
	//
	// 在 Agent 执行完成后、返回结果前被调用，可基于运行时信息
	// 决定是否丢弃输出或要求修订。多个 Decider 按注册顺序执行，
	// 布尔字段通过 OR 合并。
	Deciders []Decider

	// AllowedTools 是工具白名单（为空时允许所有工具）。
	AllowedTools []string

	// DisallowedTools 是工具黑名单（优先级高于白名单）。
	DisallowedTools []string

	// PermissionHandler 是可选的权限决策函数。
	//
	// 在工具执行前被调用，返回 allow/deny/ask 决策。
	// nil 时跳过权限检查，回退到 AllowedTools/DisallowedTools 过滤逻辑。
	PermissionHandler PermissionHandler

	// PermissionMode 控制工具权限的评估方式。
	//
	// 可选值：
	//   - PermissionModeDefault（默认）— 使用 PermissionHandler 进行决策
	//   - PermissionModePlan — 自动允许只读工具（实现 ConcurrencySafeTool），写入类交给 PermissionHandler
	//   - PermissionModeBypass — 跳过所有权限检查
	//
	// 空字符串等同于 PermissionModeDefault。
	PermissionMode PermissionMode

	// SessionID 是当前 Agent 会话的唯一标识。
	//
	// 用于会话持久化场景：配合 Store 字段实现会话的 Save/Load/Resume。
	// 为空时表示不使用持久化会话标识。
	SessionID string

	// Store 是会话持久化存储后端。
	//
	// 可选实现包括 MemoryStore（内存）和 FileStore（磁盘文件）。
	// nil 时表示不启用会话持久化。
	Store SessionStore

	// Fallback 是模型降级配置（可选）。
	//
	// 当主模型返回非 413 的临时错误（overload/503 等）时，
	// 按顺序尝试 FallbackConfig.Models 中的备用模型。
	Fallback *FallbackConfig

	// Tokenizer 用于精确计算 token 数量（可选，默认 EstimateTokenizer）。
	Tokenizer Tokenizer
}

AgentConfig 保存 Agent 的所有配置参数。

通过 `DefaultConfig` 获取默认值，或使用 Functional Options 模式覆盖。

func DefaultConfig 

func DefaultConfig() AgentConfig

DefaultConfig 返回合理的默认配置。

返回：

  • AgentConfig - 包含默认配置值的结构体

type AgentEvent 

type AgentEvent struct {
	Type       AgentEventType      // 事件类型
	Content    string              // 事件内容
	Thinking   string              // 思考内容（AgentEventThinking 事件使用）
	StopReason bamboo.FinishReason // 停止原因（AgentEventStop 事件使用）
	Usage      *bamboo.Usage       // Token 用量（AgentEventUsage 事件使用）
	ToolCall   *ToolCallRecord     // 工具调用记录（可选）
	Result     *AgentResult        // 代理结果（可选）
	Error      error               // 错误信息（可选）
}

AgentEvent 代理事件结构体 包含事件类型、内容、工具调用记录、代理结果和错误信息

type AgentEventType 

type AgentEventType string

AgentEventType 代理事件类型 用于标识不同类型的代理事件，支持流式输出和状态跟踪 

const (
	// AgentEventText 文本输出事件
	AgentEventText AgentEventType = "text"

	// AgentEventThinking 思考事件
	AgentEventThinking AgentEventType = "thinking"

	// AgentEventToolCall 工具调用事件
	AgentEventToolCall AgentEventType = "tool_call"

	// AgentEventToolResult 工具执行结果事件
	AgentEventToolResult AgentEventType = "tool_result"

	// AgentEventComplete 代理完成事件
	AgentEventComplete AgentEventType = "complete"

	// AgentEventError 错误事件
	AgentEventError AgentEventType = "error"

	// AgentEventCompress 压缩事件
	AgentEventCompress AgentEventType = "compress"

	// AgentEventUsage Token 使用量事件
	AgentEventUsage AgentEventType = "usage"

	// AgentEventStop 停止事件（含 stopReason）
	AgentEventStop AgentEventType = "stop"
)

type AgentResult 

type AgentResult struct {
	Content    string                 // 最终内容输出
	Messages   []bamboo.BambooMessage // 消息历史记录
	ToolCalls  []ToolCallRecord       // 工具调用记录列表
	Usage      bamboo.Usage           // Token使用统计
	Iterations int                    // 迭代次数
	ExitReason TerminalReason         // 退出原因（end_turn/aborted/blocking_limit/model_error/max_iterations）
}

AgentResult 代理执行结果 包含代理执行的完整信息，包括消息、工具调用和资源使用

type AgentToolOption 

type AgentToolOption func(*agentToolConfig)

AgentToolOption 配置 AgentTool 行为的 Functional Option。

func WithMaxNestingDepth 

func WithMaxNestingDepth(n int) AgentToolOption

WithMaxNestingDepth 设置 Agent-as-Tool 的最大嵌套深度。

参数说明：

  • n - 最大深度值，必须 > 0 且 <= 10

使用示例： 

tool := NewAgentTool("helper", "desc", ag, WithMaxNestingDepth(2))

func WithSummaryMode 

func WithSummaryMode(b bool) AgentToolOption

WithSummaryMode 设置是否只返回摘要内容。

参数说明：

  • b - true 仅返回 Content 字符串；false 返回完整序列化结果

使用示例： 

tool := NewAgentTool("helper", "desc", ag, WithSummaryMode(false))

type CollapseCompressor 

type CollapseCompressor struct {
	// CollapseThreshold 是触发折叠的连续同类型消息数量阈值，默认 5。
	CollapseThreshold int
}

CollapseCompressor 基于主题折叠的上下文压缩器实现。

将连续的同类型消息（user / assistant / tool_result）分组，当某组消息 数量达到阈值时，将该组除最后一条外的消息折叠为单条摘要消息，从而 减少消息总数。

压缩策略：

  • 按消息类型（user / assistant / tool_result）分组连续消息
  • 组内消息数 >= CollapseThreshold 时触发折叠
  • 折叠后保留组内最后一条消息，前置消息替换为摘要
  • 摘要格式："[{N} {type} messages collapsed]"

func NewCollapseCompressor 

func NewCollapseCompressor() *CollapseCompressor

NewCollapseCompressor 创建基于主题折叠的上下文压缩器。

使用默认配置初始化：

  • CollapseThreshold - 5

返回：

  • *CollapseCompressor - 新创建的压缩器实例

func (*CollapseCompressor) Compress 

func (c *CollapseCompressor) Compress(_ context.Context, messages []bamboo.BambooMessage, _ int64) ([]bamboo.BambooMessage, error)

Compress 折叠连续的同类型消息组，保留每组最后一条消息。

参数说明：

  • ctx - 上下文（当前未使用，预留以符合 ContextCompressor 接口）
  • messages - 原始消息列表
  • maxTokens - 最大 token 数限制（当前未使用）

返回：

  • []bamboo.BambooMessage - 折叠后的消息列表
  • error - 始终为 nil（此压缩器不会失败）

type ContextCompressor 

type ContextCompressor interface {
	Compress(ctx context.Context, messages []bamboo.BambooMessage, maxTokens int64) ([]bamboo.BambooMessage, error)
}

ContextCompressor 定义上下文压缩器的接口。

定义了上下文压缩的核心能力，包括：

  • Compress - 压缩消息历史，保留关键信息

type ContinueReason 

type ContinueReason string

ContinueReason describes why the ReAct loop continues iterating. 

const (
	// ContinueToolUse indicates the model requested one or more tool calls.
	ContinueToolUse ContinueReason = "tool_use"

	// ContinueMaxTokensRetry indicates the loop is retrying after hitting max_tokens.
	ContinueMaxTokensRetry ContinueReason = "max_tokens_retry"

	// ContinueCollapseDrain indicates the loop is retrying after a collapse drained the budget.
	ContinueCollapseDrain ContinueReason = "collapse_drain_retry"

	// ContinueReactiveCompact indicates the loop is retrying after a reactive compaction.
	ContinueReactiveCompact ContinueReason = "reactive_compact_retry"

	// ContinueStopHook indicates the loop is retrying because a stop hook was triggered.
	ContinueStopHook ContinueReason = "stop_hook_retry"

	// ContinueModelFallback indicates the loop is retrying after falling back to another model.
	ContinueModelFallback ContinueReason = "model_fallback_retry"
)

type Decider 

type Decider interface {
	// BeforeFinalize 在 Agent 即将返回结果前被调用。
	//
	// 参数说明：
	//   - ctx - 调用方上下文（用于取消控制）
	//   - info - 运行时信息（迭代次数、工具调用次数等）
	//   - result - 当前 Agent 执行结果（只读，不应修改）
	//
	// 返回：
	//   - *FinalizeDecision - 决策结果，nil 表示不干预
	//   - error - 执行错误，非 nil 时会中断后续 Decider 执行
	BeforeFinalize(ctx context.Context, info RunInfo, result *AgentResult) (*FinalizeDecision, error)
}

Decider 是决策钩子接口。

在 Agent 执行完成后、返回结果前被调用， 可以基于 RunInfo 和 AgentResult 决定是否丢弃输出或要求修订。

与 Hook 的区别：

  • Hook 作用于迭代内的事件点（工具调用前后、迭代前后等）
  • Decider 作用于整个 Run 结束后的「最终决策点」

type EstimateTokenizer 

type EstimateTokenizer struct{}

EstimateTokenizer uses the simple chars/4 heuristic.

func (EstimateTokenizer) CountMessageTokens 

func (e EstimateTokenizer) CountMessageTokens(messages []bamboo.BambooMessage) int

CountMessageTokens 使用 chars/4 启发式估算消息列表的 token 总数。

func (EstimateTokenizer) CountTokens 

func (e EstimateTokenizer) CountTokens(text string) int

CountTokens 使用 chars/4 启发式估算文本 token 数。

type FallbackConfig 

type FallbackConfig struct {
	// Models is the ordered list of models to try after the primary model fails.
	Models []string

	// MaxRetries is the max retry count per model (default: 1).
	MaxRetries int

	// StripThinking removes thinking blocks from messages when switching models.
	StripThinking bool
}

FallbackConfig defines model fallback behavior.

When the primary model returns a non-413 error (overload, 503, etc.), the loop tries each model in Models order until one succeeds.

type FileStore 

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

FileStore 是 SessionStore 的文件系统实现。

将会话消息以 JSON 文件形式持久化到磁盘，每个会话对应一个文件 （文件名为 `<sessionID>.json`）。适用于需要跨进程恢复会话的场景。

并发安全说明：所有方法通过互斥锁保护文件操作，可安全并发调用。

func NewFileStore 

func NewFileStore(baseDir string) (*FileStore, error)

NewFileStore 创建一个新的文件会话存储。

如果 baseDir 不存在会自动创建（包含所有父级目录）。

参数说明：

  • baseDir - 会话文件存储的根目录

返回：

  • *FileStore - 文件存储实例
  • error - 目录创建失败时返回错误

func (*FileStore) Delete 

func (f *FileStore) Delete(_ context.Context, sessionID string) error

Delete 删除指定会话的持久化文件。

如果会话文件不存在，视为幂等操作，不返回错误。

参数说明：

  • ctx - 上下文（当前实现未使用，预留以符合 SessionStore 接口）
  • sessionID - 要删除的会话唯一标识

返回：

  • error - 文件删除失败时返回（文件不存在除外）

func (*FileStore) Exists 

func (f *FileStore) Exists(_ context.Context, sessionID string) (bool, error)

Exists 检查指定会话的持久化文件是否存在。

参数说明：

  • ctx - 上下文（当前实现未使用，预留以符合 SessionStore 接口）
  • sessionID - 要检查的会话唯一标识

返回：

  • bool - true 表示会话文件存在
  • error - 文件状态检查失败时返回

func (*FileStore) Load 

func (f *FileStore) Load(_ context.Context, sessionID string) ([]bamboo.BambooMessage, error)

Load 从磁盘读取指定会话的消息并反序列化。

参数说明：

  • ctx - 上下文（当前实现未使用，预留以符合 SessionStore 接口）
  • sessionID - 会话唯一标识

返回：

  • []bamboo.BambooMessage - 反序列化后的消息列表
  • error - 会话不存在时返回 ErrSessionNotFound，反序列化失败时返回对应错误

func (*FileStore) Save 

func (f *FileStore) Save(_ context.Context, sessionID string, messages []bamboo.BambooMessage) error

Save 将指定会话的消息序列化为 JSON 并写入磁盘文件。

参数说明：

  • ctx - 上下文（当前实现未使用，预留以符合 SessionStore 接口）
  • sessionID - 会话唯一标识，用作文件名
  • messages - 要持久化的消息列表

返回：

  • error - 序列化或文件写入失败时返回

type FinalizeDecision 

type FinalizeDecision struct {
	// DiscardOutput 表示是否丢弃当前输出。
	DiscardOutput bool

	// Revise 表示是否需要修订（重新执行）。
	Revise bool

	// Reason 是决策原因，用于审计和调试。
	Reason string
}

FinalizeDecision 是 Decider 返回的决策结果。

在 Agent 执行完成后、返回结果前被使用：

  • DiscardOutput=true 表示丢弃当前输出（不返回给调用方）
  • Revise=true 表示需要重新执行一次（修订）
  • Reason 是人类可读的决策原因

func RunDeciders 

func RunDeciders(ctx context.Context, deciders []Decider, info RunInfo, result *AgentResult) (*FinalizeDecision, error)

RunDeciders 按顺序执行多个 Decider，使用 OR 合并布尔字段。

行为约定：

  • 没有 Decider 时返回空的 FinalizeDecision（默认放行）
  • 任一 Decider 返回 error 时立即返回该 error，不继续执行后续 Decider
  • 所有 Decider 的布尔字段按 OR 合并（任一为 true 则结果为 true）
  • 所有 Decider 的 Reason 按注册顺序用 "; " 拼接

参数说明：

  • ctx - 调用方上下文
  • deciders - Decider 列表（按注册顺序）
  • info - 运行时信息
  • result - 当前 Agent 执行结果

返回：

  • *FinalizeDecision - 合并后的决策结果
  • error - 执行错误

type Handoff 

type Handoff struct {
	// ToAgentID 是目标 Agent 的唯一标识符。
	ToAgentID string

	// Description 是转移功能的描述，展示给 LLM 以辅助决策。
	Description string

	// ToolName 可选：覆盖自动生成的工具名。
	// 为空时自动生成 "handoff_to_<ToAgentID>"。
	ToolName string

	// Filter 可选：动态过滤函数。
	// 返回 false 时 HandoffTool 执行会返回不可用提示而非真正跳转。
	Filter func(ctx context.Context) bool

	// OnInvoke 可选：转移回调。
	// 在跳转记录成功后执行，可用于准备上下文或通知目标 Agent。
	OnInvoke func(ctx context.Context, args HandoffArgs) error
}

Handoff 定义 Agent 间转移的配置。

描述了从当前 Agent 转移到目标 Agent 的完整信息， 包括目标 Agent ID、描述信息、可选的过滤条件和回调函数。

字段说明：

  • ToAgentID: 目标 Agent 的唯一标识符
  • Description: 转移功能的描述，会作为工具描述展示给 LLM
  • ToolName: 可选的自定义工具名，为空时自动生成为 "handoff_to_<ToAgentID>"
  • Filter: 可选的上下文过滤函数，返回 false 时表示当前不可用
  • OnInvoke: 可选的转移回调，在跳转记录成功后执行

type HandoffArgs 

type HandoffArgs struct {
	// Reason 是转移原因，必填字段。
	Reason string `json:"reason"`

	// Note 是给目标 Agent 的上下文提示，选填字段。
	Note string `json:"note"`
}

HandoffArgs 是 Handoff 工具的输入参数。

当 LLM 决定进行 Agent 转移时，会通过工具参数传入这些信息。

字段说明：

  • Reason: 转移原因，说明为什么要转移到目标 Agent
  • Note: 给目标 Agent 的上下文提示，帮助目标 Agent 快速理解任务

type HandoffTracker 

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

HandoffTracker 追踪 Agent 跳转历史并检测循环。

通过记录每次跳转的 from→to 路径，实现两个层级的保护：

  • 循环检测：同一 Agent 被访问超过 2 次时判定为循环
  • 最大跳转限制：跳转次数超过 maxHandoffHops（5）时拒绝继续

非并发安全，调用方需自行保证同一跳转链路串行记录。

func NewHandoffTracker 

func NewHandoffTracker() *HandoffTracker

NewHandoffTracker 创建一个新的 HandoffTracker。

返回初始化的空跳转追踪器，后续通过 Record 方法记录跳转。

返回：

  • *HandoffTracker: 新建的跳转追踪器

func (*HandoffTracker) GetHistory 

func (t *HandoffTracker) GetHistory() []string

GetHistory 返回跳转历史的副本。

返回当前已记录的所有跳转路径，格式为 "fromID->toID" 的字符串切片。 返回的是副本，修改不会影响内部状态。

返回：

  • []string: 跳转历史路径列表

func (*HandoffTracker) Record 

func (t *HandoffTracker) Record(fromID, toID string) error

Record 记录一次 Agent 间跳转。

在记录新跳转后执行两项检查：

  1. 最大跳转次数检查：超过 maxHandoffHops 返回 ErrHandoffMaxHops
  2. 循环检测：同一 Agent 被访问超过 2 次返回 ErrHandoffCycleDetected

参数说明：

  • fromID: 源 Agent ID
  • toID: 目标 Agent ID

返回：

  • error: 检测到循环或超过最大跳转次数时返回对应错误

type Hook 

type Hook interface {
	// Event 返回此 Hook 监听的事件类型。
	Event() HookEvent

	// Execute 执行 Hook 逻辑并返回结果。
	//
	// 参数说明：
	//   - ctx - 带有 5s 超时的上下文（由 HookRegistry 注入）
	//   - hctx - 当前事件的上下文信息
	//
	// 返回：
	//   - *HookResult - Hook 执行结果（nil 表示不干预，等同于 continue）
	//   - error - 执行错误
	Execute(ctx context.Context, hctx HookContext) (*HookResult, error)
}

Hook 是所有具体钩子需要实现的接口。

一个 Hook 实例只绑定到一个 HookEvent，由 Event() 声明。 Execute 在 HookRegistry 管理下被调用，享有独立的 5s 超时保护。

type HookAction 

type HookAction string

HookAction 定义 Hook 执行后的后续动作。 

const (
	// HookActionContinue 表示继续正常流程（默认）。
	HookActionContinue HookAction = "continue"

	// HookActionDeny 表示拒绝当前操作，立即中断。
	HookActionDeny HookAction = "deny"

	// HookActionTransform 表示使用 TransformedInput 替换原始输入后继续。
	HookActionTransform HookAction = "transform"
)

type HookContext 

type HookContext struct {
	// Event 是触发此 Hook 的事件类型。
	Event HookEvent

	// ToolName 是当前操作的工具名称（tool 事件时有值）。
	ToolName string

	// Input 是工具输入的原始 JSON（pre_tool_use 时有值）。
	Input []byte

	// Output 是工具输出的文本结果（post_tool_use 时有值）。
	Output string

	// Iteration 是当前 ReAct 循环的迭代序号（0-based，iteration 事件时有值）。
	Iteration int
}

HookContext 提供 Hook 执行时的上下文信息。

字段按事件类型选择性填充：

  • pre_tool_use → ToolName + Input 有值
  • post_tool_use → ToolName + Output 有值
  • pre/post_iteration → Iteration 有值

type HookEvent 

type HookEvent string

HookEvent 标识 Hook 触发的事件类型。

目前定义了 8 个核心事件，覆盖工具调用前后、上下文压缩前后、迭代循环前后、 用户输入提交时以及 Agent 即将停止时。 

const (
	// HookPreToolUse 在工具执行前触发，可拦截或修改工具输入。
	HookPreToolUse HookEvent = "pre_tool_use"

	// HookPostToolUse 在工具执行后触发，可审计或处理工具输出。
	HookPostToolUse HookEvent = "post_tool_use"

	// HookPreCompact 在上下文压缩前触发。
	HookPreCompact HookEvent = "pre_compact"

	// HookPostCompact 在上下文压缩后触发。
	HookPostCompact HookEvent = "post_compact"

	// HookPreIteration 在每次 ReAct 迭代开始前触发。
	HookPreIteration HookEvent = "pre_iteration"

	// HookPostIteration 在每次 ReAct 迭代结束后触发。
	HookPostIteration HookEvent = "post_iteration"

	// HookStop 在 Agent 即将停止（无工具调用、准备返回最终结果）时触发。
	// 通过返回 PreventStop=true 可阻止停止并强制继续迭代。
	HookStop HookEvent = "stop"

	// HookUserPromptSubmit 在用户输入提交时触发（追加到 session 之前）。
	// 可通过 transform 动作修改用户输入内容。
	HookUserPromptSubmit HookEvent = "user_prompt_submit"

	// HookSessionStart 在 ExecuteStream 的最开始触发（在 ReAct 循环之前）。
	// 适用于会话初始化、资源准备等场景。
	HookSessionStart HookEvent = "session_start"

	// HookSessionEnd 在 ExecuteStream 的最末尾触发（在返回最终结果之前）。
	// 适用于会话清理、持久化等场景。
	HookSessionEnd HookEvent = "session_end"
)

type HookRegistry 

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

HookRegistry 管理 Hook 的注册与按事件触发执行。

设计要点：

  • 零开销：未注册任何 Hook 时，Execute 立即返回 nil，不产生任何额外开销
  • 顺序执行：同一事件下多个 Hook 按注册顺序依次执行
  • deny 中断：任一 Hook 返回 deny 时立即停止后续 Hook
  • 超时保护：每个 Hook 执行受 5s 超时限制

并发安全说明：Hook 在 Agent 初始化阶段注册，运行阶段只读， 因此未加锁；若需运行时动态注册，应在外部自行同步。

func NewHookRegistry 

func NewHookRegistry() *HookRegistry

NewHookRegistry 创建一个空的 HookRegistry。

func (*HookRegistry) Execute 

func (r *HookRegistry) Execute(ctx context.Context, event HookEvent, hctx HookContext) (*HookResult, error)

Execute 执行指定事件的所有 Hook。

行为约定：

  • 没有注册任何 Hook → 立即返回 (nil, nil)，零开销
  • 每个单 Hook 执行享有 5s 超时
  • 任一 Hook 返回 deny → 立即中断，返回该 deny 结果
  • 任一 Hook 返回 error → 立即中断，返回该错误
  • 全部 Hook 返回 continue/transform/nil → 返回最后一个非 nil 结果， 若全为 nil 则返回 {Action: continue}

参数说明：

  • ctx - 父上下文（用于取消控制）
  • event - 要触发的事件类型
  • hctx - 事件上下文信息

返回：

  • *HookResult - 最终结果（nil 表示无 Hook 被触发）
  • error - 执行错误

func (*HookRegistry) Register 

func (r *HookRegistry) Register(h Hook)

Register 注册一个 Hook 到对应的事件列表。

注册顺序即为同一事件下的执行顺序。

参数说明：

  • h - 要注册的 Hook 实例

type HookResult 

type HookResult struct {
	// Action 是 Hook 指示的后续动作。
	Action HookAction

	// TransformedInput 在 Action==transform 时作为新的工具输入。
	TransformedInput []byte

	// TransformedOutput 在 post_tool_use 事件中设置时，替换工具输出的内容。
	TransformedOutput *string

	// PreventStop 在 stop 事件中为 true 时，阻止 Agent 停止并强制继续迭代。
	PreventStop bool

	// Reason 在 Action==deny 时提供拒绝原因。
	Reason string
}

HookResult 是 Hook 执行后返回的结果。

Action 决定后续流程走向；仅当 Action==transform 时 TransformedInput 才生效， 仅当 Action==deny 时 Reason 才会被记录到错误信息中。 PreventStop 仅在 stop 事件中生效，TransformedOutput 仅在 post_tool_use 事件中生效。

type LoopStrategy 

type LoopStrategy interface {
	Execute(ctx context.Context, core *agentCore, input string) (*AgentResult, error)
}

LoopStrategy 定义 Agent 执行周期的迭代策略。

定义了执行策略的核心能力，包括：

  • Execute - 执行 Agent 任务并返回最终结果

type MemoryStore 

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

MemoryStore 是 SessionStore 的内存实现。

func NewMemoryStore 

func NewMemoryStore() *MemoryStore

NewMemoryStore 创建一个新的内存会话存储。

func (*MemoryStore) Delete 

func (m *MemoryStore) Delete(_ context.Context, sessionID string) error

Delete 从内存中删除指定会话的消息。 如果会话不存在，则不做任何操作。

func (*MemoryStore) Exists 

func (m *MemoryStore) Exists(_ context.Context, sessionID string) (bool, error)

Exists 检查指定会话 ID 是否存在于内存存储中。

func (*MemoryStore) Load 

func (m *MemoryStore) Load(_ context.Context, sessionID string) ([]bamboo.BambooMessage, error)

Load 从内存中获取指定会话的消息，并通过深拷贝防止外部修改内部状态。

func (*MemoryStore) Save 

func (m *MemoryStore) Save(_ context.Context, sessionID string, messages []bamboo.BambooMessage) error

Save 将消息持久化到内存中，并通过深拷贝避免外部修改影响存储状态。

type MessageTruncator 

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

MessageTruncator 消息裁剪压缩器，保留最近 N 条消息的完整内容。

不使用 AI 总结，而是将旧消息中的大型内容替换为 "[truncated]" 占位符。 ToolUseBlock 结构始终保持完整，避免破坏工具调用的配对关系。

func NewMessageTruncator 

func NewMessageTruncator(keepRecent int) *MessageTruncator

NewMessageTruncator 创建消息裁剪压缩器。

参数说明：

  • keepRecent - 保留最近几条消息完整不变（<=0 时默认 4）

返回：

  • *MessageTruncator - 新创建的裁剪压缩器实例

func (*MessageTruncator) Compress 

func (t *MessageTruncator) Compress(_ context.Context, messages []bamboo.BambooMessage, _ int64) ([]bamboo.BambooMessage, error)

Compress 裁剪旧消息内容，保留最近 N 条消息不变。

策略：

  • 当消息总数 <= keepRecent 时，原样返回
  • 旧消息中的 TextBlock 超过 100 字符时替换为 "[truncated]"
  • ToolUseBlock 始终保留完整（维持工具调用配对）
  • 其他类型 block（ToolResult 等）替换为 "[truncated]"

type MicrocompactCompressor 

type MicrocompactCompressor struct {
	// MaxToolResultChars 是工具结果内容触发截断的字符阈值，默认 10000。
	MaxToolResultChars int

	// PreserveRecentResults 是保留完整的最近工具结果数量，默认 3。
	PreserveRecentResults int
}

MicrocompactCompressor 缓存感知的工具结果压缩器实现。

针对工具调用返回的大体量结果进行截断处理，将超出阈值的内容替换为 简短摘要，从而减少上下文占用。最近 N 条工具结果保持完整，确保 当前对话所需的工具输出不被破坏。

压缩策略：

  • 识别消息中包含 ToolResultBlock 的用户消息（工具结果由 user 角色承载）
  • 保留最近 PreserveRecentResults 条工具结果完整不变
  • 更早的工具结果若 Content 长度超过 MaxToolResultChars，则替换为截断摘要
  • 摘要格式："[Tool result truncated: {前 200 字符}...({总字符数} chars total)]"

func NewMicrocompactCompressor 

func NewMicrocompactCompressor() *MicrocompactCompressor

NewMicrocompactCompressor 创建缓存感知的工具结果压缩器。

使用默认配置初始化：

  • MaxToolResultChars - 10000
  • PreserveRecentResults - 3

返回：

  • *MicrocompactCompressor - 新创建的压缩器实例

func (*MicrocompactCompressor) Compress 

func (m *MicrocompactCompressor) Compress(_ context.Context, messages []bamboo.BambooMessage, _ int64) ([]bamboo.BambooMessage, error)

Compress 截断旧的大型工具结果，保留最近 N 条工具结果完整。

参数说明：

  • ctx - 上下文（当前未使用，预留以符合 ContextCompressor 接口）
  • messages - 原始消息列表
  • maxTokens - 最大 token 数限制（当前未使用）

返回：

  • []bamboo.BambooMessage - 压缩后的消息列表
  • error - 始终为 nil（此压缩器不会失败）

type Option 

type Option func(*agentOptions)

Option 是配置 Agent 的函数式选项类型。

func WithAllowedTools 

func WithAllowedTools(names ...string) Option

WithAllowedTools 设置工具白名单。

func WithCompressor 

func WithCompressor(compressor ContextCompressor) Option

WithCompressor 设置上下文压缩器。

func WithConfig 

func WithConfig(config AgentConfig) Option

WithConfig 设置完整的 Agent 配置。

func WithDeciders 

func WithDeciders(deciders ...Decider) Option

WithDeciders 注册 Decider 决策钩子列表。

多次调用 WithDeciders 会累积追加，而非覆盖。

参数说明：

  • deciders - 要注册的一个或多个 Decider 实例

func WithDisallowedTools 

func WithDisallowedTools(names ...string) Option

WithDisallowedTools 设置工具黑名单。

func WithFallbackModels 

func WithFallbackModels(models ...string) Option

WithFallbackModels 设置模型降级列表。

当主模型返回非 413 的临时错误时，按顺序尝试这些备用模型。

func WithFourLevelCompression 

func WithFourLevelCompression(client bamboo.BambooClient) Option

WithFourLevelCompression 配置四级压缩管道。

按以下顺序串联四个压缩器，形成多级压缩管道：

  1. SnipCompressor — 基于 `<snip>` 标记裁剪旧消息
  2. MicrocompactCompressor — 截断大型工具结果
  3. CollapseCompressor — 折叠连续同类型消息
  4. SummaryCompressor — AI 总结更早的对话历史

参数说明：

  • client - Bamboo 客户端，用于 SummaryCompressor 调用 AI 模型生成摘要

func WithHooks 

func WithHooks(hooks ...Hook) Option

WithHooks 注册 Hook 列表到 Agent 配置中。

多次调用 WithHooks 会累积追加，而非覆盖。

参数说明：

  • hooks - 要注册的一个或多个 Hook 实例

func WithLoopStrategy 

func WithLoopStrategy(strategy LoopStrategy) Option

WithLoopStrategy 设置循环策略。

func WithMaxConcurrentTools 

func WithMaxConcurrentTools(n int) Option

WithMaxConcurrentTools 设置最大并发工具执行数量。

func WithMaxIterations 

func WithMaxIterations(n int) Option

WithMaxIterations 设置最大循环迭代次数。

func WithMaxTokens 

func WithMaxTokens(n int64) Option

WithMaxTokens 设置每次响应的最大 token 数。

func WithPermissionHandler 

func WithPermissionHandler(handler PermissionHandler) Option

WithPermissionHandler 设置权限决策函数。

func WithPermissionMode 

func WithPermissionMode(mode PermissionMode) Option

WithPermissionMode 设置权限评估模式。

func WithPromptCacheKey 

func WithPromptCacheKey(key string) Option

WithPromptCacheKey 设置 OpenAI prompt cache 路由键。

func WithSessionID 

func WithSessionID(id string) Option

WithSessionID 设置当前 Agent 会话的唯一标识。

用于会话持久化场景，配合 WithSessionStore 实现 Save/Load/Resume。

参数说明：

  • id - 会话唯一标识字符串

func WithSessionStore 

func WithSessionStore(store SessionStore) Option

WithSessionStore 设置会话持久化存储后端。

配合 WithSessionID 使用，实现会话的跨进程恢复。

参数说明：

  • store - SessionStore 实现（如 MemoryStore、FileStore）

func WithSystemCacheControl 

func WithSystemCacheControl(ttl string) Option

WithSystemCacheControl 设置 system prompt 缓存控制。

func WithSystemPrompt 

func WithSystemPrompt(prompt string) Option

WithSystemPrompt 设置系统提示词。

func WithTemperature 

func WithTemperature(f float64) Option

WithTemperature 设置生成温度参数。

func WithThinkingConfig 

func WithThinkingConfig(effort string) Option

WithThinkingConfig 设置思考/推理配置。

func WithTokenizer 

func WithTokenizer(t Tokenizer) Option

WithTokenizer 设置自定义 Token 计数器。

func WithTools 

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

WithTools 注册给定的工具。

type PermissionBehavior 

type PermissionBehavior string

PermissionBehavior 定义权限检查的三种可能决策。 

const (
	// PermissionAllow 表示允许执行工具调用。
	PermissionAllow PermissionBehavior = "allow"
	// PermissionDeny 表示拒绝执行工具调用。
	PermissionDeny PermissionBehavior = "deny"
	// PermissionAsk 表示需要进一步确认（例如询问用户）后再决定是否执行。
	PermissionAsk PermissionBehavior = "ask"
)

type PermissionDecisionReason 

type PermissionDecisionReason struct {
	// Type 是决策来源类型，例如 "rule"、"mode"、"handler"、"default"。
	Type string
	// Detail 是决策来源的详细说明。
	Detail string
}

PermissionDecisionReason 描述权限决策的来源（用于审计/日志）。

type PermissionHandler 

type PermissionHandler func(ctx context.Context, toolName string, input json.RawMessage) (PermissionResult, error)

PermissionHandler 是一个可注入的函数，用于制定权限决策。 SDK 调用者通过实现该函数提供自定义权限逻辑（例如 CLI 提示、规则引擎）。

type PermissionMode 

type PermissionMode string

PermissionMode 控制工具权限的评估方式。 

const (
	// PermissionModeDefault 使用 PermissionHandler 进行 allow/deny/ask 决策。
	PermissionModeDefault PermissionMode = "default"
	// PermissionModePlan 自动允许只读工具，将写入类工具交给 PermissionHandler 处理。
	PermissionModePlan PermissionMode = "plan"
	// PermissionModeBypass 跳过所有权限检查，自动允许所有工具。
	PermissionModeBypass PermissionMode = "bypass"
)

type PermissionResult 

type PermissionResult struct {
	// Behavior 是权限决策行为：allow、deny 或 ask。
	Behavior PermissionBehavior
	// Reason 是决策原因的描述，可用于日志和审计。
	Reason string
}

PermissionResult 是权限检查的结果。

type PipelineCompressor 

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

PipelineCompressor 管道组合压缩器，按注册顺序串联执行多个 ContextCompressor。

前一个压缩器的输出作为后一个压缩器的输入，形成处理管道。

func NewPipelineCompressor 

func NewPipelineCompressor(compressors ...ContextCompressor) *PipelineCompressor

NewPipelineCompressor 创建管道组合压缩器。

参数说明：

  • compressors - 按执行顺序排列的压缩器列表

返回：

  • *PipelineCompressor - 新创建的管道压缩器实例

func (*PipelineCompressor) Compress 

func (p *PipelineCompressor) Compress(ctx context.Context, messages []bamboo.BambooMessage, maxTokens int64) ([]bamboo.BambooMessage, error)

Compress 按管道顺序依次执行压缩器。

任一压缩器返回错误时，立即中止并返回该错误。

type ReActLoop 

type ReActLoop struct{}

ReActLoop 实现 Reason-Act 迭代策略。

执行流程如下：

  • 向 AI 发送消息（流式）
  • 如果 AI 返回 tool_use → 执行工具 → 追加结果 → 继续循环
  • 如果 AI 返回 end_turn → 返回最终结果
  • 如果达到最大迭代次数 → 强制停止

func NewReActLoop 

func NewReActLoop() *ReActLoop

NewReActLoop 创建一个新的 ReActLoop 实例。

返回：

  • *ReActLoop - ReActLoop 实例

func (*ReActLoop) Execute 

func (l *ReActLoop) Execute(ctx context.Context, core *agentCore, input string) (*AgentResult, error)

Execute 执行 Agent 任务并返回最终结果（非流式）。

内部委托给 ExecuteStream 并传入 nil 回调，避免逻辑重复。

参数说明：

  • ctx - 上下文，用于取消和超时控制
  • core - agentCore 实例
  • input - 用户输入文本

返回：

  • *AgentResult - 执行结果
  • error - 执行错误

func (*ReActLoop) ExecuteStream 

func (l *ReActLoop) ExecuteStream(
	ctx context.Context,
	core *agentCore,
	input string,
	onEvent func(AgentEvent),
) (*AgentResult, error)

ExecuteStream 执行 Agent 任务并实时通过回调发送事件。

使用 ReAct 迭代策略执行任务，支持工具调用、流式输出和 Hook 集成。 在每次迭代中检查上下文长度，必要时进行压缩。

参数说明：

  • ctx - 上下文，用于取消和超时控制
  • core - agentCore 实例
  • input - 用户输入文本
  • onEvent - 事件回调（nil 时不发事件，等同 Execute）

返回：

  • *AgentResult - 执行结果，包含生成内容、工具调用记录和使用量
  • error - 执行错误，如上下文取消、AI 调用失败或工具执行失败

type RunInfo 

type RunInfo struct {
	// AgentID 是当前 Agent 的标识符。
	AgentID string

	// TurnCount 是本次 Run 期间的 ReAct 循环迭代次数。
	TurnCount int

	// ToolCallCount 是本次 Run 期间累计的工具调用次数。
	ToolCallCount int
}

RunInfo 提供给 Decider 的运行时信息。

在 Agent 执行完成、调用 BeforeFinalize 时填充， 用于让 Decider 根据运行指标做出决策。

type Session 

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

Session 管理内存中的对话历史

提供线程安全的消息追加、获取和清空功能

func NewSession 

func NewSession(tools *tool.Registry) *Session

NewSession 创建一个新的会话，关联指定的工具注册表

func (*Session) AppendMessage 

func (s *Session) AppendMessage(msg bamboo.BambooMessage)

AppendMessage 将消息追加到对话历史中

func (*Session) Clear 

func (s *Session) Clear()

Clear 清空对话历史

func (*Session) GetMessages 

func (s *Session) GetMessages() []bamboo.BambooMessage

GetMessages 返回对话历史中所有消息的副本 返回副本以防止外部修改影响会话状态

func (*Session) Tools 

func (s *Session) Tools() *tool.Registry

Tools 返回与此会话关联的工具注册表

type SessionStore 

type SessionStore interface {
	// Save 将指定会话 ID 的消息持久化。
	Save(ctx context.Context, sessionID string, messages []bamboo.BambooMessage) error
	// Load 获取指定会话 ID 的消息。
	// 如果会话不存在，返回 ErrSessionNotFound。
	Load(ctx context.Context, sessionID string) ([]bamboo.BambooMessage, error)
	// Delete 删除指定会话 ID 的消息。
	Delete(ctx context.Context, sessionID string) error
	// Exists 检查指定会话 ID 是否存在已存储的消息。
	Exists(ctx context.Context, sessionID string) (bool, error)
}

SessionStore 定义会话消息历史的持久化接口。 实现包括 MemoryStore（默认）和 FileStore（Task 20）。

type SnipCompressor 

type SnipCompressor struct {
	// Marker 是触发裁剪的标记字符串，默认 "<snip>"。
	Marker string

	// PreserveRecent 是最近保留的消息数量，默认 4。
	// 这些消息不会被裁剪，即使包含标记。
	PreserveRecent int
}

SnipCompressor 基于 `<snip>` 标记的裁剪压缩器实现。

扫描消息历史中带有 `<snip>...</snip>` 标记的内容块，将包含该标记的旧消息 整体移除，从而实现精准的上下文裁剪。最近 N 条消息始终保留，避免误删 当前对话上下文。

压缩策略：

  • PreserveRecent 之前的消息为"可裁剪区"，之后的为"保留区"
  • 可裁剪区内，任一 TextBlock 包含 Marker 字符串的消息将被整体移除
  • 保留区消息原样返回

func NewSnipCompressor 

func NewSnipCompressor() *SnipCompressor

NewSnipCompressor 创建基于 `<snip>` 标记的裁剪压缩器。

使用默认配置初始化：

  • Marker - "<snip>"
  • PreserveRecent - 4

返回：

  • *SnipCompressor - 新创建的压缩器实例

func (*SnipCompressor) Compress 

func (s *SnipCompressor) Compress(_ context.Context, messages []bamboo.BambooMessage, _ int64) ([]bamboo.BambooMessage, error)

Compress 移除包含 snip 标记的旧消息，保留最近 N 条消息不变。

参数说明：

  • ctx - 上下文（当前未使用，预留以符合 ContextCompressor 接口）
  • messages - 原始消息列表
  • maxTokens - 最大 token 数限制（当前未使用）

返回：

  • []bamboo.BambooMessage - 裁剪后的消息列表
  • error - 始终为 nil（此压缩器不会失败）

type StreamingLoopStrategy 

type StreamingLoopStrategy interface {
	LoopStrategy

	// ExecuteStream 执行 Agent 任务，通过回调实时发送事件。
	//
	// 参数说明：
	//   - ctx - 上下文，用于取消和超时控制
	//   - core - agentCore 实例
	//   - input - 用户输入文本
	//   - onEvent - 事件回调，nil 时等同于无操作（Execute 行为）
	//
	// 返回：
	//   - *AgentResult - 执行结果
	//   - error - 执行错误
	ExecuteStream(ctx context.Context, core *agentCore, input string, onEvent func(AgentEvent)) (*AgentResult, error)
}

StreamingLoopStrategy 扩展 LoopStrategy，支持真正的流式输出。

实现此接口的策略可以通过 ExecuteStream 方法实时发送事件， 而非等到全部完成后才返回结果。

type SummaryCompressor 

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

SummaryCompressor 基于 AI 总结的上下文压缩器实现。

通过调用 AI 模型生成对话摘要，实现消息历史的智能压缩。

func NewSummaryCompressor 

func NewSummaryCompressor(client bamboo.BambooClient) *SummaryCompressor

NewSummaryCompressor 创建基于 AI 总结的上下文压缩器。

使用默认配置初始化压缩器：

  • keepRecent - 默认保留最近 2 轮对话（即 4 条消息）
  • summaryPrompt - 使用预设的英文提示词生成摘要

参数说明：

  • client - Bamboo 客户端，用于调用 AI 模型

返回：

  • *SummaryCompressor - 新创建的压缩器实例

func (*SummaryCompressor) Compress 

func (c *SummaryCompressor) Compress(ctx context.Context, messages []bamboo.BambooMessage, maxTokens int64) ([]bamboo.BambooMessage, error)

Compress 压缩消息历史，保留最近 N 轮对话并总结更早的消息。

压缩策略：

  • 保留最近 N*2 条消息（N 轮对话）
  • 将更早的消息通过 AI 总结为一条摘要
  • 当消息总数 <= keepRecent*2 时，不做压缩直接返回

参数说明：

  • ctx - 上下文，用于取消和超时控制
  • messages - 原始消息列表
  • maxTokens - 最大 token 数限制（当前未使用）

返回：

  • []bamboo.BambooMessage - 压缩后的消息列表（[摘要] + 最近消息）
  • error - 执行错误，如 AI 调用失败

type TerminalReason 

type TerminalReason string

TerminalReason describes why the ReAct loop terminated. 

const (
	// TerminalEndTurn indicates the model ended its turn normally.
	TerminalEndTurn TerminalReason = "end_turn"

	// TerminalAborted indicates the loop was aborted during streaming.
	TerminalAborted TerminalReason = "aborted_streaming"

	// TerminalBlockingLimit indicates a hard blocking limit was reached.
	TerminalBlockingLimit TerminalReason = "blocking_limit"

	// TerminalModelError indicates an unrecoverable model error occurred.
	TerminalModelError TerminalReason = "model_error"

	// TerminalMaxIterations indicates the maximum number of iterations was reached.
	TerminalMaxIterations TerminalReason = "max_iterations"
)

type Tokenizer 

type Tokenizer interface {
	CountTokens(text string) int
	CountMessageTokens(messages []bamboo.BambooMessage) int
}

Tokenizer counts tokens for text and messages.

type ToolCallRecord 

type ToolCallRecord struct {
	ID      string          // 工具调用唯一标识
	Name    string          // 工具名称
	Input   json.RawMessage // 工具输入参数（JSON格式）
	Result  string          // 工具执行结果
	IsError bool            // 是否为错误结果
}

ToolCallRecord 工具调用记录 记录每次工具调用的详细信息，包括输入参数和执行结果

type Transition 

type Transition struct {
	// Continue is set when the loop should perform another iteration.
	Continue *ContinueReason

	// Terminal is set when the loop should stop and return a result.
	Terminal *TerminalReason
}

Transition represents the loop's next action: either continue with a reason or terminate.

func NewContinueTransition 

func NewContinueTransition(reason ContinueReason) Transition

NewContinueTransition returns a Transition that continues the loop for the given reason.

func NewTerminalTransition 

func NewTerminalTransition(reason TerminalReason) Transition

NewTerminalTransition returns a Transition that terminates the loop for the given reason.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.