hosted

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Feb 23, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

包 hosted 提供由平台托管的工具注册与远程服务接入能力。

概述

hosted 解决的核心问题是:Agent 在执行过程中需要调用外部能力(如网络搜索、 文件检索、代码执行等),这些能力由平台侧统一托管而非 Agent 自行实现。 本包提供了标准化的工具接口、注册中心与内置工具实现,使 Agent 能够以 统一方式发现和调用托管服务。

核心接口

本包围绕以下类型展开:

  • HostedTool:托管工具接口,定义 Type / Name / Schema / Execute 标准契约
  • ToolRegistry:工具注册中心,线程安全地管理工具的注册、查找与 Schema 导出
  • HostedToolType:工具类型枚举(web_search / file_search / code_execution / retrieval)

内置工具

  • WebSearchTool:网络搜索工具,通过 HTTP API 执行实时搜索并返回结构化结果
  • FileSearchTool:文件搜索工具,基于 FileSearchStore 接口执行语义检索

每个工具均实现 HostedTool 接口,支持 JSON Schema 参数描述与 context 感知执行。

使用方式

  1. 创建 ToolRegistry 并注册所需工具
  2. 通过 Registry.GetSchemas() 将工具能力暴露给 LLM
  3. LLM 返回工具调用时,通过 Registry.Get(name) 查找并执行对应工具

扩展方式

实现 HostedTool 接口即可接入自定义托管工具,例如数据库查询、 内部 API 网关调用或第三方 SaaS 服务集成。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CodeExecConfig added in v1.0.0

type CodeExecConfig struct {
	Executor CodeExecutor
	Timeout  time.Duration
	Logger   *zap.Logger
}

CodeExecConfig configures the code execution tool.

type CodeExecOutput added in v1.0.0

type CodeExecOutput struct {
	Stdout   string        `json:"stdout"`
	Stderr   string        `json:"stderr"`
	ExitCode int           `json:"exit_code"`
	Duration time.Duration `json:"duration"`
}

CodeExecOutput holds the result of a code execution.

type CodeExecTool added in v1.0.0

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

CodeExecTool provides sandboxed code execution as a hosted tool.

func NewCodeExecTool added in v1.0.0

func NewCodeExecTool(config CodeExecConfig) *CodeExecTool

NewCodeExecTool creates a new code execution tool.

func (*CodeExecTool) Description added in v1.0.0

func (t *CodeExecTool) Description() string

func (*CodeExecTool) Execute added in v1.0.0

func (t *CodeExecTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*CodeExecTool) Name added in v1.0.0

func (t *CodeExecTool) Name() string

func (*CodeExecTool) Schema added in v1.0.0

func (t *CodeExecTool) Schema() llm.ToolSchema

func (*CodeExecTool) Type added in v1.0.0

func (t *CodeExecTool) Type() HostedToolType

type CodeExecutor added in v1.0.0

type CodeExecutor interface {
	Execute(ctx context.Context, language string, code string, timeout time.Duration) (*CodeExecOutput, error)
}

CodeExecutor is the interface for sandboxed code execution. This is a local interface following the workflow-local interface pattern (§15) to avoid importing agent/execution directly.

type FileSearchResult

