feat: trace Letta Agent SDK sessions

.changeset/quiet-letta-sessions.md

@@ -0,0 +1,7 @@
+---
+"braintrust": minor
+---
+
+feat: trace Letta Agent SDK sessions
+
+Add automatic and manual tracing for Letta Agent SDK 0.8.28 and later 0.8.x releases, including agent creation, session resumption, streamed turns, tool calls, errors, and cancellation.

js/package.json

@@ -190,6 +190,7 @@
   "license": "MIT",
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.60.0",
+    "@letta-ai/letta-agent-sdk": "0.8.28",
     "@nodelib/fs.walk": "^1.2.8",
     "@types/argparse": "^2.0.14",
     "@types/async": "^3.2.24",

js/src/auto-instrumentations/configs/all.ts

@@ -34,6 +34,7 @@ import { openRouterConfigs } from "./openrouter";
 import { openRouterAgentConfigs } from "./openrouter-agent";
 import { piCodingAgentConfigs } from "./pi-coding-agent";
 import { strandsAgentSDKConfigs } from "./strands-agent-sdk";
+import { lettaAgentSDKConfigs } from "./letta-agent-sdk";
 import { elevenLabsConfigs } from "./elevenlabs";
 import { voyageAIConfigs } from "./voyageai";
 import { typeSafeConfigs } from "./typesafe";
@@ -124,6 +125,10 @@ const defaultInstrumentationConfigGroups: readonly InstrumentationConfigGroup[]
       integrations: ["strandsAgentSDK"],
       configs: strandsAgentSDKConfigs,
     },
+    {
+      integrations: ["lettaAgentSDK"],
+      configs: lettaAgentSDKConfigs,
+    },
     {
       integrations: ["flue"],
       configs: flueConfigs,

js/src/auto-instrumentations/configs/letta-agent-sdk.ts

@@ -0,0 +1,50 @@
+import type { InstrumentationConfig } from "@apm-js-collab/code-transformer";
+import { lettaAgentSDKChannels } from "../../instrumentation/plugins/letta-agent-sdk-channels";
+
+// Both entrypoints bundle the same client and session base classes. Local,
+// remote, and cloud sessions all execute turns through RemoteClientSessionCore.
+export const lettaAgentSDKConfigs: InstrumentationConfig[] = [
+  "dist/index.js",
+  "dist/client-entry.js",
+].flatMap((filePath) =>
+  [
+    {
+      channel: lettaAgentSDKChannels.createAgent,
+      className: "LettaAgentClientBase",
+      methodName: "createAgent",
+      kind: "Async" as const,
+    },
+    {
+      channel: lettaAgentSDKChannels.resumeSession,
+      className: "LettaAgentClientBase",
+      methodName: "resumeSession",
+      kind: "Sync" as const,
+    },
+    {
+      channel: lettaAgentSDKChannels.send,
+      className: "RemoteClientSessionCore",
+      methodName: "send",
+      kind: "Async" as const,
+    },
+    {
+      channel: lettaAgentSDKChannels.stream,
+      className: "RemoteClientSessionCore",
+      methodName: "stream",
+      kind: "Sync" as const,
+    },
+    {
+      channel: lettaAgentSDKChannels.close,
+      className: "RemoteClientSessionCore",
+      methodName: "close",
+      kind: "Sync" as const,
+    },
+  ].map(({ channel, ...functionQuery }) => ({
+    channelName: channel.channelName,
+    module: {
+      name: "@letta-ai/letta-agent-sdk",
+      versionRange: ">=0.8.28 <0.9.0",
+      filePath,
+    },
+    functionQuery,
+  })),
+);

js/src/exports.ts

@@ -224,6 +224,7 @@ export { wrapCursorSDK } from "./wrappers/cursor-sdk";
 export { wrapPiCodingAgentSDK } from "./wrappers/pi-coding-agent";
 export { wrapCloudflareAgent } from "./wrappers/cloudflare-agent";
 export { wrapStrandsAgentSDK } from "./wrappers/strands-agent-sdk";
+export { wrapLettaAgentSDK } from "./wrappers/letta-agent-sdk";
 export { wrapCloudflareAIChat } from "./wrappers/cloudflare-ai-chat";
 export { wrapGoogleGenerativeAI } from "./wrappers/google-generative-ai";
 export { wrapGoogleGenAI } from "./wrappers/google-genai";

js/src/instrumentation/braintrust-plugin.test.ts

@@ -22,6 +22,7 @@ import { LangChainPlugin } from "./plugins/langchain-plugin";
 import { LangSmithPlugin } from "./plugins/langsmith-plugin";
 import { PiCodingAgentPlugin } from "./plugins/pi-coding-agent-plugin";
 import { StrandsAgentSDKPlugin } from "./plugins/strands-agent-sdk-plugin";
+import { LettaAgentSDKPlugin } from "./plugins/letta-agent-sdk-plugin";
 import { VoyageAIPlugin } from "./plugins/voyageai-plugin";
 import { TypeSafePlugin } from "./plugins/typesafe-plugin";
 import { CloudflareAIChatPlugin } from "./plugins/cloudflare-ai-chat-plugin";
@@ -37,6 +38,33 @@ function createPluginClassMock() {
   });
 }
 
