tools

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Jul 29, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetDifyRetrievedRecords added in v0.0.17 

func GetDifyRetrievedRecords(m map[string]any, key string) []dify.RetrievedRecord

GetDifyRetrievedRecords retrieves the []dify.RetrievedRecord slice accumulated under key from a TaskOutput.Metadata snapshot. Returns nil if the key is absent or the map is nil.

func NewDifyRetrievalTool 

func NewDifyRetrievalTool(cfg DifyRetrievalConfig, opts ...DifyRetrievalOption) agentloop.Tool

NewDifyRetrievalTool creates an agentloop Tool that retrieves relevant document segments from a Dify knowledge base. Host, ApiKey, DatasetId and RetrievalModel are fixed at construction time and never exposed to the LLM.

Available options:

Example — two tools splitting FAQ vs knowledge base, both collecting references: 

const refsKey = "rag_refs"
cfg := tools.DifyRetrievalConfig{
    Host:      "https://api.dify.ai",
    ApiKey:    os.Getenv("DIFY_API_KEY"),
    DatasetId: os.Getenv("DIFY_DATASET_ID"),
    RetrievalModel: &dify.RetrieveModelParam{
        TopK:                  5,
        SearchMethod:          dify.SearchMethodHybrid,
        RerankingEnable:       true,
        RerankingMode:         dify.RerankModeWeightedScore,
        Weights:               &dify.WeightModel{
            VectorSetting:  &dify.WeightVectorSetting{VectorWeight: 0.7},
            KeywordSetting: &dify.WeightKeywordSetting{KeywordWeight: 0.3},
        },
        ScoreThresholdEnabled: true,
        ScoreThreshold:        0.4,
    },
}
agent, _ := agentloop.NewAgent(agentloop.AgentConfig{
    Tools: []agentloop.Tool{
        tools.NewDifyRetrievalTool(cfg,
            tools.WithDifyToolName("query_faq"),
            tools.WithDifyMetadataAppendKey(refsKey),
            tools.WithDifyDocNameFilter("FAQ", "contains"),
        ),
        tools.NewDifyRetrievalTool(cfg,
            tools.WithDifyToolName("query_knowledge_base"),
            tools.WithDifyMetadataAppendKey(refsKey),
            tools.WithDifyDocNameFilter("FAQ", "not contains"),
        ),
    },
})
out, _ := agent.Execute(rail, req)
refs := tools.GetDifyRetrievedRecords(out.Metadata, refsKey)

func NewTavilyExtractTool added in v0.0.25 

func NewTavilyExtractTool(apiKey string, opts ...TavilyExtractOption) agentloop.Tool

NewTavilyExtractTool creates an agentloop Tool that extracts web page content from URLs using Tavily Extract. apiKey is captured in a closure and never exposed to the LLM. opts are applied to configure the tool and per-call request fields.

Example: 

agent, _ := agentloop.NewAgent(agentloop.AgentConfig{
    Tools: []agentloop.Tool{tools.NewTavilyExtractTool(os.Getenv("TAVILY_API_KEY"))},
})

func NewTavilySearchTool 

func NewTavilySearchTool(apiKey string, maxResults int, opts ...TavilySearchOption) agentloop.Tool

NewTavilySearchTool creates an agentloop Tool that performs a Tavily web search. apiKey is captured in a closure and never exposed to the LLM. maxResults controls how many results are returned (1-20); pass 0 to use the default of 5. opts are applied to the SearchReq after args, allowing callers to set any additional fields.

Example: 

agent, _ := agentloop.NewAgent(agentloop.AgentConfig{
    Tools: []agentloop.Tool{tools.NewTavilySearchTool(os.Getenv("TAVILY_API_KEY"), 5)},
})

func NewTavilySocialMediaSearchTool added in v0.0.29 

func NewTavilySocialMediaSearchTool(apiKey string, maxResults int, opts ...TavilySearchOption) agentloop.Tool

NewTavilySocialMediaSearchTool creates an agentloop Tool that searches Facebook and X (Twitter) via Tavily with IncludeDomains pre-set to ["facebook.com", "x.com"]. The tool is exposed to the LLM as "search_social_media". Additional opts (e.g., WithSearchOption for date ranges) are applied after the domain restriction.

Types

type DifyRetrievalArgs 

type DifyRetrievalArgs struct {
	// Query is the search query used to retrieve relevant segments. Required.
	Query string `json:"query"`
}

DifyRetrievalArgs are the typed arguments for the dify_retrieval tool.

type DifyRetrievalConfig 

type DifyRetrievalConfig struct {
	// Host is the base URL of the Dify API (e.g. "https://api.dify.ai").
	Host string

	// ApiKey is the Dify dataset API key.
	ApiKey string

	// DatasetId is the ID of the Dify knowledge base (dataset) to query.
	DatasetId string

	// RetrievalModel controls retrieval behaviour (TopK, search method, reranking, etc.).
	// If nil, Dify will use the dataset's default retrieval settings.
	RetrievalModel *dify.RetrieveModelParam
}

DifyRetrievalConfig holds the caller-controlled parameters for NewDifyRetrievalTool. These are fixed at construction time and never exposed to the LLM.

type DifyRetrievalOption added in v0.0.17 

type DifyRetrievalOption func(o *difyRetrievalOpts)

