Zai Web Search

zai-web-search

Live web search through z.ai's web_search_prime MCP server, included with the GLM Coding Plan subscription (no separate API recharge needed — see references/protocol_notes.md for why this matters and why the script uses MCP and not the REST API).

The single Python script handles the MCP streamable-HTTP handshake, SSE parsing, and the multiply-escaped JSON response so you can just call it.

Division of labor with reference-search

These two skills are complementary, not competing:

| Skill | Sources | Best for | Output shape | |---|---|---|---| | reference-search | InspireHEP / OpenAlex / Semantic Scholar APIs | Academic papers, metadata, BibTeX, abstracts, citation context, baselines | Markdown-ready citations with quoted match sentences | | zai-web-search (this) | Live web via z.ai search-prime | Recent trends, news, blogs, docs, non-academic resources, "what is the field doing right now" | title / link / snippet per result |

Default routing:

• "Find papers on X", "baseline citation for Y", "section needs references" → reference-search
• "Latest trends in X", "what is the community doing about Y", "search the web for Z", anything outside academic DBs → zai-web-search
• A claim that needs both a primary source (academic) and current context (web) → run both and merge.

Trigger conditions

Invoke this skill when the user says any of:

• "search the web for X", "웹 검색", "인터넷에서 찾아봐"
• "latest / recent trends in X", "최근 동향", "최신 트렌드", "what's new in X"
• "current state of X", "how is the field approaching Y"
• a web-lookup need that is clearly not an academic-DB query (news, blogs, docs, repos, product pages)
• explicit "z.ai search" / "GLM web search" / "use the web"

Prerequisites

The key is the single source of truth — pi's own credential store, not a duplicate:

test -f ~/.pi/agent/auth.json python3 -c "import json;print(json.load(open('/home/axect/.pi/agent/auth.json'))['zai-coding-cn']['key'])" >/dev/null

If either fails, tell the user: > The z.ai key is not configured in ~/.pi/agent/auth.json under zai-coding-cn.key. This key ships with the GLM Coding Plan login — it is the same key pi already uses for the default model. Re-login via pi if it is missing.

Do not create a second credential file. Do not ask the user to paste the key into a skill config. auth.json is the SoT.

Script usage

python3 scripts/web_search.py "" [--limit 8] [--domain example.com] [--json] [--auth PATH]

Arguments:

• query (positional or --query / -q): the search query. MCP recommends ≤70 chars; the script hard-rejects >200.
• --limit / -n (default 8): max results.
• --domain : restrict to a domain (e.g. arxiv.org, nature.com). Optional.
• --json : machine-readable output for piping into another script. Default is human-readable [i] title / link / snippet.
• --auth (default ~/.pi/agent/auth.json): override the credential path (rarely needed).

Resolve the script path relative to this SKILL.md (skill dir + scripts/web_search.py).

Examples

# human-readable, top 6 results python3 scripts/web_search.py "autoregressive sampler Ising correlation failure" -n 6

# restrict to arXiv, JSON for downstream processing python3 scripts/web_search.py "flow sampler critical slowing down" --domain arxiv.org --json

# pipe into a quick relevance filter python3 scripts/web_search.py "..." --json | python3 -c "import sys,json; ..."

How to use the results

• The script prints title / link / snippet. Snippets are short summaries from the search engine, not the page content — do not treat them as quotes from the source.
• For anything you plan to cite, open the link and verify the claim against the real page before quoting. Web-search snippets are for discovery and triage, not citation.
• When a result looks like an arXiv/paper link and you need BibTeX or abstract text, hand off to reference-search or bibtex-gen with the arXiv ID / DOI.

Error handling

| Exit code | Meaning | Action | |---|---|---| | 0 | success | use the printed results | | 1 | bad argument (query empty / too long) | fix the call | | 2 | auth.json missing or no zai-coding-cn.key | user must (re-)configure pi login | | 3 | auth rejected (HTTP 401 / MCP -401) | key invalid or expired → re-login via pi | | 4 | search-side error (429, 5xx, MCP error) | surface the message; retry once after a short wait for transient 429 | | 5 | network or parse failure | show stderr; check connectivity | | 64 | usage error | show --help |

Do not auto-retry on auth errors (exit 2/3). For 429, a single retry after 20–60s is reasonable; persistent 429 means either rate-limit or (for the REST endpoint) insufficient balance — but the MCP endpoint used here is covered by the Coding Plan, so persistent 429 on MCP is a rate-limit, not a billing issue.

Limits and honest use

• Snippets are short and may truncate; do not over-claim what a page says from the snippet alone.
• Web search can return stale or SEO-heavy results — cross-check claims that matter.
• This is a discovery tool. Pair with reference-search for citation-grade literature and with direct page reads (curl / a reader tool) when you need to quote.

References

• references/protocol_notes.md — why MCP-not-REST, the streamable-HTTP handshake, SSE + multiply-escaped JSON parsing, and the gotchas that made this skill necessary.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Axect
• Source: Axect/skills
• License: MIT

Install and usage instructions live in the source repository linked above.