+vi.mock("./plugins/letta-agent-sdk-plugin", () => ({
+  LettaAgentSDKPlugin: createPluginClassMock(),
+}));
+
+describe("Letta Agent SDK registration", () => {
+  it("enables and disables the plugin with the registry", () => {
+    vi.mocked(LettaAgentSDKPlugin).mockClear();
+    const plugin = new BraintrustPlugin();
+    plugin.enable();
+    expect(LettaAgentSDKPlugin).toHaveBeenCalledOnce();
+    const instance = vi.mocked(LettaAgentSDKPlugin).mock.results[0].value;
+    expect(instance.enable).toHaveBeenCalledOnce();
+    plugin.disable();
+    expect(instance.disable).toHaveBeenCalledOnce();
+  });
+
+  it("honors the integration opt-out", () => {
+    vi.mocked(LettaAgentSDKPlugin).mockClear();
+    const plugin = new BraintrustPlugin({
+      integrations: { lettaAgentSDK: false },
+    });
+    plugin.enable();
+    expect(LettaAgentSDKPlugin).not.toHaveBeenCalled();
+    plugin.disable();
+  });
+});
+
 // Preserve the re-exported utility functions (parseMetricsFromUsage, etc.)
 // while mocking out the OpenAIPlugin class — those utilities are also
 // imported and tested at the bottom of this file via braintrust-plugin's

js/src/instrumentation/braintrust-plugin.ts

@@ -27,6 +27,7 @@ import { LangChainPlugin } from "./plugins/langchain-plugin";
 import { LangSmithPlugin } from "./plugins/langsmith-plugin";
 import { PiCodingAgentPlugin } from "./plugins/pi-coding-agent-plugin";
 import { StrandsAgentSDKPlugin } from "./plugins/strands-agent-sdk-plugin";
+import { LettaAgentSDKPlugin } from "./plugins/letta-agent-sdk-plugin";
 import { ElevenLabsPlugin } from "./plugins/elevenlabs-plugin";
 import { VoyageAIPlugin } from "./plugins/voyageai-plugin";
 import { TypeSafePlugin } from "./plugins/typesafe-plugin";
