tool

package
v0.5.11 Latest Latest
Warning

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

Go to latest
Published: Aug 12, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package tool 提供工具系统的扩展功能

auth.go 实现工具认证系统和 ToolContext 状态感知:

  • Credential: 统一的认证凭据管理
  • ToolContext: 工具执行时的上下文,可感知和修改 Session 状态
  • AuthProvider: 认证提供者接口(支持 API Key、OAuth、JWT)

参考 Google ADK Go 的 ToolContext 设计。

使用示例:

// 注册认证提供者
registry := NewCredentialRegistry()
registry.Register("github", NewAPIKeyAuth("ghp_xxx"))

// 工具执行时获取认证
tool := NewAuthenticatedTool(myTool, registry, "github")

Package tool 的中间件模块

提供工具执行中间件,增强工具能力:

  • 超时控制:限制工具执行时间
  • 自动重试:失败后指数退避重试
  • 速率限制:Token Bucket 限流
  • 中间件链:组合多个中间件

使用示例:

wrapped := tool.WithTimeout(myTool, 5*time.Second)
wrapped = tool.WithRetry(wrapped, 3, time.Second)
result, err := wrapped.Execute(ctx, args)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func WithMiddleware

func WithMiddleware(t aitool.Tool, mws ...Middleware) aitool.Tool

WithMiddleware 将多个中间件应用到工具上

中间件按从左到右的顺序包裹,即第一个中间件在最外层。

func WithRateLimit

func WithRateLimit(t aitool.Tool, rps float64) aitool.Tool

WithRateLimit 为工具添加速率限制

rps 为每秒允许的请求数(基于 Token Bucket 算法)。

func WithRetry

func WithRetry(t aitool.Tool, maxRetries int, backoff time.Duration) aitool.Tool

WithRetry 为工具添加失败重试能力

maxRetries 为最大重试次数(不含首次执行),backoff 为初始退避时间。 每次重试退避时间翻倍,上限 30 秒。

func WithTimeout

func WithTimeout(t aitool.Tool, timeout time.Duration) aitool.Tool

WithTimeout 为工具添加执行超时限制

func WithToolContext

func WithToolContext(ctx context.Context, tc *ToolContext) context.Context

WithToolContext 将 ToolContext 注入到 context 中

Types

type APIKeyAuth

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

APIKeyAuth API Key 认证提供者

func NewAPIKeyAuth

func NewAPIKeyAuth(name, apiKey string) *APIKeyAuth

NewAPIKeyAuth 创建 API Key 认证

func (*APIKeyAuth) GetCredential

func (a *APIKeyAuth) GetCredential(_ context.Context) (*Credential, error)

func (*APIKeyAuth) Name

func (a *APIKeyAuth) Name() string

func (*APIKeyAuth) RefreshCredential

func (a *APIKeyAuth) RefreshCredential(ctx context.Context) (*Credential, error)

type AuthProvider

type AuthProvider interface {
	// Name 提供者名称
	Name() string

	// GetCredential 获取认证凭据
	GetCredential(ctx context.Context) (*Credential, error)

	// RefreshCredential 刷新凭据(OAuth 场景)
	RefreshCredential(ctx context.Context) (*Credential, error)
}

AuthProvider 认证提供者接口

type BearerAuth

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

BearerAuth Bearer Token 认证提供者

func NewBearerAuth

func NewBearerAuth(name, token string) *BearerAuth

NewBearerAuth 创建 Bearer Token 认证

func (*BearerAuth) GetCredential

func (a *BearerAuth) GetCredential(_ context.Context) (*Credential, error)

func (*BearerAuth) Name

func (a *BearerAuth) Name() string

func (*BearerAuth) RefreshCredential

func (a *BearerAuth) RefreshCredential(ctx context.Context) (*Credential, error)

type Credential

