Add tooling utilities

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

@@ -540,9 +540,6 @@ export type Frequency = string;
 // @public
 export type FrequencyOutput = string;
 
-// @public
-export function fromConnectionId(toolType: connectionToolType, connectionIds: string[]): ToolDefinitionParent;
-
 // @public
 export function fromFunctionDefinition(functionDefintion: FunctionDefinition): FunctionToolDefinition;
 
@@ -1614,6 +1611,49 @@ export interface ToolResourcesOutput {
     file_search?: FileSearchToolResourceOutput;
 }
 
+// @public
+export class ToolSet {
+    addAzureAISearchTool(indexConnectionId: string, indexName: string): {
+        definition: AzureAISearchToolDefinition;
+        resources: ToolResources;
+    };
+    addCodeInterpreterTool(fileIds?: string[], dataSources?: Array<VectorStoreDataSource>): {
+        definition: CodeInterpreterToolDefinition;
+        resources: ToolResources;
+    };
+    addConnectionTool(toolType: connectionToolType, connectionIds: string[]): {
+        definition: ToolDefinition;
+    };
+    addFileSearchTool(vectorStoreIds?: string[], vectorStores?: Array<VectorStoreConfigurations>, definitionDetails?: FileSearchToolDefinitionDetails): {
+        definition: FileSearchToolDefinition;
+        resources: ToolResources;
+    };
+    toolDefinitions: ToolDefinition[];
+    toolResources: ToolResources;
+}
+
+// @public
+export class ToolUtility {
+    static createAzureAISearchTool(indexConnectionId: string, indexName: string): {
+        definition: AzureAISearchToolDefinition;
+        resources: ToolResources;
+    };
+    static createCodeInterpreterTool(fileIds?: string[], dataSources?: Array<VectorStoreDataSource>): {
+        definition: CodeInterpreterToolDefinition;
+        resources: ToolResources;
+    };
+    static createConnectionTool(toolType: connectionToolType, connectionIds: string[]): {
+        definition: ToolDefinition;
+    };
+    static createFileSearchTool(vectorStoreIds?: string[], vectorStores?: Array<VectorStoreConfigurations>, definitionDetails?: FileSearchToolDefinitionDetails): {
+        definition: FileSearchToolDefinition;
+        resources: ToolResources;
+    };
+    static createFunctionTool(functionDefinition: FunctionDefinition): {
+        definition: FunctionToolDefinition;
+    };
+}
+
 // @public
 export type Trigger = TriggerParent | RecurrenceTrigger | CronTrigger;
 

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

