@cuylabs/agent-a365-observability 4.7.0 → 4.8.0

package/README.md

@@ -179,11 +179,11 @@ resolution, `context/` owns baggage and TurnContext mapping, `runtime/` owns
 Microsoft SDK startup and lazy loading, and `tracing/` owns the agent-core
 tracing config adapter.
 
-Use agent-core for portable OpenTelemetry spans:
+Use agent-core and AI SDK v7 for portable OpenTelemetry spans:
 
 - `invoke_agent` agent spans
-- `execute_tool` tool spans
-- AI SDK model spans nested under the agent turn
+- AI SDK `chat` model spans nested under the agent turn
+- AI SDK `execute_tool` tool spans when tools run
 
 Use this package for Agent 365-specific context on those spans:
 
@@ -212,7 +212,7 @@ See [docs/agent-core-otel.md](./docs/agent-core-otel.md) for details.
 
 Phoenix is a normal OTLP destination. You pass a span processor/exporter into `agent-core` tracing, and `agent-core` owns the tracer provider lifecycle for that example.
 
-Agent 365 is different. The Microsoft SDK owns the exporter and adds an Agent 365 span processor that copies baggage into span attributes. `agent-core` still emits the agent, tool, and AI SDK spans, while this package starts the Microsoft exporter and wraps each request with the tenant, agent, conversation, channel, and caller baggage that Agent 365 expects.
+Agent 365 is different. The Microsoft SDK owns the exporter and adds an Agent 365 span processor that copies baggage into span attributes. `agent-core` still emits the agent and AI SDK spans, while this package starts the Microsoft exporter and wraps each request with the tenant, agent, conversation, channel, and caller baggage that Agent 365 expects.
 
 ## AI SDK Telemetry
 
@@ -220,6 +220,8 @@ Agent 365 is different. The Microsoft SDK owns the exporter and adds an Agent 36
 
 This package does not replace that model telemetry. It adds the Microsoft Agent 365 layer: exporter startup, token resolution, and baggage that flows `microsoft.tenant.id`, `gen_ai.agent.id`, conversation, channel, and caller identity onto the spans.
 
