@azure/ai-agents 1.0.0-alpha.20250509.4 → 1.0.0-beta.1

package/README.md

@@ -1,15 +1,11 @@
 # Azure AI Agents client library for JavaScript
 
-Use the AI Agents client library (in preview) to:
+Use the AI Agents client library to:
 
-- **Enumerate connections** in your Azure AI Foundry project and get connection properties.
-  For example, get the inference endpoint URL and credentials associated with your Azure OpenAI connection.
-- **Develop Agents using the Azure AI Agent Service**, leveraging an extensive ecosystem of models, tools, and capabilities from OpenAI, Microsoft, and other LLM providers. The Azure AI Agent Service enables the building of Agents for a wide range of generative AI use cases. The package is currently in private preview.
-- **Enable OpenTelemetry tracing**.
+- **Develop Agents using the Azure AI Agent Service**, leveraging an extensive ecosystem of models, tools, and capabilities from OpenAI, Microsoft, and other LLM providers. The Azure AI Agent Service enables the building of Agents for a wide range of generative AI use cases.
 
 [Product documentation](https://aka.ms/azsdk/azure-ai-projects/product-doc)
-
-| [Samples](https://github.com/Azure/azure-sdk-for-js/tree/feature/azure-ai-agents/sdk/ai/ai-agents/samples)
+| [Samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/ai/ai-agents/samples/)
 | [Package (npm)](https://www.npmjs.com/package/@azure/ai-agents)
 | [API reference documentation](https://learn.microsoft.com/javascript/api/overview/azure/ai-projects-readme?view=azure-node-preview)
 
@@ -17,16 +13,12 @@ Use the AI Agents client library (in preview) to:
 
 - [Getting started](#getting-started)
   - [Prerequisite](#prerequisite)
+  - [Authorization](#authorization)
   - [Install the package](#install-the-package)
 - [Key concepts](#key-concepts)
   - [Create and authenticate the client](#create-and-authenticate-the-client)
 - [Examples](#examples)
-  - [Enumerate connections](#enumerate-connections)
-    - [Get properties of all connections](#get-properties-of-all-connections)
-    - [Get properties of all connections of a particular type](#get-properties-of-all-connections-of-a-particular-type)
-    - [Get properties of a default connection](#get-properties-of-a-default-connection)
-    - [Get properties of a connection by its connection name](#get-properties-of-a-connection-by-its-connection-name)
-  - [Agents (Preview)](#agents-private-preview)
+  - [Agents](#agents)
     - [Create an Agent](#create-agent) with:
       - [File Search](#create-agent-with-file-search)
       - [Code interpreter](#create-agent-with-code-interpreter)
@@ -39,14 +31,11 @@ Use the AI Agents client library (in preview) to:
     - [Create message](#create-message) with:
       - [File search attachment](#create-message-with-file-search-attachment)
       - [Code interpreter attachment](#create-message-with-code-interpreter-attachment)
+      - [Image input](#create-message-with-image-inputs)
     - [Execute Run, Create Thread and Run, or Stream](#create-run-run_and_process-or-stream)
     - [Retrieve message](#retrieve-message)
     - [Retrieve file](#retrieve-file)
     - [Tear down by deleting resource](#teardown)
-    - [Tracing](#tracing)
-  - [Tracing](#tracing)
-    - [Installation](#installation)
-    - [Tracing example](#tracing-example)
 - [Troubleshooting](#troubleshooting)
   - [Exceptions](#exceptions)
   - [Reporting issues](#reporting-issues)
@@ -60,9 +49,11 @@ Use the AI Agents client library (in preview) to:
 - [LTS versions of Node.js](https://github.com/nodejs/release#release-schedule)
 - An [Azure subscription][azure_sub].
 - A [project in Azure AI Foundry](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects?tabs=ai-studio).
-- The project endpoint. It can be found in your Azure AI Foundry project overview page, under "Project details". Below we will assume the environment variable `PROJECT_ENDPOINT` was defined to hold this value.
-- Entra ID is needed to authenticate the client. Your application needs an object that implements the [TokenCredential](https://learn.microsoft.com/javascript/api/@azure/core-auth/tokencredential) interface. Code samples here use [DefaultAzureCredential](https://learn.microsoft.com/javascript/api/@azure/identity/defaultazurecredential?view=azure-node-latest). To get that working, you will need:
-  - The `Contributor` role. Role assigned can be done via the "Access Control (IAM)" tab of your Azure AI Project resource in the Azure portal.
+
+### Authorization
+
+- [Entra ID][entra_id] is needed to authenticate the client. Your application needs an object that implements the [TokenCredential](https://learn.microsoft.com/javascript/api/@azure/core-auth/tokencredential) interface. Code samples here use [DefaultAzureCredential](https://learn.microsoft.com/javascript/api/@azure/identity/defaultazurecredential?view=azure-node-latest). To get that working, you will need:
+  - The `Contributor` role. Role assigned can be done via the "Access Control (IAM)" tab of your Azure AI Project resource in the Azure portal. Learn more about role assignments [here](https://learn.microsoft.com/azure/role-based-access-control/role-assignments-portal).
   - [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed.
   - You are logged into your Azure account by running `az login`.
   - Note that if you have multiple Azure subscriptions, the subscription that contains your Azure AI Project resource must be your default subscription. Run `az account list --output table` to list all your subscription and see which one is the default. Run `az account set --subscription "Your Subscription ID or Name"` to change your default subscription.
@@ -77,7 +68,9 @@ npm install @azure/ai-agents @azure/identity
 
 ### Create and authenticate the client
 
-The class factory method `fromConnectionString` is used to construct the client. To construct a client:
+The `AgentsClient` is used to construct the client. Currently, we recommend that you use the AgentsClient through the [Azure AI Projects Client Library](https://www.npmjs.com/package/@azure/ai-projects) using `client.agents`.
+
+To construct a client:
 
 ```ts snippet:setup
 import { AgentsClient } from "@azure/ai-agents";
@@ -90,11 +83,9 @@ const client = new AgentsClient(projectEndpoint, new DefaultAzureCredential());
 
 ## Examples
 
-### Agents (Preview)
+### Agents
 
-Agents in the Azure AI Projects client library are designed to facilitate various interactions and operations within your AI projects. They serve as the core components that manage and execute tasks, leveraging different tools and resources to achieve specific goals. The following steps outline the typical sequence for interacting with Agents. See the "agents" folder in the [package samples](https://github.com/Azure/azure-sdk-for-js/tree/feature/azure-ai-agents/sdk/ai/ai-agents/samples) for additional Agent samples.
-
-Agents are actively being developed. A sign-up form for private preview is coming soon.
+Agents in the Azure AI Projects client library are designed to facilitate various interactions and operations within your AI projects. They serve as the core components that manage and execute tasks, leveraging different tools and resources to achieve specific goals. The following steps outline the typical sequence for interacting with Agents. See the [package samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/ai/ai-agents/samples/) for additional Agent samples.
 
 #### Create Agent
 
@@ -114,19 +105,30 @@ You can use `ToolSet` to do this:
 ```ts snippet:toolSet
 import { ToolSet } from "@azure/ai-agents";
 
+// Upload file for code interpreter tool
+const filePath1 = "./data/nifty500QuarterlyResults.csv";
+const fileStream1 = fs.createReadStream(filePath1);
+const codeInterpreterFile = await client.files.upload(fileStream1, "assistants", {
+  fileName: "myLocalFile",
+});
+console.log(`Uploaded local file, file ID : ${codeInterpreterFile.id}`);
+// Upload file for file search tool
+const filePath2 = "./data/sampleFileForUpload.txt";
+const fileStream2 = fs.createReadStream(filePath2);
+const fileSearchFile = await client.files.upload(fileStream2, "assistants", {
+  fileName: "sampleFileForUpload.txt",
+});
+console.log(`Uploaded file, file ID: ${fileSearchFile.id}`);
+// Create vector store for file search tool
+const vectorStore = await client.vectorStores
+  .createAndPoll({
+    fileIds: [fileSearchFile.id],
+  })
+  .pollUntilDone();
 // Create tool set
 const toolSet = new ToolSet();
-await toolSet.addFileSearchTool([vectorStore.id]);
-await toolSet.addCodeInterpreterTool([codeInterpreterFile.id]);
-
-// Create agent with tool set
-const agent = await client.createAgent("gpt-4o", {
-  name: "my-agent",
-  instructions: "You are a helpful agent",
-  tools: toolSet.toolDefinitions,
-  toolResources: toolSet.toolResources,
-});
-console.log(`Created agent, agent ID: ${agent.id}`);
+toolSet.addFileSearchTool([vectorStore.id]);
+toolSet.addCodeInterpreterTool([codeInterpreterFile.id]);
 ```
 
 #### Create Agent with File Search
@@ -152,7 +154,7 @@ console.log(`Created vector store, vector store ID: ${vectorStore.id}`);
 const fileSearchTool = ToolUtility.createFileSearchTool([vectorStore.id]);
 
 const agent = await client.createAgent("gpt-4o", {
-  name: "SDK Test Agent - Retrieval",
+  name: "File Search Agent",
   instructions: "You are helpful agent that can help fetch data from files you know about.",
   tools: [fileSearchTool.definition],
   toolResources: fileSearchTool.resources,
@@ -189,7 +191,7 @@ console.log(`Created agent, agent ID: ${agent.id}`);
 
 #### Create Agent with Bing Grounding
 
-To enable your Agent to perform search through Bing search API, you use `ToolUtility.createConnectionTool()` along with a connection.
+To enable your Agent to perform search through Bing search API, you use `ToolUtility.createBingGroundingTool()` along with a connection. See [here](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/bing-grounding?tabs=python&pivots=overview) to learn more about Grounding with Bing Search.
 
 Here is an example:
 
@@ -219,15 +221,15 @@ Here is an example to integrate Azure AI Search:
 ```ts snippet:AISearch
 import { ToolUtility } from "@azure/ai-agents";
 
-const connectionId = process.env["AZURE_AI_CONNECTION_ID"] || "<connection-name>";
+const connectionName = process.env["AZURE_AI_SEARCH_CONNECTION_NAME"] || "<connection-name>";
 
 // Initialize Azure AI Search tool
-const azureAISearchTool = ToolUtility.createAzureAISearchTool(connectionId, "ai-search-sample", {
+const azureAISearchTool = ToolUtility.createAzureAISearchTool(connectionName, "search-index", {
   queryType: "simple",
   topK: 3,
-  filter: "",
-  indexConnectionId: "",
-  indexName: "",
+  filter: "", // Add string here to filter results
+  indexConnectionId: connectionName,
+  indexName: "search-index",
 });
 
 // Create agent with the Azure AI search tool
@@ -314,7 +316,7 @@ class FunctionToolExecutor {
 
   public invokeTool(toolCall: RequiredToolCall & FunctionToolDefinition): ToolOutput | undefined {
     console.log(`Function tool call - ${toolCall.function.name}`);
-    const args = [];
+    const args: any[] = [];
     if (toolCall.function.parameters) {
       try {
         const params = JSON.parse(toolCall.function.parameters);
@@ -329,14 +331,21 @@ class FunctionToolExecutor {
       }
     }
     const result = this.functionTools
-      .find((tool) => tool.definition.function.name === toolCall.function.name)
-      ?.func(...args);
+      .map((tool) =>
+        tool.definition.function.name === toolCall.function.name ? tool.func(...args) : undefined,
+      )
+      .find((r) => r !== undefined);
     return result
       ? {
           toolCallId: toolCall.id,
           output: JSON.stringify(result),
         }
-      : undefined;
+      : {
+          toolCallId: toolCall.id,
+          output: JSON.stringify({
+            error: `No matching tool found for function: ${toolCall.function.name}`,
+          }),
+        };
   }
 
   public getFunctionDefinitions(): FunctionToolDefinition[] {
@@ -425,7 +434,7 @@ console.log(`Created thread, thread ID: ${thread.id}`);
 
 #### Create Thread with Tool Resource
 
-In some scenarios, you might need to assign specific resources to individual threads. To achieve this, you provide the `toolResources` argument to `createThread`. In the following example, you create a vector store and upload a file, enable an Agent for file search using the `tools` argument, and then associate the file with the thread using the `toolResources` argument.
+In some scenarios, you might need to assign specific resources to individual threads. To achieve this, you provide the `toolResources` argument to `threads.create`. In the following example, you create a vector store and upload a file, enable an Agent for file search using the `tools` argument, and then associate the file with the thread using the `toolResources` argument.
 
 ```ts snippet:threadWithTool
 import { ToolUtility } from "@azure/ai-agents";
@@ -458,7 +467,7 @@ const thread = await client.threads.create({ toolResources: fileSearchTool.resou
 
 #### List Threads
 
-To list all threads attached to a given agent, use the list_threads API:
+To list all threads attached to a given agent, use `threads.list`:
 
 ```ts snippet:listThreads
 const threads = client.threads.list();
@@ -549,65 +558,7 @@ You can send messages to Azure agents with image inputs in following ways:
 - **Using a public image accessible via URL**
 - **Using a base64 encoded image string**
 
-The following examples demonstrate each method:
-
-##### Create message using uploaded image file
-
-```ts snippet:imageInputWithFile
-const imagePath = "./data/image_file.png";
-// Upload the local image file
-const fileStream = fs.createReadStream(imagePath);
-const imageFile = await client.files.upload(fileStream, "assistants", {
-  fileName: "image_file.png",
-});
-console.log(`Uploaded file, file ID: ${imageFile.id}`);
-
-// Create a message with both text and image content
-console.log("Creating message with image content...");
-const inputMessage = "Hello, what is in the image?";
-const content = [
-  {
-    type: "text",
-    text: inputMessage,
-  },
-  {
-    type: "image_file",
-    image_file: {
-      file_id: imageFile.id,
-      detail: "high",
-    },
-  },
-];
-const message = await client.messages.create(thread.id, "user", content);
-console.log(`Created message, message ID: ${message.id}`);
-```
-
-##### Create message with an image URL input
-
-```ts snippet:imageInputWithUrl
-const imageUrl =
-  "https://github.com/Azure/azure-sdk-for-js/blob/0aa88ceb18d865726d423f73b8393134e783aea6/sdk/ai/ai-projects/data/image_file.png?raw=true";
-
-// Create a message with both text and image content
-console.log("Creating message with image content...");
-const inputMessage = "Hello, what is in the image?";
-const content = [
-  {
-    type: "text",
-    text: inputMessage,
-  },
-  {
-    type: "image_url",
-    image_url: {
-      url: imageUrl,
-      detail: "high",
-    },
-  },
-];
-
-const message = await client.messages.create(thread.id, "user", content);
-console.log(`Created message, message ID: ${message.id}`);
-```
+The following example demonstrates base64 method:
 
 ##### Create message with base64-encoded image input
 
@@ -653,7 +604,7 @@ console.log(`Created message, message ID: ${message.id}`);
 
 #### Create Run, Run_and_Process, or Stream
 
-Here is an example of `createRun` and poll until the run is completed:
+Here is an example of `runs.create` and poll until the run is completed:
 
 ```ts snippet:createRun
 import { delay } from "@azure/core-util";
@@ -768,7 +719,7 @@ for await (const dataPoint of messages) {
 
 ### Retrieve File
 
-Files uploaded by Agents cannot be retrieved back. If your use case needs to access the file content uploaded by the Agents, you are advised to keep an additional copy accessible by your application. However, files generated by Agents are retrievable by `getFileContent`.
+Files uploaded by Agents cannot be retrieved back. If your use case needs to access the file content uploaded by the Agents, you are advised to keep an additional copy accessible by your application. However, files generated by Agents are retrievable by `files.getContent`.
 
 Here is an example retrieving file ids from messages:
 
@@ -835,7 +786,7 @@ Client methods that make service calls raise an [RestError](https://learn.micros
 import { RestError } from "@azure/core-rest-pipeline";
 
 try {
-  const result = await client.connections.listConnections();
+  const thread = await client.threads.create();
 } catch (e) {
   if (e instanceof RestError) {
     console.log(`Status code: ${e.code}`);
@@ -859,7 +810,7 @@ To report issues with the client library, or request additional features, please
 
 ## Next steps
 
-Have a look at the [package samples](https://github.com/Azure/azure-sdk-for-js/tree/feature/azure-ai-agents/sdk/ai/ai-agents/samples) folder, containing fully runnable code.
+Have a look at the [package samples](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/ai/ai-agents/samples) folder, containing fully runnable code.
 
 ## Contributing
 
@@ -883,7 +834,4 @@ additional questions or comments.
 [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
 [entra_id]: https://learn.microsoft.com/azure/ai-services/authentication?tabs=powershell#authenticate-with-microsoft-entra-id
 [azure_identity_npm]: https://www.npmjs.com/package/@azure/identity
-[default_azure_credential]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential
 [azure_sub]: https://azure.microsoft.com/free/
-[evaluators]: https://learn.microsoft.com/azure/ai-studio/how-to/develop/evaluate-sdk
-[evaluator_library]: https://learn.microsoft.com/azure/ai-studio/how-to/evaluate-generative-ai-app#view-and-manage-the-evaluators-in-the-evaluator-library

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@azure/ai-agents",
-  "version": "1.0.0-alpha.20250509.4",
-  "description": "A generated SDK for AgentsClient.",
+  "version": "1.0.0-beta.1",
+  "description": "Azure AI Agents client library.",
   "engines": {
     "node": ">=18.0.0"
   },
@@ -71,14 +71,14 @@
     "@azure/core-tracing": "^1.2.0"
   },
   "devDependencies": {
-    "@azure/dev-tool": ">=1.0.0-alpha <1.0.0-alphb",
-    "@azure/eslint-plugin-azure-sdk": ">=3.0.0-alpha <3.0.0-alphb",
+    "@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/monitor-opentelemetry-exporter": ">=1.0.0-alpha <1.0.0-alphb",
+    "@azure/monitor-opentelemetry-exporter": "^1.0.0-beta.31",
     "@azure-tools/test-credential": "^2.0.0",
-    "@azure-tools/test-recorder": ">=4.1.0-alpha <4.1.0-alphb",
-    "@azure-tools/test-utils-vitest": ">=1.0.0-alpha <1.0.0-alphb",
+    "@azure-tools/test-recorder": "^4.1.0",
+    "@azure-tools/test-utils-vitest": "^1.0.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/instrumentation": "0.57.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",