Examples

Runnable examples live in the repository under examples/. Clone the same tag as your server deployment so examples and public contracts remain aligned.

LangChain Deep Agents research Agent

The custom Python Agent demonstrates both supported integration styles:

• MCP, recommended: discover web_search and web_fetch through the gateway's standard /mcp endpoint.
• REST custom tools: define LangChain @tool functions that call /v1/search and /v1/fetch directly.

Both modes use the same research system prompt and treat every title, snippet, and fetched page as untrusted data.

LangChain Deep Agents demo

The recording demonstrates MCP tool discovery, streaming Agent and subagent steps, web_search calls, web_fetch calls, and the final cited answer. Download the original .cast recording for local playback with asciinema play, or open the uploaded recording on asciinema.org.

cd examples/deepagents
cp .env.example .env
# Fill WEB_SEARCH_API_KEY, DEEPAGENTS_MODEL, and the model provider key.
uv sync --locked
uv run --env-file .env python agent.py --transport mcp "Compare MCP and REST for Agent tools"
uv run --env-file .env python agent.py --transport rest "Compare MCP and REST for Agent tools"

Add --stream to print main/subagent steps, bounded tool-call arguments, tool completion events, and answer tokens in real time. Reasoning blocks are not exposed:

uv run --env-file .env python agent.py --transport mcp --stream \
  "Research the latest Camofox Browser information and cite sources"

To use a custom OpenAI-compatible model endpoint, set DEEPAGENTS_MODEL to the provider-native model name and configure DEEPAGENTS_MODEL_PROVIDER=openai, DEEPAGENTS_BASE_URL, and DEEPAGENTS_API_KEY. Local HTTP model endpoints are allowed; remote custom endpoints must use HTTPS. The example model factory also exposes timeout and retry settings.

Read the Deep Agents example README for configuration and error-handling details.

Codex, Claude Code, OpenCode, Pi, OpenClaw, and HermesAgent

The CLI is the recommended installation path because it writes idempotently, preserves unrelated settings, stores backups, and never persists the token.

export WEB_SEARCH_API_KEY="..."
camofox-web-search install codex --endpoint https://search.example.com --scope user
camofox-web-search install claude --endpoint https://search.example.com --scope project
camofox-web-search install opencode --endpoint https://search.example.com --scope user
camofox-web-search install pi --endpoint https://search.example.com --scope user
camofox-web-search install openclaw --endpoint https://search.example.com --scope user
camofox-web-search install hermes --endpoint https://search.example.com --scope user

The manual configuration examples show the exact managed entries for auditing or custom provisioning. Codex, Claude Code, and OpenCode use MCP. Pi installs its native npm extension. OpenClaw and HermesAgent use native provider APIs while calling the same REST gateway.

OpenClaw native provider

The OpenClaw npm plugin registers the canonical web_search and web_fetch tools. It stores the API key as an environment SecretRef and requires a Gateway restart after installation.

export WEB_SEARCH_API_KEY="..."
camofox-web-search install openclaw --endpoint https://search.example.com --scope user
openclaw gateway restart
openclaw plugins inspect camofox --runtime --json

Read the dedicated OpenClaw installation and usage guide. The complete OpenClaw example covers manual JSON5 configuration and local package development.

HermesAgent native provider

The PyPI plugin registers HermesAgent's canonical web_search and web_extract. The installer locates the Hermes Python environment automatically; use --hermes-python when needed.

export WEB_SEARCH_API_KEY="..."
camofox-web-search install hermes --endpoint https://search.example.com --scope user
camofox-web-search doctor hermes --endpoint https://search.example.com --scope user --live

Read the dedicated HermesAgent installation and usage guide. The complete HermesAgent example covers manual PyPI and backend configuration.

Direct API calls

curl --fail https://search.example.com/v1/search \
  -H "Authorization: Bearer $WEB_SEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Model Context Protocol","count":5,"freshness":"month"}'

curl --fail https://search.example.com/v1/fetch \
  -H "Authorization: Bearer $WEB_SEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/","max_chars":20000}'

Use /openapi.json for the complete REST contract and camofox-web-search-client when a typed TypeScript client is preferred.