Principle:Helicone Helicone Response Parsing

Knowledge Sources	Helicone
Domains	LLM Observability, Response Normalization, Anthropic
Last Updated	2026-02-14 00:00 GMT

Overview

Response Parsing is the provider-specific process of extracting and normalizing LLM response content into Helicone's unified LlmSchema["response"] structure, handling multiple response formats from a single provider.

Description

Each LLM provider returns responses in a different structure. Anthropic alone has at least four distinct response formats: the Claude 3 Messages API format (with type: "message" and a content array), the AWS Bedrock Anthropic format (with output.message.content), the legacy choices-based format, and error responses. A response parser must detect which format is present and extract messages, tool calls, and error information into a normalized array of Message objects.

Response Parsing solves the problem of format heterogeneity within a single provider. While Mapper Type Detection operates at the provider level, Response Parsing handles the within-provider variation that arises from API version differences, hosting platform wrappers (Bedrock), and error vs. success responses.

Usage

Use Response Parsing within a provider-specific mapper to convert the raw response body into the normalized LlmSchema["response"]. The Anthropic response parser (getLLMSchemaResponse) is called by the mapAnthropicRequest mapper function. Similar parser functions exist for other providers (OpenAI, Gemini, etc.) but follow the same principle of multi-format detection and normalization.

Theoretical Basis

Response Parsing follows a format detection cascade pattern:

1. Error detection first -- if the response contains an error field, it is immediately normalized into the error.heliconeMessage structure, short-circuiting all other parsing.
2. Format-specific branches -- the parser checks for format indicators in priority order:
   • AWS Bedrock Anthropic (response.output.message.content) -- the Bedrock wrapper nests the Anthropic response inside an output.message envelope.
   • Claude 3 Messages API (response.type === "message" || "message_stop" with response.content) -- the native Anthropic format with a content array containing text and tool_use blocks.
   • Legacy choices format (response.choices[]) -- an older or proxy-transformed format that uses OpenAI-style choices arrays.
3. Content block normalization -- each content block is converted to a Message object using a helper function (anthropicContentToMessage) that handles text, tool_use, and fallback types. Tool use blocks are converted to functionCall-typed messages with extracted name and input arguments.
4. String cleanup -- all message content strings are cleaned of artifact "undefined" substrings and trimmed, preventing rendering issues from incomplete streaming or malformed data.

This multi-branch approach is necessary because Helicone must support the same provider across different hosting contexts (direct API, AWS Bedrock, Azure, proxy layers) without requiring users to specify the exact sub-format.

Related Pages

Implemented By

• Implementation:Helicone_Helicone_GetLLMSchemaResponse