Skip to content

Instrument LangGraph Platform background run submission and joining #2437

Description

@lforst

Follow-up to #2199.

The implementation for #2199 is intentionally limited to runs.wait and runs.stream: the caller starts execution and follows it through completion in the same call. Background execution was explicitly deferred.

Scope

Add Braintrust instrumentation for the background run workflow in @langchain/langgraph-sdk:

  • client.runs.create(threadId, assistantId, options): submit a background run.
  • client.runs.createBatch(payloads, options): submit background runs in a batch.
  • client.runs.join(threadId, runId, options): wait for an existing run.
  • client.runs.joinStream(threadId, runId, options): consume an existing run's output.

A run may be submitted in one process and joined in another. Define how the resulting observations correlate using the provider's run/thread identifiers; do not depend solely on in-memory state. A submission acknowledgement must not be represented as completion of the remote agent execution.

Note: runs.wait(threadId, assistantId, options) starts a new run and returns its final state. It is already in the parent implementation's scope; it is not the API for joining an existing run.

Acceptance criteria

  • Support automatic instrumentation and an explicit wrapper through shared typed channels, following the instrumentation specification.
  • Define submission, batch, join, and joined-stream span semantics, including what each span's lifetime measures and how separate processes correlate.
  • Capture useful inputs/results, errors, and allowlisted execution metadata without copying arbitrary configuration, headers, or credentials.
  • Preserve promise/iterator behavior, cancellation, and user-visible errors; prevent duplicate spans when wrapper and automatic instrumentation are combined.
  • Keep entity CRUD outside the instrumentation scope.
  • Add e2e tests using the real SDK for submission followed by joining from a separate process/client, batch submissions, joined streaming, errors, and cancellation.
  • Test pinned and separately named latest SDK aliases, ESM/CommonJS, and wrapped/automatic/combined/disabled modes. Assert paired span-tree snapshots, update the CI summary, and verify three consecutive replay runs.
  • Document the supported APIs and cross-process tracing behavior.

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions