dd-trace 5.117.0 → 5.118.0

package/packages/datadog-plugin-openai-agents/src/integration.js

@@ -0,0 +1,503 @@
+'use strict'
+
+const { storage } = require('../../datadog-core')
+const { storage: llmobsStorage } = require('../../dd-trace/src/llmobs/storage')
+const LLMObsTagger = require('../../dd-trace/src/llmobs/tagger')
+const { getOpenAIModelProvider } = require('../../dd-trace/src/llmobs/plugins/openai/utils')
+const {
+  extractInputMessages,
+  extractOutputMessages,
+  extractGenerationOutputMessages,
+  extractMetrics,
+  extractMetadata,
+} = require('../../dd-trace/src/llmobs/plugins/openai-agents/utils')
+const { AGENTS_ERROR_TYPE, applyError, deriveSpanName } = require('./util')
+
+const COMPONENT = 'openai-agents'
+const DEFAULT_MODEL_PROVIDER = 'openai'
+const MODEL_BASE_URL_STORE_KEY = Symbol('openai-agents.model-base-url')
+const legacyStorage = storage('legacy')
+
+const KIND_TO_SPAN_KIND = {
+  agent: 'internal',
+  tool: 'internal',
+  task: 'internal',
+  llm: 'client',
+}
+
+/**
+ * @typedef {{
+ *   spanId: string,
+ *   traceId: string,
+ *   currentTopLevelAgentSpanId?: string,
+ *   currentTopLevelAgentName?: string,
+ *   inputOaiSpan?: object,
+ *   inputMessages?: Array<{ role: string, content: string }>,
+ *   outputOaiSpan?: object,
+ *   metadata?: Record<string, unknown>,
+ *   groupId?: string,
+ *   llmobsParentStore?: object,
+ * }} LLMObsTraceInfo
+ */
+
+/**
+ * Owns tracer/tagger refs, maps agents-core span ids → dd-trace spans, and
+ * reconstructs workflow-level input/output from the first and last response
+ * spans of the top-level agent.
+ */
+class OpenAIAgentsIntegration {
+  #tracer
+  #config
+  #enabled = false
+  #service
+  /**
+   * LLMObs is gated independently of APM tracing: when DD_LLMOBS_ENABLED is
+   * false we keep emitting APM spans for the agent workflow but skip all
+   * LLMObs tagging and the work that feeds it.
+   * @type {LLMObsTagger}
+   */
+  #tagger
+  /** @type {Map<string, import('../../dd-trace/src/opentracing/span')>} */
+  #oaiToDdSpan = new Map()
+  /** @type {Map<string, LLMObsTraceInfo>} */
+  #traceInfo = new Map()
+
+  constructor ({ tracer, config } = {}) {
+    this.#tracer = tracer
+    this.#config = config ?? { llmobs: {} }
+    this.#tagger = new LLMObsTagger(this.#config, true)
+  }
+
+  get enabled () {
+    return this.#enabled
+  }
+
+  /**
+   * Apply plugin lifecycle configuration.
+   *
+   * @param {{ enabled?: boolean, service?: string }} [config]
+   */
+  configure (config) {
+    this.#enabled = !!config?.enabled
+    this.#service = config?.service
+  }
+
+  /**
+   * @param {string} spanId agents-core spanId
+   * @returns {import('../../dd-trace/src/opentracing/span') | undefined}
+   */
+  getDDSpan (spanId) {
+    return this.#oaiToDdSpan.get(spanId)
+  }
+
+  /**
+   * Ensure a function span is available synchronously at Tool.invoke. Newer
+   * agents-core versions dispatch processor callbacks after an async exporter
+   * callback, which can otherwise happen after user tool code has started.
+   *
+   * @param {object} oaiSpan
+   * @returns {import('../../dd-trace/src/opentracing/span') | undefined}
+   */
+  getOrStartToolSpan (oaiSpan) {
+    if (!oaiSpan?.spanId) return
+    const existingSpan = this.#oaiToDdSpan.get(oaiSpan.spanId)
+    if (existingSpan) return existingSpan
+    this.startSpan(oaiSpan, 'tool')
+    return this.#oaiToDdSpan.get(oaiSpan.spanId)
+  }
+
+  clearState () {
+    // Finish any dd-trace spans still in-flight so we don't leak open traces
+    // when agents-core's TracingProcessor.shutdown() runs (e.g., process
+    // exiting mid-run).
+    for (const ddSpan of this.#oaiToDdSpan.values()) {
+      ddSpan.finish()
+    }
+    this.#oaiToDdSpan.clear()
+    this.#traceInfo.clear()
+  }
+
+  // ── Trace lifecycle ─────────────────────────────────────────────────────────
+
+  startTrace (oaiTrace) {
+    const traceId = oaiTrace.traceId
+    if (!traceId) return
+
+    const name = oaiTrace.name || 'Agent workflow'
+    const parentSpan = legacyStorage.getStore()?.span
+    const ddSpan = this.#tracer.startSpan(name, {
+      childOf: parentSpan,
+      tags: this.#getSpanTags('internal'),
+    })
+
+    const llmobsParentStore = this.#isLLMObsEnabled() ? llmobsStorage.getStore() : undefined
+    this.#oaiToDdSpan.set(traceId, ddSpan)
+    this.#traceInfo.set(traceId, {
+      spanId: ddSpan.context().toSpanId(),
+      traceId,
+      groupId: oaiTrace.groupId || undefined,
+      metadata: oaiTrace.metadata,
+      llmobsParentStore,
+    })
+
+    this.#tagger.registerLLMObsSpan(ddSpan, {
+      kind: 'workflow',
+      name,
+      integration: COMPONENT,
+      parent: llmobsParentStore?.span,
+      sessionId: oaiTrace.groupId || undefined,
+    })
+    if (LLMObsTagger.tagMap.has(ddSpan)) {
+      llmobsStorage.enterWith({ ...llmobsParentStore, span: ddSpan })
+    }
+  }
+
+  endTrace (oaiTrace) {
+    this.#completeWorkflowSpan(oaiTrace.traceId)
+  }
+
+  /**
+   * Finish the workflow dd-trace span and clear its bookkeeping. Used by both
+   * agents-core's normal `Trace.end()` path and the orphan-recovery path
+   * (when `withTrace` skips its end callback because the body threw). When
+   * `rootAgentSpan` is provided, its `error` field is reflected onto the
+   * workflow span before finishing.
+   *
+   * @param {string | undefined} traceId
+   * @param {object} [rootAgentSpan] - parentless oai-span that ended in error.
+   */
+  #completeWorkflowSpan (traceId, rootAgentSpan) {
+    if (!traceId) return
+    const ddSpan = this.#oaiToDdSpan.get(traceId)
+    if (!ddSpan) return
+    const info = this.#traceInfo.get(traceId)
+
+    if (rootAgentSpan?.error) {
+      ddSpan.setTag('error', true)
+      ddSpan.setTag('error.type', AGENTS_ERROR_TYPE)
+      if (rootAgentSpan.error.message) {
+        ddSpan.setTag('error.message', rootAgentSpan.error.message)
+      }
+    }
+
+    if (this.#isLLMObsEnabled()) this.#setTraceAttributes(ddSpan, traceId)
+    ddSpan.finish()
+    if (info && LLMObsTagger.tagMap.has(ddSpan)) {
+      llmobsStorage.enterWith(info.llmobsParentStore)
+    }
+    this.#oaiToDdSpan.delete(traceId)
+    this.#traceInfo.delete(traceId)
+  }
+
+  // ── Span lifecycle ──────────────────────────────────────────────────────────
+
+  startSpan (oaiSpan, llmobsKind) {
+    const spanId = oaiSpan.spanId
+    if (!spanId || this.#oaiToDdSpan.has(spanId)) return
+
+    const parentSpan = this.#resolveParent(oaiSpan)
+    const spanName = deriveSpanName(oaiSpan)
+
+    const ddSpan = this.#tracer.startSpan(spanName, {
+      childOf: parentSpan,
+      tags: this.#getSpanTags(KIND_TO_SPAN_KIND[llmobsKind] ?? 'internal'),
+    })
+
+    this.#oaiToDdSpan.set(spanId, ddSpan)
+
+    if (this.#isLLMObsEnabled()) {
+      const llmobsOptions = {
+        kind: llmobsKind,
+        name: spanName,
+        integration: COMPONENT,
+        parent: parentSpan,
+      }
+
+      if (oaiSpan.spanData?.type === 'response' || oaiSpan.spanData?.type === 'generation') {
+        // Model name only arrives with the response; tagged in
+        // `#setResponseAttributes` once known. Model provider is resolved from
+        // the agents-openai client's baseURL captured at getResponse time.
+        llmobsOptions.modelProvider = this.#getCurrentModelProvider()
+      }
+
+      this.#tagger.registerLLMObsSpan(ddSpan, llmobsOptions)
+      this.#updateTraceInfoInput(oaiSpan, spanName)
+    }
+  }
+
+  endSpan (oaiSpan) {
+    const spanId = oaiSpan.spanId
+    const ddSpan = this.#oaiToDdSpan.get(spanId)
+    if (!ddSpan) return
+
+    applyError(ddSpan, oaiSpan)
+
+    if (oaiSpan.spanData?.type === 'handoff') {
+      const spanName = deriveSpanName(oaiSpan)
+      ddSpan.setOperationName(spanName)
+      if (this.#isLLMObsEnabled()) this.#tagger.setName(ddSpan, spanName)
+    }
+
+    if (this.#isLLMObsEnabled()) {
+      const spanData = oaiSpan.spanData
+      switch (spanData?.type) {
+        case 'response':
+          this.#setResponseAttributes(ddSpan, oaiSpan)
+          this.#updateTraceInfoOutput(oaiSpan)
+          break
+        case 'generation':
+          this.#setGenerationAttributes(ddSpan, oaiSpan)
+          this.#updateTraceInfoOutput(oaiSpan)
+          break
+        case 'function':
+          this.#tagger.tagTextIO(ddSpan, spanData.input ?? '', spanData.output ?? '')
+          break
+        case 'handoff':
+          this.#tagger.tagTextIO(ddSpan, spanData.from_agent ?? '', spanData.to_agent ?? '')
+          break
+        case 'agent':
+          this.#setAgentAttributes(ddSpan, oaiSpan)
+          break
+        case 'custom':
+          if (spanData.data && typeof spanData.data === 'object') {
+            this.#tagger.tagMetadata(ddSpan, spanData.data)
+          }
+          break
+      }
+    }
+
+    ddSpan.finish()
+    // agents-core's withTrace skips Trace.end() when its callback throws, so an
+    // errored parentless span is our last chance to finalize the workflow.
+    if (oaiSpan.parentId == null && oaiSpan.error) {
+      this.#completeWorkflowSpan(oaiSpan.traceId, oaiSpan)
+    }
+    this.#oaiToDdSpan.delete(spanId)
+  }
+
+  // ── Per-type attribute setters ──────────────────────────────────────────────
+
+  #setResponseAttributes (ddSpan, oaiSpan) {
+    const response = oaiSpan.spanData?._response
+    const input = oaiSpan.spanData?._input
+    if (response?.model) {
+      this.#tagger.tagModelName(ddSpan, response.model)
+    }
+
+    // Override the LLMObs span name to `{parent_agent_name} (LLM)` only when
+    // the response is a direct child of the top-level agent (Python parity:
+    // see `_llmobs_set_response_attributes` in dd-trace-py). For bare
+    // `withResponseSpan` calls outside a `Runner.run()` flow the default
+    // name (`openai_agents.response`) stays.
+    const parentAgentName = this.#llmSpanParentAgentName(oaiSpan)
+    if (parentAgentName) {
+      this.#tagger.setName(ddSpan, `${parentAgentName} (LLM)`)
+    }
+
+    // Always tag LLM I/O so the LLMObs event shape is consistent across
+    // happy/error paths. The extract* helpers emit placeholder messages
+    // when their source is absent.
+    const inputMessages = extractInputMessages(input, response?.instructions)
+    this.#tagger.tagLLMIO(ddSpan, inputMessages, extractOutputMessages(response))
+
+    // Cache messages for the workflow span's trace-level input (Python
+    // parity: last message of the first response under the top-level agent).
+    // Avoids re-running extractInputMessages in #setTraceAttributes.
+    const info = this.#traceInfo.get(oaiSpan.traceId)
+    if (info && info.inputOaiSpan === oaiSpan) {
+      info.inputMessages = inputMessages
+    }
+
+    if (response) {
+      const metrics = extractMetrics(response)
+      if (metrics) this.#tagger.tagMetrics(ddSpan, metrics)
+
+      const metadata = extractMetadata(response)
+      if (metadata) this.#tagger.tagMetadata(ddSpan, metadata)
+    }
+  }
+
+  /**
+   * Tag a Chat Completions generation span from agents-core's public span data.
+   *
+   * @param {import('../../dd-trace/src/opentracing/span')} ddSpan
+   * @param {object} oaiSpan
+   */
+  #setGenerationAttributes (ddSpan, oaiSpan) {
+    const spanData = oaiSpan.spanData
+    if (spanData?.model) {
+      this.#tagger.tagModelName(ddSpan, spanData.model)
+    }
+
+    const parentAgentName = this.#llmSpanParentAgentName(oaiSpan)
+    if (parentAgentName) {
+      this.#tagger.setName(ddSpan, `${parentAgentName} (LLM)`)
+    }
+
+    const inputMessages = extractInputMessages(spanData?.input)
+    this.#tagger.tagLLMIO(ddSpan, inputMessages, extractGenerationOutputMessages(spanData?.output))
+
+    const info = this.#traceInfo.get(oaiSpan.traceId)
+    if (info && info.inputOaiSpan === oaiSpan) {
+      info.inputMessages = inputMessages
+    }
+
+    const metrics = extractMetrics({
+      usage: spanData?.usage ?? spanData?.output?.at(-1)?.usage,
+    })
+    if (metrics) this.#tagger.tagMetrics(ddSpan, metrics)
+    if (spanData?.model_config) this.#tagger.tagMetadata(ddSpan, spanData.model_config)
+  }
+
+  /**
+   * If this response span's parent is the top-level agent span of the trace,
+   * return that agent's dd-trace span name. Used to set the LLMObs span name
+   * to `${agentName} (LLM)` (Python parity).
+   *
+   * @param {object} oaiSpan
+   * @returns {string | undefined}
+   */
+  #llmSpanParentAgentName (oaiSpan) {
+    const traceInfo = this.#traceInfo.get(oaiSpan.traceId)
+    if (!traceInfo?.currentTopLevelAgentSpanId) return
+    if (oaiSpan.parentId !== traceInfo.currentTopLevelAgentSpanId) return
+    return traceInfo.currentTopLevelAgentName
+  }
+
+  #setAgentAttributes (ddSpan, oaiSpan) {
+    const spanData = oaiSpan.spanData
+    let metadata
+    if (Array.isArray(spanData?.handoffs) && spanData.handoffs.length > 0) {
+      metadata = { handoffs: spanData.handoffs }
+    }
+    if (Array.isArray(spanData?.tools) && spanData.tools.length > 0) {
+      metadata ??= {}
+      metadata.tools = spanData.tools
+    }
+    if (spanData?.output_type) {
+      metadata ??= {}
+      metadata.output_type = spanData.output_type
+    }
+    if (metadata) this.#tagger.tagMetadata(ddSpan, metadata)
+  }
+
+  #setTraceAttributes (ddSpan, traceId) {
+    const info = this.#traceInfo.get(traceId)
+    if (!info) return
+
+    // Workflow-level input is the last input message of the first response
+    // span under the top-level agent; output is `response.output_text` of
+    // the last response span. Matches dd-trace-py's
+    // `OaiSpanAdapter.llmobs_trace_input` / `response_output_text`. The
+    // input messages were cached during #setResponseAttributes.
+    const lastInputMessage = info.inputMessages?.at(-1)
+    const inputValue = typeof lastInputMessage?.content === 'string' ? lastInputMessage.content : ''
+    const outputSpanData = info.outputOaiSpan?.spanData
+    let outputValue = outputSpanData?._response?.output_text ?? ''
+    if (outputSpanData?.type === 'generation') {
+      const outputMessages = extractGenerationOutputMessages(outputSpanData.output)
+      outputValue = outputMessages.at(-1)?.content ?? ''
+    }
+
+    this.#tagger.tagTextIO(ddSpan, inputValue, outputValue)
+
+    if (info.metadata && Object.keys(info.metadata).length > 0) {
+      this.#tagger.tagMetadata(ddSpan, info.metadata)
+    }
+  }
+
+  // ── Trace-info reconstruction (Python parity) ───────────────────────────────
+
+  #updateTraceInfoInput (oaiSpan, spanName) {
+    const info = this.#traceInfo.get(oaiSpan.traceId)
+    if (!info) return
+
+    const parentId = oaiSpan.parentId
+    const type = oaiSpan.spanData?.type
+
+    // Identify the first top-level agent span under the root trace and
+    // stash its display name so `${agentName} (LLM)` doesn't have to read
+    // the dd-trace span context's private fields later.
+    if (type === 'agent' && parentId == null) {
+      info.currentTopLevelAgentSpanId = oaiSpan.spanId
+      info.currentTopLevelAgentName = spanName
+    }
+
+    // Capture the first response span whose parent is the top-level agent
+    // as the workflow-level input source.
+    if (
+      (type === 'response' || type === 'generation') &&
+      parentId &&
+      !info.inputOaiSpan &&
+      parentId === info.currentTopLevelAgentSpanId
+    ) {
+      info.inputOaiSpan = oaiSpan
+    }
+  }
+
+  #updateTraceInfoOutput (oaiSpan) {
+    const info = this.#traceInfo.get(oaiSpan.traceId)
+    if (!info) return
+
+    if (
+      oaiSpan.parentId &&
+      info.currentTopLevelAgentSpanId &&
+      oaiSpan.parentId === info.currentTopLevelAgentSpanId
+    ) {
+      info.outputOaiSpan = oaiSpan
+    }
+  }
+
+  // ── Helpers ─────────────────────────────────────────────────────────────────
+
+  #resolveParent (oaiSpan) {
+    const parentId = oaiSpan.parentId
+    const traceId = oaiSpan.traceId
+    if (parentId) {
+      const parent = this.#oaiToDdSpan.get(parentId)
+      if (parent) return parent
+    }
+    if (traceId) {
+      const root = this.#oaiToDdSpan.get(traceId)
+      if (root) return root
+    }
+  }
+
+  /**
+   * Read the mutable tracer configuration so remote/runtime enablement is
+   * reflected without reconstructing the plugin.
+   *
+   * @returns {boolean}
+   */
+  #isLLMObsEnabled () {
+    return !!this.#config.llmobs?.DD_LLMOBS_ENABLED
+  }
+
+  /**
+   * Resolve model provider from the model invocation's async-local context.
+   *
+   * @returns {string}
+   */
+  #getCurrentModelProvider () {
+    const baseURL = legacyStorage.getStore()?.[MODEL_BASE_URL_STORE_KEY]
+    return baseURL ? getOpenAIModelProvider(baseURL) : DEFAULT_MODEL_PROVIDER
+  }
+
+  /**
+   * Build common APM tags without overriding the tracer's global service when
+   * the integration has no explicit service configuration.
+   *
+   * @param {string} spanKind
+   * @returns {Record<string, string>}
+   */
+  #getSpanTags (spanKind) {
+    const tags = {
+      component: COMPONENT,
+      'span.kind': spanKind,
+    }
+    if (this.#service) tags.service = this.#service
+    return tags
+  }
+}
+
+module.exports = { MODEL_BASE_URL_STORE_KEY, OpenAIAgentsIntegration }

