Documentation
¶
Overview ¶
Package tool 定义 Agent 工具调用（function calling）的基础设施。
它与具体的 Agent / Provider 解耦，只回答三个问题：
- 有哪些工具（Definition 描述给模型的元信息）；
- 如何组织它们（Registry 按名注册 / 解析）；
- 如何调用它们（Executor 解析工具 → 校验参数 → 套用中间件 → 执行）。
上层 internal/agent 通过 ToolRunner 把工具执行桥接到 Runtime（事件流 + 权限门禁）， 因此本包不依赖 agent，避免循环引用。
Index ¶
- Variables
- func BooleanProperty(description string) map[string]any
- func IntegerProperty(description string) map[string]any
- func NumberProperty(description string) map[string]any
- func Schema(description string, properties map[string]any, required ...string) map[string]any
- func StringProperty(description string) map[string]any
- type Call
- type Definition
- type Executor
- type ExecutorOption
- type Func
- type Middleware
- type Next
- type Registry
- type Result
- type Tool
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound 表示工具未注册。 ErrNotFound = errors.New("tool: tool not found") // ErrInvalidArguments 表示工具参数非法（无法解析为输入结构或不是合法 JSON）。 ErrInvalidArguments = errors.New("tool: invalid arguments") )
工具相关错误。
Functions ¶
func BooleanProperty ¶
BooleanProperty 构造一个 boolean 类型属性。
func IntegerProperty ¶
IntegerProperty 构造一个 integer 类型属性。
func NumberProperty ¶
NumberProperty 构造一个 number 类型属性。
func StringProperty ¶
StringProperty 构造一个 string 类型属性。
Types ¶
type Call ¶
type Call struct {
ID string `json:"id,omitempty"` // 调用唯一 ID（模型生成）
Name string `json:"name"` // 工具名
Arguments json.RawMessage `json:"arguments,omitempty"` // 参数（JSON）
}
Call 是一次待执行的工具调用。
type Definition ¶
type Definition struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
InputSchema map[string]any `json:"input_schema"`
}
Definition 描述一个工具，用于暴露给模型（function calling 的 tool 定义）。
InputSchema 是参数的 JSON Schema（object 类型），模型据此生成调用参数。
type Executor ¶
type Executor struct {
// contains filtered or unexported fields
}
Executor 执行工具调用：解析工具 → 校验参数 → 套用中间件 → 执行。
语义约定：所有失败（工具不存在 / 参数非法 / 超时 / panic / 工具返回错误）都 收敛为 Result.IsError=true，而不会向上抛出中断整个流程——模型据此纠正行为。
func NewExecutor ¶
func NewExecutor(registry *Registry, opts ...ExecutorOption) *Executor
NewExecutor 创建执行器；默认在最内层附带 Recover 中间件（panic 不逃逸）。
type ExecutorOption ¶
type ExecutorOption func(*Executor)
ExecutorOption 配置 Executor。
func WithMiddlewares ¶
func WithMiddlewares(ms ...Middleware) ExecutorOption
WithMiddlewares 追加中间件（先加入的越靠内层）。
type Func ¶
type Func[In, Out any] struct { // contains filtered or unexported fields }
Func 把普通函数适配为 Tool：In 为入参结构，Out 为返回结构。
Execute 内部完成 json.Unmarshal(In) → fn(ctx, in) → 返回 Out。
func NewFunc ¶
func NewFunc[In, Out any](name, description string, inputSchema map[string]any, fn func(context.Context, In) (Out, error)) *Func[In, Out]
NewFunc 基于一个强类型函数构建工具。
- name：唯一工具名（模型用它发起调用）；
- description：用途描述（模型据此判断何时使用）；
- inputSchema：In 的 JSON Schema（可用 Schema 构造器生成）；
- fn：实际执行逻辑。
func (*Func[In, Out]) Definition ¶
func (f *Func[In, Out]) Definition() Definition
Definition 实现 Tool。
type Middleware ¶
Middleware 包裹工具执行：在真正调用工具前后做校验 / 超时 / 恢复 / 日志等。
中间件在 Executor 中按注册顺序包裹（先注册的越靠内层）。约定：中间件应调用 next 继续执行，并在需要时改造 ctx / call / 返回值。
func Logging ¶
func Logging(logf func(format string, args ...any)) Middleware
Logging 在工具执行前后记录日志；logf 为 nil 时使用标准库 log。
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry 注册并解析工具。
工具按名称唯一；List 返回全部工具的 Definition，供 Provider 暴露给模型 （即 function calling 里的 tools 参数）。
type Result ¶
type Result struct {
Content string `json:"content"` // 回传给模型的文本
Data any `json:"data,omitempty"` // 结构化结果（供上层业务使用）
IsError bool `json:"is_error"` // 是否为失败结果
Err error `json:"-"` // 底层错误（仅供日志 / 观测，不回传模型）
}
Result 是一次工具调用的结果。
无论成功还是失败，Content 都会回传给模型（因此始终是可读文本）； IsError 标识这次调用是否失败，模型可据此纠正后续行为。
type Tool ¶
type Tool interface {
// Definition 返回工具的元信息（名称 / 描述 / 参数 schema）。
Definition() Definition
// Execute 执行工具；args 是模型生成的参数（JSON，空时视为 {}）。
Execute(ctx context.Context, args json.RawMessage) (any, error)
}
Tool 是可被 Agent 调用的一个工具。
实现约定：
- Execute 返回的 error 会被上层包装为"工具执行失败"的结果（Result.IsError=true）， 而不会中断整个调用流程——模型可以看到错误信息并尝试纠正。
- 返回的 any 会被序列化为结果内容（Result.Content）回传给模型。
Source Files
Directories