🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
import type { NormalizerContext, ProviderAdapter } from "../types";
import {
parseMetadata,
stringifyToolResultContent,
isRichToolResult,
getNestedProperty,
} from "../helpers";
import { z } from "zod";
/**
* Detection schemas for Gemini/VertexAI formats
*
* Two main format families (inner structure is identical):
* 1. Raw Gemini API (Vertex): {candidates: [{content: {parts, role}}]}
* 2. Google ADK: {content: {parts, role}} or {config, contents: [{parts, role}]}
*/
// Raw Gemini API response: {candidates: [{content: {...}}]}
const GeminiRawAPISchema = z.looseObject({
candidates: z.array(
z.looseObject({
content: z.looseObject({
parts: z.array(z.any()).optional(),
role: z.string().optional(),
}),
}),
),
});
// ADK output format: {content: {parts: [...], role: "..."}}
const GeminiADKOutputSchema = z.looseObject({
content: z.looseObject({
parts: z.array(z.any()),
role: z.string(),
}),
});
// ADK invocation input format (root span of the OpenInference ADK
// instrumentation): {user_id, session_id, new_message: {parts, role}, run_config}
const GeminiADKInvocationInputSchema = z.looseObject({
user_id: z.string(),
session_id: z.string(),
new_message: z.looseObject({
parts: z.array(z.any()),
role: z.string().optional(),
}),
});
// ADK input format: {config: {tools, system_instruction}, contents: [...]}
const GeminiADKInputSchema = z.looseObject({
config: z.looseObject({
tools: z.array(z.any()).optional(),
system_instruction: z.string().optional(),
}),
contents: z.array(z.any()),
});
// Simple request format: {contents: [{parts: [...], role: "..."}]}
const GeminiRequestSchema = z.looseObject({
contents: z.array(
z.looseObject({
parts: z.array(z.any()),
role: z.string().optional(),
}),
),
});
/**
* Case-insensitive field accessor
* Handles both snake_case and camelCase (e.g., function_call OR functionCall)
*/
function getField(obj: unknown, snakeName: string, camelName: string): unknown {
if (!obj || typeof obj !== "object") return undefined;
const o = obj as Record<string, unknown>;
return o[snakeName] ?? o[camelName];
}
// Note: Gemini tools come from config.tools with function_declarations, not from messages
// The format {role: "tool", content: {type: "function"}} is LangGraph, handled by langgraph adapter
/**
* Thinking part structure for Gemini
*/
type ThinkingPart = {
content: string;
};
/**
* Extract tool calls, text, and thinking from parts array
* Handles: function_call/functionCall, text, function_response/functionResponse, thought
* snake_case is from python SDK while camelCase is from JavaScript SDK / REST
* Gemini indicates thinking with `thought: true` flag on text parts
*/
function extractFromParts(parts: unknown[]): {
toolCalls: Array<Record<string, unknown>>;
thinkingParts: ThinkingPart[];
text: string;
} {
const toolCalls: Array<Record<string, unknown>> = [];
const thinkingParts: ThinkingPart[] = [];
const textParts: string[] = [];
for (const part of parts) {
if (typeof part === "string") {
textParts.push(part);
continue;
}
if (!part || typeof part !== "object") continue;
const p = part as Record<string, unknown>;
// Check for function_call OR functionCall (case-insensitive)
const fc = getField(p, "function_call", "functionCall");
if (fc && typeof fc === "object") {
const functionCall = fc as Record<string, unknown>;
toolCalls.push({
id: functionCall.id || "",
name: functionCall.name,
arguments:
typeof functionCall.args === "string"
? functionCall.args
: JSON.stringify(functionCall.args ?? {}),
type: "function",
});
continue;
}
// {text: "..."} or {type: "text", text: "..."}
// text can be a string (normal response) or an object (when responseMimeType: "application/json")
// Check for thought flag (Gemini thinking indicator)
if (p.text !== undefined && p.text !== null) {
const textContent =
typeof p.text === "string" ? p.text : JSON.stringify(p.text, null, 2);
// Gemini uses `thought: true` flag to indicate thinking content
if (p.thought === true) {
thinkingParts.push({ content: textContent });
} else {
textParts.push(textContent);
}
continue;
}
// {function_response: {name, response}} OR {functionResponse: {name, response}}
const fr = getField(p, "function_response", "functionResponse");
if (fr && typeof fr === "object") {
const functionResponse = fr as Record<string, unknown>;
textParts.push(JSON.stringify(functionResponse.response || {}));
}
}
return {
toolCalls,
thinkingParts,
text: textParts.join(""),
};
}
/**
* Extract tool declarations from Google ADK tools array
* Handles: {function_declarations: [{name, description, parameters}]}
*/
function extractToolDeclarations(tools: unknown[]): Array<{
name: string;
description?: string;
parameters?: Record<string, unknown>;
}> {
const declarations: Array<{
name: string;
description?: string;
parameters?: Record<string, unknown>;
}> = [];
for (const tool of tools) {
if (!tool || typeof tool !== "object") continue;
const t = tool as Record<string, unknown>;
// Check for function_declarations OR functionDeclarations
const fd = getField(t, "function_declarations", "functionDeclarations");
if (fd && Array.isArray(fd)) {
for (const decl of fd as Array<Record<string, unknown>>) {
const toolDef: Record<string, unknown> = {
name: (decl.name as string) || "",
};
if (decl.description !== null && decl.description !== undefined) {
toolDef.description = decl.description;
}
if (decl.parameters !== null && decl.parameters !== undefined) {
toolDef.parameters = decl.parameters;
}
declarations.push(
toolDef as {
name: string;
description?: string;
parameters?: Record<string, unknown>;
},
);
}
}
}
return declarations;
}
// normalize a single Gemini message to ChatML format
function normalizeGeminiMessage(msg: unknown): Record<string, unknown> {
if (!msg || typeof msg !== "object") return {};
const message = msg as Record<string, unknown>;
let normalized = { ...message };
// convert Gemini "model" role → "assistant"
// if (message.role === "model") {
// normalized.role = "assistant";
// }
// handle direct tool call message format
// {type: "tool_call", name: "...", args: {...}} → {role: "assistant", tool_calls: [...]}
if (
normalized.type === "tool_call" &&
normalized.name &&
typeof normalized.name === "string"
) {
const toolCall: Record<string, unknown> = {
id: normalized.id || "",
name: normalized.name,
arguments:
typeof normalized.args === "string"
? normalized.args
: JSON.stringify(normalized.args ?? {}),
type: "function",
};
const { type: _type, name: _name, args: _args, ...rest } = normalized;
normalized = {
...rest,
role: rest.role || "assistant",
tool_calls: [toolCall],
};
}
// normalize existing tool_calls array
if (normalized.tool_calls && Array.isArray(normalized.tool_calls)) {
normalized.tool_calls = normalized.tool_calls.map((tc) => {
if (!tc || typeof tc !== "object") return {};
const toolCall = tc as Record<string, unknown>;
// Convert Gemini format {type: "tool_call", name, args} → flat format
if (toolCall.type === "tool_call" && "args" in toolCall) {
return {
id: toolCall.id || "",
name: toolCall.name,
arguments:
typeof toolCall.args === "string"
? toolCall.args
: JSON.stringify(toolCall.args ?? {}),
type: "function",
};
}
return toolCall;
});
}
// process top-level parts array
// Gemini format: {parts: [{function_call/text/function_response}], role: "..."}
if (normalized.parts && Array.isArray(normalized.parts)) {
const { toolCalls, thinkingParts, text } = extractFromParts(
normalized.parts,
);
if (toolCalls.length > 0) {
normalized.tool_calls = toolCalls;
}
if (thinkingParts.length > 0) {
normalized.thinking = thinkingParts.map((t) => ({
type: "thinking" as const,
content: t.content,
}));
}
if (text) {
normalized.content = text;
}
// Remove parts to avoid showing in passthrough (regardless of content)
delete normalized.parts;
}
// process nested content.parts[]
// Gemini format: {content: {parts: [{function_call: {...}}], role: "model"}}
if (
normalized.content &&
typeof normalized.content === "object" &&
!Array.isArray(normalized.content) &&
"parts" in normalized.content
) {
const content = normalized.content as Record<string, unknown>;
if (Array.isArray(content.parts)) {
const { toolCalls, thinkingParts } = extractFromParts(content.parts);
if (toolCalls.length > 0) {
normalized.tool_calls = toolCalls;
}
if (thinkingParts.length > 0) {
normalized.thinking = thinkingParts.map((t) => ({
type: "thinking" as const,
content: t.content,
}));
}
// Extract role if nested
if (content.role && typeof content.role === "string") {
normalized.role = content.role;
}
}
}
// process content as array (structured content format)
// Gemini format: {content: [{type: "text", text: "..."}]}
if (Array.isArray(normalized.content)) {
const { text, thinkingParts } = extractFromParts(normalized.content);
if (text) {
normalized.content = text;
}
if (thinkingParts.length > 0) {
normalized.thinking = thinkingParts.map((t) => ({
type: "thinking" as const,
content: t.content,
}));
}
}
// For tool messages with rich object content, spread into message
// so it goes to json passthrough field and renders as PrettyJsonView.
// Rich = nested structure OR 3+ keys. Simple <=2 scalar keys.
if (
normalized.role === "tool" &&
typeof normalized.content === "object" &&
normalized.content !== null &&
!Array.isArray(normalized.content)
) {
if (isRichToolResult(normalized.content)) {
// Rich object: spread for table rendering
const { content, ...rest } = normalized;
return { ...rest, ...content };
}
// Simple object: stringify for text rendering
normalized.content = stringifyToolResultContent(normalized.content);
}
return normalized;
}
// normalize messages
function normalizeMessages(data: unknown[]): unknown[] {
return data.map(normalizeGeminiMessage);
}
// unwrap outer wrappers first then normalize inner structure
function preprocessData(data: unknown): unknown {
if (!data) return data;
// ========================================
// STEP 1: Unwrap Raw Gemini API format
// ========================================
// {candidates: [{content: {parts, role}}]} → {parts, role, ...otherFields}
if (GeminiRawAPISchema.safeParse(data).success) {
const obj = data as Record<string, unknown>;
const candidates = obj.candidates as Array<Record<string, unknown>>;
if (candidates[0]?.content) {
// Unwrap: merge first candidate's content with other top-level fields
const { candidates: _candidates, ...otherFields } = obj;
return normalizeGeminiMessage({
...candidates[0].content,
...otherFields,
});
}
}
// ========================================
// STEP 2: Unwrap ADK output format
// ========================================
// {content: {parts, role}, finish_reason: "..."} → {parts, role, finish_reason: "..."}
if (GeminiADKOutputSchema.safeParse(data).success) {
const obj = data as Record<string, unknown>;
const content = obj.content as Record<string, unknown>;
if ("parts" in content && Array.isArray(content.parts)) {
const { content: _content, ...otherFields } = obj;
return normalizeGeminiMessage({ ...content, ...otherFields });
}
}
// ========================================
// STEP 3: Unwrap ADK invocation input format (root invocation span)
// ========================================
// {new_message: {parts, role}, user_id, session_id, run_config, ...} → [{parts, role}]
if (GeminiADKInvocationInputSchema.safeParse(data).success) {
const obj = data as Record<string, unknown>;
const newMessage = obj.new_message as Record<string, unknown>;
if ("parts" in newMessage && Array.isArray(newMessage.parts)) {
// new_message is the user's request to the agent; default the role
return normalizeMessages([{ role: "user", ...newMessage }]);
}
}
// ========================================
// STEP 4: Handle ADK input format
// ========================================
// {config: {tools, system_instruction}, contents: [...]}
if (GeminiADKInputSchema.safeParse(data).success) {
const obj = data as Record<string, unknown>;
const config = obj.config as Record<string, unknown> | undefined;
const contents = obj.contents;
if (config && Array.isArray(contents)) {
const messages: unknown[] = [];
// Extract system_instruction from config and prepend as system message
const systemInstruction = getField(
config,
"system_instruction",
"systemInstruction",
);
if (systemInstruction && typeof systemInstruction === "string") {
messages.push({
role: "system",
content: systemInstruction,
});
}
messages.push(...contents);
// Extract and attach Gemini ADK config tools if present. Top-level
// normalized input.tools are extracted separately, without changing
// normalized ChatML for existing traces.
if ("tools" in config && Array.isArray(config.tools)) {
const extractedTools = extractToolDeclarations(config.tools);
if (extractedTools.length > 0) {
return normalizeMessages(messages).map((msg) => ({
...(msg as Record<string, unknown>),
tools: extractedTools,
}));
}
}
// No tools, just normalize messages
return normalizeMessages(messages);
}
}
// ========================================
// STEP 5: Handle simple request format
// ========================================
// {contents: [{parts, role}], model: "..."}
if (GeminiRequestSchema.safeParse(data).success) {
const obj = data as Record<string, unknown>;
return normalizeMessages(obj.contents as unknown[]);
}
// ========================================
// STEP 6: Handle arrays
// ========================================
if (Array.isArray(data)) {
return normalizeMessages(data);
}
// ========================================
// STEP 7: Handle messages wrapper
// ========================================
if (typeof data === "object" && "messages" in data) {
const obj = data as Record<string, unknown>;
return {
...obj,
messages: Array.isArray(obj.messages)
? normalizeMessages(obj.messages)
: obj.messages,
};
}
return data;
}
export const geminiAdapter: ProviderAdapter = {
id: "gemini",
detect(ctx: NormalizerContext): boolean {
const meta = parseMetadata(ctx.metadata);
if (ctx.framework === "gemini") return true;
// EXCLUSIONS: Fast checks for explicit non-Gemini indicators
const scopeName = getNestedProperty(meta, "scope", "name");
if (scopeName === "pydantic-ai") return false;
if (scopeName === "agent_framework") return false;
if (
typeof scopeName === "string" &&
scopeName.includes("Microsoft.Extensions.AI")
)
return false;
// HINTS: Fast checks for explicit Gemini indicators
if (ctx.observationName?.toLowerCase().includes("gemini")) return true;
if (ctx.observationName?.toLowerCase().includes("vertex")) return true;
if (meta?.ls_provider === "google_vertexai") return true;
// Metadata attributes check
if (meta && typeof meta === "object" && "attributes" in meta) {
const attributes = (meta as Record<string, unknown>).attributes;
if (
attributes &&
typeof attributes === "object" &&
(attributes as Record<string, unknown>)["gen_ai.system"] ===
"gcp.vertex.agent"
) {
return true;
}
}
// STRUCTURAL: Schema-based detection on metadata (check metadata first for performance)
if (GeminiRequestSchema.safeParse(ctx.metadata).success) return true;
if (GeminiADKInputSchema.safeParse(ctx.metadata).success) return true;
if (GeminiADKInvocationInputSchema.safeParse(ctx.metadata).success)
return true;
if (GeminiRawAPISchema.safeParse(ctx.metadata).success) return true;
if (GeminiADKOutputSchema.safeParse(ctx.metadata).success) return true;
// Schema-based detection on data (slower, do last)
if (GeminiRequestSchema.safeParse(ctx.data).success) return true;
if (GeminiADKInputSchema.safeParse(ctx.data).success) return true;
if (GeminiADKInvocationInputSchema.safeParse(ctx.data).success) return true;
if (GeminiRawAPISchema.safeParse(ctx.data).success) return true;
if (GeminiADKOutputSchema.safeParse(ctx.data).success) return true;
return false;
},
preprocess(
data: unknown,
_kind: "input" | "output",
_ctx: NormalizerContext,
): unknown {
return preprocessData(data);
},
};