tools

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Nov 18, 2025 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ValidateInput 

func ValidateInput(tool Tool, input map[string]interface{}) error

ValidateInput 验证工具输入

Types

type BaseEnhancedTool 

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

BaseEnhancedTool 增强工具的基础实现 提供默认行为，简化自定义工具开发

func NewBaseEnhancedTool 

func NewBaseEnhancedTool(name, description string) *BaseEnhancedTool

func (*BaseEnhancedTool) Description 

func (t *BaseEnhancedTool) Description() string

func (*BaseEnhancedTool) Execute 

func (t *BaseEnhancedTool) Execute(ctx context.Context, args map[string]interface{}) (interface{}, error)

Execute 需要由具体工具实现

func (*BaseEnhancedTool) IsLongRunning 

func (t *BaseEnhancedTool) IsLongRunning() bool

func (*BaseEnhancedTool) Metadata 

func (t *BaseEnhancedTool) Metadata() map[string]interface{}

func (*BaseEnhancedTool) Name 

func (t *BaseEnhancedTool) Name() string

func (*BaseEnhancedTool) Priority 

func (t *BaseEnhancedTool) Priority() int

func (*BaseEnhancedTool) RequiresApproval 

func (t *BaseEnhancedTool) RequiresApproval() bool

func (*BaseEnhancedTool) RetryPolicy 

func (t *BaseEnhancedTool) RetryPolicy() *RetryPolicy

func (*BaseEnhancedTool) Schema 

func (t *BaseEnhancedTool) Schema() *types.ToolSchema

func (*BaseEnhancedTool) SetLongRunning 

func (t *BaseEnhancedTool) SetLongRunning(v bool)

func (*BaseEnhancedTool) SetMetadata 

func (t *BaseEnhancedTool) SetMetadata(key string, value interface{})

func (*BaseEnhancedTool) SetPriority 

func (t *BaseEnhancedTool) SetPriority(p int)

func (*BaseEnhancedTool) SetRequireApproval 

func (t *BaseEnhancedTool) SetRequireApproval(v bool)

func (*BaseEnhancedTool) SetRetryPolicy 

func (t *BaseEnhancedTool) SetRetryPolicy(policy *RetryPolicy)

func (*BaseEnhancedTool) SetSchema 

func (t *BaseEnhancedTool) SetSchema(schema *types.ToolSchema)

Setter 方法

func (*BaseEnhancedTool) SetTimeout 

func (t *BaseEnhancedTool) SetTimeout(d time.Duration)

func (*BaseEnhancedTool) Timeout 

func (t *BaseEnhancedTool) Timeout() time.Duration

type BaseLongRunningTool 

type BaseLongRunningTool struct {
	BaseTool
	// contains filtered or unexported fields
}

BaseLongRunningTool 长时运行工具的基础实现 可以嵌入到具体工具中

func NewBaseLongRunningTool 

func NewBaseLongRunningTool(name, description string, executor *LongRunningExecutor) *BaseLongRunningTool

NewBaseLongRunningTool 创建基础长时运行工具

func (*BaseLongRunningTool) Cancel 

func (t *BaseLongRunningTool) Cancel(ctx context.Context, taskID string) error

Cancel 实现 LongRunningTool 接口

func (*BaseLongRunningTool) Execute 

func (t *BaseLongRunningTool) Execute(ctx context.Context, args map[string]interface{}, tc *ToolContext) (interface{}, error)

Execute 需要由具体工具实现

func (*BaseLongRunningTool) GetStatus 

func (t *BaseLongRunningTool) GetStatus(ctx context.Context, taskID string) (*TaskStatus, error)

GetStatus 实现 LongRunningTool 接口

func (*BaseLongRunningTool) IsLongRunning 

func (t *BaseLongRunningTool) IsLongRunning() bool

IsLongRunning 实现 LongRunningTool 接口

func (*BaseLongRunningTool) StartAsync 

func (t *BaseLongRunningTool) StartAsync(ctx context.Context, args map[string]interface{}) (string, error)

StartAsync 实现 LongRunningTool 接口

type BaseTool 

type BaseTool struct {
	ToolName        string // 导出字段
	ToolDescription string // 导出字段
}

BaseTool 基础工具实现（提供默认的空方法）

func NewBaseTool 

func NewBaseTool(name, description string) *BaseTool

NewBaseTool 创建基础工具

func (*BaseTool) Description 

func (t *BaseTool) Description() string

func (*BaseTool) Execute 

func (t *BaseTool) Execute(ctx context.Context, input map[string]interface{}, tc *ToolContext) (interface{}, error)