DifyRetrievalOption is a functional option that customises the tool after DifyRetrievalConfig has been applied.

func WithDifyDocNameFilter added in v0.0.17 

func WithDifyDocNameFilter(value, operator string) DifyRetrievalOption

WithDifyDocNameFilter adds a document_name metadata filtering condition to the retrieval request. operator is one of the Dify comparison operators: "contains", "not contains", "start with", "end with", "is", "is not", etc. value is the keyword to match against document names.

This is a convenience wrapper for the common FAQ / knowledge-base split pattern where one tool queries only documents whose name contains a keyword and another queries everything else: 

tools.NewDifyRetrievalTool(cfg,
    tools.WithDifyToolName("query_faq"),
    tools.WithDifyDocNameFilter("FAQ", "contains"),
)
tools.NewDifyRetrievalTool(cfg,
    tools.WithDifyToolName("query_knowledge_base"),
    tools.WithDifyDocNameFilter("FAQ", "not contains"),
)

If the config already has a RetrievalModel with MetadataFilteringConditions, the new condition is appended (logical operator defaults to "and").

func WithDifyMetadataAppendKey added in v0.0.17 

func WithDifyMetadataAppendKey(metaKey string) DifyRetrievalOption

WithDifyMetadataAppendKey enables post-retrieval record collection. After each successful Dify call the raw []dify.RetrievedRecord slice is appended to AgentContext.Metadata under metaKey. The caller can read it back from TaskOutput.Metadata after Execute returns: 

const refsKey = "rag_refs"
out, _ := agent.Execute(rail, req)
refs := tools.GetDifyRetrievedRecords(out.Metadata, refsKey)

func WithDifyToolDescription added in v0.0.17 

func WithDifyToolDescription(desc string) DifyRetrievalOption

WithDifyToolDescription overrides the tool description shown to the LLM.

func WithDifyToolName added in v0.0.17 

func WithDifyToolName(name string) DifyRetrievalOption

WithDifyToolName overrides the tool name that is registered with the LLM. Useful when an agent uses multiple Dify knowledge bases simultaneously and each tool needs a distinct, descriptive name.

type TavilyExtractArgs added in v0.0.25 

type TavilyExtractArgs struct {
	// URLs is the list of URLs to extract content from. Required.
	URLs []string `json:"urls" desc:"List of URLs to extract content from."`

	Query string `json:"query,omitempty" desc:"Optional query to rerank extracted content chunks by relevance."`
}

TavilyExtractArgs are the typed arguments for the tavily_extract tool.

type TavilyExtractOption added in v0.0.25 

type TavilyExtractOption func(o *tavilyExtractCfg)

TavilyExtractOption is a functional option that customizes NewTavilyExtractTool. Use WithTavilyExtractName to override the tool name, and WithExtractReqOpt to modify per-call request fields before they are sent to Tavily.

func WithExtractReqOpt added in v0.0.26 

func WithExtractReqOpt(fn func(*TavilyExtractReq)) TavilyExtractOption

WithExtractReqOpt applies fn to each TavilyExtractReq before it is sent to Tavily. It is applied after all TavilyExtractArgs fields have been set, so it can override any field.

func WithTavilyExtractName added in v0.0.26 

func WithTavilyExtractName(name string) TavilyExtractOption

WithTavilyExtractName overrides the tool name exposed to the LLM (default: "tavily_extract").

type TavilyExtractReq added in v0.0.25 

type TavilyExtractReq struct {
	// URLs is the list of URLs to extract content from. Required.
	URLs []string `json:"urls"`

	// Query is an optional query used to rerank extracted content chunks by relevance.
	Query string `json:"query,omitempty"`

	// ExtractDepth controls extraction depth. One of "basic" or "advanced".
	ExtractDepth string `json:"extract_depth,omitempty"`

	// Format is the output format of extracted content. One of "markdown" or "text".
	Format string `json:"format,omitempty"`
}

type TavilySearchArgs 

type TavilySearchArgs struct {
	// Query is the search query string. Required.
	Query string `json:"query"`

	// Topic narrows the search category. One of "general", "news", "finance".
	Topic string `json:"topic,omitempty"`

	// TimeRange restricts results to a time window. One of "day", "week", "month", "year".
	TimeRange string `json:"time_range,omitempty"`

	// StartDate returns results published after this date (format: YYYY-MM-DD).
	StartDate string `json:"start_date,omitempty"`

	// EndDate returns results published before this date (format: YYYY-MM-DD).
	EndDate string `json:"end_date,omitempty"`
}

TavilySearchArgs are the typed arguments for the tavily_search tool.

type TavilySearchOption 

type TavilySearchOption func(o *tavilySearchConfig)

TavilySearchOption is a functional option for NewTavilySearchTool.

func WithSearchOption added in v0.0.25 

func WithSearchOption(fn func(*search.SearchReq)) TavilySearchOption

WithSearchOption applies fn to each SearchReq before it is sent to Tavily. It is applied after all TavilySearchArgs fields have been set, so it can override any field.

func WithToolDescription added in v0.0.25 

func WithToolDescription(desc string) TavilySearchOption

WithToolDescription overrides the tool description exposed to the LLM.

func WithToolName added in v0.0.25 

func WithToolName(name string) TavilySearchOption

WithToolName overrides the tool name exposed to the LLM (default: "tavily_search").

Source Files

View all Source files

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.