docs: add native Google Vertex AI provider RFC

[mason5052]

Summary

Add examples/proposals/vertex_ai_provider.md, a planning RFC for a future native Google Vertex AI provider (vertex). RFC/docs only - no code, schema, migration, frontend, or provider runtime changes, and no new env vars or types. Every VERTEX_* key and type named is explicitly labeled a candidate.

Problem

Issue #321 requests a native Vertex AI provider with service-account / ADC auth, opened after #310 clarified that Vertex AI is not natively supported today (the only Google option, gemini, targets AI Studio and takes an API key, not GCP project credentials). The issue already contains a full implementation outline and four open questions, and the author explicitly asks for maintainer direction on adapter strategy and Gemini-vs-Claude scope before implementing. Per PentAGI's recent contribution pattern (and the lesson from #268), a planning RFC is the right first step for provider-sized work rather than a speculative implementation PR.

Solution

A self-contained RFC under examples/proposals/ (matching the existing mcp_client_integration.md / flow_concurrency.md style) that:

• Distinguishes the current options - AI Studio gemini, direct Anthropic, AWS Bedrock, and the custom OpenAI-compatible LiteLLM-proxy workaround - from the proposed native vertex provider.
• Recommends a staged approach - v1 Gemini-on-Vertex with ADC / service-account auth; Claude-on-Vertex deferred to a maintainer decision, with the note that it likely belongs on the Anthropic adapter (Vertex auth/endpoint mode) rather than the Gemini-shaped path because the message schema differs.
• Models auth on the existing Bedrock multi-auth precedent (ADC default chain plus a service-account file), and flags that service-account JSON is sensitive and must be file-mounted / secret-managed, never pasted into UI or written to logs.
• Captures config/migration touch points (the CLAUDE.md provider checklist, the REST Valid() whitelist, and the PROVIDER_TYPE enum-swap migration pattern) so the eventual implementation size is clear, and restates the issue's open questions for maintainers.

All wording is framed as proposed/candidate/future; the RFC states up front that native Vertex support does not exist today.

User Impact

• Gives maintainers a concrete, reviewable artifact to settle the adapter-strategy and Gemini-vs-Claude-scope questions before any code lands.
• Documents, in one place, why the LiteLLM-proxy workaround is currently needed and what a native provider would replace.
• No runtime impact whatsoever - documentation only.

Test Plan

• git diff --check clean.
• RFC/docs-only diff: a single new file examples/proposals/vertex_ai_provider.md. No code, schema, migration, generated, frontend, or provider runtime files changed.
• Confirmed no overlap with open PR feat: upgrade MiniMax default model to M3 #328 (which touches config.go, providers.go, provider/provider.go, server/models/providers.go, and minimax/*); this RFC touches none of those.
• Confirmed no existing vertex provider package, proposal, or open PR exists.
• Verified the referenced facts against main: the 10 current provider types, the AI Studio gemini API-key path, the Bedrock multi-auth fields, and the 20260227_120000_add_cn_providers.sql enum-swap migration.
• Verified all wording is hedged (proposed / candidate / future / RFC) and never claims native Vertex support exists.

Refs #321

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds an RFC proposing a future native Google Vertex AI provider (“vertex”) to support GCP IAM-based authentication and Gemini-on-Vertex, documenting scope, architecture options, migration/config considerations, and open questions.

Changes:

• Introduces an RFC document outlining motivation, goals/non-goals, and a staged implementation plan for a vertex provider.
• Documents candidate configuration keys and authentication approaches (ADC / service-account file).
• Captures migration considerations, testing strategy, security considerations, and open questions for maintainers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.