package/packages/datadog-plugin-openai-agents/src/processor.js

@@ -0,0 +1,108 @@
+'use strict'
+
+const log = require('../../dd-trace/src/log')
+
+const SPAN_KIND_BY_TYPE = {
+  agent: 'agent',
+  function: 'tool',
+  handoff: 'tool',
+  guardrail: 'task',
+  custom: 'task',
+  generation: 'llm',
+  response: 'llm',
+}
+
+// Lifecycle methods are awaited by agents-core. Share one resolved Promise
+// across every callback so we don't allocate per span event.
+const RESOLVED = Promise.resolve()
+
+/**
+ * dd-trace-js implementation of the agents-core `TracingProcessor` interface.
+ * Registered via `addTraceProcessor(new DDOpenAIAgentsProcessor(integration))` inside
+ * the `@openai/agents` module load hook. Mirrors Python's LLMObsTraceProcessor.
+ *
+ * Each agents-core Span / Trace lifecycle event turns into a dd-trace span
+ * (APM + LLMObs-annotated) keyed off the agents-core spanId / traceId. Parent
+ * hierarchy is resolved through the agents-core parentId chain, which gives us
+ * correct multi-agent handoff nesting that ctx-argument capture cannot provide.
+ *
+ * agents-core awaits the lifecycle methods, so each one returns a settled
+ * Promise even though the work is synchronous.
+ */
+class DDOpenAIAgentsProcessor {
+  /**
+   * @param {() => (import('./integration').OpenAIAgentsIntegration | undefined)} getIntegration - Lazy accessor for the
+   *   current OpenAIAgentsIntegration singleton. Read on each lifecycle event
+   *   so re-instantiating the plugin doesn't strand the processor against an
+   *   old integration reference inside agents-core.
+   */
+  constructor (getIntegration) {
+    this._getIntegration = getIntegration
+  }
+
+  onTraceStart (oaiTrace) {
+    const integration = this._getIntegration()
+    if (!integration?.enabled) return RESOLVED
+    try {
+      integration.startTrace(oaiTrace)
+    } catch (err) {
+      log.warn('[openai-agents] onTraceStart failed: %s', err)
+    }
+    return RESOLVED
+  }
+
+  onTraceEnd (oaiTrace) {
+    const integration = this._getIntegration()
+    if (!integration?.enabled) return RESOLVED
+    try {
+      integration.endTrace(oaiTrace)
+    } catch (err) {
+      log.warn('[openai-agents] onTraceEnd failed: %s', err)
+    }
+    return RESOLVED
+  }
+
+  onSpanStart (oaiSpan) {
+    const integration = this._getIntegration()
+    if (!integration?.enabled) return RESOLVED
+    if (!oaiSpan?.spanData) return RESOLVED // guard NoopSpan
+    const kind = SPAN_KIND_BY_TYPE[oaiSpan.spanData.type]
+    if (!kind) return RESOLVED // span types without an LLMObs kind are not traced
+    try {
+      integration.startSpan(oaiSpan, kind)
+    } catch (err) {
+      log.warn('[openai-agents] onSpanStart failed: %s', err)
+    }
+    return RESOLVED
+  }
+
+  onSpanEnd (oaiSpan) {
+    const integration = this._getIntegration()
+    if (!integration?.enabled) return RESOLVED
+    if (!oaiSpan?.spanData) return RESOLVED
+    try {
+      integration.endSpan(oaiSpan)
+    } catch (err) {
+      log.warn('[openai-agents] onSpanEnd failed: %s', err)
+    }
+    return RESOLVED
+  }
+
+  forceFlush () {
+    // dd-trace exports on its own schedule; nothing to force here.
+    return RESOLVED
+  }
+
+  shutdown () {
+    const integration = this._getIntegration()
+    if (!integration) return RESOLVED
+    try {
+      integration.clearState()
+    } catch (err) {
+      log.warn('[openai-agents] shutdown cleanup failed: %s', err)
+    }
+    return RESOLVED
+  }
+}
+
+module.exports = { DDOpenAIAgentsProcessor }

