zai-research

name

zai-research

description

Z.ai-powered web research for Pi: web search, URL/PDF/JSON/API reading, and GitHub repo deep-read. Reaches for five agent tools — zai_web_search (Z.ai web search), fetch_content (webReader pages, local PDF extraction, direct JSON/API fetches, and article extraction for noisy docs), search_repo_docs / get_repo_structure / read_repo_file (Z.ai zread over GitHub). Use whenever work needs current or version-sensitive information, structured API metadata, or deep-reading a GitHub repo without cloning. Auth comes from the configured Z.ai (zai) provider key.

zai-research

Five agent tools that route research through Z.ai, so the agent reaches for current sources instead of trusting possibly-stale training data.

• zai_web_search — Z.ai web search (web_search_prime). Returns page titles, URLs, summaries. Use recency for time-bounded queries, domain to restrict to a site, content_size: high for deeper summaries.
• fetch_content — URL reader with four modes:
  • Web pages default to Z.ai webReader markdown.
  • PDFs are extracted locally with provider-free unpdf, page-by-page.
  • REST/JSON API endpoints use return_format: "json" for direct bounded HTTP fetch + parsed JSON.
  • Noisy docs pages use extract: "article" for local readability extraction before markdown conversion. Accepts one URL or an array (urls, max 20).
• search_repo_docs — Z.ai zread search_doc. Searches a GitHub repo's docs, issues, and commits.
• get_repo_structure — Z.ai zread get_repo_structure. Lists a repo's directory tree.
• read_repo_file — Z.ai zread read_file. Reads a specific file from a repo — no clone needed.

When to use which

Situation	Tool
Current info, version-sensitive API/SDK/model behavior, "what's the latest on X"	zai_web_search
Read a page, doc, or PDF in full (found via search or given by the user)	fetch_content
Confirm model IDs, version lists, config keys, or other structured API metadata	fetch_content with return_format: "json"
Strip nav/sidebar/footer noise from a docs page	fetch_content with extract: "article"
Walk a page/PDF longer than one context window	fetch_content with window
Understand what a GitHub repo does, its recent changes, known issues	search_repo_docs
Map a repo's layout before reading files	get_repo_structure
Read a specific file's source from a repo without cloning	read_repo_file

The guiding rule: reach for zai_web_search before trusting training data on anything that moves (models, SDKs, APIs, library versions, recent events), and chain search_repo_docs → get_repo_structure → read_repo_file to deep-read a repo. Cite the URL/repo in your answer.

The Z.ai-first research flow

1. Search first for current/version-sensitive topics. Prefer zai_web_search with a tight query (Z.ai recommends ≤70 chars). Add recency for news/release timing, domain for an authoritative source.
2. Read in depth with fetch_content on the best result — or choose a precise mode:
   • return_format: "json" for structured API endpoints.
   • extract: "article" for noisy docs pages.
   • default markdown/text for normal pages. For a GitHub repo, skip the clone and use the zread tools.
3. Verify before asserting. Model/API facts change; never state a version number, model name, config key, or signature from memory alone when you could have searched or fetched the current source. If zai_web_search and training disagree, trust the fresh result and cite it.

Patterns

Pick a library/SDK with current evidence:

zai_web_search: query="Hono vs Express 2026 benchmarks", content_size="high"

Time-bounded "is X released yet":

zai_web_search: query="Z.ai GLM-5.2 release", recency="oneMonth"

Fetch structured API metadata directly:

fetch_content: url="https://api.example.com/model-info", return_format="json"

Use this for model IDs, version lists, config schemas, feature flags, and other API data where a rendered docs page would be noisy or indirect.

Strip boilerplate from a docs page:

fetch_content: url="https://docs.example.com/models", extract="article"

Use this when the default page read returns navigation, sidebars, footers, or repeated chrome around the actual article.

Deep-read a GitHub repo without cloning:

search_repo_docs:   repo="modelcontextprotocol/typescript-sdk", query="StreamableHTTPClientTransport requestInit headers"
get_repo_structure: repo="modelcontextprotocol/typescript-sdk"
read_repo_file:     repo="modelcontextprotocol/typescript-sdk", path="src/client/streamableHttp.ts"

Read a doc the user linked (HTML or PDF):

fetch_content: url="https://example.com/guide"        # webReader → markdown
fetch_content: url="https://arxiv.org/pdf/1706.03762" # local unpdf → markdown

Window over long content: A single-URL text-mode fetch (markdown, text, article, or PDF) that exceeds the per-call budget returns the first ~500 lines plus a footer, instead of dropping the tail. Walk the rest by passing window:{start_line}:

