Documentation
¶
Index ¶
- func GetDifyRetrievedRecords(m map[string]any, key string) []dify.RetrievedRecord
- func NewDifyRetrievalTool(cfg DifyRetrievalConfig, opts ...DifyRetrievalOption) agentloop.Tool
- func NewTavilySearchTool(apiKey string, maxResults int, opts ...TavilySearchOption) agentloop.Tool
- type DifyRetrievalArgs
- type DifyRetrievalConfig
- type DifyRetrievalOption
- type TavilySearchArgs
- type TavilySearchOption
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:
- WithDifyToolName — override the name shown to the LLM (default: "dify_retrieval")
- WithDifyToolDescription — override the description shown to the LLM
- WithDifyMetadataAppendKey — append raw RetrievedRecords to AgentContext.Metadata
- WithDifyDocNameFilter — add a document_name filter condition (FAQ/KB split pattern)
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 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)},
})
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 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 ¶
TavilySearchOption is a functional option that customizes the SearchReq before it is sent to Tavily. It is applied after all TavilySearchArgs fields have been set, so it can override any field.
Source Files