Community Tools

Third-party integrations for web search, content fetching, and image search

Overview

Community tools provide integrations with external services for enhanced agent capabilities. These tools require API keys and configuration through DeerFlow’s tool configuration system.

Community tools may require additional setup and API keys. Check the configuration requirements for each tool before use.

---

web_search (Tavily)

Search the web using the Tavily search API.

Configuration

tools:
  web_search:
    provider: tavily
    api_key: your-tavily-api-key
    max_results: 5

Parameters

query · str · required

The query to search for.

Example

# Search for recent information
result = web_search(
    query="latest developments in AI language models 2024"
)

Return Type

Returns a JSON string with normalized search results:

[
  {
    "title": "Article Title",
    "url": "https://example.com/article",
    "snippet": "Article description or excerpt..."
  }
]

---

web_fetch

Fetch the contents of a web page at a given URL. Multiple providers are available.

Providers

Tavily

Uses Tavily’s content extraction API.

Configuration:

tools:
  web_search:
    provider: tavily
    api_key: your-tavily-api-key

Example:

web_fetch(url="https://example.com/article")

Returns:

# Article Title

[Article content, truncated to 4096 characters]

Firecrawl

Uses Firecrawl for advanced web scraping with JavaScript rendering.

Configuration:

tools:
  web_search:
    provider: firecrawl
    api_key: your-firecrawl-api-key

Example:

web_fetch(url="https://example.com/dynamic-page")

Returns: Markdown-formatted content with title

Jina AI

Uses Jina AI’s reader API with readability extraction.

Configuration:

tools:
  web_fetch:
    timeout: 10

Example:

web_fetch(url="https://example.com/article")

Returns: Markdown-formatted article content (up to 4096 characters)

Parameters

url · str · required

The URL to fetch the contents of.

Important Notes

• Only fetch EXACT URLs provided by the user or returned from search results
• Cannot access content requiring authentication (private Google Docs, login walls)
• Do NOT add www. to URLs that don’t have them
• URLs must include the schema: https://example.com is valid, example.com is invalid

Examples

# Good: Exact URL from search results
web_fetch(url="https://blog.example.com/article")

# Good: User-provided URL
web_fetch(url="https://docs.python.org/3/library/os.html")

# Bad: Missing schema
web_fetch(url="example.com")  # ERROR: Invalid URL

# Bad: Adding www unnecessarily
web_fetch(url="https://www.example.com")  # If original was https://example.com

Error Handling

All providers return error messages as strings:

Error: [error description]

---

web_search (Firecrawl)

Search the web using Firecrawl’s search API.

Configuration

tools:
  web_search:
    provider: firecrawl
    api_key: your-firecrawl-api-key
    max_results: 5

Parameters

query · str · required

The query to search for.

Example

result = web_search(
    query="machine learning best practices"
)

Return Type

Returns a JSON string with normalized search results:

[
  {
    "title": "Article Title",
    "url": "https://example.com/article",
    "snippet": "Article description..."
  }
]

---

image_search

Search for images online using DuckDuckGo. Use this tool BEFORE image generation to find reference images.

Configuration

tools:
  image_search:
    max_results: 5

Parameters

query · str · required

Search keywords describing the images you want to find. Be specific for better results.

max_results · int

Maximum number of images to return. Default is 5.

size · str

Image size filter. Options: "Small", "Medium", "Large", "Wallpaper". Use "Large" for reference images.

type_image · str

Image type filter. Options: "photo", "clipart", "gif", "transparent", "line". Use "photo" for realistic references.

layout · str

Layout filter. Options: "Square", "Tall", "Wide". Choose based on your generation needs.

When to Use

• Before generating character/portrait images: Search for similar poses, expressions, styles
• Before generating specific objects/products: Search for accurate visual references
• Before generating scenes/locations: Search for architectural or environmental references
• Before generating fashion/clothing: Search for style and detail references

Examples

# Good: Specific query for portrait reference
image_search(
    query="Japanese woman street photography 1990s",
    type_image="photo",
    size="Large"
)

# Good: Product reference
image_search(
    query="modern minimalist desk lamp metal",
    type_image="photo",
    layout="Square"
)

# Bad: Too vague
image_search(query="woman")  # Not specific enough

Return Type

Returns a JSON string with search results:

{
  "query": "Japanese woman street photography 1990s",
  "total_results": 5,
  "results": [
    {
      "title": "Image title",
      "image_url": "https://example.com/image.jpg",
      "thumbnail_url": "https://example.com/thumb.jpg"
    }
  ],
  "usage_hint": "Use the 'image_url' values as reference images in image generation. Download them first if needed."
}

Using Results

The returned image URLs can be used as reference images in image generation tools:

# 1. Search for reference images
results = image_search(
    query="vintage camera Leica M3",
    type_image="photo",
    size="Large"
)

# 2. Parse results (in practice, this would be done by the agent)
import json
data = json.loads(results)
reference_url = data["results"][0]["image_url"]

# 3. Use in image generation (pseudocode)
generate_image(
    prompt="A vintage Leica M3 camera on a wooden desk",
    reference_images=[reference_url]
)

---

Configuration Examples

Using Tavily for Search

tools:
  web_search:
    provider: tavily
    api_key: tvly-xxxxxxxxxxxxx
    max_results: 10

Using Firecrawl for Search

tools:
  web_search:
    provider: firecrawl
    api_key: fc-xxxxxxxxxxxxx
    max_results: 5

Using Jina AI for Fetching

tools:
  web_fetch:
    timeout: 15

Image Search

tools:
  image_search:
    max_results: 10

---

Best Practices

Web Search

• Use specific, targeted queries
• Search before fetching to find relevant URLs
• Respect max_results configuration

# Good: Specific query
web_search(query="Python asyncio best practices 2024")

# Bad: Too broad
web_search(query="programming")

Web Fetch

• Only fetch URLs from search results or user input
• Never modify URLs (especially don’t add/remove www.)
• Always include URL schema (https://)
• Handle authentication limitations gracefully

# Good: Exact URL
web_fetch(url="https://docs.python.org/3/library/asyncio.html")

# Bad: Modified URL
web_fetch(url="https://www.docs.python.org/3/library/asyncio.html")

Image Search

• Be specific in search queries
• Use appropriate filters for your use case
• Always search before generating images
• Use "photo" type for realistic references
• Use "Large" size for best quality references

# Good: Specific query with filters
image_search(
    query="Victorian era portrait photography woman formal dress",
    type_image="photo",
    size="Large",
    layout="Tall"
)

# Bad: Vague query
image_search(query="photo")

---

Error Handling

All community tools handle errors gracefully:

Search Errors

result = web_search(query="test")
# If error occurs:
# "Error: [error description]"

Fetch Errors

result = web_fetch(url="https://invalid-url.com")
# Returns:
# "Error: [error description]"

Image Search Errors

result = image_search(query="test")
# If no results:
# {"error": "No images found", "query": "test"}

---

Dependencies

Tavily

pip install tavily-python

Firecrawl

pip install firecrawl-py

Jina AI

Requires custom client implementation (included in DeerFlow).

Image Search

pip install ddgs