Bing grounding sample (#31859)

Co-authored-by: Grace Brigham <[email protected]>

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

@@ -258,6 +258,13 @@ export interface ConnectionsOperations {
     listConnections: (options?: ListConnectionsQueryParamProperties, requestParams?: OptionalRequestParameters) => Promise<ListConnectionsResponseOutput>;
 }
 
+// @public
+export enum connectionToolType {
+    BingGrounding = "bing_grounding",
+    MicrosoftFabric = "microsoft_fabric",
+    SharePointGrounding = "sharepoint_grounding"
+}
+
 // @public
 export type ConnectionType = "AzureOpenAI" | "Serverless" | "AzureBlob" | "AIServices" | "CognitiveSearch";
 
@@ -499,6 +506,9 @@ 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;
 

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

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+/**
+ * 
+ * FILE: agents_bing_grounding.ts
+ *
+ * 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.
+ *
+ * USAGE:
+ *  npx ts-node agents_bing_grounding.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
+ *  BING_CONNECTION_NAME - the name of the connection with Bing search grounding
+ */
+
+import { AIProjectsClient, fromConnectionId, connectionToolType } 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 bingConnection = await client.connections.getConnection(process.env["BING_CONNECTION_NAME"] || "<connection-name>");
+  const connectionId = bingConnection.id;
+
+  // Initialize agent bing tool with the connection id
+  const bingTool = fromConnectionId(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]
+    }, {
+      headers: {"x-ms-enable-preview": "true"}
+    });
+  console.log(connectionId)
+  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: "How does wikipedia explain Euler's Identity?"});
+  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:`);
+  messages.data.forEach((m) => console.log(m.content));
+}
+
+main().catch((err) => {
+  console.error("The sample encountered an error:", err);
+});

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

@@ -0,0 +1,99 @@
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+/**
+ * 
+ * FILE: agents_bing_grounding_streaming.ts
+ *
+ * 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.
+ *
+ * USAGE:
+ *  npx ts-node agents_bing_grounding_streaming.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
+ *  BING_CONNECTION_NAME - the name of the connection with Bing search grounding
+ */
+
+import { AIProjectsClient, DoneEvent, ErrorEvent, MessageDeltaChunk, MessageDeltaTextContent, MessageStreamEvent, RunStreamEvent, ThreadRunOutput, fromConnectionId, connectionToolType } from "@azure/ai-projects"
+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> {
+  const client = AIProjectsClient.fromConnectionString(connectionString || "", new DefaultAzureCredential());
+  const bingConnection = await client.connections.getConnection(process.env["BING_CONNECTION_NAME"] || "<connection-name>");
+  const connectionId = bingConnection.id;
+
+  const bingTool = fromConnectionId(connectionToolType.BingGrounding, [connectionId]);
+
+  const agent  = await client.agents.createAgent(
+    "gpt-4-0125-preview", {
+      name: "my-agent", 
+      instructions: "You are a helpful agent",
+      tools: [bingTool]
+    }, {
+      headers: {"x-ms-enable-preview": "true"}
+    });
+  console.log(connectionId)
+  console.log(`Created agent, agent ID : ${agent.id}`);
+
+  const thread = await client.agents.createThread()
+  console.log(`Created thread, thread ID: ${thread.id}`);
+
+  const message = await client.agents.createMessage(thread.id, {role: "user", content: "How does wikipedia explain Euler's Identity?"});
+  console.log(`Created message, message ID: ${message.id}`);
+
+  const streamEventMessages = await client.agents.createRunStreaming(thread.id, agent.id);
+
+  for await (const eventMessage of streamEventMessages) {
+    switch (eventMessage.event) {
+      case RunStreamEvent.ThreadRunCreated:
+        console.log(`ThreadRun status: ${(eventMessage.data as ThreadRunOutput).status}`)
+        break;
+      case MessageStreamEvent.ThreadMessageDelta:
+        {
+          const messageDelta = eventMessage.data as MessageDeltaChunk;
+          messageDelta.delta.content.forEach((contentPart) => {
+            if (contentPart.type === "text") {
+              const textContent = contentPart as MessageDeltaTextContent
+              const textValue = textContent.text?.value || "No text"
+              console.log(`Text delta received:: ${textValue}`)
+            }
+          });
+        }
+        break;
+
+      case RunStreamEvent.ThreadRunCompleted:
+        console.log("Thread Run Completed");
+        break;
+      case ErrorEvent.Error:
+        console.log(`An error occurred. Data ${eventMessage.data}`);
+        break;
+      case DoneEvent.Done:
+        console.log("Stream completed.");
+        break;
+    }
+  }
+
+  client.agents.deleteAgent(agent.id)
+  console.log(`Deleted agent, agent ID: ${agent.id}`);
+
+  const messages = await client.agents.listMessages(thread.id)
+  console.log(`Messages:`);
+  messages.data.forEach((m) => console.log(m.content));
+}
+
+main().catch((err) => {
+  console.error("The sample encountered an error:", err);
+});

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

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-import { FunctionDefinition, FunctionToolDefinition, RequiredActionOutput, RequiredToolCallOutput, ToolDefinitionOutputParent } from "./inputOutputs.js";
+import { FunctionDefinition, FunctionToolDefinition, RequiredActionOutput, RequiredToolCallOutput, ToolDefinitionOutputParent, ToolDefinitionParent } from "./inputOutputs.js";
 
 
 /**
@@ -28,3 +28,29 @@ export function fromFunctionDefinition(functionDefintion: FunctionDefinition): F
         function: functionDefintion
     }
 }
+
+/** Types of connection tools sued to configure an agent */
+export enum connectionToolType {
+  /** Bing grounding search tool */
+  BingGrounding = "bing_grounding",
+  /** Microsoft Fabric tool */
+  MicrosoftFabric = "microsoft_fabric",
+  /** Sharepoint tool */
+  SharePointGrounding = "sharepoint_grounding",
+}
+
+/**
+ * Creates a tool definition for a connection tool with the given connection ids.
+ *
+ * @param toolType - The type of the connection tool.
+ * @param connectionIds - A list of the IDs of the connections to use.
+ * @returns The function tool definition.
+ */
+export function fromConnectionId(toolType : connectionToolType, connectionIds: string[]) : ToolDefinitionParent {
+  return {
+    type: toolType,
+    [toolType]: {
+      connections: connectionIds.map(connectionId => ({connection_id: connectionId}))
+    }
+  }
+}