type Credential struct {
	// Type 认证类型
	Type CredentialType `json:"type"`

	// Token 认证令牌/密钥
	Token string `json:"-"` // 不序列化

	// Metadata 额外认证信息
	Metadata map[string]string `json:"metadata,omitempty"`

	// ExpiresAt 过期时间(OAuth 场景)
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

Credential 认证凭据

func (*Credential) Header

func (c *Credential) Header() string

Header 返回 HTTP Authorization 头

func (*Credential) IsExpired

func (c *Credential) IsExpired() bool

IsExpired 是否已过期

type CredentialRegistry

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

CredentialRegistry 认证凭据注册表 统一管理多个认证提供者

func NewCredentialRegistry

func NewCredentialRegistry() *CredentialRegistry

NewCredentialRegistry 创建凭据注册表

func (*CredentialRegistry) GetCredential

func (r *CredentialRegistry) GetCredential(ctx context.Context, name string) (*Credential, error)

GetCredential 获取指定名称的认证凭据

func (*CredentialRegistry) Register

func (r *CredentialRegistry) Register(name string, provider AuthProvider)

Register 注册认证提供者

type CredentialType

type CredentialType int

CredentialType 认证类型

const (
	// CredentialAPIKey API Key 认证
	CredentialAPIKey CredentialType = iota

	// CredentialOAuth OAuth 认证
	CredentialOAuth

	// CredentialJWT JWT 认证
	CredentialJWT

	// CredentialBasic Basic Auth 认证
	CredentialBasic

	// CredentialBearer Bearer Token 认证
	CredentialBearer

	// CredentialCustom 自定义认证
	CredentialCustom
)

type Middleware

type Middleware func(next aitool.Tool) aitool.Tool

Middleware 工具中间件函数

func RateLimitMiddleware

func RateLimitMiddleware(rps float64) Middleware

RateLimitMiddleware 返回速率限制中间件

func RetryMiddleware

func RetryMiddleware(maxRetries int, backoff time.Duration) Middleware

RetryMiddleware 返回重试中间件

func TimeoutMiddleware

func TimeoutMiddleware(timeout time.Duration) Middleware

TimeoutMiddleware 返回超时中间件

type ToolContext

type ToolContext struct {
	// SessionID 当前会话 ID
	SessionID string

	// AgentID 当前 Agent ID
	AgentID string

	// State 可读写的会话状态
	State map[string]any

	// Credentials 认证注册表
	Credentials *CredentialRegistry
	// contains filtered or unexported fields
}

ToolContext 工具执行上下文 提供工具执行时的状态感知和修改能力

func GetToolContext

func GetToolContext(ctx context.Context) *ToolContext

GetToolContext 从 context 中获取 ToolContext

func NewToolContext

func NewToolContext(sessionID, agentID string, state map[string]any, creds *CredentialRegistry) *ToolContext

NewToolContext 创建工具上下文

func (*ToolContext) DeleteState

func (tc *ToolContext) DeleteState(key string)

DeleteState 删除状态值

func (*ToolContext) GetCredential

func (tc *ToolContext) GetCredential(ctx context.Context, name string) (*Credential, error)

GetCredential 获取认证凭据

func (*ToolContext) GetState

func (tc *ToolContext) GetState(key string) (any, bool)

GetState 获取状态值

func (*ToolContext) SetState

func (tc *ToolContext) SetState(key string, value any)

SetState 设置状态值(自动追踪变更)

func (*ToolContext) StateChanges

func (tc *ToolContext) StateChanges() map[string]any

StateChanges 返回所有状态变更

Directories

Path Synopsis
Package api 提供常用 API 集成工具
Package api 提供常用 API 集成工具
Package browser 提供浏览器自动化工具
Package browser 提供浏览器自动化工具
Package database 提供数据库查询工具
Package database 提供数据库查询工具
Package datetime 提供日期时间处理工具
Package datetime 提供日期时间处理工具
Package file 提供 AI Agent 的文件操作工具
Package file 提供 AI Agent 的文件操作工具
Package http 提供 HTTP API 调用工具
Package http 提供 HTTP API 调用工具
Package math 提供数学计算工具
Package math 提供数学计算工具
Package python 提供 AI Agent 的 Python 代码执行工具
Package python 提供 AI Agent 的 Python 代码执行工具
Package sandbox 提供 AI Agent 的沙箱代码执行环境
Package sandbox 提供 AI Agent 的沙箱代码执行环境
Package search 提供搜索引擎工具
Package search 提供搜索引擎工具
Package shell 提供 AI Agent 的 Shell 命令执行工具
Package shell 提供 AI Agent 的 Shell 命令执行工具
Package text 提供文本处理工具
Package text 提供文本处理工具

Jump to

Keyboard shortcuts

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