@@ -88,6 +89,7 @@ export class BraintrustPlugin extends BasePlugin {
   private langSmithPlugin: LangSmithPlugin | null = null;
   private piCodingAgentPlugin: PiCodingAgentPlugin | null = null;
   private strandsAgentSDKPlugin: StrandsAgentSDKPlugin | null = null;
+  private lettaAgentSDKPlugin: LettaAgentSDKPlugin | null = null;
   private elevenLabsPlugin: ElevenLabsPlugin | null = null;
   private voyageAIPlugin: VoyageAIPlugin | null = null;
   private typeSafePlugin: TypeSafePlugin | null = null;
@@ -252,6 +254,11 @@ export class BraintrustPlugin extends BasePlugin {
       this.strandsAgentSDKPlugin.enable();
     }
 
+    if (integrations.lettaAgentSDK !== false) {
+      this.lettaAgentSDKPlugin = new LettaAgentSDKPlugin();
+      this.lettaAgentSDKPlugin.enable();
+    }
+
     if (integrations.cloudflareAIChat !== false) {
       this.cloudflareAIChatPlugin = new CloudflareAIChatPlugin();
       this.cloudflareAIChatPlugin.enable();
@@ -426,6 +433,11 @@ export class BraintrustPlugin extends BasePlugin {
       this.strandsAgentSDKPlugin = null;
     }
 
+    if (this.lettaAgentSDKPlugin) {
+      this.lettaAgentSDKPlugin.disable();
+      this.lettaAgentSDKPlugin = null;
+    }
+
     if (this.cloudflareAIChatPlugin) {
       this.cloudflareAIChatPlugin.disable();
       this.cloudflareAIChatPlugin = null;

js/src/instrumentation/config.ts

@@ -50,6 +50,7 @@ export interface InstrumentationIntegrationsConfig {
   openaiCodexSDK?: boolean;
   piCodingAgent?: boolean;
   strandsAgentSDK?: boolean;
+  lettaAgentSDK?: boolean;
   cloudflareAgents?: boolean;
   langchain?: boolean;
   langgraph?: boolean;
@@ -96,6 +97,11 @@ const envIntegrationAliases: Record<
   strandsagentsdk: "strandsAgentSDK",
   "strands-agent-sdk": "strandsAgentSDK",
   "@strands-agents/sdk": "strandsAgentSDK",
+  lettaAgentSDK: "lettaAgentSDK",
+  lettaagentsdk: "lettaAgentSDK",
+  letta: "lettaAgentSDK",
+  "letta-agent-sdk": "lettaAgentSDK",
+  "@letta-ai/letta-agent-sdk": "lettaAgentSDK",
   agents: "cloudflareAgents",
   "cloudflare-agents": "cloudflareAgents",
   cloudflareagents: "cloudflareAgents",
@@ -210,6 +216,7 @@ export function getDefaultInstrumentationIntegrations(): Record<
     elevenlabs: true,
     piCodingAgent: true,
     strandsAgentSDK: true,
+    lettaAgentSDK: true,
     cloudflareAgents: true,
   };
 }

js/src/instrumentation/plugins/instrumentation-names.test.ts

@@ -34,6 +34,7 @@ import { openRouterAgentChannels } from "./openrouter-agent-channels";
 import { openRouterChannels } from "./openrouter-channels";
 import { piCodingAgentChannels } from "./pi-coding-agent-channels";
 import { strandsAgentSDKChannels } from "./strands-agent-sdk-channels";
+import { lettaAgentSDKChannels } from "./letta-agent-sdk-channels";
 
 describe("built-in instrumentation provenance names", () => {
   it.each([
@@ -88,6 +89,7 @@ describe("built-in instrumentation provenance names", () => {
       strandsAgentSDKChannels.agentStream,
       INSTRUMENTATION_NAMES.STRANDS_AGENT_SDK,
     ],
+    [lettaAgentSDKChannels.send, INSTRUMENTATION_NAMES.LETTA_AGENT_SDK],
   ])("uses %s for its canonical channel group", (channel, expected) => {
     expect(channel.instrumentationName).toBe(expected);
   });

js/src/instrumentation/plugins/letta-agent-sdk-channels.ts

@@ -0,0 +1,32 @@
+import type { LettaMessage } from "../../vendor-sdk-types/letta-agent-sdk";
+import { channel, defineChannels } from "../core/channel-definitions";
+import { INSTRUMENTATION_NAMES } from "../../span-origin";
+
+export const lettaAgentSDKChannels = defineChannels(
+  "@letta-ai/letta-agent-sdk",
+  {
+    createAgent: channel<[Record<string, unknown>?], string>({
+      channelName: "LettaAgentClient.createAgent",
+      kind: "async",
+    }),
+    resumeSession: channel<[string, Record<string, unknown>?], object>({
+      channelName: "LettaAgentClient.resumeSession",
+      kind: "sync-stream",
+    }),
+    send: channel<[unknown, Record<string, unknown>?], void>({
+      channelName: "LettaSession.send",
+      kind: "async",
+    }),
+    stream: channel<[], AsyncGenerator<LettaMessage>>({
+      channelName: "LettaSession.stream",
+      kind: "sync-stream",
+    }),
+    close: channel<[], void>({
+      channelName: "LettaSession.close",
+      kind: "sync-stream",
+    }),
+  },
+  { instrumentationName: INSTRUMENTATION_NAMES.LETTA_AGENT_SDK },
+);
+
+export type { LettaMessage } from "../../vendor-sdk-types/letta-agent-sdk";