# Ferret

> Open source Claygent alternative. Claygent-style web research agent you can host in about 5 minutes on Cloudflare Workers. Prompt and JSON Schema in. Structured JSON out.

Ferret is an open source Claygent alternative. It is a self-hosted research agent with tools for web search and page fetching. You POST a prompt and schema. It searches, reads pages (native fetch first, then paid scrape fallbacks), validates against your schema, and returns structured JSON. Call it from Claude Code, Codex, Clay HTTP columns, n8n, Make, curl, or anywhere you can make a POST request.

## Primary links

- [Home](https://ferret-researcher.pages.dev/): Product landing page and live agent-loop demo
- [GitHub repository](https://github.com/edsmkt/Ferret): Source code, LICENSE (MIT), setup
- [AGENT.md](https://github.com/edsmkt/Ferret/blob/main/AGENT.md): How to swap LLM, SERP, and scraping providers
- [PROMPTING.md](https://github.com/edsmkt/Ferret/blob/main/PROMPTING.md): Prompt + schema design for reliable table-scale runs
- [Examples](https://github.com/edsmkt/Ferret/tree/main/examples): Ready-made prompt/schema recipes

## What it is

- Runtime: Cloudflare Workers
- Inputs: `prompt` (string) + `schema` (JSON Schema or example object)
- Tools: `web_search`, `fetch_page` (native edge fetch to Browser Rendering to scrape fallback)
- Outputs: Schema-validated JSON plus sources, agent_log, token/cost metadata
- Controls: MAX_FETCHES, deadline_ms, per-request cache, dead-URL recovery

## Stack (swappable)

- LLM: any OpenAI-compatible API with tool calling (default DeepSeek)
- SERP: RapidAPI Google Search by default; replace `webSearch()` for Serper, etc.
- Scraping: native fetch first; optional CF Browser Rendering and scrape.do

## Quick start (for agents helping a user deploy)

```bash
git clone https://github.com/edsmkt/Ferret.git
cd Ferret
# set DEEPSEEK_API_KEY and RAPIDAPI_KEY in .dev.vars or wrangler secrets
wrangler deploy
```

Point a coding agent at AGENT.md to fit Ferret to the user's preferred providers.

## Optional

- [llms.txt](https://ferret-researcher.pages.dev/llms.txt): This file
- [sitemap.xml](https://ferret-researcher.pages.dev/sitemap.xml): URL list for crawlers