AgentPrism Documentation

To use the data transformation utilities, install @evilmartians/agent-prism-data along with its peer dependency @evilmartians/agent-prism-types using npm.

npm install @evilmartians/agent-prism-data @evilmartians/agent-prism-types

Install the TypeScript type definitions and semantic convention constants package using npm.

npm install @evilmartians/agent-prism-types

The TraceViewer component is the fastest way to implement a complete trace visualization interface. It includes a Trace List, a hierarchical Tree View with search, and a Details Panel for inspecting span attributes.

To use it, pass an array of data objects containing a traceRecord (metadata) and spans (the normalized span tree). Use the openTelemetrySpanAdapter to convert raw OTLP data into the required span format.

import { TraceViewer } from "./components/agent-prism/TraceViewer";
import { openTelemetrySpanAdapter } from "@evilmartians/agent-prism-data";

function App() {
  return (
    <TraceViewer
      data={[
        {
          traceRecord: yourTraceRecord,
          spans: 
            openTelemetrySpanAdapter.convertRawDocumentsToSpans(yourTraceData),
        },
      ]}
    />
  );
}

To start the development environment for the AgentPrism SaaS application, run the development command using your preferred package manager. Once started, the application will be available at http://localhost:3000.

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

AgentPrism requires React 19+, Tailwind CSS 3, and TypeScript. Installation involves three steps: copying the UI components, installing the data/types packages, and installing the required UI dependencies.

1. Copy UI components Use degit to copy the component source directly into your project structure:

npx degit evilmartians/agent-prism/packages/ui/src/components src/components/agent-prism

2. Install data and types packages

npm install @evilmartians/agent-prism-data @evilmartians/agent-prism-types

3. Install UI dependencies

npm install @radix-ui/react-collapsible @radix-ui/react-tabs classnames lucide-react react-json-pretty react-resizable-panels

AgentPrism uses semantic tokens for colors based on the OKLCH color space. To use these colors in your Tailwind configuration, you must import agentPrismTailwindColors from the theme module.

1. Import the theme types in your tailwind.config.js.
2. Extend the theme by adding agentPrismTailwindColors to the colors object.
3. Customize colors by modifying the theme.css file in your components folder. This file sets CSS variables on :root.

Because tokens use OKLCH, you can use Tailwind's opacity syntax (e.g., bg-agentprism-primary/50).

import { agentPrismTailwindColors } from "./src/components/theme";

export default {
  theme: {
    extend: {
      colors: agentPrismTailwindColors,
    },
  },
};

When integrating Langfuse data with AgentPrism, the top-level data object must follow the LangfuseDocument shape. A LangfuseDocument consists of a single LangfuseTrace and an array of its associated LangfuseObservation objects.

LangfuseDocument

{
  trace: LangfuseTrace;
  observations: LangfuseObservation[];
}

export type LangfuseDocument = {
  trace: LangfuseTrace;
  observations: LangfuseObservation[];
};

The Tabs component supports two visual styles via the theme prop:

• underline: A standard tab bar with an underline indicator for the active tab. This is the default theme.
• pill: A segmented control style where the active tab appears as a highlighted pill within a container.

You can import both TypeScript types for UI-ready spans and raw data structures, as well as semantic convention constants for OpenInference and OpenTelemetry mappings.

Use import type for type-only imports to ensure they are stripped during compilation.

// Import types
import type {
  TraceSpan,
  TraceSpanAttribute,
  TraceSpanCategory,
  OpenTelemetrySpan,
  OpenTelemetryDocument,
} from "@evilmartians/agent-prism-types";

// Import constants for OpenInference semantic conventions
import {
  OPENINFERENCE_ATTRIBUTES,
  OPENINFERENCE_MAPPINGS,
  OPENTELEMETRY_GENAI_MAPPINGS,
} from "@evilmartians/agent-prism-types";

The openTelemetrySpanAdapter provides several utility methods to extract specific information from an individual span, such as cost, duration, tokens, and status. This is useful for populating UI components or performing analytics on traces.

import { openTelemetrySpanAdapter } from "@evilmartians/agent-prism-data";

// Extract information from spans
const category = openTelemetrySpanAdapter.getSpanCategory(otlpSpan);
const cost = openTelemetrySpanAdapter.getSpanCost(otlpSpan);
const duration = openTelemetrySpanAdapter.getSpanDuration(otlpSpan);
const inputOutput = openTelemetrySpanAdapter.getSpanInputOutput(otlpSpan);
const status = openTelemetrySpanAdapter.getSpanStatus(otlpSpan);
const tokens = openTelemetrySpanAdapter.getSpanTokensCount(otlpSpan);