type FileSearchResult struct {
	FileID   string         `json:"file_id"`
	FileName string         `json:"file_name"`
	Content  string         `json:"content"`
	Score    float64        `json:"score"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

FileSearchResult代表文件搜索结果.

type FileSearchStore added in v1.0.0

type FileSearchStore interface {
	Search(ctx context.Context, query string, limit int) ([]FileSearchResult, error)
	Index(ctx context.Context, fileID string, content []byte) error
}

FileSearchStore is the store interface for file search operations. It operates on text queries (not raw vectors), distinct from rag.VectorStore.

type FileSearchTool

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

FileSearchTool 执行文件搜索功能.

func NewFileSearchTool

func NewFileSearchTool(store FileSearchStore, maxResults int) *FileSearchTool

NewFileSearchTool创建了一个新的文件搜索工具.

func (*FileSearchTool) Description

func (t *FileSearchTool) Description() string

func (*FileSearchTool) Execute

func (t *FileSearchTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*FileSearchTool) Name

func (t *FileSearchTool) Name() string

func (*FileSearchTool) Schema

func (t *FileSearchTool) Schema() llm.ToolSchema

func (*FileSearchTool) Type

func (t *FileSearchTool) Type() HostedToolType

type HostedTool

type HostedTool interface {
	Type() HostedToolType
	Name() string
	Description() string
	Schema() llm.ToolSchema
	Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)
}

HostToole 代表由提供者托管的工具.

type HostedToolType

type HostedToolType string

Hosted ToolType 定义了主机工具的类型.

const (
	ToolTypeWebSearch  HostedToolType = "web_search"
	ToolTypeFileSearch HostedToolType = "file_search"
	ToolTypeCodeExec   HostedToolType = "code_execution"
	ToolTypeRetrieval  HostedToolType = "retrieval"
)

type RetrievalResult added in v1.0.0

type RetrievalResult struct {
	DocumentID string         `json:"document_id"`
	Content    string         `json:"content"`
	Score      float64        `json:"score"`
	Metadata   map[string]any `json:"metadata,omitempty"`
}

RetrievalResult represents a single retrieval result.

type RetrievalStore added in v1.0.0

type RetrievalStore interface {
	Retrieve(ctx context.Context, query string, topK int) ([]RetrievalResult, error)
}

RetrievalStore is the interface for document retrieval. Local interface to avoid importing rag package directly (§15).

type RetrievalTool added in v1.0.0

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

RetrievalTool provides RAG retrieval as a hosted tool.

func NewRetrievalTool added in v1.0.0

func NewRetrievalTool(store RetrievalStore, maxResults int, logger *zap.Logger) *RetrievalTool

NewRetrievalTool creates a new retrieval tool.

func (*RetrievalTool) Description added in v1.0.0

func (t *RetrievalTool) Description() string

func (*RetrievalTool) Execute added in v1.0.0

func (t *RetrievalTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*RetrievalTool) Name added in v1.0.0

func (t *RetrievalTool) Name() string

func (*RetrievalTool) Schema added in v1.0.0

func (t *RetrievalTool) Schema() llm.ToolSchema

func (*RetrievalTool) Type added in v1.0.0

func (t *RetrievalTool) Type() HostedToolType

type ToolExecuteFunc added in v1.0.0

type ToolExecuteFunc func(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

ToolExecuteFunc is the function signature for tool execution.

type ToolMiddleware added in v1.0.0

type ToolMiddleware func(next ToolExecuteFunc) ToolExecuteFunc

ToolMiddleware wraps tool execution with cross-cutting concerns.

func WithLogging added in v1.0.0

func WithLogging(logger *zap.Logger) ToolMiddleware

WithLogging returns a middleware that logs tool invocations.

func WithMetrics added in v1.0.0

func WithMetrics(onExecute func(name string, duration time.Duration, err error)) ToolMiddleware

WithMetrics returns a middleware that calls a metrics callback after execution.

func WithTimeout added in v1.0.0

func WithTimeout(d time.Duration) ToolMiddleware

WithTimeout returns a middleware that enforces an execution timeout.

type ToolRegistry

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

ToolRegistry manages hosted tools.

func NewToolRegistry

func NewToolRegistry(logger *zap.Logger) *ToolRegistry

NewToolRegistry创建了新的主机工具注册.

func (*ToolRegistry) Execute added in v1.0.0

func (r *ToolRegistry) Execute(ctx context.Context, name string, args json.RawMessage) (json.RawMessage, error)

Execute looks up a tool by name and executes it with the middleware chain applied.

func (*ToolRegistry) Get

func (r *ToolRegistry) Get(name string) (HostedTool, bool)

按名称获取主机工具 。

func (*ToolRegistry) GetSchemas

func (r *ToolRegistry) GetSchemas() []llm.ToolSchema

GetSchemas 返回所有工具的策略 。

func (*ToolRegistry) List

func (r *ToolRegistry) List() []HostedTool

列表返回所有已注册的工具 。

func (*ToolRegistry) Register

func (r *ToolRegistry) Register(tool HostedTool)

注册注册一个主机工具 。

func (*ToolRegistry) Use added in v1.0.0

func (r *ToolRegistry) Use(middleware ...ToolMiddleware)

Use appends middleware(s) to the registry's middleware chain.

type WebSearchArgs

type WebSearchArgs struct {
	Query      string `json:"query"`
	MaxResults int    `json:"max_results,omitempty"`
}

WebSearchArgs 代表网络搜索参数.

type WebSearchConfig

type WebSearchConfig struct {
	APIKey     string
	Endpoint   string
	MaxResults int
	Timeout    time.Duration
}

WebSearchConfig 配置了网络搜索工具.

type WebSearchResult

type WebSearchResult struct {
	Title   string `json:"title"`
	URL     string `json:"url"`
	Snippet string `json:"snippet"`
}

WebSearchResult代表搜索结果.

type WebSearchTool

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

WebSearchTool执行网络搜索功能.

func NewWebSearchTool

func NewWebSearchTool(config WebSearchConfig) *WebSearchTool

新WebSearchTooll创建了新的网络搜索工具.

func (*WebSearchTool) Description

func (t *WebSearchTool) Description() string

func (*WebSearchTool) Execute

func (t *WebSearchTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*WebSearchTool) Name

func (t *WebSearchTool) Name() string

func (*WebSearchTool) Schema

func (t *WebSearchTool) Schema() llm.ToolSchema

func (*WebSearchTool) Type

func (t *WebSearchTool) Type() HostedToolType

Jump to

Keyboard shortcuts

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