func (*BaseTool) InputSchema 

func (t *BaseTool) InputSchema() map[string]interface{}

func (*BaseTool) Name 

func (t *BaseTool) Name() string

func (*BaseTool) Prompt 

func (t *BaseTool) Prompt() string

type Context 

type Context interface {
	// Context 返回 Go 标准 context
	Context() context.Context

	// Value 获取上下文值
	Value(key interface{}) interface{}
}

Context 工具执行的基础上下文接口 提供最小的上下文信息

type EnhancedContext 

type EnhancedContext interface {
	Context // 继承基础接口

	// CallID 工具调用的唯一标识符
	CallID() string

	// AgentID 当前 Agent ID
	AgentID() string

	// SessionID 当前会话 ID
	SessionID() string

	// InvocationID 当前调用 ID
	InvocationID() string

	// State 访问会话状态
	State() session.State

	// Actions 获取事件动作
	Actions() *session.EventActions

	// SearchMemory 搜索 Agent 记忆
	SearchMemory(ctx context.Context, query string) ([]MemoryResult, error)

	// GetArtifact 获取 Artifact
	GetArtifact(ctx context.Context, name string) (interface{}, error)

	// SaveArtifact 保存 Artifact
	SaveArtifact(ctx context.Context, name string, data interface{}) error

	// EmitEvent 发送自定义事件
	EmitEvent(event *types.Event) error

	// Logger 获取日志记录器
	Logger() Logger

	// Tracer 获取追踪器
	Tracer() Tracer

	// Metrics 获取指标收集器
	Metrics() Metrics
}

EnhancedContext 增强的工具执行上下文 参考 Google ADK-Go 的 tool.Context 设计

type EnhancedTool 

type EnhancedTool interface {
	Tool // 继承基础接口

	// IsLongRunning 是否为长时运行工具
	// 长时运行工具会先返回资源 ID，稍后完成操作
	IsLongRunning() bool

	// Timeout 工具执行超时时间
	// 返回 0 表示使用默认超时
	Timeout() time.Duration

	// RequiresApproval 是否需要人工审批
	RequiresApproval() bool

	// Priority 工具优先级 (用于并发控制)
	// 数值越大优先级越高
	Priority() int

	// RetryPolicy 重试策略
	RetryPolicy() *RetryPolicy

	// Metadata 工具元数据
	Metadata() map[string]interface{}
}

EnhancedTool 增强的工具接口 参考 Google ADK-Go 的工具设计

type ExecuteRequest 

type ExecuteRequest struct {
	Tool    Tool
	Input   map[string]interface{}
	Context *ToolContext
	Timeout time.Duration
}

ExecuteRequest 执行请求

type ExecuteResult 

type ExecuteResult struct {
	Success    bool
	Output     interface{}
	Error      error
	DurationMs int64
	StartedAt  time.Time
	EndedAt    time.Time
}

ExecuteResult 执行结果

type Executor 

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

Executor 工具执行器

func NewExecutor 

func NewExecutor(config ExecutorConfig) *Executor

NewExecutor 创建工具执行器

func (*Executor) Execute 

func (e *Executor) Execute(ctx context.Context, req *ExecuteRequest) *ExecuteResult

Execute 执行单个工具

func (*Executor) ExecuteBatch 

func (e *Executor) ExecuteBatch(ctx context.Context, requests []*ExecuteRequest) []*ExecuteResult

ExecuteBatch 批量执行工具

func (*Executor) Wait 

func (e *Executor) Wait()

Wait 等待所有执行完成

type ExecutorConfig 

type ExecutorConfig struct {
	MaxConcurrency int           // 最大并发数
	DefaultTimeout time.Duration // 默认超时时间
}

ExecutorConfig 执行器配置

type Field 

type Field struct {
	Key   string
	Value interface{}
}

Field 日志字段

type Logger 

type Logger interface {
	Debug(msg string, fields ...Field)
	Info(msg string, fields ...Field)
	Warn(msg string, fields ...Field)
	Error(msg string, fields ...Field)
}

Logger 日志接口

type LongRunningExecutor 

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

LongRunningExecutor 长时运行工具执行器 管理异步任务的生命周期

func NewLongRunningExecutor 

func NewLongRunningExecutor() *LongRunningExecutor

NewLongRunningExecutor 创建长时运行工具执行器

func (*LongRunningExecutor) Cancel 

func (e *LongRunningExecutor) Cancel(ctx context.Context, taskID string) error

Cancel 取消任务

func (*LongRunningExecutor) Cleanup 

func (e *LongRunningExecutor) Cleanup(before time.Time) int

