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.
Follow-up to #2199.
The implementation for #2199 is intentionally limited to
runs.waitandruns.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