Merge pull request #3810 from MicrosoftDocs/main

3/28/2025 PM Publish

Author: Taojunshen

articles/ai-services/agents/how-to/tools/licensed-data.md

@@ -0,0 +1,82 @@
+---
+title: 'How to use Agents with your licensed data'
+titleSuffix: Azure AI services
+description: Learn how to connect your licensed data for grounding with Azure AI Agent Service.
+services: cognitive-services
+manager: nitinme
+ms.service: azure
+ms.topic: how-to
+ms.date: 03/04/2025
+author: aahill
+ms.author: aahi
+recommendations: false
+---
+
+# Bring your licensed data
+
+Azure AI Agent Service integrates your own licensed data from specialized data providers, 
+such as Tripadvisor. This integration enhances the quality of your agent's responses with high-quality, fresh data, 
+such as travel guidance and reviews. These insights empower your agents to deliver nuanced, informed 
+solutions tailored to specific use cases.
+
+Tripadvisor is the first licensed data provider and you can ground with your licensed Tripadvisor data through the API, SDK, and Azure AI Foundry portal. 
+
+> [!IMPORTANT]
+> - Your use of connected non-Microsoft services is subject to the terms between you and the service provider. By connecting to a non-Microsoft service, you acknowledge that some of your data, such as prompt content, is passed to the non-Microsoft service, and/or your application might receive data from the non-Microsoft service. You're responsible for your use of non-Microsoft data.
+> - Grounding with licensed data incurs usage with licensed data providers, review the pricing plan with your selected licensed data providers.
+
+## Prerequisites
+
+* Obtain an API key for your [Tripadvisor developer account](https://www.tripadvisor.com/developers?screen=credentials).
+
+## Setup
+1. Go to [Azure AI Foundry portal](https://ai.azure.com/) and select your AI Project. Select **Management Center**.
+   
+   :::image type="content" source="../../media/tools/licensed-data/project-assets.png" alt-text="A screenshot showing the selectors for the management center for an AI project." lightbox="../../media/tools/licensed-data/project-assets.png":::
+
+1. Select **+new connection** in the settings page.
+
+   :::image type="content" source="../../media/tools/licensed-data/connected-resources.png" alt-text="A screenshot showing the connections for the selected AI project." lightbox="../../media/tools/licensed-data/connected-resources.png":::
+   
+1. Select **custom keys** in **other resource types**.
+
+   :::image type="content" source="../../media/tools/licensed-data/custom-keys.png" alt-text="A screenshot showing the custom key option in the settings page." lightbox="../../media/tools/licensed-data/custom-keys.png":::
+
+1. Enter the following information to create a connection to store your Tripadvisor key:
+   1. Set **Custom keys** to "key", with the value being your Tripadvisor API key.
+   1. Make sure **is secret** is checked.
+   1. Set the connection name to your connection name. You use this connection name in your sample code or Foundry Portal later.
+   1. For the **Access** setting, you can choose either *this project only* or *shared to all projects*. Just make sure in your code, the connection string of the project you entered has access to this connection.
+
+   :::image type="content" source="../../media/tools/licensed-data/connect-custom-resource.png" alt-text="A screenshot showing the screen for adding Tripadvisor connection information." lightbox="../../media/tools/licensed-data/connect-custom-resource.png":::
+
+## Use Tripadvisor tool through Foundry portal
+
+1. To use the Tripadvisor tool in the Azure AI Foundry, in the **Create and debug** screen for your agent, scroll down the **Setup** pane on the right to **action**. Then select **Add**.
+
+    :::image type="content" source="../../media/tools/knowledge-tools.png" alt-text="A screenshot showing the available tool categories in the Azure AI Foundry portal." lightbox="../../media/tools/knowledge-tools.png":::
+
+1. Select **Tripadvisor** and follow the prompts to add the tool. 
+
+   :::image type="content" source="../../media/tools/knowledge-tools-list.png" alt-text="A screenshot showing available knowledge tools." lightbox="../../media/tools/knowledge-tools-list.png":::
+
+1. Give a name for your Tripadvisor tool and provide an optional description.
+ 
+    :::image type="content" source="../../media/tools/licensed-data/add-data-source.png" alt-text="A screenshot showing the Tripadvisor data source." lightbox="../../media/tools/licensed-data/add-data-source.png":::
+
+1. Select the custom key connection you just created. 
+
+    :::image type="content" source="../../media/tools/licensed-data/add-connection.png" alt-text="A screenshot showing the connection for your Tripadvisor tool, and a JSON example." lightbox="../../media/tools/licensed-data/add-connection.png":::
+
+1. Finish and start chatting.
+
+## Connect Tripadvisor through code-first experience
+
+You can follow the instructions in [OpenAPI Spec tool](./openapi-spec.md) to connect Tripadvisor through OpenAPI spec.
+
+1. Remember to store and import Tripadvisor OpenAPI spec. You can find it through Foundry Portal.
+
+1. Make sure you have updated the authentication method to be `connection` and fill in the connection ID of your custom key connection.
+   ``` python
+   auth = OpenApiConnectionAuthDetails(security_scheme=OpenApiConnectionSecurityScheme(connection_id="your_connection_id"))
+   ```

articles/ai-services/agents/includes/quickstart-csharp.md

@@ -4,7 +4,7 @@ author: aahill
 ms.author: aahi
 ms.service: azure-ai-agent-service
 ms.topic: include
-ms.date: 01/15/2025
+ms.date: 03/28/2025
 ---
 
 | [Reference documentation](/dotnet/api/overview/azure/ai.projects-readme) | [Samples](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects/tests/Samples) | [Library source code](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects) | [Package (NuGet)](https://www.nuget.org/packages/Azure.AI.Projects/) |
@@ -38,7 +38,7 @@ ms.date: 01/15/2025
 Install the .NET package to your project. For example if you're using the .NET CLI, run the following command.
 
 ```console
-dotnet add package Azure.AI.Projects
+dotnet add package Azure.AI.Projects --prerelease
 dotnet add package Azure.Identity
 ```
 

articles/ai-services/agents/includes/quickstart-javascript.md

@@ -4,7 +4,7 @@ author: aahill
 ms.author: aahi
 ms.service: azure-ai-agent-service
 ms.topic: include
-ms.date: 03/21/2025
+ms.date: 03/28/2025
 ms.custom: devx-track-js
 ---
 
@@ -88,112 +88,7 @@ Set this connection string as an environment variable named `PROJECT_CONNECTION_
 
 Next, create an `index.js` file and paste in the code below:
 
-```javascript
-// index.js
-import {
-  AIProjectsClient,
-  DoneEvent,
-  ErrorEvent,
-  isOutputOfType,
-  MessageStreamEvent,
-  RunStreamEvent,
-  ToolUtility,
-} from "@azure/ai-projects";
-import { DefaultAzureCredential } from "@azure/identity";
-import dotenv from 'dotenv';
-
-dotenv.config();
-
-// Set the connection string from the environment variable
-const connectionString = process.env.PROJECT_CONNECTION_STRING;
-const model = "gpt-4o";
-
-// Throw an error if the connection string is not set
-if (!connectionString) {
-  throw new Error("Please set the PROJECT_CONNECTION_STRING environment variable.");
-}
-
-export async function main() {
-  const client = AIProjectsClient.fromConnectionString(
-    connectionString || "",
-    new DefaultAzureCredential(),
-  );
-
-  // Step 1 code interpreter tool
-  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool([]);
-
-  // Step 2 an agent
-  const agent = await client.agents.createAgent(model, {
-    name: "my-agent",
-    instructions: "You are a helpful agent",
-    tools: [codeInterpreterTool.definition],
-    toolResources: codeInterpreterTool.resources,
-  });
-
-  // Step 3 a thread
-  const thread = await client.agents.createThread();
-
-  // Step 4 a message to thread
-  await client.agents.createMessage(
-    thread.id, {
-    role: "user",
-    content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
-  });
-
-  // Intermission is now correlated with thread
-  // Intermission messages will retrieve the message just added
-
-  // Step 5 the agent
-  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();
-
-  for await (const eventMessage of streamEventMessages) {
-    switch (eventMessage.event) {
-      case RunStreamEvent.ThreadRunCreated:
-        break;
-      case MessageStreamEvent.ThreadMessageDelta:
-        {
-          const messageDelta = eventMessage.data;
-          messageDelta.delta.content.forEach((contentPart) => {
-            if (contentPart.type === "text") {
-              const textContent = contentPart;
-              const textValue = textContent.text?.value || "No text";
-            }
-          });
-        }
-        break;
-
-      case RunStreamEvent.ThreadRunCompleted:
-        break;
-      case ErrorEvent.Error:
-        console.log(`An error occurred. Data ${eventMessage.data}`);
-        break;
-      case DoneEvent.Done:
-        break;
-    }
-  }
-
-  // 6. Print the messages from the agent
-  const messages = await client.agents.listMessages(thread.id);
-
-  // Messages iterate from oldest to newest
-  // messages[0] is the most recent
-  const messagesArray = messages.data;
-  for (let i = messagesArray.length - 1; i >= 0; i--) {
-      const m = messagesArray[i];
-      console.log(`Type: ${m.content[0].type}`);
-      if (isOutputOfType(m.content[0], "text")) {
-          const textContent = m.content[0];
-          console.log(`Text: ${textContent.text.value}`);
-      }
-  }
-
-  // 7. Delete the agent once done
-  await client.agents.deleteAgent(agent.id);
-}
-
-main().catch((err) => {
-  console.error("The sample encountered an error:", err);
-});
-```
+:::code language="JavaScript" source="~/azure-typescript-e2e-apps/quickstarts/ai-agents/js/src/index.js":::
+
 
 Run the code using `node index.js` and observe.

articles/ai-services/agents/includes/quickstart-typescript.md

@@ -4,7 +4,7 @@ author: aahill
 ms.author: aahi
 ms.service: azure-ai-agent-service
 ms.topic: include
-ms.date: 03/21/2025
+ms.date: 03/28/2025
 ms.custom: devx-track-ts
 ---
 
@@ -72,118 +72,6 @@ For example, your connection string may look something like:
 
 Set this connection string as an environment variable named `PROJECT_CONNECTION_STRING`.
 
-```typescript
-// index.ts
-import {
-  AIProjectsClient,
-  DoneEvent,
-  ErrorEvent,
-  isOutputOfType,
-  MessageStreamEvent,
-  RunStreamEvent,
-  ToolUtility
-} from "@azure/ai-projects";
-import type {
-  MessageDeltaChunk,
-  MessageDeltaTextContent,
-  MessageTextContentOutput
-} from "@azure/ai-projects";
-import { DefaultAzureCredential } from "@azure/identity";
-import dotenv from 'dotenv';
-
-dotenv.config();
-
-// Set the connection string from the environment variable
-const connectionString = process.env.PROJECT_CONNECTION_STRING;
-const model = "gpt-4o";
-
-// Throw an error if the connection string is not set
-if (!connectionString) {
-  throw new Error("Please set the PROJECT_CONNECTION_STRING environment variable.");
-}
-
-export async function main() {
-  const client = AIProjectsClient.fromConnectionString(
-    connectionString || "",
-    new DefaultAzureCredential(),
-  );
-
-  // Step 1 code interpreter tool
-  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool([]);
-
-  // Step 2 an agent
-  const agent = await client.agents.createAgent(model, {
-    name: "my-agent",
-    instructions: "You are a helpful agent",
-    tools: [codeInterpreterTool.definition],
-    toolResources: codeInterpreterTool.resources,
-  });
-
-  // Step 3 a thread
-  const thread = await client.agents.createThread();
-
-  // Step 4 a message to thread
-  await client.agents.createMessage(
-    thread.id, {
-    role: "user",
-    content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
-  });
-
-  // Intermission is now correlated with thread
-  // Intermission messages will retrieve the message just added
-
-  // Step 5 the agent
-  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();
-
-  for await (const eventMessage of streamEventMessages) {
-    switch (eventMessage.event) {
-      case RunStreamEvent.ThreadRunCreated:
-        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";
-            }
-          });
-        }
-        break;
-
-      case RunStreamEvent.ThreadRunCompleted:
-        break;
-      case ErrorEvent.Error:
-        console.log(`An error occurred. Data ${eventMessage.data}`);
-        break;
-      case DoneEvent.Done:
-        break;
-    }
-  }
-
-  // 6. Print the messages from the agent
-  const messages = await client.agents.listMessages(thread.id);
-
-  // Messages iterate from oldest to newest
-  // messages[0] is the most recent
-  const messagesArray = messages.data;
-  for (let i = messagesArray.length - 1; i >= 0; i--) {
-      const m = messagesArray[i];
-      console.log(`Type: ${m.content[0].type}`);
-      if (isOutputOfType<MessageTextContentOutput>(m.content[0], "text")) {
-          const textContent = m.content[0] as MessageTextContentOutput;
-          console.log(`Text: ${textContent.text.value}`);
-      }
-  }
-
-  // 7. Delete the agent once done
-  await client.agents.deleteAgent(agent.id);
-}
-
-main().catch((err) => {
-  console.error("The sample encountered an error:", err);
-});
-```
-
+:::code language="TypeScript" source="~/azure-typescript-e2e-apps/quickstarts/ai-agents/ts/src/index.ts":::
 
 Build the TypeScript code then run the code using `node index.js` and observe.