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 "<query>" [--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. Results are also checked locally because the upstream filter may return off-domain items.
• --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	transient HTTP/TLS failures are retried twice; then show stderr and 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.
• The upstream domain filter is not always strict; --domain therefore applies a client-side hostname check (the requested domain and its subdomains are accepted).
• 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.