Skip to content

feat: trace Letta Agent SDK sessions - #2616

Draft
KarthikS (karthiksenv) wants to merge 2 commits into
braintrustdata:mainfrom
karthiksenv:codex/letta-agent-sdk-instrumentation
Draft

KarthikS (karthiksenv) wants to merge 2 commits into
braintrustdata:mainfrom
karthiksenv:codex/letta-agent-sdk-instrumentation

Conversation

@karthiksenv

Copy link
Copy Markdown

Fixes #2577.

Adds automatic instrumentation for @letta-ai/letta-agent-sdk >=0.8.28 <0.9.0 through the standard transformer, channels, and plugin. Both the main and client entrypoints are covered. Agent creation and session resumption produce spans; a turn stays open from send() through the terminal stream() result, with tool child spans and error/cancellation handling. sendAndWaitForResult() is captured through the same path.

Also exports wrapLettaAgentSDK for manual module/client/session wrapping, preserves SDK return values and stream identity, prevents duplicate spans when combined with automatic instrumentation, and supports the integration opt-out. Client credentials and inline base64 image bytes are excluded from the logged configuration/input.

Validation on Node 24.18.0 with pnpm 10.33.0:

  • Reproduced missing spans using the published SDK before registration: 12 failing contract tests. With the fix, the targeted plugin/registry/provenance suite passes all 174 tests.
  • All 23 Letta contract tests pass against pinned 0.8.28 and separately against published 0.8.39, including both package entrypoints, queued/concurrent turns, errors, cancellation, and manual/automatic deduplication.
  • Built-package Node loader-hook smoke checks pass: two expected spans when enabled, zero with BRAINTRUST_DISABLE_INSTRUMENTATION=letta.
  • SDK build, production/test TypeScript checks, frozen-lockfile validation, formatting, changeset validation, and git diff --check pass. ESLint reports zero errors and 13 type-assertion warnings.

This is a draft pending real-provider e2e coverage. LETTA_API_KEY was unavailable, so provider cassette recording and replay remain unverified. The contract tests run the actual published SDK with stubbed runtime transport; they are not provider e2e tests, and no provider recordings were fabricated.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[bot] Instrument Letta Agent SDK (143,425 weekly downloads)

1 participant