jixu-tools-jina

jixu-tools-jina gives an Agent two explicit network capabilities: discover public webpages from bounded metadata and read selected public URLs for evidence. Credentials stay behind the Tool boundary rather than entering Events or Agent-visible inputs.

Install

npm install jixu-core jixu-tools-jina

Create the Tools

import { defineAgent } from "jixu-core";
import {
  createJinaWebReadTool,
  createJinaWebSearchTool,
} from "jixu-tools-jina";

const apiKey = process.env.JINA_API_KEY;
const webSearch = createJinaWebSearchTool({ apiKey });
const webRead = createJinaWebReadTool({ apiKey });

const agent = defineAgent({
  instructions: "Use web evidence carefully and cite resolved URLs.",
  model: { provider: "model", model: "configured-model" },
  modelCapabilities,
  tools: [webSearch, webRead],
});

Capabilities

Discover before reading

web_search is metadata-first. It asks Jina Search not to fetch candidate page bodies, then returns only bounded discovery metadata. Descriptions are relevance hints rather than source evidence.

The optional site input is a hostname constraint separate from the query. maxResults accepts 1 through 10. Each result reports descriptionTruncated, and the top-level result reports whether count or metadata bounds truncated the response. A Jina no-results assertion remains a successful empty set.

After selecting relevant URLs, use web_read for the actual source. When several independent sources are already known, request their reads together so the Harness can dispatch one parallel Tool batch instead of paying for a model continuation between every page.

Bound each source read

web_read accepts an optional maxTokens input from 500 through 8,000 and defaults to 4,000. Use roughly 500–2,000 for a narrow fact and raise the limit only when source coverage requires it.

Reader output removes image markup, keeps link text inline with one deduplicated URL summary, and reports contentTruncated when either Jixu's character bound or Jina's selected token limit is reached.

Both Tools are declared idempotent and network-risking. They enforce request timeouts, response byte limits, bounded metadata or content, cancellation, and typed upstream failures.

Trust boundary

Search metadata and retrieved web content are untrusted evidence, not instructions or durable authority. The Agent should inspect candidate relevance, read the sources that support its claims, cite resolved URLs, and avoid treating retrieved text as privileged context.