pi-web-search-research-llm-gcp

Web search & research tools for the Pi coding agent, backed by Vertex AI Gemini with Google Search grounding and Google Cloud Agent Platform credentials.

This uses Google Cloud credentials, not a Gemini API key.

Setup

1. Install: pi install npm:pi-web-search-research-llm-gcp
2. Authenticate: gcloud auth login
3. In Pi: /setup-search → project ID → region → model for web_search → model for web_research → model for web_fetch. Saved across sessions; no restart needed. Enable Vertex AI in the project.

Commands

Enter these slash commands in Pi, not in your shell:

Setup flow

/setup-search asks for:

1. Google Cloud project ID.
2. Vertex AI region (default: eu).
3. Model for web_search.
4. Model for web_research.
5. Model for web_fetch.

Leave the project or region blank to keep its current value. Select Keep … to leave a tool's model unchanged. The command lists Gemini text models and checks access when you select a different model.

Project and region are saved after both inputs are accepted. Model changes are saved only after all three model choices are complete. If you cancel model selection or a model check fails, the project and region remain saved, but model changes from that run are not saved. Changes take effect without a restart.

Tools

These are tools the agent calls, not slash commands. Ask Pi to search, research, or read a URL; the agent chooses the tool.

Registers three tools the model can call:

• web_search — quick fact-check / verification. Returns a concise synthesized answer + source URLs.
• web_research — in-depth research on complex topics. Returns a structured answer with documentation details, code snippets, and source URLs.
• web_fetch — reads one public webpage through Gemini url_context and extracts its substantive content into Markdown.

The search and research tools:

• Ground answers with Google Search.
• Can read specific URLs passed in the query via Gemini url_context.
• Use high thinking for the configured Gemini 3.5 Flash-Lite and Gemini 3.7 Flash models.
• Resolve Gemini vertexaisearch.cloud.google.com redirect links to clean destination URLs.
• Render source URLs as OSC-8 terminal hyperlinks in the Pi TUI when supported by your terminal.
• Prefix results with a compact, brutalist high-contrast Vertex AI provenance/cost summary in Pi TUI, including the actual flex pricing or standard pricing tier used for that call.

web_fetch uses URL Context only, without Google Search. It asks Gemini to:

Extract all information from this webpage into Markdown.

The result is model-generated Markdown, not a byte-for-byte copy of the original webpage. Supply an absolute public HTTP(S) URL of at most 2048 characters. URLs with embedded credentials, localhost URLs, and private or reserved IP addresses are rejected. This tool does not use your browser login to read private pages.

Preview

Configuration

Settings are saved in vertex-gemini-search.json in Pi's agent directory. Saved project, region, and model values take precedence over environment variables. Use /setup-search again to change them.

For environment-only setup, set these variables before starting Pi:

Authentication

Authentication follows this order:

1. If VERTEX_ACCESS_TOKEN is set, use that token. This bypasses gcloud and the service-account environment variable.
2. Otherwise, run gcloud auth print-access-token. If VERTEX_IMPERSONATE_SERVICE_ACCOUNT is set, add --impersonate-service-account to that command.

Normal user account (including an admin account):

unset VERTEX_ACCESS_TOKEN VERTEX_IMPERSONATE_SERVICE_ACCOUNT
gcloud auth login

The extension uses the active gcloud account. If you previously configured gcloud's auth/impersonate_service_account property, unset it with gcloud config unset auth/impersonate_service_account to use the user directly. The user needs access to Vertex AI and permission to consume services on the selected project. An admin title alone does not establish access to that project.

Service-account impersonation:

unset VERTEX_ACCESS_TOKEN
gcloud auth login
export VERTEX_IMPERSONATE_SERVICE_ACCOUNT="your-service-account@your-project.iam.gserviceaccount.com"

Your logged-in user needs roles/iam.serviceAccountTokenCreator on the service account. The service account itself needs Vertex AI access and serviceusage.services.use on the selected project; your user's admin permissions do not carry over to the service account. Common predefined roles are roles/aiplatform.user and roles/serviceusage.serviceUsageConsumer. The IAM Service Account Credentials API must be enabled for impersonation.

Both paths require Vertex AI to be enabled, billing to be configured, and the selected models to be available in your project and region. Organization restrictions can still block access. This extension uses gcloud CLI credentials, not gcloud auth application-default login.

Set or unset environment variables before starting Pi. A running Pi process does not inherit later changes from your shell.

Cost estimate configuration

Each result includes a compact estimated cost summary, for example:

◆ Gemini Search [gemini-3.5-flash-lite, eu, €0.0131/$0.0141, 2 sources, standard pricing]

Defaults:

• GEMINI_SEARCH_GROUNDING_USD_PER_1000=14
• USD_TO_EUR=0.93
• VERTEX_FLEX_TOKEN_DISCOUNT=0.5

The estimate uses response token counts from Vertex AI and approximate list token rates. Gemini 3.7 Flash research calls use the introductory rate of $0.75 per 1M input tokens and $3.75 per 1M output tokens through December 31, 2026. Regional endpoint pricing may differ. URL Context results report token costs, but the estimate does not add a Google Search grounding charge because web_fetch does not use Google Search. Flex is preferred by default via the Vertex AI Flex PayGo headers. If the project or region does not support Flex, the extension falls back to the standard tier and reports standard pricing in that result.

The pricing preference applies to all three tools. Each Pi session starts with flex. Use /search-pricing standard to bypass Flex, or /search-pricing flex to try Flex again after a fallback. These changes do not persist across sessions.

Migration from the old package

@nilskluewer/pi-vertex-gemini-search is deprecated. Use pi-web-search-research-llm-gcp instead. Remove the old package before installing the replacement so both extensions do not register the same tools and commands:

pi remove npm:@nilskluewer/pi-vertex-gemini-search
pi install npm:pi-web-search-research-llm-gcp

Both packages use the same vertex-gemini-search.json settings file.

License

MIT