Share via

BaggageBuilder class

Package:
@microsoft/agents-a365-observability

Per request baggage builder for OpenTelemetry context propagation.

This class provides a fluent API for setting baggage values that will be propagated in the OpenTelemetry context.

Example

const scope = new BaggageBuilder()
  .tenantId("tenant-123")
  .agentId("agent-456")
  .build();

scope.enter();
// Baggage is set in this context
// ... do work ...
scope.exit();
// Baggage is restored after exiting the context

Methods

agentAuid(undefined | null | string)

Set the agent AUID baggage value.
agentBlueprintId(undefined | null | string)

Set the agent blueprint ID baggage value.
agentDescription(undefined | null | string)

Set the agent description baggage value.
agentEmail(undefined | null | string)

Set the agent email baggage value.
agentId(undefined | null | string)

Set the agent ID baggage value.
agentName(undefined | null | string)

Set the agent name baggage value.
agentPlatformId(undefined | null | string)

Set the agent platform ID baggage value.
agentVersion(undefined | null | string)

Set the agent version baggage value.
build()

Apply the collected baggage to the current context.
callerAgentPlatformId(undefined | null | string)

Set the caller agent platform ID baggage value.
callerClientIp(undefined | null | string)

Set the caller client IP baggage value. Used to capture the originating client IP for the request so it can be propagated via OpenTelemetry baggage.
channelLink(undefined | null | string)

Set the channel link/URL.
channelName(undefined | null | string)

Set the channel name (e.g., Teams, Slack).
conversationId(undefined | null | string)

Set the conversation ID baggage value.
conversationItemLink(undefined | null | string)

Set the conversation item link baggage value.
invokeAgentServer(undefined | null | string, number)

Sets the invoke agent server address and port baggage values.
operationSource(undefined | null | string)

Set the operation source baggage value. Used for server spans to identify the service (e.g., ATG, ACF).
sessionDescription(undefined | null | string)

Set the session description baggage value.
sessionId(string)

Set the session ID baggage value.
setPairs(undefined | null | Record<string, any> | Iterable<[string, any]>)

Set multiple baggage pairs from a dictionary or iterable.
setRequestContext(null | string, null | string)

Convenience method to begin a request baggage scope with common fields.
tenantId(undefined | null | string)

Set the tenant ID baggage value.
userEmail(undefined | null | string)

Set the user email baggage value.
userId(undefined | null | string)

Set the user ID baggage value.
userName(undefined | null | string)

Set the user name baggage value.

Method Details

agentAuid(undefined | null | string)

Set the agent AUID baggage value.

function agentAuid(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The agent AUID

Returns

BaggageBuilder

Self for method chaining

agentBlueprintId(undefined | null | string)

Set the agent blueprint ID baggage value.

function agentBlueprintId(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The agent blueprint ID

Returns

BaggageBuilder

Self for method chaining

agentDescription(undefined | null | string)

Set the agent description baggage value.

function agentDescription(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The agent description

Returns

BaggageBuilder

Self for method chaining

agentEmail(undefined | null | string)

Set the agent email baggage value.

function agentEmail(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The agent email

Returns

BaggageBuilder

Self for method chaining

agentId(undefined | null | string)

Set the agent ID baggage value.

function agentId(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The agent ID

Returns

BaggageBuilder

Self for method chaining

agentName(undefined | null | string)

Set the agent name baggage value.

function agentName(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The agent name

Returns

BaggageBuilder

Self for method chaining

agentPlatformId(undefined | null | string)

Set the agent platform ID baggage value.

function agentPlatformId(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The agent platform ID

Returns

BaggageBuilder

Self for method chaining

agentVersion(undefined | null | string)

Set the agent version baggage value.

function agentVersion(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The agent version (e.g., '1.0.0', '2025-05-01')

Returns

BaggageBuilder

Self for method chaining

build()

Apply the collected baggage to the current context.

function build(): BaggageScope

Returns

BaggageScope

A context manager that restores the previous baggage on exit

callerAgentPlatformId(undefined | null | string)

Set the caller agent platform ID baggage value.

function callerAgentPlatformId(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The caller agent platform identifier

Returns

BaggageBuilder

Self for method chaining

callerClientIp(undefined | null | string)

Set the caller client IP baggage value. Used to capture the originating client IP for the request so it can be propagated via OpenTelemetry baggage.

function callerClientIp(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The caller client IP address

Returns

BaggageBuilder

Self for method chaining

Set the channel link/URL.

function channelLink(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The channel link

Returns

BaggageBuilder

Self for method chaining

channelName(undefined | null | string)

Set the channel name (e.g., Teams, Slack).

function channelName(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The channel name

Returns

BaggageBuilder

Self for method chaining

conversationId(undefined | null | string)

Set the conversation ID baggage value.

function conversationId(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The conversation ID

Returns

BaggageBuilder

Self for method chaining

Set the conversation item link baggage value.

function conversationItemLink(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The conversation item link

Returns

BaggageBuilder

Self for method chaining

invokeAgentServer(undefined | null | string, number)

Sets the invoke agent server address and port baggage values.

function invokeAgentServer(address: undefined | null | string, port?: number): BaggageBuilder

Parameters

address

undefined | null | string

The server address (hostname) of the target agent service.

port

number

Optional server port. Only recorded when different from 443.

Returns

BaggageBuilder

The current builder instance for method chaining.

operationSource(undefined | null | string)

Set the operation source baggage value. Used for server spans to identify the service (e.g., ATG, ACF).

function operationSource(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The operation source

Returns

BaggageBuilder

Self for method chaining

sessionDescription(undefined | null | string)

Set the session description baggage value.

function sessionDescription(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The session description

Returns

BaggageBuilder

Self for method chaining

sessionId(string)

Set the session ID baggage value.

function sessionId(value: string): BaggageBuilder

Parameters

value

string

The session ID

Returns

BaggageBuilder

Self for method chaining

setPairs(undefined | null | Record<string, any> | Iterable<[string, any]>)

Set multiple baggage pairs from a dictionary or iterable.

function setPairs(pairs: undefined | null | Record<string, any> | Iterable<[string, any]>): BaggageBuilder

Parameters

pairs

undefined | null | Record<string, any> | Iterable<[string, any]>

Dictionary or iterable of key-value pairs

Returns

BaggageBuilder

Self for method chaining

setRequestContext(null | string, null | string)

Convenience method to begin a request baggage scope with common fields.

static function setRequestContext(tenantId?: null | string, agentId?: null | string): BaggageScope

Parameters

tenantId

null | string

The tenant ID

agentId

null | string

The agent ID

Returns

BaggageScope

A context manager that restores the previous baggage on exit

tenantId(undefined | null | string)

Set the tenant ID baggage value.

function tenantId(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The tenant ID

Returns

BaggageBuilder

Self for method chaining

userEmail(undefined | null | string)

Set the user email baggage value.

function userEmail(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The user email

Returns

BaggageBuilder

Self for method chaining

userId(undefined | null | string)

Set the user ID baggage value.

function userId(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The user ID

Returns

BaggageBuilder

Self for method chaining

userName(undefined | null | string)

Set the user name baggage value.

function userName(value: undefined | null | string): BaggageBuilder

Parameters

value

undefined | null | string

The user name

Returns

BaggageBuilder

Self for method chaining