# Send Dify Knowledge Base Search to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "dify-kb-search",
    "name": "Dify Knowledge Base Search",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/xiaowenzhou/dify-kb-search",
    "canonicalUrl": "https://clawhub.ai/xiaowenzhou/dify-kb-search",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/dify-kb-search",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=dify-kb-search",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "scripts/list_datasets.py",
      "scripts/search.py"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "dify-kb-search",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-02T13:19:18.745Z",
      "expiresAt": "2026-05-09T13:19:18.745Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=dify-kb-search",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=dify-kb-search",
        "contentDisposition": "attachment; filename=\"dify-kb-search-1.1.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "dify-kb-search"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/dify-kb-search"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/dify-kb-search",
    "downloadUrl": "https://openagent3.xyz/downloads/dify-kb-search",
    "agentUrl": "https://openagent3.xyz/skills/dify-kb-search/agent",
    "manifestUrl": "https://openagent3.xyz/skills/dify-kb-search/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/dify-kb-search/agent.md"
  }
}
```
## Documentation

### Dify Knowledge Base Search Skill

🔍 Search your Dify Knowledge Base to get accurate, contextual answers

This skill enables AI agents to query Dify datasets for RAG (Retrieval-Augmented Generation) context retrieval. Perfect for knowledge base Q&A, documentation search, and contextual AI responses.

### ✨ Features

List Knowledge Bases - Discover all available Dify datasets
Smart Search - Query datasets with hybrid, semantic, or keyword search
Auto-Discovery - Automatically find available datasets if ID not provided
Configurable Results - Adjust top-k, search method, and reranking
Error Handling - Graceful error messages for debugging
Zero Hardcoding - All configuration via environment variables

### 1. Configure Environment Variables

Set up in openclaw.json:

{
  "env": {
    "vars": {
      "DIFY_API_KEY": "${DIFY_API_KEY}",
      "DIFY_BASE_URL": "https://dify.example.com/v1"
    }
  }
}

Environment Variables:

VariableRequiredDefaultDescriptionDIFY_API_KEY✅ Yes-Your Dify API Key (from Settings → API)DIFY_BASE_URL❌ Nohttp://localhost/v1Your Dify instance base URL

### 2. Install Dependencies

pip3 install requests

### dify_list

Lists all available knowledge bases (datasets) in your Dify instance.

Invocation: dify_list tool

Example Response:

{
  "status": "success",
  "count": 2,
  "datasets": [
    {
      "id": "dataset-abc123",
      "name": "Product Documentation",
      "doc_count": 42,
      "description": "All product guides and tutorials"
    },
    {
      "id": "dataset-xyz789",
      "name": "API Reference",
      "doc_count": 156,
      "description": "REST API documentation"
    }
  ]
}

Usage:

{}

### dify_search

Searches a Dify Dataset for relevant context chunks.

Invocation: dify_search tool (mapped to python3 scripts/search.py)

Parameters:

ParameterTypeRequiredDefaultDescriptionquerystring✅ Yes-Search query or questiondataset_idstring❌ NoAuto-discoverSpecific dataset ID to searchtop_kinteger❌ No3Number of results to returnsearch_methodstring❌ Nohybrid_searchSearch strategyreranking_enableboolean❌ NofalseEnable reranking for better results

Search Methods:

hybrid_search - Combine semantic + keyword search (recommended)
semantic_search - Meaning-based similarity search
keyword_search - Exact keyword matching

Example Usage:

{
  "query": "How do I configure OpenClaw?",
  "top_k": 5
}

{
  "query": "API authentication methods",
  "dataset_id": "dataset-xyz789",
  "search_method": "semantic_search",
  "reranking_enable": true
}

Example Response:

{
  "status": "success",
  "query": "How do I configure OpenClaw?",
  "dataset_id": "dataset-abc123",
  "count": 3,
  "results": [
    {
      "content": "To configure OpenClaw, edit the openclaw.json file...",
      "score": 0.8923,
      "title": "Installation Guide",
      "document_id": "doc-001"
    },
    {
      "content": "OpenClaw supports environment variables via...",
      "score": 0.8451,
      "title": "Configuration Options",
      "document_id": "doc-002"
    }
  ]
}

### 📋 Complete Workflow Example

[
  {
    "tool": "dify_list",
    "parameters": {}
  },
  {
    "tool": "dify_search",
    "parameters": {
      "query": "What are the system requirements?",
      "top_k": 5,
      "search_method": "hybrid_search"
    }
  }
]

### Common Errors

ErrorSolutionMissing DIFY_API_KEYSet DIFY_API_KEY in environment variablesConnection refusedCheck DIFY_BASE_URL is correct and accessibleNo datasets foundVerify dataset exists in your Dify workspaceAPI request failedCheck network connectivity and API key permissions

### Debug Mode

Run manually to see detailed errors:

DIFY_API_KEY=your-key python3 scripts/search.py <<< '{"query":"test"}'

### RAG Pipeline Integration

# Example: Use search results in AI response
results = dify_search(query, top_k=5)
context = "\\n".join([r["content"] for r in results["results"]])
final_prompt = f"Answer based on context:\\n\\n{context}\\n\\nQuestion: {query}"

### Multiple Datasets

For searching across multiple datasets, loop through them:

{
  "query": "Find information about authentication",
  "dataset_id": "dataset-api-docs"
}

Then query another dataset separately.

### 🔒 Security

Never commit API keys - Use environment variables or .env files
Rotate keys regularly - Generate new keys in Dify Settings
Restrict access - Limit API key permissions where possible

### 📖 Implementation Details

This skill uses the Dify Dataset API:

List Datasets: GET /v1/datasets
Search: POST /v1/datasets/{id}/retrieve

For API documentation, see: https://docs.dify.ai/reference/api-reference

### 📝 Changelog

v1.1.0 (2026-02-08):

✅ Added search method selection (hybrid/semantic/keyword)
✅ Added reranking support
✅ Auto-discovery of datasets
✅ Improved error handling
✅ Removed hardcoded URLs (fully configurable)
✅ Added detailed logging

v1.0.0 (2026-02-06):

Initial release
Basic list and search functionality
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: xiaowenzhou
- Version: 1.1.1
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-02T13:19:18.745Z
- Expires at: 2026-05-09T13:19:18.745Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/dify-kb-search)
- [Send to Agent page](https://openagent3.xyz/skills/dify-kb-search/agent)
- [JSON manifest](https://openagent3.xyz/skills/dify-kb-search/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/dify-kb-search/agent.md)
- [Download page](https://openagent3.xyz/downloads/dify-kb-search)