pi-jina-webtools

Registers web_search and web_fetch tools in pi-coding-agent, both powered by Jina AI: web_search uses the Jina Search Foundation API (s.jina.ai), web_fetch uses the Jina Reader API (r.jina.ai).

What you get

• web_search searches the web and returns up to 10 results, each with a title, URL and content preview. With JINA_API_KEY it uses the Jina Search Foundation API, which fetches the top results' pages itself. Without a key it falls back to Startpage (Google-powered), then Bing — each read through the Jina reader — so search still works keyless.
• web_fetch converts any URL into clean markdown, handling JavaScript rendering, PDFs and MS Office documents, so you can read a full page without curl.
• Both tools return JSON details (query, provider, truncation state) alongside the human-readable text.
• Keyed search is capped at 15 s, reader calls at 30 s. Slow responses fail instead of hanging the turn.
• Both tools honor pi's abort signal, so cancelling a turn cancels in-flight requests.
• No API key is required. Without any key everything still works, at Jina's free rate limits.
• A yellow warning on the very first start links to the key dashboard when no key is set — it shows only once, never again. /jina-key stores a key internally.

Installation

pi install npm:pi-jina-webtools

From a local checkout:

pi install /path/to/pi-jina-webtools

Quick start

The agent calls the tools automatically when it needs current information:

{
  "query": "pi-coding-agent extensions",
  "numResults": 5
}

{
  "url": "https://github.com/jina-ai/reader",
  "maxChars": 6000
}

Search responses name the engine that answered:

Search results from Jina for "pi-coding-agent extensions":
1. **...**
   https://...
   ...

Without JINA_API_KEY the response is headed Search results from Startpage (Jina Reader) for "..." — or Bing (Jina Reader) when Startpage is unreachable. Fetch responses return the page as markdown with its title and source URL.

Configuration

Set an API key in your environment (optional):

Provider	Env var
Jina AI	JINA_API_KEY

The key is optional. Everything works without it:

• With an API key, web_search uses the Jina Search Foundation API (s.jina.ai), which searches the web and fetches full page content for the top results.
• Without an API key, web_search falls back to Startpage (https://www.startpage.com/sp/search), then Bing's results feed (https://www.bing.com/search?q=...&format=rss), each read through the Jina reader (r.jina.ai). The response names the engine that answered: Startpage (Jina Reader) or Bing (Jina Reader).
• web_fetch always uses the reader and works keyless at a lower rate limit. Add an API key (free at jina.ai) to raise the limits.

The key can come from two places:

1. The JINA_API_KEY environment variable.
2. The /jina-key command, which stores the key internally in ~/.pi/agent/jina-webtools.json (override the directory with PI_CODING_AGENT_DIR). A stored key takes precedence over the environment variable.

Commands

Command	Description
/jina-key <key>	Store the Jina API key internally (overrides JINA_API_KEY). With no argument it reports whether a key is configured; clear removes the stored key.

When pi starts for the first time and no API key is configured, a yellow warning is shown once, linking to the key dashboard at jina.ai/api-dashboard. It never appears again on later starts.

The tools

web_search

Parameter	Description
query	Search query (required).
numResults	Number of results, clamped to 1-10 (default 5).

web_fetch

Parameter	Description
url	URL of the page to fetch. Must start with http:// or https://.
maxChars	Maximum characters of content to return, clamped to 1000-30000 (default 6000).

Guidelines shipped with the tools:

• Use web_search when you need current information or facts not in the codebase.
• Use web_fetch to read the full content of a page returned by web_search.
• Use web_fetch to read the full content of a web page instead of curl.

How it works

1. web_search with a key calls GET https://s.jina.ai/{query}?count={numResults} with Accept: application/json and Authorization: Bearer $JINA_API_KEY.
2. web_search without a key calls the reader on Startpage, GET https://r.jina.ai/https://www.startpage.com/sp/search?query={query}, and parses the markdown result blocks (## [title](url) headings with snippet paragraphs, skipping affiliate ad URLs). If Startpage returns nothing it falls back to Bing's RSS feed (https://www.bing.com/search?q={query}&format=rss).
3. web_fetch validates the URL, then calls GET https://r.jina.ai/{url} with the same headers.
4. All calls parse the JSON response (code/data envelope) and map it to structured results.
5. Non-OK responses surface Jina's own message/readableMessage text, so the agent sees the real reason (401, 429, blocked domain, ...).

Troubleshooting

• Search says No search engine returned parseable results. Startpage and Bing are both unreachable or rate-limited; retry later, or run /jina-key <key> to switch to the Jina Search API.
• Keyed search returns 401 Authentication required. The key is missing or invalid. Run /jina-key <key> with a fresh key from jina.ai/api-dashboard, or fix JINA_API_KEY. Without a valid key, search falls back to the keyless engine chain (Startpage → Bing) via the reader.
• The startup warning is annoying. It shows only once, on the very first start — it never appears again, so there is nothing to disable.
• Fetch is slow or times out. The reader renders JavaScript-heavy pages, and a slow page fails with a clear timeout error after 30 s. curl the URL directly as a fallback.
• Content is truncated. web_fetch caps output at maxChars (default 6000) to protect context; raise it or fetch sub-pages via returned links.

Development

Requires Node.js ≥ 22.19 and npm.

npm install
npm test
npm run typecheck

Credits

• Jina AI for the Search Foundation and Reader APIs
• badlogic, pi-coding-agent and the tool API

License

MIT