@@ -0,0 +1,91 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+/**
+ * 
+ * FILE: agents_azure_ai_search.ts
+ *
+ * DESCRIPTION:
+ *  This sample demonstrates how to use agent operations with the 
+ *  Azure AI Search tool from the Azure Agents service using a synchronous client.
+ *
+ * USAGE:
+ *  npx ts-node agents_azure_ai_search.ts
+ *
+ *  Before running the sample:
+ *
+ *  npm install @azure/ai-projects @azure/identity @azure/core-util dotenv
+ *
+ *  Set this environment variables with your own values:
+ *  AZURE_AI_PROJECTS_CONNECTION_STRING - the Azure AI Project connection string, as found in your AI Studio Project
+ *  AZURE_AI_SEARCH_CONNECTION_NAME - the name of the connection with Azure AI search, must be a CognitiveSearch connection
+ */
+
+import { AIProjectsClient, MessageContentOutput, isOutputOfType, MessageTextContentOutput, ToolUtility } from "@azure/ai-projects"
+import { delay } from "@azure/core-util";
+import { DefaultAzureCredential } from "@azure/identity";
+
+import * as dotenv from "dotenv";
+dotenv.config();
+
+const connectionString = process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<endpoint>>;<subscription>;<resource group>;<project>";
+
+export async function main(): Promise<void> {
+  // Create an Azure AI Client from a connection string, copied from your AI Studio project.
+  // At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"
+  // Customer needs to login to Azure subscription via Azure CLI and set the environment variables
+  const client = AIProjectsClient.fromConnectionString(connectionString || "", new DefaultAzureCredential());
+  const connectionName = process.env["AZURE_AI_SEARCH_CONNECTION_NAME"] || "<connection-name>";
+  const connection = await client.connections.getConnection(connectionName);
+
+  // Initialize Azure AI Search tool
+  const azureAISearchTool = ToolUtility.createAzureAISearchTool(connection.id, connection.name)
+
+  // Create agent with the Azure AI search tool
+  const agent  = await client.agents.createAgent(
+    "gpt-4-0125-preview", {
+      name: "my-agent", 
+      instructions: "You are a helpful agent",
+      tools: [azureAISearchTool.definition],
+      tool_resources: azureAISearchTool.resources
+    }, {
+      headers: {"x-ms-enable-preview": "true"}
+    });
+  console.log(`Created agent, agent ID : ${agent.id}`);
+
+  // Create thread for communication
+  const thread = await client.agents.createThread()
+  console.log(`Created thread, thread ID: ${thread.id}`);
+
+  // Create message to thread
+  const message = await client.agents.createMessage(thread.id, {role: "user", content: "Hello, send an email with the datetime and weather information in New York"});
+  console.log(`Created message, message ID: ${message.id}`);
+
+  // Create and process agent run in thread with tools
+  let run = await client.agents.createRun(thread.id, agent.id);
+  while (run.status === "queued" || run.status === "in_progress") {
+    await delay(1000);
+    run = await client.agents.getRun(thread.id, run.id);
+  }
+  if (run.status === "failed") {
+      console.log(`Run failed: ${run.last_error}`);
+  }
+  console.log(`Run finished with status: ${run.status}`);
+
+  // Delete the assistant when done
+  client.agents.deleteAgent(agent.id)
+  console.log(`Deleted agent, agent ID: ${agent.id}`);
+
+  // Fetch and log all messages
+  const messages = await client.agents.listMessages(thread.id)
+  console.log(`Messages:`);
+  const agentMessage: MessageContentOutput = messages.data[0].content[0];
+  if (isOutputOfType<MessageTextContentOutput>(agentMessage, "text")) {
+    const textContent = agentMessage as MessageTextContentOutput;
+    console.log(`Text Message Content - ${textContent.text.value}`);
+  }
+}
+
+main().catch((err) => {
+  console.error("The sample encountered an error:", err);
+});

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

@@ -7,7 +7,7 @@
  *
  * DESCRIPTION:
  *  This sample demonstrates how to use agent operations with the Grounding with Bing Search tool from
- *  the Azure Agents service using a asynchronous client.
+ *  the Azure Agents service using a client.
  *
  * USAGE:
  *  npx ts-node agents_bing_grounding.ts
@@ -21,7 +21,7 @@
  *  BING_CONNECTION_NAME - the name of the connection with Bing search grounding
  */
 
-import { AIProjectsClient, fromConnectionId, connectionToolType, MessageContentOutput, isOutputOfType, MessageTextContentOutput } from "@azure/ai-projects"
+import { AIProjectsClient, ToolUtility, connectionToolType, MessageContentOutput, isOutputOfType, MessageTextContentOutput } from "@azure/ai-projects"
 import { delay } from "@azure/core-util";
 import { DefaultAzureCredential } from "@azure/identity";
 