+`createA365TracingConfig()` defaults `emitToolSpans` to `false`. AI SDK v7 already emits `execute_tool` spans with the Agent 365 GenAI tool keys, including `gen_ai.tool.name`, `gen_ai.tool.call.id`, `gen_ai.tool.call.arguments`, and `gen_ai.tool.call.result` when content recording is enabled. Disabling agent-core's extra tool-span layer avoids duplicate `execute_tool` spans for one tool call while preserving model and tool observability from the AI SDK integration.
+
 If you need to plug in another AI SDK telemetry integration, pass it through `createA365TracingConfig()`:
 
 ```typescript
@@ -235,6 +237,8 @@ const agent = createAgent({
 
 Set `useGenAIOpenTelemetry: false` only when you intentionally want to use global AI SDK telemetry integrations or another model-span integration.
 
+Set `emitToolSpans: true` only when your agent execution path does not use AI SDK v7 tool telemetry and you need agent-core to emit tool spans itself.
+
 ## TurnContext Mapping
 
 `runWithA365TurnContext(...)` follows Microsoft's

package/dist/index.d.ts

@@ -126,6 +126,26 @@ type A365TracingConfigOptions = {
     agentId?: string;
     agentDescription?: string;
     agentVersion?: string;
+    /**
+     * Whether to record prompts/tool arguments in GenAI spans.
+     *
+     * Defaults to agent-core's tracing default.
+     */
+    recordInputs?: boolean;
+    /**
+     * Whether to record responses/tool results in GenAI spans.
+     *
+     * Defaults to agent-core's tracing default.
+     */
+    recordOutputs?: boolean;
+    /**
+     * Whether agent-core should emit its own `execute_tool` spans.
+     *
+     * Agent 365 defaults this to `false` because AI SDK v7's
+     * `GenAIOpenTelemetry` already emits A365-compatible tool spans. Keeping both
+     * enabled can produce duplicate `execute_tool` spans for one tool call.
+     */
+    emitToolSpans?: boolean;
     /**
      * Include tenant as a static span attribute. Prefer `runWithA365Context`
      * when tenant varies per request.
@@ -140,6 +160,9 @@ type A365TracingConfig = {
     agentId?: string;
     agentDescription?: string;
     agentVersion?: string;
+    recordInputs?: boolean;
+    recordOutputs?: boolean;
+    emitToolSpans?: boolean;
     useGenAIOpenTelemetry?: boolean;
     telemetryIntegrations?: TelemetryOptions["integrations"];
     useGlobalTelemetryIntegrations?: boolean;

package/dist/index.js

@@ -1003,6 +1003,9 @@ function createA365TracingConfig(options = {}) {
     ...isNonEmpty(options.agentId) ? { agentId: options.agentId.trim() } : {},
     ...isNonEmpty(options.agentDescription) ? { agentDescription: options.agentDescription.trim() } : {},
     ...isNonEmpty(options.agentVersion) ? { agentVersion: options.agentVersion.trim() } : {},
+    ...options.recordInputs !== void 0 ? { recordInputs: options.recordInputs } : {},
+    ...options.recordOutputs !== void 0 ? { recordOutputs: options.recordOutputs } : {},
+    emitToolSpans: options.emitToolSpans ?? false,
     ...options.useGenAIOpenTelemetry !== void 0 ? { useGenAIOpenTelemetry: options.useGenAIOpenTelemetry } : {},
     ...options.telemetryIntegrations ? { telemetryIntegrations: options.telemetryIntegrations } : {},
     ...options.useGlobalTelemetryIntegrations !== void 0 ? {

package/docs/agent-core-otel.md

@@ -8,7 +8,7 @@ replace agent-core telemetry and it does not create agent-core spans itself.
 agent-core's OpenTelemetry middleware emits:
 
 - `invoke_agent` spans for agent turns;
-- `execute_tool` spans for tool calls;
+- optional `execute_tool` spans for tool calls when `emitToolSpans` is enabled;
 - AI SDK GenAI spans for model calls when AI SDK telemetry is enabled.
 
 The root agent span includes common GenAI attributes such as:
@@ -27,6 +27,14 @@ The root agent span includes common GenAI attributes such as:
 stable agent metadata. Per-request metadata belongs in baggage via
 `runWithA365Context(...)`.
 
+The A365 tracing adapter intentionally defaults `emitToolSpans` to `false`.
+AI SDK v7's `GenAIOpenTelemetry` integration already emits `execute_tool`
+spans for tool executions, and Microsoft's Agent 365 exporter recognizes those
+spans. Keeping both the AI SDK tool span and the agent-core tool span enabled
+can create duplicate `execute_tool` records for one tool call. Override
+`emitToolSpans: true` only for execution paths that do not use AI SDK v7 tool
+telemetry.
+
 ## What This Package Adds
 
 This package wraps the turn in Agent 365 baggage before agent-core starts its

package/docs/architecture.md

@@ -31,7 +31,8 @@ Per agent:
 
 1. the host calls `createAgent({ tracing: createA365TracingConfig(...) })`;
 2. agent-core installs its normal OpenTelemetry middleware;
-3. agent-core emits `invoke_agent`, `execute_tool`, and AI SDK model spans.
+3. agent-core emits `invoke_agent` spans and AI SDK v7 emits model and
+   `execute_tool` spans.
 
 Per turn:
 

package/docs/microsoft-a365-observability.md

@@ -47,8 +47,7 @@ are documented in [sdk-and-auth-flow.md](./sdk-and-auth-flow.md).
 ## Scope Classes
 
 Microsoft exposes explicit scope classes for several span shapes. agent-core
-already emits equivalent agent and tool spans, and AI SDK telemetry covers model
-spans.
+already emits the agent span, and AI SDK telemetry covers model and tool spans.
 
 The main shape difference is `OutputScope`, which creates a separate
 `output_messages` span. agent-core currently records output messages on the

package/docs/microsoft-node-package-comparison.md

@@ -18,8 +18,8 @@ Microsoft's Node observability packages have three practical layers:
 The cuylabs adapter sits beside those framework extensions. OpenAI Agents and
 LangChain need extension packages because their framework callbacks must be
 converted into Agent 365-shaped OpenTelemetry spans. agent-core already emits
-agent, tool, and model spans, so this adapter focuses on startup, token
-resolution, and Agent 365 baggage.
+agent spans and AI SDK v7 already emits model/tool spans, so this adapter
+focuses on startup, token resolution, and Agent 365 baggage.
 
 ## What We Use
 
@@ -45,7 +45,7 @@ resolution, and Agent 365 baggage.
 | Microsoft capability    | Status               | Reason                                                                                                         |
 | ----------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------- |
 | `InvokeAgentScope`      | Not used by default. | agent-core already emits the agent turn span. Creating another scope would duplicate `invoke_agent` telemetry. |
-| `ExecuteToolScope`      | Not used by default. | agent-core already emits tool spans around tool execution.                                                     |
+| `ExecuteToolScope`      | Not used by default. | AI SDK v7 already emits Agent 365-shaped tool spans for agent-core tool calls.                                 |
 | `InferenceScope`        | Not used by default. | AI SDK telemetry already emits model spans under the agent turn.                                               |
 | OpenAI Agents extension | Not used by default. | It patches `@openai/agents`; agent-core is the harness we adapt.                                               |
 | LangChain extension     | Not used by default. | It patches LangChain callbacks; agent-core already owns the turn and tool lifecycle.                           |

package/docs/sdk-and-auth-flow.md

@@ -33,7 +33,9 @@ processor and an export processor. The baggage processor copies current Agent
 
 Per agent, the host passes `createA365TracingConfig(...)` into
 `createAgent({ tracing })`. agent-core still owns the real agent telemetry. It
-emits agent turn spans, tool spans, and AI SDK model spans.
+emits agent turn spans and AI SDK v7 emits model/tool spans. The A365 adapter
+defaults agent-core's extra `execute_tool` span layer off so one tool execution
+does not produce duplicate Agent 365 tool records.
 
 Per turn, the host or channel adapter calls `runWithA365Context(...)` or
 `runWithA365TurnContext(...)` before running `agent.chat(...)`. The adapter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-a365-observability",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "Microsoft Agent 365 observability adapter for @cuylabs/agent-core",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,7 +26,7 @@
     "typescript": "^5.7.0",
     "vitest": "^4.0.18",
     "zod": "^3.25.76 || ^4.1.8",
-    "@cuylabs/agent-core": "^4.7.0"
+    "@cuylabs/agent-core": "^4.8.0"
   },
   "peerDependencies": {
     "@cuylabs/agent-core": "^4.0.0",