Adding Tracing for Agents

sdk/ai/ai-projects/package.json

@@ -58,19 +58,25 @@
     "@azure-rest/core-client": "^2.1.0",
     "@azure/core-auth": "^1.6.0",
     "@azure/core-rest-pipeline": "^1.5.0",
-    "@azure/core-util": "^1.9.0",
-    "@azure/logger": "^1.1.4",
-    "tslib": "^2.6.2",
     "@azure/core-paging": "^1.5.0",
-    "@azure/core-sse": "^2.1.3"
+    "@azure/logger": "^1.1.4",
+    "@azure/core-sse": "^2.1.3",
+    "@azure/core-tracing": "^1.2.0",
+    "@azure/core-util": "^1.9.0",
+    "tslib": "^2.6.2"
   },
   "devDependencies": {
     "@azure/dev-tool": "^1.0.0",
     "@azure/eslint-plugin-azure-sdk": "^3.0.0",
     "@azure/identity": "^4.3.0",
+    "@azure/opentelemetry-instrumentation-azure-sdk": "^1.0.0-beta.7",
     "@azure-tools/test-credential": "^2.0.0",
     "@azure-tools/test-recorder": "^4.1.0",
+    "@azure-tools/test-utils-vitest": "^1.0.0",
     "@microsoft/api-extractor": "^7.40.3",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/instrumentation": "0.53.0",
+    "@opentelemetry/sdk-trace-node": "^1.9.0",
     "@vitest/browser": "^2.0.5",
     "@vitest/coverage-istanbul": "^2.0.5",
     "@types/node": "^18.0.0",
@@ -112,18 +118,22 @@
     "./package.json": "./package.json",
     ".": {
       "browser": {
+        "source": "./src/index.ts",
         "types": "./dist/browser/index.d.ts",
         "default": "./dist/browser/index.js"
       },
       "react-native": {
+        "source": "./src/index.ts",
         "types": "./dist/react-native/index.d.ts",
         "default": "./dist/react-native/index.js"
       },
       "import": {
+        "source": "./src/index.ts",
         "types": "./dist/esm/index.d.ts",
         "default": "./dist/esm/index.js"
       },
       "require": {
+        "source": "./src/index.ts",
         "types": "./dist/commonjs/index.d.ts",
         "default": "./dist/commonjs/index.js"
       }

sdk/ai/ai-projects/review/ai-projects.api.md

@@ -167,6 +167,7 @@ export class AIProjectsClient {
     readonly agents: AgentsOperations;
     readonly connections: ConnectionsOperations;
     static fromConnectionString(connectionString: string, credential: TokenCredential, options?: AIProjectsClientOptions): AIProjectsClient;
+    readonly telemetry: TelemetryOperations;
 }
 
 // @public (undocumented)
@@ -1448,6 +1449,13 @@ export interface SystemDataOutput {
     readonly lastModifiedAt?: string;
 }
 
+// @public
+export interface TelemetryOperations {
+    getConnectionString(): Promise<string>;
+    // Warning: (ae-forgotten-export) The symbol "TelemetryOptions" needs to be exported by the entry point index.d.ts
+    updateSettings(options: TelemetryOptions): void;
+}
+
 // @public
 export interface ThreadDeletionStatusOutput {
     deleted: boolean;

sdk/ai/ai-projects/samples-dev/agents/agents_basics_tracing_console.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+
+import { context } from "@opentelemetry/api";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { createAzureSdkInstrumentation } from "@azure/opentelemetry-instrumentation-azure-sdk";
+import {
+    ConsoleSpanExporter,
+    NodeTracerProvider,
+    SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-node";
+
+import * as dotenv from "dotenv";
+dotenv.config();
+
+const provider = new NodeTracerProvider();
+provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+provider.register();
+
+registerInstrumentations({
+    instrumentations: [createAzureSdkInstrumentation()],
+});
+
+import { AIProjectsClient } from "@azure/ai-projects"
+import { DefaultAzureCredential } from "@azure/identity";
+
+const connectionString = process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<endpoint>>;<subscription>;<resource group>;<project>";
+
+export async function main(): Promise<void> {
+
+    const client = AIProjectsClient.fromConnectionString(connectionString || "", new DefaultAzureCredential());
+
+
+    const agent = await client.agents.createAgent("gpt-4o", { name: "my-agent", instructions: "You are helpful agent" }, { tracingOptions: { tracingContext: context.active() } });
+
+
+    console.log(`Created agent, agent ID : ${agent.id}`);
+
+    client.agents.deleteAgent(agent.id);
+
+    console.log(`Deleted agent`);
+}
+
+main().catch((err) => {
+    console.error("The sample encountered an error:", err);
+});

sdk/ai/ai-projects/src/agents/assistants.ts

@@ -4,7 +4,8 @@
 import { Client, createRestError } from "@azure-rest/core-client";
 import { AgentDeletionStatusOutput, AgentOutput, OpenAIPageableListOfAgentOutput } from "../generated/src/outputModels.js";
 import { CreateAgentParameters, DeleteAgentParameters, GetAgentParameters, ListAgentsParameters, UpdateAgentParameters } from "../generated/src/parameters.js";
-
+import { TracingUtility } from "../tracing.js";
+import { traceEndCreateAgent, traceStartCreateAgent } from "./assistantsTrace.js";
 
 const expectedStatuses = ["200"];
 
@@ -20,80 +21,85 @@ enum Tools {
 
 /** Creates a new agent. */
 export async function createAgent(
-    context: Client,
-    options: CreateAgentParameters,
-  ): Promise<AgentOutput> {
-    validateCreateAgentParameters(options);
-    const result = await  context.path("/assistants").post(options);
-    if (!expectedStatuses.includes(result.status)) {
+  context: Client,
+  options: CreateAgentParameters,
+): Promise<AgentOutput> {
+  validateCreateAgentParameters(options);
+  return TracingUtility.withSpan("CreateAgent", options,
+    async (updatedOptions) => {
+      const result = await context.path("/assistants").post(updatedOptions);
+      if (!expectedStatuses.includes(result.status)) {
         throw createRestError(result);
-    }
-    return result.body; 
-  }
+      }
+      return result.body as AgentOutput;
+    },
+    traceStartCreateAgent, traceEndCreateAgent,
+  );
+}
 
-  /** Gets a list of agents that were previously created. */
-  export async function listAgents(
-    context: Client,
-    options?: ListAgentsParameters,
-  ): Promise<OpenAIPageableListOfAgentOutput> {
-    validateListAgentsParameters(options);
-    const result = await  context
+/** Gets a list of agents that were previously created. */
+export async function listAgents(
+  context: Client,
+  options?: ListAgentsParameters,
+): Promise<OpenAIPageableListOfAgentOutput> {
+  validateListAgentsParameters(options);
+  const result = await context
     .path("/assistants")
     .get(options);
-    if (!expectedStatuses.includes(result.status)) {
-        throw createRestError(result);
-    }
-    return result.body; 
+  if (!expectedStatuses.includes(result.status)) {
+    throw createRestError(result);
   }
+  return result.body;
+}
 
-  /** Retrieves an existing agent. */
+/** Retrieves an existing agent. */
 export async function getAgent(
-    context: Client,
-    assistantId: string,
-    options?: GetAgentParameters,
-  ): Promise<AgentOutput> {
-    validateAssistantId(assistantId);
-    const result = await context
+  context: Client,
+  assistantId: string,
+  options?: GetAgentParameters,
+): Promise<AgentOutput> {
+  validateAssistantId(assistantId);
+  const result = await context
     .path("/assistants/{assistantId}", assistantId)
     .get(options);
-    if (!expectedStatuses.includes(result.status)) {
-        throw createRestError(result);
-    }
-    return result.body; 
+  if (!expectedStatuses.includes(result.status)) {
+    throw createRestError(result);
   }
+  return result.body;
+}
 
-  /** Modifies an existing agent. */
+/** Modifies an existing agent. */
 export async function updateAgent(
-    context: Client,
-    assistantId: string,
-    options?: UpdateAgentParameters,
-  ): Promise<AgentOutput> {
-    validateUpdateAgentParameters(assistantId, options);
-    const result = await context
+  context: Client,
+  assistantId: string,
+  options?: UpdateAgentParameters,
+): Promise<AgentOutput> {
+  validateUpdateAgentParameters(assistantId, options);
+  const result = await context
     .path("/assistants/{assistantId}", assistantId)
     .post(options);
-    if (!expectedStatuses.includes(result.status)) {
-        throw createRestError(result);
-    }
-    return result.body;
+  if (!expectedStatuses.includes(result.status)) {
+    throw createRestError(result);
   }
+  return result.body;
+}
 
 
-  /** Deletes an agent. */
+/** Deletes an agent. */
 export async function deleteAgent(
-    context: Client,
-    assistantId: string,
-    options?: DeleteAgentParameters,
-  ): Promise<AgentDeletionStatusOutput> {
-    validateAssistantId(assistantId);
-    const result = await context
+  context: Client,
+  assistantId: string,
+  options?: DeleteAgentParameters,
+): Promise<AgentDeletionStatusOutput> {
+  validateAssistantId(assistantId);
+  const result = await context
     .path("/assistants/{assistantId}", assistantId)
     .delete(options);
-    if (!expectedStatuses.includes(result.status)) {
-        throw createRestError(result);
-    }
-    return result.body;
+  if (!expectedStatuses.includes(result.status)) {
+    throw createRestError(result);
   }
+  return result.body;
+}
 
 function validateCreateAgentParameters(options: CreateAgentParameters | UpdateAgentParameters): void {
   if (options.body.tools) {
@@ -118,12 +124,12 @@ function validateCreateAgentParameters(options: CreateAgentParameters | UpdateAg
         throw new Error("Only one vector store ID is allowed");
       }
       if (options.body.tool_resources.file_search.vector_stores) {
-         if (options.body.tool_resources.file_search.vector_stores.length > 1) {
-            throw new Error("Only one vector store is allowed");
-         }
-         if (options.body.tool_resources.file_search.vector_stores[0]?.configuration.data_sources.some(value => !["uri_asset", "id_asset"].includes(value.type))) {
-            throw new Error("Vector store data type must be one of 'uri_asset', 'id_asset'");
-         }
+        if (options.body.tool_resources.file_search.vector_stores.length > 1) {
+          throw new Error("Only one vector store is allowed");
+        }
+        if (options.body.tool_resources.file_search.vector_stores[0]?.configuration.data_sources.some(value => !["uri_asset", "id_asset"].includes(value.type))) {
+          throw new Error("Vector store data type must be one of 'uri_asset', 'id_asset'");
+        }
       }
     }
     if (options.body.tool_resources.azure_ai_search) {
@@ -133,7 +139,7 @@ function validateCreateAgentParameters(options: CreateAgentParameters | UpdateAg
     }
   }
   if (options.body.temperature && (options.body.temperature < 0 || options.body.temperature > 2)) {
-      throw new Error("Temperature must be between 0 and 2");
+    throw new Error("Temperature must be between 0 and 2");
   }
   if (options.body.metadata) {
     if (Object.keys(options.body.metadata).length > 16) {
@@ -150,16 +156,16 @@ function validateCreateAgentParameters(options: CreateAgentParameters | UpdateAg
 
 function validateListAgentsParameters(options?: ListAgentsParameters): void {
   if (options?.queryParameters?.limit && (options.queryParameters.limit < 1 || options.queryParameters.limit > 100)) {
-      throw new Error("Limit must be between 1 and 100");
+    throw new Error("Limit must be between 1 and 100");
   }
   if (options?.queryParameters?.order && !["asc", "desc"].includes(options.queryParameters.order)) {
-      throw new Error("Order must be 'asc' or 'desc'");
+    throw new Error("Order must be 'asc' or 'desc'");
   }
 }
 
 function validateAssistantId(assistantId: string): void {
   if (!assistantId) {
-      throw new Error("Assistant ID is required");
+    throw new Error("Assistant ID is required");
   }
 }
 

sdk/ai/ai-projects/src/agents/assistantsTrace.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { TracingSpan } from "@azure/core-tracing";
+import { AgentOutput } from "../generated/src/outputModels.js";
+import { TracingAttributeOptions, TracingAttributes, TracingUtility, TrackingOperationName } from "../tracing.js";
+import { CreateAgentParameters } from "../generated/src/parameters.js";
+import { addInstructionsEvent, formatAgentApiResponse } from "./traceUtility.js";
+
+/**
+ * Traces the start of creating an agent.
+ * @param span - The span to trace.
+ * @param options - The options for creating an agent.
+ */
+export function traceStartCreateAgent(span: Omit<TracingSpan, "end">, options: CreateAgentParameters): void {
+    const attributes: TracingAttributeOptions = {
+        operationName: TrackingOperationName.CREATE_AGENT,
+        name: options.body.name,
+        model: options.body.model,
+        description: options.body.description,
+        instructions: options.body.instructions,
+        topP: options.body.top_p,
+        temperature: options.body.temperature,
+        responseFormat: formatAgentApiResponse(options.body.response_format),
+        genAiSystem: TracingAttributes.AZ_AI_AGENT_SYSTEM
+    };
+    TracingUtility.setSpanAttributes(span,TrackingOperationName.CREATE_AGENT, attributes)
+    addInstructionsEvent(span, options.body);
+}
+
+
+/**
+ * Traces the end of creating an agent.
+ * @param span - The span to trace.
+ * @param _options - The options for creating an agent.
+ * @param result - The result of creating an agent.
+ */
+export  async function traceEndCreateAgent(span: Omit<TracingSpan, "end">, _options: CreateAgentParameters, result: Promise<AgentOutput>): Promise<void> {
+    const resolvedResult = await result;
+    const attributes: TracingAttributeOptions = {
+        agentId: resolvedResult.id,
+    };
+    TracingUtility.updateSpanAttributes(span, attributes);
+}