package/packages/datadog-plugin-openai-agents/src/util.js

@@ -0,0 +1,60 @@
+'use strict'
+
+// agents-core's `error` is a plain `{ message, data }` object, not a JS Error
+// — there's no constructor to name and no stack. We tag a stable type constant
+// and stringify `data` into the message so the LLMObs error shape stays
+// consistent with other integrations.
+const AGENTS_ERROR_TYPE = 'AgentsCoreError'
+
+/**
+ * Build the dd-trace span name from an agents-core oai-span. Handoffs collapse
+ * the target agent name into snake_case under a `transfer_to_` prefix; other
+ * span types use the SDK-provided name, falling back to
+ * `openai_agents.<type>` (or `openai_agents.request` when even the type is
+ * missing).
+ *
+ * @param {object} oaiSpan
+ * @returns {string}
+ */
+function deriveSpanName (oaiSpan) {
+  const spanData = oaiSpan.spanData
+  if (spanData?.type === 'handoff') {
+    const toAgent = spanData.to_agent || ''
+    if (toAgent) return `transfer_to_${toAgent.replaceAll(' ', '_').toLowerCase()}`
+  }
+  if (spanData?.name) return spanData.name
+  return spanData?.type ? `openai_agents.${spanData.type}` : 'openai_agents.request'
+}
+
+/**
+ * Apply agents-core's error shape onto a dd-trace span. No-op when the
+ * oai-span has no error attached.
+ *
+ * @param {object} ddSpan
+ * @param {object} oaiSpan
+ */
+function applyError (ddSpan, oaiSpan) {
+  const err = oaiSpan.error
+  if (!err) return
+
+  ddSpan.setTag('error', true)
+
+  let errorMessage = err.message || 'Error'
+  if (err.data) {
+    try {
+      errorMessage = JSON.stringify(err.data)
+    } catch {
+      // circular / non-serializable — fall back to the raw message
+    }
+  }
+
+  ddSpan.setTag('error.type', AGENTS_ERROR_TYPE)
+  ddSpan.setTag('error.message', errorMessage)
+  ddSpan.setTag('error.stack', err.stack || '')
+}
+
+module.exports = {
+  AGENTS_ERROR_TYPE,
+  deriveSpanName,
+  applyError,
+}