Install the TypeScript SDK to send conversation and trace data (beta)

The Pendo TypeScript SDK lets you instrument TypeScript-based AI agents to send conversation and trace data to Pendo directly from your backend, with no Pendo Web SDK required. This article covers installation, initialization, and enabling tracing with OpenTelemetry or LangChain.js.

For a conceptual overview of tracing and what trace data looks like in Pendo, see Understand and review agent traces.

Prerequisites

Before you begin, you must have:

• Node.js 18 or later.
• Full conversations activated for your agent in Pendo. For setup steps, see Add and configure AI agents in Pendo.
• Your app's Public App ID. A subscription admin can find this in Settings > Subscription settings > Applications after opening the relevant app.
• Your Agent ID. To find it, go to Product > Agent Analytics, then select the settings icon next to the agent name.

Install the SDK

To install the Pendo TypeScript SDK, run:

npm install pendo-server-sdk

Initialize the SDK

Call init() once at startup, before your agent handles any requests. Pass your Public App ID and a default visitor and account identity, then update the context for each request.

import { init, setContext } from 'pendo-server-sdk';

// Initialize at app startup  
init({
    apiKey: process.env.PENDO_SDK_API_KEY,
    agentId: 'my-agent',
  });
  
  // Per request: overrides init-time identity for this call tree
  await setContext(
    { visitorId: user.email, accountId: user.orgId, conversationId: threadId },
    async () => agent.invoke({ input: message }),
  );

Get tracing data

The TypeScript SDK can capture conversation and trace data through both OpenTelemetry (OTel) and LangChain.js.

Set up traces with OpenTelemetry

To set up traces with OpenTelemetry, you must have OTel installed in your Node.js environment.

If OTel is running, the Pendo SDK captures trace data automatically, with no additional SDK configuration required.

Set up traces with LangChain.js

To set up traces with LangChain.js, you must have it installed in your Node.js environment.

Add the PendoCallbackHandler to your LangChain configuration. The handler automatically captures each prompt, response, tool call, LLM call, and execution step as your agent runs. No additional tracking calls are required.

import { PendoCallbackHandler } from 'pendo-server-sdk/langchain_callback';

const handler = new PendoCallbackHandler();
const result = await llm.invoke(prompt, { callbacks: [handler] });

Verify your setup

After setting up the SDK, run your agent in your development or staging environment and submit a test prompt. Then confirm data is reaching Pendo:

• Check Agent Analytics. Conversation data is processed in hourly batches. After your code is live in production, new messages typically appear within 15 minutes after the start of the next batch. Go to Product > Agent Analytics, select your agent, and open the Conversations tab to confirm that prompts and responses appear.
• Check for trace data. Conversations with trace data display an activity icon next to the relevant prompt or response in the conversation view. Select it to open the Conversation trace view. For more information, see Understand and review agent traces.

Tip: If your application retries API calls or replays events, reuse the same messageId to avoid duplicate records in Pendo.

Record user reactions manually

The TypeScript SDK automatically captures prompts, responses, and trace data through your chosen setup option.

If you also want to record user_reaction events, such as thumbs-up or thumbs-down feedback, you must send them manually using recordReaction:

import { recordReaction } from "pendo-server-sdk";
  
  recordReaction({
    conversationId,
    reactionType,        // 'thumbs_up', 'thumbs_down', or 'unreact'
    messageId,           // same id as the message this reaction is tied to
    feedbackComment,     // optional free-text string
    visitorId,
    accountId,
  });

Troubleshooting

If data isn't appearing in Pendo, review these checks in order: