native-agy-gateways.md

Native agy credentials and gateways

omni agy uses the native Gemini API when configured with an API key or gateway. A gateway must match the API protocol, authentication method, and models agy requests. Serving a Gemini model through an OpenAI-compatible API does not make that endpoint compatible with agy.

These settings apply to the native Antigravity CLI. The antigravity Python SDK harness has separate authentication settings.

Choose a connection

Run omni setup → Antigravity → Configure native agy API key / gateway → Add a credential.

What you have	Setup option	Requirements
Google Gemini API key	Gemini — API key	A key issued by Google AI Studio; setup supplies the Google API root.
External native Gemini gateway	Gemini API gateway — URL + key	Gemini generateContent and streamGenerateContent, x-goog-api-key authentication, and the models agy requests. No Databricks dependency.
Databricks workspace	Databricks — profile	An authenticated Databricks profile, the databricks extra, and access to the workspace's native Gemini API and corresponding model services.
OpenAI Responses or Chat Completions endpoint, including one serving Gemini	No direct agy support	Requires a protocol adapter that is not currently provided. This applies to Databricks and external gateways alike.
External native Gemini gateway requiring Bearer auth or a token-refresh command	No direct support in the gateway option	Requires an authentication adapter; pasting a Bearer token into the key field does not change the header agy sends.

External Gemini API gateway

Obtain the native Gemini API root and the key accepted by that route from your gateway operator. This may be a gateway virtual key or, for provider-key pass-through, a Google API key. For example:

Prompt	Example
Gateway label	team-gemini — a name you choose, not a URL
Gemini gateway API root	https://gateway.example/gemini
Gateway API key	The key accepted by that gateway's native Gemini route
agy model	Leave blank for agy's default, or use a value accepted by agy --model

With that example root, agy sends requests to https://gateway.example/gemini/v1beta/models/<model>:streamGenerateContent. Do not include /v1beta, /responses, /chat/completions, /openai, or a model operation in the root. The URL must be reachable from the machine running agy; localhost refers to that machine, including when it is a remote host.

The gateway must preserve Gemini request and response fields, streaming events, tool calls, tool results, and reasoning metadata such as thought signatures. It must also serve the auxiliary Gemini models agy requests. Setting the main model does not redirect every auxiliary request to that model. A gateway that only answers a simple text prompt has not demonstrated the complete agent flow.

Setup validates recognizable URL mistakes before asking for a key. It does not send an inference request to prove an arbitrary gateway's compatibility. A saved credential or green setup row is not evidence that the full agent flow succeeded; use the smoke steps below. External gateway keys are stored in Omnigent's secret store and referenced by configuration. This option does not refresh expiring upstream tokens.

Gateway candidates

The following gateways document native Gemini-compatible frontends. These are documented candidates, not a list of gateways live-verified with agy.

Gateway	API root to enter	Authentication and compatibility notes
LiteLLM Google AI Studio pass-through	http://127.0.0.1:4000/gemini for a local proxy	Supports Gemini-native requests and streaming without protocol translation. Configure the Google key on the proxy and use a LiteLLM key in Omnigent. Allow all main and auxiliary models agy requests.
Bifrost GenAI integration	http://127.0.0.1:8080/genai for a local instance	Documents a GenAI client using a Bifrost virtual key. Configure the Gemini backend and model routing. Because this frontend adapts requests and responses, verify tool and reasoning metadata through the full agent flow.
Cloudflare AI Gateway Google AI Studio route	https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/google-ai-studio	The provider-key pass-through example uses a Google key. Configurations requiring the additional cf-aig-authorization header need more header support than the current URL-and-key form provides.

Use each gateway's current documentation to configure its upstream credentials and access controls. OpenAI-compatible routes from the same products are not interchangeable with these native Gemini routes.

Test an independent gateway

Keep the existing credentialless mock journey as the deterministic regression test. It runs actual setup, a fresh daemon, the runner, and real agy against a fake native Gemini server, including a file-tool round trip:

OMNIGENT_E2E_ANTIGRAVITY=mock uv run --no-sync pytest \
  tests/e2e_ui/shells/test_antigravity_gateway_setup.py -q -k direct

For independent live evidence, use a pinned LiteLLM release and an authorized Google AI Studio key or an already configured native Gemini gateway. Configure its /gemini root through Gemini API gateway — URL + key, make it the Gemini default, and run the tool, follow-up, and resume smoke. Check gateway logs to confirm that the main and auxiliary requests went through that gateway with the expected models. Use an intentionally invalid gateway key in a separate test credential to verify authentication fails instead of bypassing the gateway. Record the gateway version, agy version, model choices, and results.

That live run tests the gateway implementation and its actual upstream. The mock journey does not establish a third-party gateway's compatibility. A local gateway backed by Omnigent's Databricks adapter is useful for testing setup, but does not replace this independent canary. Run the same smoke against a second gateway before claiming interoperability across implementations.

Databricks

Use Databricks — profile and enter your existing profile name, for example work. Do not paste a workspace URL or a token into the generic gateway option. This path requires a local profile on the host; managed connection: databricks providers are not supported for native Gemini. The profile uses Databricks SDK authentication. For a CLI OAuth login:

databricks auth login --profile work
omni setup

Install the databricks extra in the environment running Omnigent if setup asks for it, for example pip install 'omnigent[databricks]'. PAT and service-principal credentials belong in the Databricks profile configuration; they do not require an interactive OAuth login.