Cleanup 清理已完成的任务 清理指定时间之前完成的任务

func (*LongRunningExecutor) GetStatus 

func (e *LongRunningExecutor) GetStatus(ctx context.Context, taskID string) (*TaskStatus, error)

GetStatus 获取任务状态

func (*LongRunningExecutor) ListTasks 

func (e *LongRunningExecutor) ListTasks(filter func(*TaskStatus) bool) []*TaskStatus

ListTasks 列出所有任务

func (*LongRunningExecutor) StartAsync 

func (e *LongRunningExecutor) StartAsync(
	ctx context.Context,
	tool Tool,
	args map[string]interface{},
) (string, error)

StartAsync 异步启动工具

func (*LongRunningExecutor) UpdateProgress 

func (e *LongRunningExecutor) UpdateProgress(taskID string, progress float64, metadata map[string]interface{}) error

UpdateProgress 更新任务进度（供工具内部调用）

type LongRunningTool 

type LongRunningTool interface {
	Tool

	// IsLongRunning 标记为长时运行工具
	IsLongRunning() bool

	// StartAsync 异步启动工具执行
	// 返回任务 ID，可用于查询状态或取消
	StartAsync(ctx context.Context, args map[string]interface{}) (string, error)

	// GetStatus 获取任务执行状态
	GetStatus(ctx context.Context, taskID string) (*TaskStatus, error)

	// Cancel 取消正在执行的任务
	Cancel(ctx context.Context, taskID string) error
}

LongRunningTool 长时运行工具接口 参考 Google ADK-Go 的长时运行工具设计

使用场景: - 文件上传/下载 - 数据库备份 - 机器学习训练 - 大数据处理

type MemoryResult 

type MemoryResult struct {
	Content   string
	Score     float64
	Timestamp time.Time
	Metadata  map[string]interface{}
}

MemoryResult 记忆搜索结果

type Metrics 

type Metrics interface {
	IncrementCounter(name string, value int64)
	RecordDuration(name string, duration time.Duration)
}

Metrics 指标接口 (简化版)

type Predicate 

type Predicate func(ctx ReadonlyContext, tool Tool) bool

Predicate 工具过滤谓词 用于动态决定是否暴露某个工具给 LLM

func AndPredicate 

func AndPredicate(predicates ...Predicate) Predicate

AndPredicate 组合多个谓词 (AND)

func NotPredicate 

func NotPredicate(predicate Predicate) Predicate

NotPredicate 取反谓词

func OrPredicate 

func OrPredicate(predicates ...Predicate) Predicate

OrPredicate 组合多个谓词 (OR)

func PrefixPredicate 

func PrefixPredicate(prefix string) Predicate

PrefixPredicate 基于前缀的过滤器

func StringPredicate 

func StringPredicate(allowedTools []string) Predicate

StringPredicate 基于工具名称的过滤器

type ReadonlyContext 

type ReadonlyContext interface {
	AgentID() string
	SessionID() string
	State() session.ReadonlyState
}

ReadonlyContext 只读上下文

type Registry 

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

Registry 工具注册表

func NewRegistry 

func NewRegistry() *Registry

NewRegistry 创建工具注册表

func (*Registry) Create 

func (r *Registry) Create(name string, config map[string]interface{}) (Tool, error)

Create 创建工具实例

func (*Registry) Has 

func (r *Registry) Has(name string) bool

Has 检查工具是否已注册

func (*Registry) List 

func (r *Registry) List() []string

List 列出所有已注册的工具

func (*Registry) Register 

func (r *Registry) Register(name string, factory ToolFactory)

Register 注册工具

type RetryPolicy 

type RetryPolicy struct {
	// MaxRetries 最大重试次数
	MaxRetries int

	// InitialBackoff 初始退避时间
	InitialBackoff time.Duration

	// MaxBackoff 最大退避时间
	MaxBackoff time.Duration

	// BackoffMultiplier 退避倍数
	BackoffMultiplier float64

	// RetryableErrors 可重试的错误类型
	RetryableErrors []string
}

RetryPolicy 重试策略

func DefaultRetryPolicy 

func DefaultRetryPolicy() *RetryPolicy

DefaultRetryPolicy 默认重试策略

func NoRetryPolicy 

func NoRetryPolicy() *RetryPolicy

NoRetryPolicy 不重试策略

type Span 

type Span interface {
	End()
	SetAttribute(key string, value interface{})
	RecordError(err error)
}

Span 追踪 span 接口

type TaskState 

type TaskState int

TaskState 任务状态枚举 

