Google SDK Integration in Phoenix#

Phoenix's client library integrates with Google's Gemini models through the legacy google-generativeai SDK. The integration lives in phoenix-client and handles bidirectional conversion between Phoenix's internal prompt format and the types expected by the Google SDK.

Entry Points#

The two public symbols are 1:

• to_chat_messages_and_kwargs(obj, *, variables, formatter) — converts a v1.PromptVersionData into a (list[protos.Content], GoogleModelKwargs) tuple ready to pass directly to GenerativeModel(...). This is the primary function used when formatting a stored Phoenix prompt for inference.
• create_prompt_version_from_google(obj) — the inverse direction (Google → Phoenix); currently raises NotImplementedError.

PromptVersion.format(sdk="google_generativeai") in types/prompts.py calls to_chat_messages_and_kwargs and wraps the result in a GoogleGenerativeaiPrompt dataclass, which implements Mapping[str, Any] so it can be unpacked with ** directly into SDK calls.

Provider Routing#

PromptVersion supports eight model providers 2:

"OPENAI" | "AZURE_OPENAI" | "ANTHROPIC" | "GOOGLE" | "DEEPSEEK" | "XAI" | "AWS" | "OLLAMA"

The internal _to_sdk() function maps "GOOGLE" → "google_generativeai" 3. All other providers that share an OpenAI-compatible interface (DeepSeek, xAI, Ollama, Azure OpenAI) are routed to the "openai" SDK formatter instead.

Prompt Formatting Details#

to_chat_messages_and_kwargs applies template variable substitution and converts each v1.PromptMessage into protos.Content objects:

• System messages are extracted and placed into system_instruction on GoogleModelKwargs (as a single string or a list), since the Google SDK does not accept a "system" role in the message list 4.
• Role mapping: Phoenix roles "assistant", "model", "ai" → Google "model"; "user" → "user"; "tool" → "user". "system" and "developer" roles raise NotImplementedError 5.
• Tool call / tool result parts are silently skipped during to_google conversion 6.

Invocation parameters (temperature, max_output_tokens, stop_sequences, presence_penalty, frequency_penalty, top_p, top_k) are read from the prompt's invocation_parameters.google block and packed into a GenerationConfig 7.

Tool / function calling uses Google's function_calling_config pattern. Phoenix tool-choice types map as follows 8:

Function declarations are flat { name, description, parameters } — no "type": "function" wrapper, unlike OpenAI format 9.

Dependency Structure#

google-generativeai is not a required dependency of phoenix-client. Imports are guarded by TYPE_CHECKING 10, meaning the runtime will only fail if you actually call format(sdk="google_generativeai") without the SDK installed.

In the main arize-phoenix package, google-generativeai is an optional dependency under the container extras group (no version pin), while protobuf is pinned to >=4.25.8, <6.0 11.

⚠️ Known Conflict: protobuf<6 vs. langgraph#

The legacy google-generativeai SDK requires protobuf<6.0.0. Modern packages like langgraph-api and langgraph-cli[inmem] require protobuf>=6.32.1,<7.0.0. These constraints are mutually exclusive and cannot be resolved together — especially with strict resolvers like uv 12.

Symptom: Calling prompt_obj.format(sdk="google_generativeai") (or the default "GOOGLE" routing) raises ModuleNotFoundError: No module named 'google.generativeai' when only the new google-genai SDK is installed 12.

Current state (as of Phoenix 19.13.0 / arize-phoenix-client 2.13.0): Phoenix's backend already supports the new google-genai SDK in Evals, Model Providers, and Playground — but phoenix-client prompt formatters still target the legacy google.generativeai module. Issue #15040 tracks adding a new sdk="google_genai" formatter path that uses google.genai.types.Content instead 12.

Workaround: Avoid co-installing google-generativeai and langgraph-api. Use the new google-genai package as your runtime SDK, and wait for the phoenix-client formatter to be updated. Track #15040 for progress.

Key Files#