Skip to content

Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.

feat(ts-sdk): add Letta instrumentation (#1422)

Amad Naseem24224bdfad86
diff --git a/sdk/typescript/package-lock.json b/sdk/typescript/package-lock.json
index ee844a25..f905040b 100644
--- a/sdk/typescript/package-lock.json
+++ b/sdk/typescript/package-lock.json
@@ -27,6 +27,7 @@
"@digitalocean/gradient": "^0.1.0-alpha.2",
"@eslint/js": "^9.2.0",
"@google-cloud/vertexai": "^1.12.0",
+ "@letta-ai/letta-client": "^1.12.1",
"@mendable/firecrawl-js": "^1.29.3",
"@types/jest": "^29.0.0",
"ai21": "^1.3.0",
@@ -1312,6 +1313,13 @@
"@jridgewell/sourcemap-codec": "^1.4.14"
}
},
+ "node_modules/@letta-ai/letta-client": {
+ "version": "1.12.1",
+ "resolved": "https://registry.npmjs.org/@letta-ai/letta-client/-/letta-client-1.12.1.tgz",
+ "integrity": "sha512-rYjXMXpkfssj7VBBX3qCp6mdpNRv6YPNrliYsjkhWoQDqGg3J9bsgIQ28ZhQTddabYxRUIwcdzuaizFx8pvZ7A==",
+ "dev": true,
+ "license": "Apache-2.0"
+ },
"node_modules/@mendable/firecrawl-js": {
"version": "1.29.3",
"resolved": "https://registry.npmjs.org/@mendable/firecrawl-js/-/firecrawl-js-1.29.3.tgz",
diff --git a/sdk/typescript/package.json b/sdk/typescript/package.json
index 8d338d05..e1cb0f1a 100644
--- a/sdk/typescript/package.json
+++ b/sdk/typescript/package.json
@@ -60,6 +60,7 @@
"@digitalocean/gradient": "^0.1.0-alpha.2",
"@eslint/js": "^9.2.0",
"@google-cloud/vertexai": "^1.12.0",
+ "@letta-ai/letta-client": "^1.12.1",
"@mendable/firecrawl-js": "^1.29.3",
"@types/jest": "^29.0.0",
"ai21": "^1.3.0",
diff --git a/sdk/typescript/src/instrumentation/__tests__/letta-wrapper.test.ts b/sdk/typescript/src/instrumentation/__tests__/letta-wrapper.test.ts
new file mode 100644
index 00000000..fafc0dc3
--- /dev/null
+++ b/sdk/typescript/src/instrumentation/__tests__/letta-wrapper.test.ts
@@ -0,0 +1,332 @@
+import { SpanKind } from '@opentelemetry/api';
+import { isTracingSuppressed } from '@opentelemetry/core';
+import { ATTR_SERVICE_NAME, ATTR_TELEMETRY_SDK_NAME } from '@opentelemetry/semantic-conventions';
+import OpenlitConfig from '../../config';
+import OpenLitHelper from '../../helpers';
+import SemanticConvention from '../../semantic-convention';
+import LettaWrapper from '../letta/wrapper';
+import LettaInstrumentation from '../letta';
+
+jest.mock('../../config');
+jest.mock('../../helpers', () => ({
+ __esModule: true,
+ default: {
+ handleException: jest.fn(),
+ getChatModelCost: jest.fn().mockReturnValue(0.0025),
+ createStreamProxy: async (stream: any, gen: any) =>
+ new Proxy(stream, {
+ get(target, prop, receiver) {
+ if (prop === Symbol.asyncIterator) return () => gen;
+ return Reflect.get(target, prop, receiver);
+ },
+ }),
+ },
+ applyCustomSpanAttributes: jest.fn(),
+}));
+jest.mock('@opentelemetry/core', () => ({
+ isTracingSuppressed: jest.fn().mockReturnValue(false),
+}));
+
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+
+describe('letta wrapper', () => {
+ let mockSpan: any;
+ let mockTracer: any;
+
+ beforeEach(() => {
+ mockSpan = {
+ setAttribute: jest.fn(),
+ setStatus: jest.fn(),
+ end: jest.fn(),
+ recordException: jest.fn(),
+ isRecording: jest.fn().mockReturnValue(true),
+ };
+ mockTracer = { startSpan: jest.fn(() => mockSpan) };
+
+ (OpenlitConfig as any).environment = 'openlit-testing';
+ (OpenlitConfig as any).applicationName = 'openlit-test';
+ (OpenlitConfig as any).captureMessageContent = true;
+ (OpenlitConfig as any).maxContentLength = null;
+ (OpenlitConfig as any).pricingInfo = { chat: {} };
+ (isTracingSuppressed as jest.Mock).mockReturnValue(false);
+ });
+
+ afterEach(() => {
+ jest.clearAllMocks();
+ });
+
+ function attrs(): Record<string, any> {
+ return Object.fromEntries((mockSpan.setAttribute as jest.Mock).mock.calls);
+ }
+
+ async function runOp(
+ endpoint: string,
+ impl: (...a: any[]) => any,
+ args: any[],
+ agentScoped = true
+ ) {
+ const wrapped = LettaWrapper._patchOperation(mockTracer, endpoint, agentScoped, '1.12.1')(impl);
+ const result = await wrapped.apply({}, args);
+ await flush();
+ return result;
+ }
+
+ it('opens a create_agent span with agent metadata', async () => {
+ const agent = {
+ id: 'agent-123',
+ name: 'Support Bot',
+ agent_type: 'memgpt_agent',
+ system: 'You are a helpful assistant.',
+ llm_config: { model: 'gpt-4o-mini', provider_name: 'openai', context_window: 8192 },
+ };
+ await runOp('letta.create', async () => agent, [{ name: 'Support Bot', model: 'gpt-4o-mini' }]);
+
+ expect(mockTracer.startSpan).toHaveBeenCalledWith('create_agent support_bot', {
+ kind: SpanKind.CLIENT,
+ attributes: {
+ [SemanticConvention.GEN_AI_OPERATION]: SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,
+ [SemanticConvention.GEN_AI_PROVIDER_NAME_OTEL]: SemanticConvention.GEN_AI_SYSTEM_LETTA,
+ },
+ });
+
+ const a = attrs();
+ expect(a[ATTR_TELEMETRY_SDK_NAME]).toBe('openlit');
+ expect(a[ATTR_SERVICE_NAME]).toBe('openlit-test');
+ expect(a[SemanticConvention.ATTR_DEPLOYMENT_ENVIRONMENT]).toBe('openlit-testing');
+ expect(a[SemanticConvention.GEN_AI_PROVIDER_NAME]).toBe('letta');
+ expect(a[SemanticConvention.GEN_AI_PROVIDER_NAME_OTEL]).toBe('letta');
+ expect(a[SemanticConvention.GEN_AI_OPERATION]).toBe('create_agent');
+ expect(a[SemanticConvention.GEN_AI_SDK_VERSION]).toBe('1.12.1');
+ expect(a[SemanticConvention.SERVER_ADDRESS]).toBe('api.letta.com');
+ expect(a[SemanticConvention.SERVER_PORT]).toBe(443);
+ expect(a[SemanticConvention.GEN_AI_AGENT_ID]).toBe('agent-123');
+ expect(a[SemanticConvention.GEN_AI_AGENT_NAME]).toBe('Support Bot');
+ expect(a[SemanticConvention.GEN_AI_AGENT_TYPE]).toBe('memgpt_agent');
+ expect(a[SemanticConvention.GEN_AI_AGENT_INSTRUCTIONS]).toBe('You are a helpful assistant.');
+ expect(a[SemanticConvention.GEN_AI_REQUEST_MODEL]).toBe('gpt-4o-mini');
+ expect(a[SemanticConvention.GEN_AI_REQUEST_CONTEXT_WINDOW]).toBe(8192);
+ expect(typeof a[SemanticConvention.GEN_AI_CLIENT_OPERATION_DURATION]).toBe('number');
+ expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: 1 });
+ expect(mockSpan.end).toHaveBeenCalledTimes(1);
+ });
+
+ it('applies custom span attributes on every span', async () => {
+ const { applyCustomSpanAttributes } = jest.requireMock('../../helpers');
+ await runOp('letta.retrieve', async () => ({ id: 'agent-1' }), ['agent-1']);
+ expect(applyCustomSpanAttributes).toHaveBeenCalledWith(mockSpan);
+ });
+
+ it('names a message create span chat {model} and records usage + cost', async () => {
+ const response = {
+ messages: [{ message_type: 'assistant_message', content: 'Hi there' }],
+ usage: { prompt_tokens: 12, completion_tokens: 4, total_tokens: 16, step_count: 1 },
+ };
+ await runOp('letta.create_message', async () => response, [
+ 'agent-1',
+ { messages: [{ role: 'user', content: 'hello' }], model: 'gpt-4o' },
+ ]);
+
+ expect(mockTracer.startSpan).toHaveBeenCalledWith('chat gpt-4o', {
+ kind: SpanKind.CLIENT,
+ attributes: {
+ [SemanticConvention.GEN_AI_OPERATION]: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ [SemanticConvention.GEN_AI_PROVIDER_NAME_OTEL]: SemanticConvention.GEN_AI_SYSTEM_LETTA,
+ },
+ });
+
+ const a = attrs();
+ expect(a[SemanticConvention.GEN_AI_OPERATION]).toBe('chat');
+ expect(a[SemanticConvention.GEN_AI_AGENT_ID]).toBe('agent-1');
+ expect(a[SemanticConvention.GEN_AI_REQUEST_MESSAGE_COUNT]).toBe(1);
+ expect(a[SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS]).toBe(12);
+ expect(a[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS]).toBe(4);
+ expect(a[SemanticConvention.GEN_AI_USAGE_TOTAL_TOKENS]).toBe(16);
+ expect(a[SemanticConvention.GEN_AI_AGENT_STEP_COUNT]).toBe(1);
+ expect(a[SemanticConvention.GEN_AI_USAGE_COST]).toBe(0.0025);
+ expect(JSON.parse(a[SemanticConvention.GEN_AI_INPUT_MESSAGES])).toEqual([
+ { role: 'user', content: 'hello' },
+ ]);
+ expect(JSON.parse(a[SemanticConvention.GEN_AI_OUTPUT_MESSAGES])).toEqual(response.messages);
+ expect(mockSpan.end).toHaveBeenCalledTimes(1);
+ });
+
+ it('wraps a streaming message response and records streaming attributes', async () => {
+ async function* stream() {
+ yield { message_type: 'assistant_message', content: 'Hel' };
+ yield { message_type: 'assistant_message', content: 'lo' };
+ yield {
+ message_type: 'usage_statistics',
+ prompt_tokens: 8,
+ completion_tokens: 2,
+ total_tokens: 10,
+ };
+ }
+
+ const proxy = await runOp('letta.create_stream', () => stream(), [
+ 'agent-1',
+ { messages: [{ role: 'user', content: 'hi' }] },
+ ]);
+
+ const seen: any[] = [];
+ for await (const chunk of proxy) {
+ seen.push(chunk);
+ }
+ await flush();
+
+ expect(seen).toHaveLength(3);
+ const a = attrs();
+ expect(a[SemanticConvention.GEN_AI_OPERATION]).toBe('chat');
+ expect(a[SemanticConvention.GEN_AI_STREAMING_CHUNK_COUNT]).toBe(3);
+ expect(a[SemanticConvention.GEN_AI_STREAMING_RESPONSE_COUNT]).toBe(3);
+ expect(a[SemanticConvention.GEN_AI_REQUEST_IS_STREAM]).toBe(true);
+ expect(a[SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS]).toBe(8);
+ expect(a[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS]).toBe(2);
+ expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: 1 });
+ expect(mockSpan.end).toHaveBeenCalledTimes(1);
+ });
+
+ it('names list operations workflow {method}', async () => {
+ await runOp('letta.list', async () => [{ id: 'b1' }, { id: 'b2' }], [{}]);
+
+ expect(mockTracer.startSpan).toHaveBeenCalledWith(
+ 'workflow list',
+ expect.objectContaining({ kind: SpanKind.CLIENT })
+ );
+ expect(attrs()[SemanticConvention.GEN_AI_OPERATION]).toBe('workflow');
+ });
+
+ it('names attach/detach operations tool {method} with execute_tool op', async () => {
+ await runOp('letta.attach', async () => ({ id: 'agent-1' }), ['tool-1', { agent_id: 'agent-1' }]);
+
+ expect(mockTracer.startSpan).toHaveBeenCalledWith(
+ 'tool attach',
+ expect.objectContaining({ kind: SpanKind.CLIENT })
+ );
+ expect(attrs()[SemanticConvention.GEN_AI_OPERATION]).toBe('execute_tool');
+ });
+
+ it('records the exception, ends the span, and rethrows on a chat error', async () => {
+ const boom = new Error('letta down');
+ const wrapped = LettaWrapper._patchOperation(mockTracer, 'letta.create_message', true)(async () => {
+ throw boom;
+ });
+
+ await expect(wrapped.apply({}, ['agent-1', { messages: [] }])).rejects.toThrow('letta down');
+
+ expect((OpenLitHelper as any).handleException).toHaveBeenCalledWith(mockSpan, boom);
+ expect(mockSpan.end).toHaveBeenCalledTimes(1);
+ expect(attrs()[SemanticConvention.GEN_AI_PROVIDER_NAME]).toBe('letta');
+ });
+
+ it('ends the stream span exactly once when the consumer breaks early', async () => {
+ async function* stream() {
+ yield { message_type: 'assistant_message', content: 'one' };
+ yield { message_type: 'assistant_message', content: 'two' };
+ }
+
+ const proxy = await runOp('letta.create_stream', () => stream(), [
+ 'agent-1',
+ { messages: [{ role: 'user', content: 'hi' }] },
+ ]);
+
+ for await (const _chunk of proxy) {
+ break;
+ }
+ await flush();
+
+ expect(mockSpan.end).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not treat a top-level resource id as an agent id', async () => {
+ await runOp('letta.retrieve', async () => ({ label: 'persona' }), ['block-id'], false);
+ expect(attrs()[SemanticConvention.GEN_AI_AGENT_ID]).not.toBe('block-id');
+ });
+
+ it('maps an agent update to the invoke_agent operation', async () => {
+ await runOp('letta.modify', async () => ({ id: 'agent-1' }), ['agent-1', { name: 'renamed' }]);
+ expect(attrs()[SemanticConvention.GEN_AI_OPERATION]).toBe('invoke_agent');
+ });
+
+ it('rejects and ends the span on a non-chat operation error', async () => {
+ const boom = new Error('list failed');
+ const wrapped = LettaWrapper._patchOperation(mockTracer, 'letta.list', false)(async () => {
+ throw boom;
+ });
+
+ await expect(wrapped.apply({}, [{}])).rejects.toThrow('list failed');
+ await flush();
+
+ expect((OpenLitHelper as any).handleException).toHaveBeenCalledWith(mockSpan, boom);
+ expect(mockSpan.end).toHaveBeenCalledTimes(1);
+ });
+
+ it('bypasses instrumentation when tracing is suppressed', async () => {
+ (isTracingSuppressed as jest.Mock).mockReturnValue(true);
+ const original = jest.fn().mockResolvedValue({ id: 'agent-1' });
+ const wrapped = LettaWrapper._patchOperation(mockTracer, 'letta.create', false)(original);
+
+ await wrapped.apply({}, [{ name: 'bot' }]);
+ expect(original).toHaveBeenCalled();
+ expect(mockTracer.startSpan).not.toHaveBeenCalled();
+ });
+});
+
+describe('LettaInstrumentation patch targets', () => {
+ // eslint-disable-next-line @typescript-eslint/no-var-requires
+ const { isWrapped } = require('@opentelemetry/instrumentation');
+
+ it('wraps resource-client prototype methods via manualPatch', () => {
+ class Agents {
+ async create() {
+ return null;
+ }
+ async retrieve() {
+ return null;
+ }
+ async update() {
+ return null;
+ }
+ async delete() {
+ return null;
+ }
+ async list() {
+ return null;
+ }
+ }
+ class Messages {
+ async create() {
+ return null;
+ }
+ async stream() {
+ return null;
+ }
+ async createAsync() {
+ return null;
+ }
+ async list() {
+ return null;
+ }
+ async cancel() {
+ return null;
+ }
+ async reset() {
+ return null;
+ }
+ }
+
+ const fakeModule = { Agents, Messages } as any;
+ const instrumentation = new LettaInstrumentation();
+ instrumentation.manualPatch(fakeModule);
+
+ for (const method of ['create', 'retrieve', 'update', 'delete', 'list']) {
+ expect(isWrapped(Agents.prototype[method as keyof typeof Agents.prototype])).toBe(true);
+ }
+ for (const method of ['create', 'stream', 'createAsync', 'list', 'cancel', 'reset']) {
+ expect(isWrapped(Messages.prototype[method as keyof typeof Messages.prototype])).toBe(true);
+ }
+
+ // Idempotent: a second patch must not throw or rewrap.
+ instrumentation.manualPatch(fakeModule);
+ expect(isWrapped(Agents.prototype.create)).toBe(true);
+ });
+});
diff --git a/sdk/typescript/src/instrumentation/index.ts b/sdk/typescript/src/instrumentation/index.ts
index a6116e10..fb8c3531 100644
--- a/sdk/typescript/src/instrumentation/index.ts
+++ b/sdk/typescript/src/instrumentation/index.ts
@@ -40,6 +40,7 @@ import AssemblyAIInstrumentation from './assemblyai';
import TransformersInstrumentation from './transformers';
import PgInstrumentation from './pg';
import FirecrawlInstrumentation from './firecrawl';
+import LettaInstrumentation from './letta';
/**
* OTel community instrumentations loaded dynamically (like Python SDK).
@@ -122,6 +123,7 @@ export default class Instrumentations {
transformers: new TransformersInstrumentation(),
pg: new PgInstrumentation(),
firecrawl: new FirecrawlInstrumentation(),
+ letta: new LettaInstrumentation(),
};
static setup(
diff --git a/sdk/typescript/src/instrumentation/letta/index.ts b/sdk/typescript/src/instrumentation/letta/index.ts
new file mode 100644
index 00000000..44b57d38
--- /dev/null
+++ b/sdk/typescript/src/instrumentation/letta/index.ts
@@ -0,0 +1,168 @@
+import {
+ InstrumentationBase,
+ InstrumentationConfig,
+ InstrumentationModuleDefinition,
+ InstrumentationNodeModuleDefinition,
+ InstrumentationNodeModuleFile,
+ isWrapped,
+} from '@opentelemetry/instrumentation';
+import { diag } from '@opentelemetry/api';
+import { INSTRUMENTATION_PREFIX } from '../../constant';
+import LettaWrapper from './wrapper';
+
+export interface LettaInstrumentationConfig extends InstrumentationConfig {}
+
+/**
+ * Each Letta resource class lives in its own internal module file. `className`
+ * is the export patched on that file; `methods` maps a JS method to the
+ * Python-style endpoint id that drives the operation type and span name.
+ *
+ * The Python reference keys the operation type on the method suffix, so the JS
+ * `update` methods map to `letta.modify` and `messages.create` maps to
+ * `letta.create_message` (Python's own disambiguated chat endpoint) so both SDKs
+ * emit identical telemetry for the same call.
+ */
+interface LettaModule {
+ file: string;
+ className: string;
+ methods: Array<[string, string]>;
+ agentScoped: boolean;
+}
+
+const AGENT_METHODS: Array<[string, string]> = [
+ ['create', 'letta.create'],
+ ['retrieve', 'letta.retrieve'],
+ ['update', 'letta.modify'],
+ ['delete', 'letta.delete'],
+ ['list', 'letta.list'],
+];
+
+const MESSAGE_METHODS: Array<[string, string]> = [
+ ['create', 'letta.create_message'],
+ ['stream', 'letta.create_stream'],
+ ['createAsync', 'letta.create_async'],
+ ['list', 'letta.list'],
+ ['cancel', 'letta.cancel'],
+ ['reset', 'letta.reset'],
+];
+
+const MEMORY_METHODS: Array<[string, string]> = [
+ ['create', 'letta.create'],
+ ['retrieve', 'letta.retrieve'],
+ ['update', 'letta.modify'],
+ ['delete', 'letta.delete'],
+ ['list', 'letta.list'],
+];
+
+const AGENT_BLOCK_METHODS: Array<[string, string]> = [
+ ['retrieve', 'letta.retrieve'],
+ ['update', 'letta.modify'],
+ ['list', 'letta.list'],
+ ['attach', 'letta.attach'],
+ ['detach', 'letta.detach'],
+];
+
+const AGENT_ATTACH_METHODS: Array<[string, string]> = [
+ ['list', 'letta.list'],
+ ['attach', 'letta.attach'],
+ ['detach', 'letta.detach'],
+];
+
+const PASSAGE_METHODS: Array<[string, string]> = [
+ ['create', 'letta.create'],
+ ['list', 'letta.list'],
+ ['delete', 'letta.delete'],
+];
+
+const LETTA_MODULES: LettaModule[] = [
+ { file: 'resources/agents/agents.js', className: 'Agents', methods: AGENT_METHODS, agentScoped: true },
+ { file: 'resources/agents/messages.js', className: 'Messages', methods: MESSAGE_METHODS, agentScoped: true },
+ { file: 'resources/blocks/blocks.js', className: 'Blocks', methods: MEMORY_METHODS, agentScoped: false },
+ { file: 'resources/agents/blocks.js', className: 'Blocks', methods: AGENT_BLOCK_METHODS, agentScoped: true },
+ { file: 'resources/tools.js', className: 'Tools', methods: MEMORY_METHODS, agentScoped: false },
+ { file: 'resources/agents/tools.js', className: 'Tools', methods: AGENT_ATTACH_METHODS, agentScoped: true },
+ { file: 'resources/folders/folders.js', className: 'Folders', methods: MEMORY_METHODS, agentScoped: false },
+ { file: 'resources/agents/folders.js', className: 'Folders', methods: AGENT_ATTACH_METHODS, agentScoped: true },
+ { file: 'resources/agents/passages.js', className: 'Passages', methods: PASSAGE_METHODS, agentScoped: true },
+];
+
+const PACKAGE = '@letta-ai/letta-client';
+const VERSIONS = ['>=0.1.0'];
+
+export default class OpenlitLettaInstrumentation extends InstrumentationBase {
+ constructor(config: LettaInstrumentationConfig = {}) {
+ super(`${INSTRUMENTATION_PREFIX}/instrumentation-letta`, '1.0.0', config);
+ }
+
+ protected init(): void | InstrumentationModuleDefinition | InstrumentationModuleDefinition[] {
+ // The Letta client exposes resource classes as nested objects (client.agents,
+ // client.agents.messages, ...), each defined in its own internal module file.
+ // require-in-the-middle reaches those files via the `files` array, so every
+ // resource class is registered as an InstrumentationNodeModuleFile.
+ const files = LETTA_MODULES.map(
+ (mod) =>
+ new InstrumentationNodeModuleFile(
+ `${PACKAGE}/${mod.file}`,
+ VERSIONS,
+ (moduleExports: any, moduleVersion?: string) => {
+ this._patchClass(moduleExports?.[mod.className], mod.methods, mod.agentScoped, moduleVersion);
+ return moduleExports;
+ },
+ (moduleExports: any) => {
+ if (moduleExports !== undefined) this._unpatchClass(moduleExports?.[mod.className], mod.methods);
+ }
+ )
+ );
+
+ const module = new InstrumentationNodeModuleDefinition(
+ PACKAGE,
+ VERSIONS,
+ (moduleExports: any) => moduleExports,
+ () => {},
+ files
+ );
+
+ return [module];
+ }
+
+ public manualPatch(letta: any): void {
+ // Fallback entry point. Best-effort: look each resource class up by name on the
+ // object passed in; the isWrapped guard in _patchClass keeps repeat calls safe.
+ for (const mod of LETTA_MODULES) {
+ this._patchClass(letta?.[mod.className], mod.methods, mod.agentScoped);
+ }
+ }
+
+ private _patchClass(
+ target: any,
+ methods: Array<[string, string]>,
+ agentScoped: boolean,
+ moduleVersion?: string
+ ): void {
+ try {
+ const proto = target?.prototype;
+ if (!proto) return;
+ for (const [method, endpoint] of methods) {
+ if (typeof proto[method] !== 'function') continue;
+ if (isWrapped(proto[method])) continue;
+ this._wrap(proto, method, LettaWrapper._patchOperation(this.tracer, endpoint, agentScoped, moduleVersion));
+ }
+ } catch (e) {
+ diag.error('letta instrumentation: error in _patch method', e);
+ }
+ }
+
+ private _unpatchClass(target: any, methods: Array<[string, string]>): void {
+ try {
+ const proto = target?.prototype;
+ if (!proto) return;
+ for (const [method] of methods) {
+ if (typeof proto[method] === 'function' && isWrapped(proto[method])) {
+ this._unwrap(proto, method);
+ }
+ }
+ } catch {
+ /* ignore */
+ }
+ }
+}
diff --git a/sdk/typescript/src/instrumentation/letta/utils.ts b/sdk/typescript/src/instrumentation/letta/utils.ts
new file mode 100644
index 00000000..550c9b40
--- /dev/null
+++ b/sdk/typescript/src/instrumentation/letta/utils.ts
@@ -0,0 +1,333 @@
+import { Span } from '@opentelemetry/api';
+import { ATTR_SERVICE_NAME, ATTR_TELEMETRY_SDK_NAME } from '@opentelemetry/semantic-conventions';
+import OpenlitConfig from '../../config';
+import { SDK_NAME } from '../../constant';
+import OpenLitHelper, { applyCustomSpanAttributes } from '../../helpers';
+import SemanticConvention from '../../semantic-convention';
+
+export const DEFAULT_MODEL = 'gpt-4o';
+export const DEFAULT_SERVER_ADDRESS = 'api.letta.com';
+export const DEFAULT_SERVER_PORT = 443;
+
+/**
+ * Operation type per Letta method name. Mirrors OPERATION_TYPE_MAP in the Python
+ * reference (sdk/python/src/openlit/instrumentation/letta/utils.py). The type is
+ * keyed on the method suffix so identical calls emit identical telemetry in both
+ * SDKs. Anything unmapped falls back to `workflow`.
+ */
+export const OPERATION_TYPE_MAP: Record<string, string> = {
+ create: SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,
+ retrieve: SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ modify: SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ delete: SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,
+ list: SemanticConvention.GEN_AI_OPERATION_TYPE_WORKFLOW,
+ create_stream: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ create_message: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ create_async: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ cancel: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ reset: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,
+ attach: SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
+ detach: SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,
+};
+
+export function getOperationType(endpoint: string): string {
+ const method = endpoint.split('.').pop() || 'unknown';
+ return OPERATION_TYPE_MAP[method] ?? SemanticConvention.GEN_AI_OPERATION_TYPE_WORKFLOW;
+}
+
+/** Resolve the model name from response / request in the same priority order as Python. */
+function resolveModel(response: any, body: any): string {
+ if (response?.llm_config?.model) return response.llm_config.model;
+ if (body?.model) return body.model;
+ return DEFAULT_MODEL;
+}
+
+/**
+ * Span name generation ported from Python's get_span_name. The span name is built
+ * before the call runs, so it uses only the request: chat spans follow the
+ * provider pattern `chat {model}`; agent spans use `{operation} {agent_name}`;
+ * workflow/tool spans use the method suffix.
+ */
+export function getSpanName(operationType: string, endpoint: string, instance?: any, body?: any): string {
+ const method = endpoint.split('.').pop() || 'unknown';
+
+ if (operationType === SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT) {
+ return `chat ${body?.model || DEFAULT_MODEL}`;
+ }
+
+ if (
+ operationType === SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT ||
+ operationType === SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT
+ ) {
+ let agentName = 'agent';
+ if (body?.name) agentName = body.name;
+ else if (body?.slug) agentName = body.slug;
+ else if (instance?.name) agentName = instance.name;
+ else if (instance?.slug) agentName = instance.slug;
+ else if (body?.agent_id) agentName = `agent-${String(body.agent_id).slice(0, 8)}`;
+
+ if (agentName && agentName !== 'agent') {
+ agentName = agentName.replace(/ /g, '_').replace(/-/g, '_').toLowerCase();
+ if (agentName.length > 20) agentName = agentName.slice(0, 20);
+ }
+ return `${operationType} ${agentName}`;
+ }
+
+ if (operationType === SemanticConvention.GEN_AI_OPERATION_TYPE_WORKFLOW) {
+ return `workflow ${method}`;
+ }
+
+ if (operationType === SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS) {
+ return `tool ${method}`;
+ }
+
+ return `${operationType} ${method}`;
+}
+
+function truncateContent(content: string): string {
+ const limit = OpenlitConfig.maxContentLength;
+ if (typeof limit === 'number' && limit > 0 && content.length > limit) {
+ return content.slice(0, limit);
+ }
+ return content;
+}
+
+function resolveServerInfo(instance: any): [string, number] {
+ let baseUrl: string | undefined;
+ if (instance) {
+ baseUrl =
+ instance._client?.baseURL ??
+ instance._client_wrapper?._base_url ??
+ instance._client?.base_url ??
+ instance.baseURL ??
+ instance.base_url ??
+ instance._base_url;
+ }
+ if (baseUrl) {
+ try {
+ const parsed = new URL(String(baseUrl));
+ if (parsed.hostname) {
+ const port = parsed.port
+ ? Number(parsed.port)
+ : parsed.protocol === 'https:'
+ ? 443
+ : 80;
+ return [parsed.hostname, port];
+ }
+ } catch {
+ /* ignore malformed base url */
+ }
+ }
+ return [DEFAULT_SERVER_ADDRESS, DEFAULT_SERVER_PORT];
+}
+
+function setLlmConfigAttributes(span: Span, llmConfig: any): void {
+ if (!llmConfig) return;
+ if (llmConfig.model) span.setAttribute(SemanticConvention.GEN_AI_REQUEST_MODEL, llmConfig.model);
+ if (llmConfig.provider_name) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_PROVIDER, llmConfig.provider_name);
+ }
+ if (llmConfig.model_endpoint) {
+ span.setAttribute(SemanticConvention.GEN_AI_ENDPOINT, llmConfig.model_endpoint);
+ }
+ if (llmConfig.temperature != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_TEMPERATURE, llmConfig.temperature);
+ }
+ if (llmConfig.max_tokens != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_MAX_TOKENS, llmConfig.max_tokens);
+ }
+ if (llmConfig.frequency_penalty != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_FREQUENCY_PENALTY, llmConfig.frequency_penalty);
+ }
+ if (llmConfig.context_window != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_CONTEXT_WINDOW, llmConfig.context_window);
+ }
+ if (llmConfig.enable_reasoner != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_ENABLE_REASONER, llmConfig.enable_reasoner);
+ }
+ if (llmConfig.reasoning_effort != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_REASONING_EFFORT, llmConfig.reasoning_effort);
+ }
+ if (llmConfig.max_reasoning_tokens != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_USAGE_REASONING_TOKENS, llmConfig.max_reasoning_tokens);
+ }
+ if (llmConfig.handle != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_MODEL_HANDLE, llmConfig.handle);
+ }
+}
+
+function setUsageAttributes(span: Span, usage: any): void {
+ if (!usage) return;
+ if (usage.prompt_tokens != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, usage.prompt_tokens);
+ }
+ if (usage.completion_tokens != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, usage.completion_tokens);
+ }
+ if (usage.total_tokens != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_USAGE_TOTAL_TOKENS, usage.total_tokens);
+ }
+ if (usage.step_count != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_AGENT_STEP_COUNT, usage.step_count);
+ }
+ if (usage.run_ids != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_RUN_ID, String(usage.run_ids));
+ }
+ if (usage.steps_messages != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_AGENT_STEP_MESSAGES, JSON.stringify(usage.steps_messages));
+ }
+}
+
+function setRequestAttributes(span: Span, body: any, operationType: string): void {
+ if (!body || typeof body !== 'object') return;
+ if (body.model != null) span.setAttribute(SemanticConvention.GEN_AI_REQUEST_MODEL, String(body.model));
+ if (body.temperature != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_TEMPERATURE, body.temperature);
+ }
+ if (body.max_tokens != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_MAX_TOKENS, body.max_tokens);
+ }
+ if (body.frequency_penalty != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_FREQUENCY_PENALTY, body.frequency_penalty);
+ }
+ if (body.stream != null) span.setAttribute(SemanticConvention.GEN_AI_REQUEST_IS_STREAM, body.stream);
+ else if (body.streaming != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_IS_STREAM, body.streaming);
+ }
+ if (body.run_async != null) span.setAttribute(SemanticConvention.GEN_AI_REQUEST_ASYNC, body.run_async);
+ if (body.return_message_sequence_no != null) {
+ span.setAttribute(
+ SemanticConvention.GEN_AI_REQUEST_RETURN_SEQUENCE_NO,
+ body.return_message_sequence_no
+ );
+ }
+ if (body.include_final_message != null) {
+ span.setAttribute(
+ SemanticConvention.GEN_AI_REQUEST_INCLUDE_FINAL_MESSAGE,
+ body.include_final_message
+ );
+ }
+ if (operationType === SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT && Array.isArray(body.messages)) {
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_MESSAGE_COUNT, body.messages.length);
+ }
+}
+
+function setLettaSpecificAttributes(
+ span: Span,
+ body: any,
+ response: any,
+ operationType: string,
+ agentId?: string
+): void {
+ let resolvedAgentId = agentId;
+ if (!resolvedAgentId && body?.agent_id) resolvedAgentId = String(body.agent_id);
+ else if (!resolvedAgentId && response?.id) resolvedAgentId = String(response.id);
+ if (resolvedAgentId) span.setAttribute(SemanticConvention.GEN_AI_AGENT_ID, resolvedAgentId);
+
+ if (response) {
+ if (response.name != null) span.setAttribute(SemanticConvention.GEN_AI_AGENT_NAME, String(response.name));
+ if (response.slug != null) span.setAttribute(SemanticConvention.GEN_AI_AGENT_SLUG, String(response.slug));
+ if (response.description != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_AGENT_DESCRIPTION, String(response.description));
+ }
+ if (response.agent_type != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_AGENT_TYPE, response.agent_type);
+ }
+ if (response.system != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_AGENT_INSTRUCTIONS, truncateContent(String(response.system)));
+ }
+ if (response.llm_config) setLlmConfigAttributes(span, response.llm_config);
+ if (operationType === SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT && response.usage) {
+ setUsageAttributes(span, response.usage);
+ }
+ }
+
+ setRequestAttributes(span, body, operationType);
+
+ if (body?.name != null) span.setAttribute(SemanticConvention.GEN_AI_AGENT_NAME, String(body.name));
+ if (body?.slug != null) span.setAttribute(SemanticConvention.GEN_AI_AGENT_SLUG, String(body.slug));
+}
+
+function serializeContent(value: any): string {
+ try {
+ return JSON.stringify(value);
+ } catch {
+ return String(value);
+ }
+}
+
+function setContentAttributes(span: Span, body: any, response: any): void {
+ if (body?.messages != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_INPUT_MESSAGES, serializeContent(body.messages));
+ }
+ if (response?.messages != null) {
+ span.setAttribute(SemanticConvention.GEN_AI_OUTPUT_MESSAGES, serializeContent(response.messages));
+ }
+}
+
+function calculateCost(span: Span, response: any, model: string): void {
+ const pricingInfo = OpenlitConfig.pricingInfo;
+ if (!pricingInfo || !response) return;
+
+ let usage = response.usage;
+ if (!usage && Array.isArray(response)) {
+ for (let i = response.length - 1; i >= 0; i -= 1) {
+ if (response[i]?.message_type === 'usage_statistics') {
+ usage = response[i];
+ break;
+ }
+ }
+ }
+ if (usage && usage.prompt_tokens != null && usage.completion_tokens != null) {
+ const actualModel = response.llm_config?.model || model;
+ const cost = OpenLitHelper.getChatModelCost(
+ actualModel,
+ pricingInfo,
+ usage.prompt_tokens,
+ usage.completion_tokens
+ );
+ span.setAttribute(SemanticConvention.GEN_AI_USAGE_COST, cost);
+ }
+}
+
+/**
+ * Sets the common framework + Letta-specific attributes on a span. Mirrors
+ * process_letta_response + common_framework_span_attributes in the Python reference.
+ */
+export function processLettaResponse(
+ span: Span,
+ response: any,
+ body: any,
+ operationType: string,
+ instance: any,
+ durationSeconds: number,
+ sdkVersion: string,
+ agentId?: string
+): void {
+ const model = resolveModel(response, body);
+ const [serverAddress, serverPort] = resolveServerInfo(instance);
+
+ span.setAttribute(ATTR_TELEMETRY_SDK_NAME, SDK_NAME);
+ span.setAttribute(SemanticConvention.GEN_AI_SDK_VERSION, sdkVersion);
+ span.setAttribute(SemanticConvention.GEN_AI_PROVIDER_NAME, SemanticConvention.GEN_AI_SYSTEM_LETTA);
+ span.setAttribute(SemanticConvention.GEN_AI_PROVIDER_NAME_OTEL, SemanticConvention.GEN_AI_SYSTEM_LETTA);
+ span.setAttribute(SemanticConvention.GEN_AI_OPERATION, operationType);
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_MODEL, model);
+ span.setAttribute(SemanticConvention.SERVER_ADDRESS, serverAddress);
+ span.setAttribute(SemanticConvention.SERVER_PORT, serverPort);
+ span.setAttribute(SemanticConvention.ATTR_DEPLOYMENT_ENVIRONMENT, OpenlitConfig.environment || '');
+ span.setAttribute(ATTR_SERVICE_NAME, OpenlitConfig.applicationName || '');
+ span.setAttribute(SemanticConvention.GEN_AI_CLIENT_OPERATION_DURATION, durationSeconds);
+
+ setLettaSpecificAttributes(span, body, response, operationType, agentId);
+
+ if (operationType === SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT && OpenlitConfig.captureMessageContent) {
+ setContentAttributes(span, body, response);
+ }
+
+ if (operationType === SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT) {
+ calculateCost(span, response, model);
+ }
+
+ applyCustomSpanAttributes(span);
+}
diff --git a/sdk/typescript/src/instrumentation/letta/wrapper.ts b/sdk/typescript/src/instrumentation/letta/wrapper.ts
new file mode 100644
index 00000000..af5caee4
--- /dev/null
+++ b/sdk/typescript/src/instrumentation/letta/wrapper.ts
@@ -0,0 +1,302 @@
+import { Span, SpanKind, SpanStatusCode, Tracer, context, trace } from '@opentelemetry/api';
+import { isTracingSuppressed } from '@opentelemetry/core';
+import OpenLitHelper from '../../helpers';
+import SemanticConvention from '../../semantic-convention';
+import { getOperationType, getSpanName, processLettaResponse } from './utils';
+
+let lettaSdkVersion = 'unknown';
+try {
+ // eslint-disable-next-line @typescript-eslint/no-var-requires
+ lettaSdkVersion = require('@letta-ai/letta-client/version').VERSION || 'unknown';
+} catch {
+ lettaSdkVersion = 'unknown';
+}
+
+/**
+ * Splits Letta method arguments into the request body and, for agent-scoped
+ * resources, the leading agent id. A leading string on a top-level resource is
+ * that resource's own id, so it is never treated as an agent id.
+ */
+function resolveArgs(args: any[], agentScoped: boolean): { body: any; agentId?: string } {
+ const agentId = agentScoped && typeof args[0] === 'string' ? args[0] : undefined;
+ const body = args.find((arg) => arg && typeof arg === 'object' && !Array.isArray(arg));
+ return { body, agentId };
+}
+
+function isAsyncIterable(value: any): boolean {
+ return value != null && typeof value[Symbol.asyncIterator] === 'function';
+}
+
+/**
+ * Instrumentation for the Letta agent platform (`@letta-ai/letta-client`). Each
+ * patched resource method becomes one CLIENT span whose name and operation type
+ * mirror the Python reference (sdk/python/src/openlit/instrumentation/letta): the
+ * method suffix drives the operation type via OPERATION_TYPE_MAP, and chat
+ * (message) operations stream their response through a traced async iterator.
+ */
+class LettaWrapper {
+ static aiSystem = SemanticConvention.GEN_AI_SYSTEM_LETTA;
+
+ /**
+ * Wraps a Letta resource method. `endpoint` is the Python-style endpoint id
+ * (e.g. `letta.create`, `letta.create_message`) that drives the operation type
+ * and span name.
+ */
+ static _patchOperation(
+ tracer: Tracer,
+ endpoint: string,
+ agentScoped: boolean,
+ version?: string
+ ): any {
+ const sdkVersion = version || lettaSdkVersion;
+ const operationType = getOperationType(endpoint);
+
+ return (originalMethod: (...args: any[]) => any) => {
+ return function (this: any, ...args: any[]) {
+ if (isTracingSuppressed(context.active())) {
+ return originalMethod.apply(this, args);
+ }
+
+ const { body, agentId } = resolveArgs(args, agentScoped);
+ const spanBody =
+ agentId && (!body || body.agent_id == null) ? { ...(body || {}), agent_id: agentId } : body;
+ const spanName = getSpanName(operationType, endpoint, this, spanBody);
+
+ const span = tracer.startSpan(spanName, {
+ kind: SpanKind.CLIENT,
+ attributes: {
+ [SemanticConvention.GEN_AI_OPERATION]: operationType,
+ [SemanticConvention.GEN_AI_PROVIDER_NAME_OTEL]: LettaWrapper.aiSystem,
+ },
+ });
+ const startTime = Date.now();
+
+ if (operationType === SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT) {
+ return LettaWrapper._handleChat(
+ originalMethod,
+ this,
+ args,
+ span,
+ startTime,
+ body,
+ operationType,
+ sdkVersion,
+ agentId
+ );
+ }
+
+ return LettaWrapper._handleOperation(
+ originalMethod,
+ this,
+ args,
+ span,
+ startTime,
+ body,
+ operationType,
+ sdkVersion,
+ agentId
+ );
+ };
+ };
+ }
+
+ /**
+ * Non-chat operations return the SDK's own promise untouched. `list` yields a
+ * PagePromise whose async iterator drives auto-pagination, so flattening it here
+ * would break paging; the span is finalized from a completion callback instead.
+ */
+ private static _handleOperation(
+ originalMethod: (...args: any[]) => any,
+ instance: any,
+ args: any[],
+ span: Span,
+ startTime: number,
+ body: any,
+ operationType: string,
+ sdkVersion: string,
+ agentId?: string
+ ): any {
+ return context.with(trace.setSpan(context.active(), span), () => {
+ let result: any;
+ try {
+ result = originalMethod.apply(instance, args);
+ } catch (e: any) {
+ LettaWrapper._finalizeError(span, e, body, operationType, instance, startTime, sdkVersion, agentId);
+ throw e;
+ }
+
+ Promise.resolve(result).then(
+ (response) => {
+ processLettaResponse(
+ span,
+ response,
+ body,
+ operationType,
+ instance,
+ (Date.now() - startTime) / 1000,
+ sdkVersion,
+ agentId
+ );
+ span.setStatus({ code: SpanStatusCode.OK });
+ span.end();
+ },
+ (e) => {
+ LettaWrapper._finalizeError(span, e, body, operationType, instance, startTime, sdkVersion, agentId);
+ }
+ );
+
+ return result;
+ });
+ }
+
+ /**
+ * Chat (message) operations may resolve to a streaming iterator. The resolved
+ * value is awaited so a stream can be wrapped in a traced async iterator; a
+ * non-streaming response is processed inline.
+ */
+ private static async _handleChat(
+ originalMethod: (...args: any[]) => any,
+ instance: any,
+ args: any[],
+ span: Span,
+ startTime: number,
+ body: any,
+ operationType: string,
+ sdkVersion: string,
+ agentId?: string
+ ): Promise<any> {
+ return context.with(trace.setSpan(context.active(), span), async () => {
+ try {
+ const resolved = await originalMethod.apply(instance, args);
+
+ if (isAsyncIterable(resolved)) {
+ return LettaWrapper._traceStream(
+ resolved,
+ span,
+ startTime,
+ body,
+ operationType,
+ instance,
+ sdkVersion,
+ agentId
+ );
+ }
+
+ processLettaResponse(
+ span,
+ resolved,
+ body,
+ operationType,
+ instance,
+ (Date.now() - startTime) / 1000,
+ sdkVersion,
+ agentId
+ );
+ span.setStatus({ code: SpanStatusCode.OK });
+ span.end();
+ return resolved;
+ } catch (e: any) {
+ LettaWrapper._finalizeError(span, e, body, operationType, instance, startTime, sdkVersion, agentId);
+ throw e;
+ }
+ });
+ }
+
+ /**
+ * Wraps a Letta message stream so chunks flow through untouched while the span
+ * accumulates chunk count, TTFT, and the collected messages. Mirrors
+ * TracedLettaStream in the Python reference.
+ */
+ private static _traceStream(
+ stream: any,
+ span: Span,
+ startTime: number,
+ body: any,
+ operationType: string,
+ instance: any,
+ sdkVersion: string,
+ agentId?: string
+ ): Promise<any> {
+ async function* traced() {
+ let chunkCount = 0;
+ let ttft = 0;
+ const messages: any[] = [];
+
+ try {
+ for await (const chunk of stream) {
+ chunkCount += 1;
+ if (chunkCount === 1) {
+ ttft = (Date.now() - startTime) / 1000;
+ }
+ messages.push(chunk);
+ if (span.isRecording()) {
+ span.setAttribute(SemanticConvention.GEN_AI_STREAMING_CHUNK_COUNT, chunkCount);
+ if (ttft > 0) span.setAttribute(SemanticConvention.GEN_AI_SERVER_TTFT, ttft);
+ }
+ yield chunk;
+ }
+
+ const synthetic: any = { messages };
+ for (const msg of messages) {
+ if (msg?.message_type === 'usage_statistics') {
+ synthetic.usage = msg;
+ break;
+ }
+ }
+
+ processLettaResponse(
+ span,
+ synthetic,
+ body,
+ operationType,
+ instance,
+ (Date.now() - startTime) / 1000,
+ sdkVersion,
+ agentId
+ );
+ span.setAttribute(SemanticConvention.GEN_AI_STREAMING_CHUNK_COUNT, chunkCount);
+ span.setAttribute(SemanticConvention.GEN_AI_SERVER_TTFT, ttft);
+ span.setAttribute(SemanticConvention.GEN_AI_REQUEST_IS_STREAM, true);
+ span.setAttribute(SemanticConvention.GEN_AI_STREAMING_RESPONSE_COUNT, messages.length);
+ span.setStatus({ code: SpanStatusCode.OK });
+ } catch (e: any) {
+ OpenLitHelper.handleException(span, e);
+ throw e;
+ } finally {
+ span.end();
+ }
+ }
+
+ return OpenLitHelper.createStreamProxy(stream, traced());
+ }
+
+ private static _finalizeError(
+ span: Span,
+ error: any,
+ body: any,
+ operationType: string,
+ instance: any,
+ startTime: number,
+ sdkVersion: string,
+ agentId?: string
+ ): void {
+ try {
+ processLettaResponse(
+ span,
+ undefined,
+ body,
+ operationType,
+ instance,
+ (Date.now() - startTime) / 1000,
+ sdkVersion,
+ agentId
+ );
+ } catch {
+ /* best-effort attributes on the error path */
+ }
+ OpenLitHelper.handleException(span, error);
+ span.end();
+ }
+}
+
+export default LettaWrapper;
diff --git a/sdk/typescript/src/semantic-convention.ts b/sdk/typescript/src/semantic-convention.ts
index cbacd6e9..6ef4ecd2 100644
--- a/sdk/typescript/src/semantic-convention.ts
+++ b/sdk/typescript/src/semantic-convention.ts
@@ -323,6 +323,31 @@ export default class SemanticConvention {
static GEN_AI_SYSTEM_MEM0 = 'mem0';
static GEN_AI_SYSTEM_BROWSER_USE = 'browser_use';
static GEN_AI_SYSTEM_FIRECRAWL = 'firecrawl';
+ static GEN_AI_SYSTEM_LETTA = 'letta';
+
+ // ----- Letta (agent platform) -----
+ // Operation type used for Letta list/memory/context workflow operations.
+ static GEN_AI_OPERATION_TYPE_WORKFLOW = 'workflow';
+
+ // Agent attributes (general, reusable)
+ static GEN_AI_AGENT_SLUG = 'gen_ai.agent.slug';
+ static GEN_AI_AGENT_INSTRUCTIONS = 'gen_ai.agent.instructions';
+ static GEN_AI_AGENT_STEP_MESSAGES = 'gen_ai.agent.step_messages';
+
+ // Model configuration attributes (general, reusable)
+ static GEN_AI_MODEL_HANDLE = 'gen_ai.model.handle';
+
+ // Additional request parameters (general, reusable across integrations)
+ static GEN_AI_REQUEST_CONTEXT_WINDOW = 'gen_ai.request.context_window';
+ static GEN_AI_REQUEST_ENABLE_REASONER = 'gen_ai.request.enable_reasoner';
+ static GEN_AI_REQUEST_ASYNC = 'gen_ai.request.async';
+ static GEN_AI_REQUEST_RETURN_SEQUENCE_NO = 'gen_ai.request.return_sequence_no';
+ static GEN_AI_REQUEST_INCLUDE_FINAL_MESSAGE = 'gen_ai.request.include_final_message';
+ static GEN_AI_REQUEST_MESSAGE_COUNT = 'gen_ai.request.message_count';
+
+ // Streaming attributes (general, reusable)
+ static GEN_AI_STREAMING_CHUNK_COUNT = 'gen_ai.streaming.chunk_count';
+ static GEN_AI_STREAMING_RESPONSE_COUNT = 'gen_ai.streaming.response_count';
// ----- MCP (Model Context Protocol) -----
// Operation types
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
index 39637cbb..3386a41f 100644
--- a/sdk/typescript/src/types.ts
+++ b/sdk/typescript/src/types.ts
@@ -3,7 +3,7 @@ import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import { metrics } from '@opentelemetry/api';
import type { Guard } from './guard/base';
-export type InstrumentationType = 'openai' | 'anthropic' | 'cohere' | 'groq' | 'mistral' | 'google-ai' | 'vertexai' | 'together' | 'ollama' | 'vllm' | 'vercel-ai' | 'langchain' | 'langgraph' | 'pinecone' | 'bedrock' | 'llamaindex' | 'huggingface' | 'replicate' | 'chroma' | 'qdrant' | 'milvus' | 'astra' | 'azure-ai-inference' | 'openai-agents' | 'strands' | 'google-adk' | 'claude-agent-sdk' | 'cursor-sdk' | 'ai21' | 'gradient' | 'browser-use' | 'mcp' | 'mem0' | 'elevenlabs' | 'assemblyai' | 'transformers' | 'pg' | 'firecrawl';
+export type InstrumentationType = 'openai' | 'anthropic' | 'cohere' | 'groq' | 'mistral' | 'google-ai' | 'vertexai' | 'together' | 'ollama' | 'vllm' | 'vercel-ai' | 'langchain' | 'langgraph' | 'pinecone' | 'bedrock' | 'llamaindex' | 'huggingface' | 'replicate' | 'chroma' | 'qdrant' | 'milvus' | 'astra' | 'azure-ai-inference' | 'openai-agents' | 'strands' | 'google-adk' | 'claude-agent-sdk' | 'cursor-sdk' | 'ai21' | 'gradient' | 'browser-use' | 'mcp' | 'mem0' | 'elevenlabs' | 'assemblyai' | 'transformers' | 'pg' | 'firecrawl' | 'letta';
export type OpenlitInstrumentations = Partial<Record<InstrumentationType, any>>;