const (
	TaskStatePending   TaskState = iota // 待执行
	TaskStateRunning                    // 执行中
	TaskStateCompleted                  // 已完成
	TaskStateFailed                     // 失败
	TaskStateCancelled                  // 已取消
)

func (TaskState) IsTerminal 

func (s TaskState) IsTerminal() bool

IsTerminal 判断是否为终态

func (TaskState) String 

func (s TaskState) String() string

String 返回状态的字符串表示

type TaskStatus 

type TaskStatus struct {
	TaskID    string                 // 任务 ID
	State     TaskState              // 当前状态
	Progress  float64                // 进度 0.0 - 1.0
	Result    interface{}            // 执行结果（完成时）
	Error     error                  // 错误信息（失败时）
	StartTime time.Time              // 开始时间
	EndTime   *time.Time             // 结束时间（完成/失败/取消时）
	Metadata  map[string]interface{} // 额外元数据
}

TaskStatus 任务状态

func WaitForCompletion 

func WaitForCompletion(executor *LongRunningExecutor, taskID string, pollInterval time.Duration, timeout time.Duration) (*TaskStatus, error)

WaitFor 等待任务完成（辅助函数）

type Tool 

type Tool interface {
	// Name 工具名称
	Name() string

	// Description 工具描述
	Description() string

	// InputSchema JSON Schema定义
	InputSchema() map[string]interface{}

	// Execute 执行工具
	Execute(ctx context.Context, input map[string]interface{}, tc *ToolContext) (interface{}, error)

	// Prompt 工具使用说明(可选)
	Prompt() string
}

Tool 工具接口

type ToolCallRecordBuilder 

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

ToolCallRecordBuilder 工具调用记录构建器

func NewToolCallRecord 

func NewToolCallRecord(id, name string, input map[string]interface{}) *ToolCallRecordBuilder

NewToolCallRecord 创建工具调用记录

func (*ToolCallRecordBuilder) Build 

func (b *ToolCallRecordBuilder) Build() *types.ToolCallRecord

Build 构建记录

func (*ToolCallRecordBuilder) SetApproval 

func (b *ToolCallRecordBuilder) SetApproval(approval types.ToolCallApproval) *ToolCallRecordBuilder

SetApproval 设置审批信息

func (*ToolCallRecordBuilder) SetResult 

func (b *ToolCallRecordBuilder) SetResult(result interface{}, err error) *ToolCallRecordBuilder

SetResult 设置结果

func (*ToolCallRecordBuilder) SetState 

func (b *ToolCallRecordBuilder) SetState(state types.ToolCallState, note string) *ToolCallRecordBuilder

SetState 设置状态

func (*ToolCallRecordBuilder) SetTiming 

func (b *ToolCallRecordBuilder) SetTiming(startedAt, completedAt time.Time) *ToolCallRecordBuilder

SetTiming 设置时间信息

type ToolContext 

type ToolContext struct {
	AgentID    string
	Sandbox    sandbox.Sandbox
	Signal     context.Context
	Emit       func(eventType string, data interface{})
	Services   map[string]interface{}
	ThreadID   string // Working Memory 会话 ID
	ResourceID string // Working Memory 资源 ID
}

ToolContext 工具执行上下文

type ToolDescriptor 

type ToolDescriptor struct {
	Name       string                 `json:"name"`
	RegistryID string                 `json:"registry_id,omitempty"`
	Config     map[string]interface{} `json:"config,omitempty"`
}

ToolDescriptor 工具描述符(用于持久化)

type ToolFactory 

type ToolFactory func(config map[string]interface{}) (Tool, error)

ToolFactory 工具工厂函数

type ToolNotFoundError 

type ToolNotFoundError struct {
	Name string
}

ToolNotFoundError 工具未找到错误

func (*ToolNotFoundError) Error 

func (e *ToolNotFoundError) Error() string

type Toolset 

type Toolset interface {
	// Name 工具集名称
	Name() string

	// Description 工具集描述
	Description() string

	// Tools 返回工具列表
	// 可以根据上下文动态决定返回哪些工具
	Tools(ctx ReadonlyContext) ([]Tool, error)

	// Initialize 初始化工具集
	Initialize(ctx context.Context) error

	// Cleanup 清理工具集资源
	Cleanup(ctx context.Context) error
}

Toolset 工具集接口 参考 Google ADK-Go 的 Toolset 设计

type Tracer 

type Tracer interface {
	StartSpan(ctx context.Context, name string) (context.Context, Span)
}

Tracer 追踪接口 (简化版)

Source Files

View all Source files

Directories

Path Synopsis

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.