Documentation
¶
Overview ¶
Package tool 提供了 Bamboo Agent 框架的工具系统核心组件
工具系统是 AI Agent 执行外部操作的核心能力,支持工具注册、并发执行和适配器转换。
主要组件:
- Tool 接口 - 定义所有工具必须实现的基本方法(Info、Execute)
- InputSchema - 工具参数的输入模式定义(Type、Properties、Required)
- Registry - 线程安全的工具注册表,支持工具注册、查找和批量注册
- ToolExecutor - 并发执行器,支持多工具并发调用和并发控制
- BambooAdapter - 适配器,将内部工具类型转换为 Bamboo SDK 类型
使用示例:
registry := tool.NewRegistry()
registry.Register(&MyTool{})
executor := tool.NewToolExecutor(registry, 10)
results := executor.ExecuteAll(ctx, toolCalls)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BambooAdapter ¶
type BambooAdapter struct{}
BambooAdapter 将内部工具类型转换为 bamboo SDK 类型。
func NewBambooAdapter ¶
func NewBambooAdapter() *BambooAdapter
NewBambooAdapter 创建一个 BambooAdapter 实例。
func (*BambooAdapter) ToBambooTool ¶
func (a *BambooAdapter) ToBambooTool(info ToolInfo) bamboo.Tool
ToBambooTool 将 ToolInfo 转换为 bamboo.Tool。
func (*BambooAdapter) ToBambooTools ¶
func (a *BambooAdapter) ToBambooTools(infos []ToolInfo) []bamboo.Tool
ToBambooTools 将多个 ToolInfo 转换为 bamboo.Tool 切片。
type ConcurrencySafeTool ¶
type ConcurrencySafeTool interface {
// IsConcurrencySafe reports whether the tool can be executed concurrently
// for the given input.
IsConcurrencySafe(input json.RawMessage) bool
}
ConcurrencySafeTool is an optional interface that tools can implement to declare whether they are safe for concurrent execution.
If a tool does NOT implement this interface, the executor treats it as NOT safe and executes it serially.
type GuardrailError ¶
type GuardrailError struct {
// GuardrailName 是触发拒绝的护栏名称，用于日志与调试。
GuardrailName string
// Reason 是人类可读的拒绝原因。
Reason string
}
GuardrailError 表示 Guardrail 拒绝执行或拒绝结果时的错误。
携带触发护栏的名称和拒绝原因，便于上层定位与日志记录。
type InputGuardrail ¶
type InputGuardrail func(ctx context.Context, input json.RawMessage) error
InputGuardrail 输入护栏函数类型。
在工具执行前对输入进行校验，返回 error 表示拒绝执行。 参数说明：
- ctx - 上下文，用于取消和超时控制
- input - 工具输入参数（JSON RawMessage）
返回：
- error - 非 nil 表示校验失败，应中止执行
type InputSchema ¶
type InputSchema struct {
// Type 是参数类型，通常为 "object"。
Type string `json:"type"`
// Properties 定义参数对象的属性键值对。
Properties map[string]PropertyDef `json:"properties,omitempty"`
// Required 列出必需参数的名称数组。
Required []string `json:"required,omitempty"`
}
InputSchema 定义工具输入参数的 schema。
符合 JSON Schema 规范，用于描述工具的输入结构。
type OutputGuardrail ¶
type OutputGuardrail func(ctx context.Context, result *ToolResult) error
OutputGuardrail 输出护栏函数类型。
在工具执行后对结果进行校验或修改，返回 error 表示拒绝该结果。 参数说明：
- ctx - 上下文，用于取消和超时控制
- result - 工具执行结果指针，可直接修改字段
返回：
- error - 非 nil 表示校验失败，应丢弃结果
type PropertyDef ¶
type PropertyDef struct {
// Type 是参数的数据类型，如 "string"、"number"、"boolean" 等。
Type string `json:"type"`
// Description 是参数的中文描述。
Description string `json:"description,omitempty"`
// Enum 定义参数的可选值列表，限制输入范围。
Enum []string `json:"enum,omitempty"`
// Minimum 定义数值类型参数的最小值。
Minimum *float64 `json:"minimum,omitempty"`
// Maximum 定义数值类型参数的最大值。
Maximum *float64 `json:"maximum,omitempty"`
// Items 定义数组类型参数的元素 schema。
Items *PropertyDef `json:"items,omitempty"`
}
PropertyDef 定义输入 schema 中的单个属性。
描述参数的类型、描述和可选值。
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry 管理所有已注册的工具，支持线程安全的注册、查找和执行。
使用读写锁（sync.RWMutex）保证并发安全，支持单个工具注册、批量注册、 按名称查找、执行工具和列出所有工具信息。
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry 创建一个空的工具注册表。
返回一个初始化完成的 `Registry` 实例，内部工具映射表已创建完成。
func (*Registry) Execute ¶
Execute 执行指定名称的工具。
如果工具不存在，返回错误。
参数说明：
- ctx - 上下文，用于取消和超时控制
- name - 工具名称
- input - 工具输入参数（JSON 字节数组）
返回：
- *ToolResult - 工具执行结果
- error - 执行错误，如工具不存在或执行失败
func (*Registry) Get ¶
Get 根据名称查找工具。
查找操作是线程安全的（读锁）。
参数说明：
- name - 工具名称
返回：
- Tool - 找到的工具实例
- bool - 是否找到（true 为找到，false 为未找到）
func (*Registry) Register ¶
Register 注册一个工具到注册表中。
如果工具名称已存在，返回错误。注册操作是线程安全的。
参数说明：
- tool - 要注册的工具实例
返回：
- error - 注册错误，如工具名称已存在
func (*Registry) RegisterBatch ¶
RegisterBatch 批量注册多个工具。
如果任何一个工具注册失败，立即停止并返回错误。
参数说明：
- tools - 要批量注册的工具列表
返回：
- error - 注册错误，如某个工具名称已存在
type StreamingToolExecutor ¶
type StreamingToolExecutor struct {
// contains filtered or unexported fields
}
StreamingToolExecutor 在流式输出期间按需调度工具执行。
包装 ToolExecutor，提供增量式的工具调用接口：
- StreamingToolExecutor.AddTool 非阻塞地将一次工具调用加入后台队列
- StreamingToolExecutor.GetCompletedResults 返回当前已完成结果的快照
- StreamingToolExecutor.GetRemainingResults 阻塞等待所有挂起调用结束后返回完整结果
- StreamingToolExecutor.Discard 取消所有尚未写入结果的挂起调用
该结构体用于 ReAct 流式迭代场景：AI 在流式输出中可能分批返回 tool_use， 调用方可以在收到一个 tool_use 后立即 AddTool 启动执行，同时继续接收后续流事件， 从而将工具执行与 AI 输出解析重叠，减少端到端延迟。
并发安全：所有方法均可在不同 goroutine 中并发调用。
func NewStreamingToolExecutor ¶
func NewStreamingToolExecutor(executor *ToolExecutor) *StreamingToolExecutor
NewStreamingToolExecutor 创建一个流式工具执行器。
参数说明：
- executor - 底层 ToolExecutor，不能为 nil
返回：
- *StreamingToolExecutor - 新创建的流式执行器
func (*StreamingToolExecutor) AddTool ¶
func (s *StreamingToolExecutor) AddTool(ctx context.Context, call ToolCallInput)
AddTool 非阻塞地提交一次工具调用。
调用后立即返回，实际执行在独立 goroutine 中进行。若已调用过 StreamingToolExecutor.Discard， 本方法为空操作。同一 StreamingToolExecutor 可并发调用 AddTool 多次，每次都会启动独立的 goroutine。
参数说明：
- ctx - 上下文，用于取消和超时控制，会透传到底层 ToolExecutor.ExecuteAll
- call - 工具调用输入（ID / Name / Input）
func (*StreamingToolExecutor) Discard ¶
func (s *StreamingToolExecutor) Discard()
Discard 取消所有尚未写入结果的挂起调用。
本方法将 discarded 标志置为 true：
- 后续 StreamingToolExecutor.AddTool 调用成为空操作
- 已在途 goroutine 完成时不会将结果写入 completed
注意：Discard 不会主动取消正在执行中的工具 goroutine（底层 ctx 的取消由调用方管理）， 仅阻止其结果被收集。调用 Discard 后，StreamingToolExecutor.GetRemainingResults 会快速返回， 因为在途 goroutine 虽然完成执行，但其结果会被丢弃。
func (*StreamingToolExecutor) GetCompletedResults ¶
func (s *StreamingToolExecutor) GetCompletedResults() []ToolCallOutput
GetCompletedResults 返回当前已完成结果的快照。
本方法不阻塞，可多次调用。返回的是 completed 切片的深拷贝， 调用方对其修改不会影响内部状态。结果按完成顺序排列（非提交顺序）。
返回：
- []ToolCallOutput - 当前已完成结果的快照
func (*StreamingToolExecutor) GetRemainingResults ¶
func (s *StreamingToolExecutor) GetRemainingResults() []ToolCallOutput
GetRemainingResults 阻塞等待所有挂起的工具调用完成，然后返回完整结果快照。
内部先调用 sync.WaitGroup.Wait 等待所有 AddTool 启动的 goroutine 归零， 再委托 StreamingToolExecutor.GetCompletedResults 返回快照。 若调用前已执行 Discard，已丢弃的调用不会写入 completed，结果仅包含 Discard 之前已完成的部分。
返回：
- []ToolCallOutput - 所有已完成结果的快照
type Tool ¶
type Tool interface {
// Info 返回工具的元信息，包括名称、描述和参数定义。
//
// 返回：
// - ToolInfo - 工具的元信息
Info() ToolInfo
// Execute 执行工具并返回执行结果或错误。
//
// 参数说明：
// - ctx - 上下文，用于取消和超时控制
// - input - 工具输入参数（JSON 格式）
//
// 返回：
// - *ToolResult - 工具执行结果
// - error - 执行错误，如参数解析失败或执行异常
Execute(ctx context.Context, input json.RawMessage) (*ToolResult, error)
}
Tool 定义了所有工具必须实现的接口。
定义了工具的完整能力，包括：
- Info - 获取工具的元信息
- Execute - 执行工具逻辑
type ToolCallInput ¶
type ToolCallInput struct {
// ID 是调用标识符，由 AI 分配，用于匹配输入和输出。
ID string
// Name 是工具名称，用于在注册表中查找对应的工具。
Name string
// Input 是调用参数，以 JSON 格式传递给工具。
Input json.RawMessage
}
ToolCallInput 表示来自 AI 的单个工具调用。
保存工具调用的标识符、名称和参数，用于并发执行。
type ToolCallOutput ¶
type ToolCallOutput struct {
// ID 是调用标识符,与 ToolCallInput.ID 匹配。
ID string
// Result 是执行结果,包含工具返回的内容。
Result *ToolResult
// Error 是执行错误,如工具不存在或执行失败。
Error error
}
ToolCallOutput 表示单个工具调用的结果。
保存工具调用的结果、错误信息,用于匹配 ToolCallInput。
type ToolExecutor ¶
type ToolExecutor struct {
// contains filtered or unexported fields
}
ToolExecutor 并发执行工具调用。
使用信号量控制并发数量,支持 Context 取消。 工具根据 ConcurrencySafeTool 可选接口的声明进行分区： 安全工具在同一个批次中并发执行，非安全工具单独串行执行。
func NewToolExecutor ¶
func NewToolExecutor(registry *Registry, maxConcurrent int) *ToolExecutor
NewToolExecutor 创建新的工具执行器。
参数说明：
- registry - 工具注册表,用于查找和执行工具
- maxConcurrent - 最大并发数,若 <= 0 则默认为 10
返回：
- *ToolExecutor - 新创建的工具执行器
func (*ToolExecutor) ExecuteAll ¶
func (e *ToolExecutor) ExecuteAll(ctx context.Context, toolCalls []ToolCallInput) ([]ToolCallOutput, error)
ExecuteAll 根据工具的并发安全声明分区后执行多个工具调用。
安全工具在同一批次内使用 goroutine 并发执行（受 maxConcurrent 信号量约束）； 非安全工具逐个串行执行。单个工具失败不影响其他工具，Context 取消会停止所有执行。 返回结果顺序与输入顺序严格一致。 每个工具执行完毕后，若结果超过该工具的 MaxResultSizeChars 限制，会自动截断。
参数说明：
- ctx - 上下文,用于取消和超时控制
- toolCalls - 工具调用列表
返回：
- []ToolCallOutput - 执行结果列表,与输入顺序一致
- error - 暂不返回错误
type ToolInfo ¶
type ToolInfo struct {
// Name 是工具的唯一标识符。
Name string `json:"name"`
// Description 是工具功能的中文描述。
Description string `json:"description"`
// Parameters 定义工具的输入参数 schema。
Parameters InputSchema `json:"parameters"`
// MaxResultSizeChars 限制工具执行结果的最大字符数。
// 超过此长度的结果会被截断并追加 "...[truncated]" 标记。
// 0 表示不限制。
MaxResultSizeChars int `json:"maxResultSizeChars,omitempty"`
}
ToolInfo 保存工具的元信息。
包含工具的名称、描述和输入参数定义。
type ToolResult ¶
type ToolResult struct {
// Content 是工具执行结果的文本内容。
Content string `json:"content"`
// IsError 标识本次执行是否为错误结果。
IsError bool `json:"isError"`
}
ToolResult 保存工具执行的结果。
包含执行结果内容和错误状态标识。
type ToolWrapper ¶
ToolWrapper 包装 Tool 的装饰器函数类型。
接收原始 Tool，返回可能被装饰后的 Tool。
func WithGuardrails ¶
func WithGuardrails(input []InputGuardrail, output []OutputGuardrail) ToolWrapper
WithGuardrails 创建一个 ToolWrapper，为 Tool 添加输入/输出护栏。
当 input 和 output 均为空时，返回的 ToolWrapper 不做包装，直接返回原始 Tool， 确保「无 guardrail 时行为不变」。
参数说明：
- input - 输入护栏列表，按顺序在工具执行前调用
- output - 输出护栏列表，按顺序在工具执行后调用
返回：
- ToolWrapper - 可用于装饰任意 Tool 的包装函数
Source Files
Directories