@@ -39,18 +39,17 @@ export async function main(): Promise<void> {
   const connectionId = bingConnection.id;
 
   // Initialize agent bing tool with the connection id
-  const bingTool = fromConnectionId(connectionToolType.BingGrounding, [connectionId]);
+  const bingTool = ToolUtility.createConnectionTool(connectionToolType.BingGrounding, [connectionId]);
 
   // Create agent with the bing tool and process assistant run
   const agent  = await client.agents.createAgent(
     "gpt-4-0125-preview", {
       name: "my-agent", 
       instructions: "You are a helpful agent",
-      tools: [bingTool]
+      tools: [bingTool.definition]
     }, {
       headers: {"x-ms-enable-preview": "true"}
     });
-  console.log(connectionId)
   console.log(`Created agent, agent ID : ${agent.id}`);
 
   // Create thread for communication

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

@@ -8,7 +8,7 @@
  *
  * DESCRIPTION:
  *  This sample demonstrates how to use agent operations with the Grounding with Bing Search tool from
- *  the Azure Agents service using a asynchronous client and streaming.
+ *  the Azure Agents service using a client and streaming.
  *
  * USAGE:
  *  npx ts-node agents_bing_grounding_streaming.ts
@@ -22,7 +22,7 @@
  *  BING_CONNECTION_NAME - the name of the connection with Bing search grounding
  */
 
-import { AIProjectsClient, DoneEvent, ErrorEvent, MessageDeltaChunk, MessageDeltaTextContent, MessageStreamEvent, RunStreamEvent, ThreadRunOutput, fromConnectionId, connectionToolType, MessageContentOutput, isOutputOfType, MessageTextContentOutput } from "@azure/ai-projects"
+import { AIProjectsClient, DoneEvent, ErrorEvent, MessageDeltaChunk, MessageDeltaTextContent, MessageStreamEvent, RunStreamEvent, ThreadRunOutput, ToolUtility, connectionToolType, MessageContentOutput, isOutputOfType, MessageTextContentOutput } from "@azure/ai-projects"
 import { DefaultAzureCredential } from "@azure/identity";
 
 import * as dotenv from "dotenv";
@@ -35,17 +35,16 @@ export async function main(): Promise<void> {
   const bingConnection = await client.connections.getConnection(process.env["BING_CONNECTION_NAME"] || "<connection-name>");
   const connectionId = bingConnection.id;
 
-  const bingTool = fromConnectionId(connectionToolType.BingGrounding, [connectionId]);
+  const bingTool = ToolUtility.createConnectionTool(connectionToolType.BingGrounding, [connectionId]);
 
   const agent  = await client.agents.createAgent(
     "gpt-4-0125-preview", {
       name: "my-agent", 
       instructions: "You are a helpful agent",
-      tools: [bingTool]
+      tools: [bingTool.definition]
     }, {
       headers: {"x-ms-enable-preview": "true"}
     });
-  console.log(connectionId)
   console.log(`Created agent, agent ID : ${agent.id}`);
 
   const thread = await client.agents.createThread()

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

@@ -7,7 +7,7 @@
  *
  * DESCRIPTION:
  *  This sample demonstrates how to use agent operations with the Microsoft Fabric tool from
- *  the Azure Agents service using a asynchronous client.
+ *  the Azure Agents service using a client.
  *
  * USAGE:
  *  npx ts-node agents_fabric.ts
@@ -21,7 +21,7 @@
  *  FABRIC_CONNECTION_NAME
  */
 
-import { AIProjectsClient, fromConnectionId, connectionToolType, MessageContentOutput, isOutputOfType, MessageTextContentOutput } from "@azure/ai-projects";
+import { AIProjectsClient, ToolUtility, connectionToolType, MessageContentOutput, isOutputOfType, MessageTextContentOutput } from "@azure/ai-projects";
 import { delay } from "@azure/core-util";
 import { DefaultAzureCredential } from "@azure/identity";
 
@@ -39,14 +39,14 @@ export async function main(): Promise<void> {
   const connectionId = fabricConnection.id;
 
   // Initialize agent Microsoft Fabric tool with the connection id
-  const fabricTool = fromConnectionId(connectionToolType.MicrosoftFabric, [connectionId]);
+  const fabricTool = ToolUtility.createConnectionTool(connectionToolType.MicrosoftFabric, [connectionId]);
 
   // Create agent with the Microsoft Fabric tool and process assistant run
   const agent  = await client.agents.createAgent(
     "gpt-4-0125-preview", {
       name: "my-agent", 
       instructions: "You are a helpful agent",
-      tools: [fabricTool]
+      tools: [fabricTool.definition]
     }, {
       headers: {"x-ms-enable-preview": "true"}
     });

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

@@ -5,7 +5,7 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 /* eslint-disable @typescript-eslint/no-unsafe-function-type */
 
-import { AIProjectsClient, FunctionDefinition, FunctionToolDefinition, FunctionToolDefinitionOutput, MessageContentOutput, MessageImageFileContentOutput, MessageTextContentOutput, RequiredToolCallOutput, SubmitToolOutputsActionOutput, ToolDefinition, ToolOutput, isOutputOfType } from "@azure/ai-projects"
+import { AIProjectsClient, FunctionToolDefinition, FunctionToolDefinitionOutput, MessageContentOutput, MessageImageFileContentOutput, MessageTextContentOutput, RequiredToolCallOutput, SubmitToolOutputsActionOutput, ToolOutput, ToolUtility, isOutputOfType } from "@azure/ai-projects"
 import { delay } from "@azure/core-util";
 import { DefaultAzureCredential } from "@azure/identity";
 
@@ -20,28 +20,30 @@ export async function main(): Promise<void> {
     const agents = client.agents;
 
     class FunctionToolExecutor {
-        private functionTools: { func: Function, definition: FunctionDefinition }[];
+        private functionTools: { func: Function, definition: FunctionToolDefinition }[];
 
         constructor() {
             this.functionTools = [{
-                func: this.getUserFavoriteCity, definition: {
+                func: this.getUserFavoriteCity, 
+                ...ToolUtility.createFunctionTool({
                     name: "getUserFavoriteCity",
                     description: "Gets the user's favorite city.",
                     parameters: {}
-                }
+                })
             }, {
-                func: this.getCityNickname, definition: {
-                    name: "getCityNickname",
-                    description: "Gets the nickname of a city, e.g. 'LA' for 'Los Angeles, CA'.",
-                    parameters: { type: "object", properties: { location: { type: "string", description: "The city and state, e.g. Seattle, Wa" } } }
-                }
-            },
-            {
-                func: this.getWeather, definition: {
+                func: this.getCityNickname,
+                ...ToolUtility.createFunctionTool({
+                  name: "getCityNickname",
+                  description: "Gets the nickname of a city, e.g. 'LA' for 'Los Angeles, CA'.",
+                  parameters: { type: "object", properties: { location: { type: "string", description: "The city and state, e.g. Seattle, Wa" } } }
+                })
+            }, {
+                func: this.getWeather,
+                ...ToolUtility.createFunctionTool({
                     name: "getWeather",
                     description: "Gets the weather for a location.",
                     parameters: { type: "object", properties: { location: { type: "string", description: "The city and state, e.g. Seattle, Wa" }, unit: { type: "string", enum: ['c', 'f'] } } }
-                }
+                })
             }];
         }
 
@@ -73,15 +75,15 @@ export async function main(): Promise<void> {
                     return undefined;
                 }
             }
-            const result = this.functionTools.find((tool) => tool.definition.name === toolCall.function.name)?.func(...args);
+            const result = this.functionTools.find((tool) => tool.definition.function.name === toolCall.function.name)?.func(...args);
             return result ? {
                 tool_call_id: toolCall.id,
                 output: JSON.stringify(result)
             } : undefined;
         }
 
         public getFunctionDefinitions(): FunctionToolDefinition[] {
-            return this.functionTools.map(tool => {return { type: "function", function: tool.definition}});
+            return this.functionTools.map(tool => {return tool.definition});
         }
     }
 

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

@@ -7,7 +7,7 @@
  *
  * DESCRIPTION:
  *  This sample demonstrates how to use agent operations with the Sharepoint tool from
- *  the Azure Agents service using a asynchronous client.
+ *  the Azure Agents service using a client.
  *
  * USAGE:
  *  npx ts-node agents_sharepoint.ts
@@ -21,7 +21,7 @@
  *  SHAREPOINT_CONNECTION_NAME
  */
 
-import { AIProjectsClient, fromConnectionId, connectionToolType, MessageContentOutput, isOutputOfType, MessageTextContentOutput } from "@azure/ai-projects";
+import { AIProjectsClient, ToolUtility, connectionToolType, MessageContentOutput, isOutputOfType, MessageTextContentOutput } from "@azure/ai-projects";
 import { delay } from "@azure/core-util";
 import { DefaultAzureCredential } from "@azure/identity";
 
@@ -39,14 +39,14 @@ export async function main(): Promise<void> {
   const connectionId = sharepointConnection.id;
 
   // Initialize agent Sharepoint tool with the connection id
-  const sharepointTool = fromConnectionId(connectionToolType.SharepointGrounding, [connectionId]);
+  const sharepointTool = ToolUtility.createConnectionTool(connectionToolType.SharepointGrounding, [connectionId]);
 
   // Create agent with the Sharepoint tool and process assistant run
   const agent  = await client.agents.createAgent(
     "gpt-4-0125-preview", {
       name: "my-agent", 
       instructions: "You are a helpful agent",
-      tools: [sharepointTool]
+      tools: [sharepointTool.definition]
     }, {
       headers: {"x-ms-enable-preview": "true"}
     });