The selected profile owns both the workspace and identity. Ambient DATABRICKS_HOST, DATABRICKS_TOKEN, and OAuth client settings cannot override it, including during token refresh. DATABRICKS_CONFIG_FILE can select a custom profile file. An invalid profile fails instead of using ambient credentials. The workspace host must be an HTTPS root. HTTP hosts, including loopback, are rejected before authentication or discovery; configure the HTTPS workspace URL in your Databricks profile.

Omnigent starts a local adapter with each agy process. It supplies the profile's Bearer token, refreshes access tokens through the profile's authentication provider, and maps agy's model names to the corresponding Databricks model services. It forwards native Gemini bodies and streaming responses unchanged to:

https://<workspace>/ai-gateway/gemini/v1beta/models/<model-service>:streamGenerateContent

The adapter requires the same main and auxiliary model versions requested by agy. An unavailable or ambiguous match fails; it does not silently select a different model version. The adapter stops with agy and is recreated on resume. Users do not need to manage its local URL or session key.

A workspace model page may instead show /ai-gateway/mlflow/v1/responses. That is an OpenAI Responses endpoint, even when its model is a Gemini service. The Databricks option uses the separate native Gemini route. Availability through Responses alone is insufficient: the native route and models must be accessible to the selected profile. Support must be verified in your workspace.

Setup verifies profile authentication. Gemini model availability is checked when agy starts; a profile with no accessible Gemini services cannot launch a session. The model catalog is discovered once at startup. Start a new session to pick up models added later.

If OAuth refresh fails, run databricks auth login --profile work again in the same environment. DATABRICKS_AUTH_STORAGE=plaintext is not required by Omnigent; some CLI versions use it to access an older file credential cache. Use a consistent storage setting for login and Omnigent. To move to the CLI's default secure store, unset that variable before logging in again. Restart an existing local host daemon after changing its authentication environment.

Select and verify the connection

Existing gateway/local providers keep their pre-upgrade routing: default: true does not activate a gemini: block for native agy. Select Make default for Gemini in setup, or explicitly include gemini in the default scope (for example default: [anthropic, openai, gemini]). Setup preserves the other families when selecting Gemini and writes an explicit scope. Until then, existing Gemini-key, legacy-key, ambient-key, and OAuth routing stays in effect.

An explicitly selected Gemini provider with an incompatible URL fails with a repair hint; it does not silently fall back to another identity. If two providers explicitly claim Gemini, setup first asks which default to keep. Canceling leaves the conflict unresolved without rewriting the configuration.

New Gemini-only gateway entries and Databricks native_gemini entries are not compatible with older Omnigent versions that lack this feature. Before downgrading, remove those new entries or restore your previous configuration.

Setup does not automatically save a detected Gemini key whose companion GOOGLE_GEMINI_BASE_URL is incompatible. Correct that environment variable and reopen setup. If an earlier setup already saved the rejected URL, edit or remove that saved provider too: changing the environment alone does not replace it.

Adding the first credential makes it the Gemini default. Adding another credential preserves the existing default. Select the desired credential and choose Make default for Gemini, then start a new omni agy session. Existing sessions retain their original connection; /model changes the model, not the provider, endpoint, or authentication method.

Create a small file in your working directory:

printf 'Gateway smoke: file tools work.\n' > gateway-smoke.txt
omni agy

Ask: Read gateway-smoke.txt using the file tool and quote its contents. Confirm a tool call occurs and the reply contains the file's actual text. Then ask a follow-up question about the content. Exit and use omni agy --resume to resume that conversation and verify continuity. In the web UI, stop the test session's terminal, click Resume session, and ask another question about the file without using tools. Earlier messages and the original tool result should appear once, followed by the new turn. Repeat in a fresh conversation after switching to another credential.

Resume deduplication applies to transcript items recorded with stable source IDs. Older items recorded before this fix retain their original IDs and may be replayed once when first resumed after upgrading; existing duplicate history is not removed.

For a 404, check both the API route and the availability of the requested model; changing /model cannot repair an incompatible API protocol. For a 401/403, check the key or profile login and model permissions. Setup rejects recognized Databricks URLs and OpenAI endpoints in the Gemini gateway field. Previously saved incompatible entries also fail at launch with guidance instead of falling back to ambient credentials.

An explicitly selected Gemini credential takes precedence over ambient keys. Without one, a stored legacy antigravity.api_key_ref takes precedence over ambient keys and uses Google's API root. Remove that legacy key in setup before switching to an ambient gateway. Otherwise the GEMINI_API_KEY / GOOGLE_GEMINI_BASE_URL environment pair is used. Without an API key, agy keeps its existing OAuth/ADC behavior. Claude, Codex, and Pi defaults remain separate.

Responses and other protocols

OpenAI Responses support is a separate feature, not another URL spelling for the current gateway option. A Gemini-to-Responses adapter would need to translate messages, tools, streaming events, generation settings, and errors in both directions. It would also need a defined policy for Gemini reasoning metadata, model mapping, and authentication. Full fidelity is not established merely by the presence of a Gemini model on a Responses endpoint.

Before offering that route, verification needs to cover real agy startup, streaming, tool calls and results over multiple turns, model and auxiliary-model selection, and process resume. It must include both Databricks and an independent external Responses implementation. Unsupported features must fail clearly. The current Databricks adapter passes Gemini messages through and does not perform this protocol translation.