@arizeai/openinference-genai 0.1.10 → 0.3.0

package/src/attributes.ts

@@ -5,6 +5,7 @@ import {
   ATTR_GEN_AI_AGENT_NAME,
   ATTR_GEN_AI_COMPLETION,
   ATTR_GEN_AI_INPUT_MESSAGES,
+  ATTR_GEN_AI_OPERATION_NAME,
   ATTR_GEN_AI_OUTPUT_MESSAGES,
   ATTR_GEN_AI_PROMPT,
   ATTR_GEN_AI_PROVIDER_NAME,
@@ -24,6 +25,15 @@ import {
   ATTR_GEN_AI_TOOL_TYPE,
   ATTR_GEN_AI_USAGE_INPUT_TOKENS,
   ATTR_GEN_AI_USAGE_OUTPUT_TOKENS,
+  GEN_AI_OPERATION_NAME_VALUE_CHAT,
+  GEN_AI_OPERATION_NAME_VALUE_CREATE_AGENT,
+  GEN_AI_OPERATION_NAME_VALUE_EMBEDDINGS,
+  GEN_AI_OPERATION_NAME_VALUE_EXECUTE_TOOL,
+  GEN_AI_OPERATION_NAME_VALUE_GENERATE_CONTENT,
+  GEN_AI_OPERATION_NAME_VALUE_INVOKE_AGENT,
+  GEN_AI_OPERATION_NAME_VALUE_INVOKE_WORKFLOW,
+  GEN_AI_OPERATION_NAME_VALUE_RETRIEVAL,
+  GEN_AI_OPERATION_NAME_VALUE_TEXT_COMPLETION,
 } from "@opentelemetry/semantic-conventions/incubating";
 
 import {
@@ -59,6 +69,43 @@ const AGENT_KIND_PREFIXES = [
   ATTR_GEN_AI_AGENT_DESCRIPTION,
 ] as const;
 
+// "plan" was added to the OTel GenAI semantic conventions
+// (open-telemetry/semantic-conventions-genai#97, merged 2026-05-11) but is not yet released,
+// so @opentelemetry/semantic-conventions exports no constant for it — hence the literal.
+const GEN_AI_OPERATION_NAME_VALUE_PLAN = "plan";
+
+// gen_ai.operation.name values that classify a span by OpenInference span kind. Mirrors
+// AGENT_KIND_PREFIXES / TOOL_EXECUTION_PREFIXES. These operations are recognized by value
+// because the conversion target — OpenInferenceSpanKind — is a closed enum with no per-
+// operation member, so each operation must be mapped into our vocabulary; the original
+// operation name is not preserved on the OI span.
+const AGENT_OPERATIONS: ReadonlySet<string> = new Set([
+  GEN_AI_OPERATION_NAME_VALUE_CREATE_AGENT,
+  GEN_AI_OPERATION_NAME_VALUE_INVOKE_AGENT,
+  GEN_AI_OPERATION_NAME_VALUE_PLAN,
+]);
+
+// "invoke_workflow" maps to CHAIN rather than AGENT: a workflow is a fixed orchestration of
+// steps (a chain), whereas AGENT is reserved for autonomous, LLM-driven control flow. An
+// explicit agent identity (agent.* attribute) still takes precedence and yields AGENT; see
+// mapSpanKind.
+const CHAIN_OPERATIONS: ReadonlySet<string> = new Set([
+  GEN_AI_OPERATION_NAME_VALUE_INVOKE_WORKFLOW,
+]);
+
+// Terminal operations describe a single concrete model/data call (a leaf in the span tree),
+// each with a direct OpenInference span kind. operation.name is authoritative for these — an
+// agent.* identity on them is context (which agent owns the call), not a signal to upgrade
+// the span to AGENT (see mapSpanKind).
+const TERMINAL_OPERATION_SPAN_KINDS: ReadonlyMap<string, OpenInferenceSpanKind> = new Map([
+  [GEN_AI_OPERATION_NAME_VALUE_CHAT, OpenInferenceSpanKind.LLM],
+  [GEN_AI_OPERATION_NAME_VALUE_TEXT_COMPLETION, OpenInferenceSpanKind.LLM],
+  [GEN_AI_OPERATION_NAME_VALUE_GENERATE_CONTENT, OpenInferenceSpanKind.LLM],
+  [GEN_AI_OPERATION_NAME_VALUE_EMBEDDINGS, OpenInferenceSpanKind.EMBEDDING],
+  [GEN_AI_OPERATION_NAME_VALUE_RETRIEVAL, OpenInferenceSpanKind.RETRIEVER],
+  [GEN_AI_OPERATION_NAME_VALUE_EXECUTE_TOOL, OpenInferenceSpanKind.TOOL],
+]);
+
 const TOOL_EXECUTION_PREFIXES = [
   ATTR_GEN_AI_TOOL_NAME,
   ATTR_GEN_AI_TOOL_DESCRIPTION,
@@ -66,6 +113,14 @@ const TOOL_EXECUTION_PREFIXES = [
   ATTR_GEN_AI_TOOL_TYPE,
 ] as const;
 
+const ATTR_GEN_AI_SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions" as const;
+const ATTR_GEN_AI_TOOL_DEFINITIONS = "gen_ai.tool.definitions" as const;
+const ATTR_GEN_AI_TOOL_CALL_ARGUMENTS = "gen_ai.tool.call.arguments" as const;
+const ATTR_GEN_AI_TOOL_CALL_RESULT = "gen_ai.tool.call.result" as const;
+const ATTR_GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read.input_tokens" as const;
+const ATTR_GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS =
+  "gen_ai.usage.cache_creation.input_tokens" as const;
+
 // Shared part parsing
 type AnyPart = GenAIInputMessagePart | GenAIOutputMessagePart;
 
@@ -82,6 +137,70 @@ const isGenAIChatMessage = (value: unknown): value is ChatMessage => {
   return true;
 };
 
+/**
+ * Normalize a GenAI tool definition into the OpenAI-style tool schema shape expected by OpenInference.
+ * @param toolDefinition - The tool definition to normalize
+ * @returns The normalized tool definition, or the original value when it cannot be normalized
+ */
+const normalizeToolDefinition = (toolDefinition: unknown): unknown => {
+  if (
+    typeof toolDefinition !== "object" ||
+    toolDefinition === null ||
+    Array.isArray(toolDefinition)
+  ) {
+    return toolDefinition;
+  }
+
+  const definition = toolDefinition as Record<string, unknown>;
+  if (typeof definition.function === "object" && definition.function !== null) {
+    return definition;
+  }
+
+  if (typeof definition.name !== "string") {
+    return definition;
+  }
+
+  const parameters = definition.parameters ?? definition.inputSchema ?? definition.input_schema;
+  const normalizedFunction: Record<string, unknown> = { name: definition.name };
+  if (typeof definition.description === "string") {
+    normalizedFunction.description = definition.description;
+  }
+  if (parameters != null) {
+    normalizedFunction.parameters = parameters;
+  }
+
+  return {
+    type: typeof definition.type === "string" ? definition.type : "function",
+    function: normalizedFunction,
+  };
+};
+
+const getSystemInstructionParts = (spanAttributes: Attributes): GenAIInputMessagePart[] | null => {
+  const systemInstructions = getString(spanAttributes[ATTR_GEN_AI_SYSTEM_INSTRUCTIONS]);
+  if (systemInstructions == null) {
+    return null;
+  }
+
+  const parsedInstructions = safelyParseJSON(systemInstructions);
+  if (Array.isArray(parsedInstructions)) {
+    const parts = parsedInstructions.flatMap((part): GenAIInputMessagePart[] => {
+      if (
+        typeof part === "object" &&
+        part !== null &&
+        "type" in part &&
+        part.type === "text" &&
+        "content" in part
+      ) {
+        return [{ type: "text", content: toStringContent(part.content) }];
+      }
+      return [];
+    });
+    return parts.length > 0 ? parts : null;
+  }
+
+  return [{ type: "text", content: systemInstructions }];
+};
+
 /**
  * Process genai message parts into openinference attributes
  *
@@ -142,10 +261,7 @@ const processMessageParts = ({
         const response = toStringContent(part.response);
 
         set(attrs, `${msgPrefix}${SemanticConventions.MESSAGE_TOOL_CALL_ID}`, id);
-        const contentPrefix = `${msgPrefix}${SemanticConventions.MESSAGE_CONTENTS}.${contentIndex}.`;
-        set(attrs, `${contentPrefix}${SemanticConventions.MESSAGE_CONTENT_TYPE}`, "text");
-        set(attrs, `${contentPrefix}${SemanticConventions.MESSAGE_CONTENT_TEXT}`, response);
-        contentIndex += 1;
+        set(attrs, `${msgPrefix}${SemanticConventions.MESSAGE_CONTENT}`, response);
         continue;
       }
       default: {
@@ -162,6 +278,30 @@ const processMessageParts = ({
   }
 };
 
+/**
+ * Set OpenInference attributes for a single tool response message.
+ *
+ * GenAI can group multiple tool_call_response parts under one tool-role message;
+ * each response needs its own OpenInference message to avoid overwriting siblings.
+ * @param params - The tool response message mapping parameters
+ */
+const setToolCallResponseMessage = ({
+  attrs,
+  msgPrefix,
+  part,
+}: {
+  attrs: Attributes;
+  msgPrefix: string;
+  part: Extract<AnyPart, { type: "tool_call_response" }>;
+}): void => {
+  const id = part.id ?? undefined;
+  const response = toStringContent(part.response);
+
+  set(attrs, `${msgPrefix}${SemanticConventions.MESSAGE_ROLE}`, "tool");
+  set(attrs, `${msgPrefix}${SemanticConventions.MESSAGE_TOOL_CALL_ID}`, id);
+  set(attrs, `${msgPrefix}${SemanticConventions.MESSAGE_CONTENT}`, response);
+};
+
 /**
  * Convert GenAI span attributes to OpenInference span attributes
  * @param spanAttributes - The span attributes containing GenAI span attributes to convert
@@ -172,11 +312,15 @@ export const convertGenAISpanAttributesToOpenInferenceSpanAttributes = (
 ): Attributes => {
   return merge(
     mapProviderAndSystem(spanAttributes),
+    mapAgentAttributes(spanAttributes),
     mapModels(spanAttributes),
     mapSpanKind(spanAttributes),
     mapInvocationParameters(spanAttributes),
     mapInputMessages(spanAttributes),
     mapOutputMessages(spanAttributes),
+    mapAgent(spanAttributes),
+    mapSystemInstructions(spanAttributes),
+    mapToolDefinitions(spanAttributes),
     mapTokenCounts(spanAttributes),
     mapToolExecution(spanAttributes),
     mapInputValue(spanAttributes),
@@ -193,10 +337,28 @@ export const convertGenAISpanAttributesToOpenInferenceSpanAttributes = (
 export const mapProviderAndSystem = (spanAttributes: Attributes): Attributes => {
   const attrs: Attributes = {};
   const provider = getString(spanAttributes[ATTR_GEN_AI_PROVIDER_NAME]);
+  set(attrs, SemanticConventions.LLM_SYSTEM, provider);
   set(attrs, SemanticConventions.LLM_PROVIDER, provider);
   return attrs;
 };
 
+/**
+ * Map GenAI agent attributes to OpenInference agent attributes.
+ *
+ * Currently only gen_ai.agent.name -> agent.name. gen_ai.agent.id and
+ * gen_ai.agent.description (which also drive AGENT span-kind detection in mapSpanKind) are
+ * intentionally not mapped, as OpenInference has no corresponding agent attributes for them.
+ *
+ * @param spanAttributes - The GenAI span attributes to read agent attributes from
+ * @returns The mapped OpenInference agent attributes
+ */
+export const mapAgentAttributes = (spanAttributes: Attributes): Attributes => {
+  const attrs: Attributes = {};
+  const agentName = getString(spanAttributes[ATTR_GEN_AI_AGENT_NAME]);
+  set(attrs, SemanticConventions.AGENT_NAME, agentName);
+  return attrs;
+};
+
 /**
  * Map model name to openinference attributes
  * @param spanAttributes - The span attributes containing model name to map
@@ -220,11 +382,28 @@ export const mapSpanKind = (spanAttributes: Attributes): Attributes => {
   const attrs: Attributes = {};
   // default to LLM for now
   let spanKind = OpenInferenceSpanKind.LLM;
-  // detect agent kind
-  if (AGENT_KIND_PREFIXES.some((prefix) => spanAttributes[prefix])) {
+  const operationName = getString(spanAttributes[ATTR_GEN_AI_OPERATION_NAME]);
+  const terminalSpanKind =
+    operationName !== undefined ? TERMINAL_OPERATION_SPAN_KINDS.get(operationName) : undefined;
+  const hasAgentAttributes = AGENT_KIND_PREFIXES.some((prefix) => spanAttributes[prefix]);
+  if (terminalSpanKind !== undefined) {
+    // Concrete leaf operation (chat/text_completion/generate_content/embeddings/retrieval/
+    // execute_tool): authoritative. An agent.* identity here is just context (which agent
+    // owns the call) and does not upgrade it to AGENT.
+    spanKind = terminalSpanKind;
+  } else if (
+    hasAgentAttributes ||
+    (operationName !== undefined && AGENT_OPERATIONS.has(operationName))
+  ) {
+    // Control-flow span: an agent.* identity, or an agent-class operation, makes it AGENT —
+    // even over a CHAIN-class operation like invoke_workflow.
     spanKind = OpenInferenceSpanKind.AGENT;
+  } else if (operationName !== undefined && CHAIN_OPERATIONS.has(operationName)) {
+    // CHAIN-class operation, only reached when no agent identity is present.
+    spanKind = OpenInferenceSpanKind.CHAIN;
   }
-  // detect tool execution kind
+  // Tool attributes force TOOL even when the operation says otherwise — covers tool-execution
+  // spans not labeled with operation.name = execute_tool.
   if (TOOL_EXECUTION_PREFIXES.some((prefix) => spanAttributes[prefix])) {
     spanKind = OpenInferenceSpanKind.TOOL;
   }
@@ -284,6 +463,9 @@ export const mapInputValue = (spanAttributes: Attributes): Attributes => {
     // fallback to deprecated prompt attribute if input is not present
     input = getString(spanAttributes[ATTR_GEN_AI_PROMPT]);
   }
+  if (!input) {
+    input = getString(spanAttributes[ATTR_GEN_AI_INPUT_MESSAGES]);
+  }
   // only set input value and mime type if input is present
   if (input) {
     set(attrs, SemanticConventions.INPUT_VALUE, input);
@@ -304,6 +486,9 @@ export const mapOutputValue = (spanAttributes: Attributes): Attributes => {
     // fallback to deprecated completion attribute if output is not present
     output = getString(spanAttributes[ATTR_GEN_AI_COMPLETION]);
   }
+  if (!output) {
+    output = getString(spanAttributes[ATTR_GEN_AI_OUTPUT_MESSAGES]);
+  }
   // only set output value and mime type if output is present
   if (output) {
     set(attrs, SemanticConventions.OUTPUT_VALUE, output);
@@ -312,6 +497,60 @@ export const mapOutputValue = (spanAttributes: Attributes): Attributes => {
   return attrs;
 };
 
+/**
+ * Map GenAI agent attributes to OpenInference attributes.
+ * @param spanAttributes - The span attributes containing agent details
+ * @returns The mapped agent attributes
+ */
+export const mapAgent = (spanAttributes: Attributes): Attributes => {
+  const attrs: Attributes = {};
+  set(attrs, SemanticConventions.AGENT_NAME, getString(spanAttributes[ATTR_GEN_AI_AGENT_NAME]));
+  return attrs;
+};
+
+/**
+ * Map GenAI system instructions into metadata for preservation.
+ * @param spanAttributes - The span attributes containing system instructions
+ * @returns The mapped metadata attributes
+ */
+export const mapSystemInstructions = (spanAttributes: Attributes): Attributes => {
+  const attrs: Attributes = {};
+  const systemInstructions = getString(spanAttributes[ATTR_GEN_AI_SYSTEM_INSTRUCTIONS]);
+  if (systemInstructions) {
+    set(attrs, `${SemanticConventions.METADATA}.gen_ai.system_instructions`, systemInstructions);
+
+    const msgPrefix = `${SemanticConventions.LLM_INPUT_MESSAGES}.0.`;
+    set(attrs, `${msgPrefix}${SemanticConventions.MESSAGE_ROLE}`, "system");
+    processMessageParts({
+      attrs,
+      msgPrefix,
+      parts: getSystemInstructionParts(spanAttributes) ?? [],
+    });
+  }
+  return attrs;
+};
+
+/**
+ * Map GenAI tool definitions to OpenInference LLM tool schema attributes.
+ * @param spanAttributes - The span attributes containing tool definitions
+ * @returns The mapped tool schema attributes
+ */
+export const mapToolDefinitions = (spanAttributes: Attributes): Attributes => {
+  const attrs: Attributes = {};
+  const toolDefinitions = getString(spanAttributes[ATTR_GEN_AI_TOOL_DEFINITIONS]);
+  const parsedToolDefinitions = safelyParseJSON(toolDefinitions);
+  if (Array.isArray(parsedToolDefinitions)) {
+    parsedToolDefinitions.forEach((toolDefinition, index) => {
+      set(
+        attrs,
+        `${SemanticConventions.LLM_TOOLS}.${index}.${SemanticConventions.TOOL_JSON_SCHEMA}`,
+        safelyJSONStringify(normalizeToolDefinition(toolDefinition)),
+      );
+    });
+  }
+  return attrs;
+};
+
 /**
  * Map input messages to openinference attributes
  * @param spanAttributes - The span attributes containing input messages to map
@@ -322,13 +561,30 @@ export const mapInputMessages = (spanAttributes: Attributes): Attributes => {
   const genAIInputMessages = safelyParseJSON(spanAttributes[ATTR_GEN_AI_INPUT_MESSAGES]);
 
   if (Array.isArray(genAIInputMessages)) {
-    (genAIInputMessages as unknown[]).forEach((msg, msgIndex) => {
+    let msgIndex = getSystemInstructionParts(spanAttributes) != null ? 1 : 0;
+    (genAIInputMessages as unknown[]).forEach((msg) => {
       if (!isGenAIChatMessage(msg)) return;
+
+      const toolCallResponses = msg.parts.filter(
+        (part): part is Extract<AnyPart, { type: "tool_call_response" }> =>
+          part?.type === "tool_call_response",
+      );
+
+      if (msg.role === "tool" && toolCallResponses.length > 0) {
+        toolCallResponses.forEach((part) => {
+          const msgPrefix = `${SemanticConventions.LLM_INPUT_MESSAGES}.${msgIndex}.`;
+          setToolCallResponseMessage({ attrs, msgPrefix, part });
+          msgIndex += 1;
+        });
+        return;
+      }
+
       const msgPrefix = `${SemanticConventions.LLM_INPUT_MESSAGES}.${msgIndex}.`;
       // set the message role
       set(attrs, `${msgPrefix}${SemanticConventions.MESSAGE_ROLE}`, msg.role);
       // process and set the rest of the message parts
       processMessageParts({ attrs, msgPrefix, parts: msg.parts });
+      msgIndex += 1;
     });
   }
 
@@ -368,6 +624,10 @@ export const mapTokenCounts = (spanAttributes: Attributes): Attributes => {
   const attrs: Attributes = {};
   const inputTokens = getNumber(spanAttributes[ATTR_GEN_AI_USAGE_INPUT_TOKENS]);
   const outputTokens = getNumber(spanAttributes[ATTR_GEN_AI_USAGE_OUTPUT_TOKENS]);
+  const cacheReadInputTokens = getNumber(spanAttributes[ATTR_GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS]);
+  const cacheCreationInputTokens = getNumber(
+    spanAttributes[ATTR_GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS],
+  );
   if (typeof inputTokens === "number") {
     set(attrs, SemanticConventions.LLM_TOKEN_COUNT_PROMPT, inputTokens);
   }
@@ -377,6 +637,16 @@ export const mapTokenCounts = (spanAttributes: Attributes): Attributes => {
   if (typeof inputTokens === "number" && typeof outputTokens === "number") {
     set(attrs, SemanticConventions.LLM_TOKEN_COUNT_TOTAL, inputTokens + outputTokens);
   }
+  if (typeof cacheReadInputTokens === "number") {
+    set(attrs, SemanticConventions.LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_READ, cacheReadInputTokens);
+  }
+  if (typeof cacheCreationInputTokens === "number") {
+    set(
+      attrs,
+      SemanticConventions.LLM_TOKEN_COUNT_PROMPT_DETAILS_CACHE_WRITE,
+      cacheCreationInputTokens,
+    );
+  }
   return attrs;
 };
 
@@ -391,11 +661,21 @@ export const mapToolExecution = (spanAttributes: Attributes): Attributes => {
   const toolName = getString(spanAttributes[ATTR_GEN_AI_TOOL_NAME]);
   const toolDescription = getString(spanAttributes[ATTR_GEN_AI_TOOL_DESCRIPTION]);
   const toolCallId = getString(spanAttributes[ATTR_GEN_AI_TOOL_CALL_ID]);
+  const toolCallArguments = getString(spanAttributes[ATTR_GEN_AI_TOOL_CALL_ARGUMENTS]);
+  const toolCallResult = getString(spanAttributes[ATTR_GEN_AI_TOOL_CALL_RESULT]);
   // parse supported tool details
-  // note: while openinference can track parameters, gen_ai does not provide this information
   set(attrs, SemanticConventions.TOOL_NAME, toolName);
   set(attrs, SemanticConventions.TOOL_DESCRIPTION, toolDescription);
   set(attrs, SemanticConventions.TOOL_CALL_ID, toolCallId);
+  set(attrs, SemanticConventions.TOOL_PARAMETERS, toolCallArguments);
+  if (toolCallArguments) {
+    set(attrs, SemanticConventions.INPUT_VALUE, toolCallArguments);
+    set(attrs, SemanticConventions.INPUT_MIME_TYPE, getMimeType(toolCallArguments));
+  }
+  if (toolCallResult) {
+    set(attrs, SemanticConventions.OUTPUT_VALUE, toolCallResult);
+    set(attrs, SemanticConventions.OUTPUT_MIME_TYPE, getMimeType(toolCallResult));
+  }
 
   return attrs;
 };