@microsoft/teams.apps
Version:
<p> <a href="https://www.npmjs.com/package/@microsoft/teams.apps" target="_blank"> <img src="https://img.shields.io/npm/v/@microsoft/teams.apps/latest" /> </a> <a href="https://www.npmjs.com/package/@microsoft/teams.apps?activeTab=code
216 lines (215 loc) • 8.47 kB
TypeScript
import { type Activity, type AgenticIdentity } from '@microsoft/teams.api';
/**
* Values accepted by the Agent365 baggage bridge. `null`, `undefined`, blank
* strings, and non-finite numbers are ignored.
*/
export type Agent365BaggageValue = string | number | null | undefined;
/**
* Optional identity fields that carry personal data. Never populated unless the
* app opts into them by name; identifier-only fields are always populated.
*/
export type Agent365BaggageInclude = 'senderName' | 'senderEmail' | 'agentName' | 'agentEmail' | 'agentDescription';
/**
* Agent365-compatible baggage keys populated by the SDK. Exported so app code
* can read or extend the same shape when creating scopes with an OpenTelemetry distro.
*/
export declare const Agent365BaggageKeys: {
/**
* Microsoft 365 tenant identifier for the operation.
*/
readonly tenantId: "microsoft.tenant.id";
/**
* Teams conversation identifier used as the Agent365 conversation/session correlation id.
*/
readonly conversationId: "gen_ai.conversation.id";
/**
* Link or service URL associated with the Teams conversation item.
*/
readonly conversationItemLink: "microsoft.conversation.item.link";
/**
* Teams channel identifier, such as `msteams`.
*/
readonly channelName: "microsoft.channel.name";
/**
* Optional channel link supplied by the app when it has one.
*/
readonly channelLink: "microsoft.channel.link";
/**
* Agent or bot identifier. Agentic app instance id is preferred when present.
*/
readonly agentId: "gen_ai.agent.id";
/**
* Agent or bot display name. Only set when `include` contains `agentName`.
*/
readonly agentName: "gen_ai.agent.name";
/**
* Agent365 user identifier for the user-backed AgenticIdentity the operation acts as.
*/
readonly agenticUserId: "microsoft.agent.user.id";
/**
* Agent365 blueprint identifier backing the agentic app.
*/
readonly agentBlueprintId: "microsoft.a365.agent.blueprint.id";
/**
* Caller display name. Only set when `include` contains `senderName`.
*/
readonly userName: "user.name";
/**
* Logical operation source for downstream Agent365 telemetry correlation.
*/
readonly operationSource: "service.name";
/**
* Caller user identifier. Azure AD object id is preferred when present.
*/
readonly userId: "user.id";
/**
* Caller email address. Only set when `include` contains `senderEmail`.
*/
readonly userEmail: "user.email";
/**
* Agent description or role metadata. Only set when `include` contains `agentDescription`.
*/
readonly agentDescription: "gen_ai.agent.description";
/**
* Agent365 user email address. Only set when `include` contains `agentEmail`.
*/
readonly agenticUserEmail: "microsoft.agent.user.email";
};
/**
* A set of Agent365 baggage entries keyed by baggage key. Prefer
* {@link Agent365BaggageKeys}; arbitrary keys are allowed for values the SDK
* does not model.
*/
export type Agent365BaggageEntries = Readonly<Record<string, Agent365BaggageValue>>;
/**
* Configures how the SDK derives Agent365 baggage from Teams activities and
* sends. Supply once via `App` options; it applies to every flow the SDK owns.
*/
export interface IAgent365BaggageOptions {
/**
* Personal-data fields to include beyond the identifier-only defaults.
* Defaults to `[]`. Add literals such as `senderName` to opt into each field.
*/
readonly include?: readonly Agent365BaggageInclude[];
/**
* Sets the `service.name` baggage value identifying the logical source of the
* operation.
*/
readonly operationSource?: Agent365BaggageValue;
/**
* Sets `microsoft.channel.link`. The SDK does not synthesize this from inbound
* activity data.
*/
readonly channelLink?: Agent365BaggageValue;
/**
* Additional baggage entries merged in after SDK-derived values.
*/
readonly additionalBaggage?: Agent365BaggageEntries;
}
/**
* Runs `fn` with the supplied Agent365 baggage layered onto the active context.
* Supplied values win over existing baggage. Use in proactive flows to open an
* identity scope before creating the span it should describe.
*
* @param values the baggage entries to set. Blank and non-finite values are skipped.
* @param fn the function to run inside the scope. Its return value is passed through.
*/
export declare function withAgent365Baggage<T>(values: Agent365BaggageEntries, fn: () => T): T;
/**
* @internal
* Resolves the baggage entries an inbound activity contributes.
*/
export declare function agent365BaggageFromActivity(activity: Activity, options: IAgent365BaggageOptions): Agent365BaggageEntries;
/**
* Identity a proactive Agent365 telemetry scope runs as. Per-operation only;
* host-wide policy is bound by {@link createAgent365Scope}.
*/
export interface IAgent365Scope {
/**
* The agentic identity scope the operation runs under, typically from
* `App.getAgenticIdentity`. Omit for app-only work; the agent id then falls back
* to the opener's `agentId`.
*/
readonly agenticIdentity?: AgenticIdentity;
/**
* The conversation the operation targets, when it has one.
*/
readonly conversationId?: string;
/**
* The human the operation runs on behalf of, when there is one. The agentic
* user id belongs on `agenticIdentity`, not here.
*/
readonly userId?: string;
/**
* Display name of the human the operation runs on behalf of. Personal data:
* only populated when the opener's `include` lists `senderName`.
*/
readonly senderName?: string;
/**
* Email of the human the operation runs on behalf of. Personal data: only
* populated when the opener's `include` lists `senderEmail`.
*/
readonly senderEmail?: string;
/**
* Display name of the agent. Personal data: only populated when the opener's
* `include` lists `agentName`.
*/
readonly agentName?: string;
/**
* Email of the agentic user the operation acts as. Personal data: only
* populated when the opener's `include` lists `agentEmail`.
*/
readonly agentEmail?: string;
/**
* Description of the agent. Personal data: only populated when the opener's
* `include` lists `agentDescription`.
*/
readonly agentDescription?: string;
/**
* Extra baggage entries merged in last. These bypass the `include` gate, since
* the caller names each entry explicitly.
*/
readonly additionalBaggage?: Agent365BaggageEntries;
}
/**
* Host-wide defaults bound into a scope opener by {@link createAgent365Scope}:
* values an {@link IAgent365Scope} cannot know per call, plus the personal-data policy.
*/
export interface IAgent365ScopeOptions extends IAgent365BaggageOptions {
/**
* Sets `microsoft.conversation.item.link` for scopes that do not carry their
* own. Typically the API client's service URL.
*/
readonly serviceUrl?: Agent365BaggageValue;
/**
* Fallback `gen_ai.agent.id` used when a scope has no `agenticIdentity`. Typically
* the app's client id.
*/
readonly agentId?: Agent365BaggageValue;
/**
* Sets `microsoft.channel.name`. Proactive work has no inbound activity to
* derive this from.
*/
readonly channelName?: Agent365BaggageValue;
}
/**
* Opens an Agent365 telemetry scope for proactive work. Returned by
* {@link createAgent365Scope} with host-wide policy applied, so call sites
* supply identity only.
*/
export type Agent365ScopeOpener = <T>(scope: IAgent365Scope, fn: () => T) => T;
/**
* Builds a reusable {@link Agent365ScopeOpener} bound to one set of options.
* Pass the same options given to `App`'s `telemetry.agent365` so proactive
* baggage matches reactive baggage, and build one per host to share.
*
* ```ts
* const withScope = createAgent365Scope({ operationSource: 'nightly-digest' });
* await withScope({ agenticIdentity, conversationId }, () => runJob());
* ```
*
* @param options host-wide baggage defaults and personal-data policy. Pass
* `false` to disable the bridge, which returns an opener that runs `fn`
* without touching the ambient context.
*/
export declare function createAgent365Scope(options?: IAgent365ScopeOptions | false): Agent365ScopeOpener;