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 ¶
- func WithMiddleware(t aitool.Tool, mws ...Middleware) aitool.Tool
- func WithRateLimit(t aitool.Tool, rps float64) aitool.Tool
- func WithRetry(t aitool.Tool, maxRetries int, backoff time.Duration) aitool.Tool
- func WithTimeout(t aitool.Tool, timeout time.Duration) aitool.Tool
- func WithToolContext(ctx context.Context, tc *ToolContext) context.Context
- type APIKeyAuth
- type AuthProvider
- type BearerAuth
- type Credential
- type CredentialRegistry
- type CredentialType
- type Middleware
- type ToolContext
- func (tc *ToolContext) DeleteState(key string)
- func (tc *ToolContext) GetCredential(ctx context.Context, name string) (*Credential, error)
- func (tc *ToolContext) GetState(key string) (any, bool)
- func (tc *ToolContext) SetState(key string, value any)
- func (tc *ToolContext) StateChanges() map[string]any
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithMiddleware ¶
func WithMiddleware(t aitool.Tool, mws ...Middleware) aitool.Tool
WithMiddleware 将多个中间件应用到工具上
中间件按从左到右的顺序包裹,即第一个中间件在最外层。
func WithRetry ¶
WithRetry 为工具添加失败重试能力
maxRetries 为最大重试次数(不含首次执行),backoff 为初始退避时间。 每次重试退避时间翻倍,上限 30 秒。
func WithTimeout ¶
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 认证凭据
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 ¶
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) 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 提供文本处理工具 |