fetch_content: url="https://example.com/long-spec"                           # → lines 1–500 + footer
fetch_content: url="https://example.com/long-spec", window={start_line: 501}  # cached, no re-fetch

The footer reads …[window: lines 1–500 of 1340 · request line 501 to continue]. Advance by passing window:{start_line: <next>}; the fetched blob is cached, so later windows do not re-fetch. Read details.next_start_line (the structured source of truth) rather than parsing the footer. max_chars (default 30000, clamped to [1000, 120000]) is the total per-call budget for text + footer; raise it only when a window is being cut mid-thought. An implicit call (no window) whose content fits one window returns the text exactly — no footer.

Guardrails

• domain accepts one whitelist domain (e.g. docs.z.ai, github.com). Use it to keep results authoritative.
• content_size: high costs more (longer summaries); use medium (default) for most queries.
• fetch_content mode precedence is: PDF URL → return_format: "json" → extract: "article" → default webReader. PDF URL routing wins over JSON or article options.
• return_format: "json" and extract: "article" are mutually exclusive. JSON mode is for structured endpoints; article mode is for HTML docs pages.
• urls batch mode applies the same options to every URL. Keep JSON batches homogeneous; one bad URL returns a per-URL error block and does not sink the rest.
• Direct local fetches (PDF, JSON, article mode) are SSRF-guarded: non-http(s), localhost, private/loopback/link-local IPv4 and IPv6, IPv4-mapped IPv6, and redirects to blocked hosts are refused. DNS rebinding is still a documented limitation of local-dev URL fetching.
• JSON mode uses compact JSON to avoid wasting tokens, with a 5 MB response cap and a clear truncation marker if rendered output exceeds the tool return cap. A truncated JSON response is explicitly marked incomplete.
• Article extraction uses a readability library plus markdown conversion. If it cannot identify a viable article, it returns full-page text with a fallback marker rather than silently discarding content.
• Windowing applies to single-URL text modes only (markdown, text, article, PDF). return_format:"json" direct fetches and multi-URL urls batches are NOT windowed — they keep the head-truncate behavior and report details.window_ignored_reason ("json" or "batch"; "fetch_error" when a single-URL fetch fails before windowing). A PDF URL with return_format:"json" still windows, because PDF precedence wins over JSON routing.
• Snapshot drift. Windowing is stateless-by-shape: line offsets are derived from the fetched blob, not pinned to a token. If a live URL changes between calls, later windows' line numbers drift relative to earlier ones. The cache is best-effort (LRU + TTL); treat offsets as valid only within one walk.
• PDF 50-page extraction cap. Local PDF extraction renders at most the first 50 pages by default. Windowing walks the extracted markdown — it cannot retrieve pages beyond that cap; fetch the source another way for those.
• Virtual wrapping (no data loss). Source lines longer than the char budget (e.g. a PDF page collapsed into one giant line) are hard-wrapped into virtual sub-lines before windowing, so line-based addressing reaches every character. details.total_lines counts virtual lines; for PDFs a "line" is roughly a page's worth of text, so PDF windowing degrades to char-paging — but nothing is unreachable.
• max_chars is the total returned budget, footer and marker included (a small overhead is reserved inside it). The char ceiling drops trailing lines (not a mid-line cut). Note: long source lines are hard-wrapped by character count into virtual sub-lines for lossless coverage, so a virtual-line boundary can split a sentence or word — wrapping is about coverage, not pretty breaks. details.truncated_by_char_ceiling is set when trailing lines are dropped.
• For a GitHub repo, prefer the zread tools over fetch_content-ing raw GitHub URLs — zread returns structured docs/issues/code, not scraped HTML.

Setup & runtime

• Auth: the extension resolves your Z.ai API key from the configured zai provider (ctx.modelRegistry), sent as Authorization: Bearer <key>. If you are already on the zai provider (e.g. glm-5.2), there is no extra setup. The key is resolved by looking up a few known zai model ids (glm-5.2/glm-4.6/glm-4.5); if your provider uses a different id and the key isn't found, the tools return a clear error pointing at the zai provider configuration. A stale/expired key triggers one automatic re-auth.
• These tools are pi-runtime-only. They register via the zai-research pi extension. In a harness without it, this skill is informational: the agent knows the research pattern (search → read → verify) but has no Z.ai channel.
• Replaces the prior pi-web-access web-search/fetch surface. Capabilities not covered here (code search, YouTube, video, GitHub clone, multi-source curation) were intentionally dropped — they depended on non-Z.ai providers (Exa/Gemini/git) and don't belong in a Z.ai plugin. Code search in particular is a candidate for a separate self-built indexer.