Клиентская библиотека Azure AI Projects для JavaScript — версия 2.0.2

Клиентская библиотека AI Projects (в предварительном просмотре) является частью Майкрософт Foundry SDK и обеспечивает лёгкий доступ к ресурсам в вашем Майкрософт Foundry Project. Он используется для следующих задач:

• Создайте и запустите агенты с помощью .agents свойства на клиенте.

• Улучшайте агенты специализированными инструментами:
  • Поиск памяти агента (предварительный просмотр)
  • Агент-агент (A2A) (Предварительный просмотр)
  • Поиск с использованием ИИ Azure
  • Пользовательский поиск Bing (Предварительный просмотр)
  • Заземление Bing
  • Автоматизация браузера (предварительный просмотр)
  • Интерпретатор кода
  • Компьютерное использование (предварительный просмотр)
  • Поиск файлов
  • Функциональный инструмент
  • Генерация изображений
  • Microsoft Fabric (Предварительный просмотр)
  • Протокол контекста модели (MCP)
  • OpenAPI
  • Майкрософт SharePoint (Превью)
  • Веб-поиск (предварительный просмотр)

• Получите клиент OpenAI , используя .getOpenAIClient. этот метод для запуска операций Responses, Conversations, Evaluation и FineTuning с вашим агентом.

• Управление хранилищами памяти (предпросмотр) для разговоров с агентами с помощью .beta.memoryStores операций.
• Ознакомьтесь с дополнительными инструментами оценки (некоторые в предварительном просмотре ), чтобы оценить производительность вашего генеративного ИИ-приложения, используя .evaluationRules, .beta.evaluationTaxonomies, .beta.evaluators, .beta.insightsи .beta.schedules операции.
• Проведите сканирование Red Team (предварительный просмотр ), чтобы выявить риски, связанные с вашим генеративным AI-приложением, используя эти .beta.redTeams операции.
• Тонкая настройка ИИ моделирует ваши данные.

• Enumerate AI Models развернуты в вашей Foundry Project с использованием операций .deployments.
• Перечислите связанные Azure ресурсы в вашем проекте Foundry, используя операции .connections.
• Загрузите документы и создайте наборы данных , чтобы ссылаться на них с помощью .datasets операций.
• Создание и перечисление индексов поиска с помощью .indexes операций.

Клиентская библиотека использует версию v1 Майкрософт Foundry data plane REST API.

документация продукта | Samples | Package (npm) | API Reference Documentation | SDK исходный код

Оглавление

• Начало работы
  • Необходимые условия
  • Авторизация
  • Установка пакета
• Основные понятия
  • Создание и проверка подлинности клиента
  • Предварительный просмотр групп операций и флаги опции
• Примеры
  • Выполнение операций с ответами с помощью клиента OpenAI
  • Выполнение операций с Агентом
  • Использование инструментов агентов
    • Встроенные инструменты
    • Connection-Based Инструменты
  • Операции оценки
  • Операции по развертыванию
  • Операции с подключениями
  • Операции с набором данных
  • Операции с файлами
  • Операции с индексами
  • Операции тонкой настройки
• Трассировка
  • Installation
  • Как включить трассировку
• Troubleshooting
  • Исключения
  • проблемы с отчетами
• Дальнейшие действия
• участие

Начало работы

Необходимые условия

• Версии Node.js LTS
• Подписка Azure.
• Проект проект в Майкрософт Foundry.
• URL конечной точки проекта в форме https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name. Его можно найти на странице обзора Майкрософт Foundry Project. Ниже предположим, что переменная FOUNDRY_PROJECT_ENDPOINT среды была определена для хранения этого значения.

Авторизация

• Для аутентификации клиента требуется Entra ID. Приложению требуется объект, реализующий интерфейс TokenCredential. Примеры кода здесь используют DefaultAzureCredential. Чтобы получить эту работу, вам потребуется:
  • Подходящее назначение роли. см. Role based control access in Майкрософт portal Foundry. Назначение роли можно выполнить через вкладку «контроль доступа (IAM)» вашего ресурса Azure AI Project в портале Azure.
  • Azure CLI установлен.
  • Вы входите в свой аккаунт Azure с помощью az login.
  • Обратите внимание, что если у вас несколько подписок на Azure, подписка, содержащая ваш ресурс Azure AI Project, должна быть вашей подпиской по умолчанию. Запустите az account list --output table, чтобы вывести список всех подписок и увидеть, какой из них используется по умолчанию. Запустите az account set --subscription "Your Subscription ID or Name", чтобы изменить подписку по умолчанию.

Установка пакета

npm install @azure/ai-projects dotenv

Ключевые понятия

Создайте и аутентифицируйте клиента с помощью Entra ID

Entra ID — единственный метод аутентификации, поддерживаемый клиентом на данный момент.

Чтобы создать , AIProjectsClientможно projectEndpoint получить из projectEndpoint. Ниже мы предположим, что переменная FOUNDRY_PROJECT_ENDPOINT окружения была определена для хранения этого значения:

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint string>";
project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());

Предварительный просмотр групп операций и флаги опции

Некоторые операции предварительного просмотра требуют явного foundryFeatures флага согласия. Рассмотрим пример.

await project.agents.createVersion(
  "preview-agent",
  {
    kind: "workflow",
  },
  { foundryFeatures: "WorkflowAgents=V1Preview" },
);
for await (const rule of project.evaluationRules.list()) {
  console.log(rule.id);
}

Группы предварительных операций включают .beta.memoryStores, .beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, .beta.schedulesи .beta.redTeams.

Примеры

Выполнение операций с ответами с помощью клиента OpenAI

В вашем проекте Майкрософт Foundry может быть развернута одна или несколько моделей ИИ. Это могут быть модели OpenAI, модели Майкрософт или модели других провайдеров. Используйте приведенный ниже код, чтобы получить аутентифицированный OpenAI из пакета openai и выполнить вызов завершения чата.

Выполните приведенный ниже код. Здесь мы предполагаем, что deploymentName (str) определено. Это название модели ИИ для развертывания в вашем Foundry Project. Как показано во вкладке "Модели + конечные точки", в столбце "Название".

Смотрите папку «responses» в package samples для дополнительных образцов, включая потоковые ответы.

const openAIClient = project.getOpenAIClient();
const response = await openAIClient.responses.create({
  model: deploymentName,
  input: "What is the size of France in square miles?",
});
console.log("response = ", JSON.stringify(response, null, 2));
const detailResponse = await openAIClient.responses.create({
  model: deploymentName,
  input: "And what is the capital city?",
  previous_response_id: response.id,
});
console.log("detailed response = ", JSON.stringify(detailResponse, null, 2));

Выполнение операций с Агентом

Свойство .agents на объекте AIProjectsClient дает вам доступ ко всем операциям Агента. Агенты используют расширение протокола ответов OpenAI, поэтому вам, скорее всего, потребуется заставить OpenAI клиента выполнять операции с агентом, как показано в примере ниже.

const openAIClient = project.getOpenAIClient();
const agent = await project.agents.createVersion("my-agent-basic", {
  kind: "prompt",
  model: deploymentName,
  instructions: "You are a helpful assistant that answers general questions",
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
const conversation = await openAIClient.conversations.create({
  items: [
    { type: "message", role: "user", content: "What is the size of France in square miles?" },
  ],
});
console.log(`Created conversation with initial user message (id: ${conversation.id})`);
// Generate response using the agent
console.log("\nGenerating response...");
const response = await openAIClient.responses.create(
  {
    conversation: conversation.id,
  },
  {
    body: { agent: { name: agent.name, type: "agent_reference" } },
  },
);
console.log(`Response output: ${response.output_text}`);
// Add a second user message to the conversation
console.log("\nAdding a second user message to the conversation...");
await openAIClient.conversations.items.create(conversation.id, {
  items: [{ type: "message", role: "user", content: "And what is the capital city?" }],
});
console.log("Added a second user message to the conversation");
// Generate second response
console.log("\nGenerating second response...");
const response2 = await openAIClient.responses.create(
  {
    conversation: conversation.id,
  },
  {
    body: { agent: { name: agent.name, type: "agent_reference" } },
  },
);
console.log(`Response output: ${response2.output_text}`);
// Clean up
console.log("\nCleaning up resources...");
await openAIClient.conversations.delete(conversation.id);
console.log("Conversation deleted");
await project.agents.deleteVersion(agent.name, agent.version);
console.log("Agent deleted");

Использование инструментов агентов

Агенты могут быть усилены специализированными инструментами для различных возможностей. Инструменты организованы по требованиям к соединению:

Встроенные инструменты

Эти инструменты работают мгновенно без необходимости внешних соединений.

Интерпретатор кода

Пишите и запускайте код на Javascript в песочнице, обрабатывайте файлы и работайте с разными форматами данных. Документация по OpenAI

const openAIClient = project.getOpenAIClient();
const response = await openAIClient.responses.create({
  model: deploymentName,
  input: "I need to solve the equation 3x + 11 = 14. Can you help me?",
  tools: [{ type: "code_interpreter", container: { type: "auto" } }],
});
console.log(`Response output: ${response.output_text}`);

Полный пример кода смотрите в agentCodeInterpreter.ts.

Поиск файлов

Встроенный инструмент RAG (Retrieval-Augmented Generation) для обработки и поиска документов с использованием векторных хранилищ для поиска знаний. Документация по OpenAI

const openAIClient = project.getOpenAIClient();
const assetFilePath = path.join(
  __dirname,
  "..",
  "samples-dev",
  "agents",
  "assets",
  "product_info.txt",
);
const vectorStore = await openAIClient.vectorStores.create({
  name: "ProductInfoStreamStore",
});
console.log(`Vector store created (id: ${vectorStore.id})`);
// Upload file to vector store
const fileStream = fs.createReadStream(assetFilePath);
const uploadedFile = await openAIClient.vectorStores.files.uploadAndPoll(
  vectorStore.id,
  fileStream,
);
console.log(`File uploaded to vector store (id: ${uploadedFile.id})`);
// Create agent with file search tool
const agent = await project.agents.createVersion("StreamingFileSearchAgent", {
  kind: "prompt",
  model: deploymentName,
  instructions:
    "You are a helpful assistant that can search through product information and provide detailed responses. Use the file search tool to find relevant information before answering.",
  tools: [
    {
      type: "file_search",
      vector_store_ids: [vectorStore.id],
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Полный пример кода смотрите в agentFileSearchStream.ts.

Генерация изображений

Генерируйте изображения на основе текстовых подсказок с настраиваемым разрешением, качеством и настройками стиля:

const agent = await project.agents.createVersion("agent-image-generation", {
  kind: "prompt",
  model: deploymentName,
  instructions: "Generate images based on user prompts",
  tools: [
    {
      type: "image_generation",
      quality: "low",
      size: "1024x1024",
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

После звонка responses.create()вы можете скачать файл, используя ответ:

import { fileURLToPath } from "url";

const openAIClient = project.getOpenAIClient();
const agent = await project.agents.createVersion("agent-image-generation", {
  kind: "prompt",
  model: deploymentName,
  instructions: "Generate images based on user prompts",
  tools: [
    {
      type: "image_generation",
      quality: "low",
      size: "1024x1024",
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
const response = await openAIClient.responses.create(
  {
    input: "Generate an image of Microsoft logo.",
  },
  {
    body: { agent: { name: agent.name, type: "agent_reference" } },
  },
);
console.log(`Response created: ${response.id}`);
const imageData = response.output?.filter((output) => output.type === "image_generation_call");
if (imageData && imageData.length > 0 && imageData[0].result) {
  console.log("Downloading generated image...");
  const __filename = fileURLToPath(import.meta.url);
  const __dirname = path.dirname(__filename);
  const filename = "microsoft.png";
  const filePath = path.join(__dirname, filename);
  // Decode base64 and save to file
  const imageBuffer = Buffer.from(imageData[0].result, "base64");
  fs.writeFileSync(filePath, imageBuffer);
  console.log(`Image downloaded and saved to: ${path.resolve(filePath)}`);
} else {
  console.log("No image data found in the response.");
}

Веб-поиск (предварительный просмотр)

Выполняйте общие поисковые запросы в интернете, чтобы получить актуальную информацию из интернета. Документация по OpenAI

const openAIClient = project.getOpenAIClient();
// Create Agent with web search tool
const agent = await project.agents.createVersion("agent-web-search", {
  kind: "prompt",
  model: deploymentName,
  instructions: "You are a helpful assistant that can search the web",
  tools: [
    {
      type: "web_search_preview",
      user_location: {
        type: "approximate",
        country: "GB",
        city: "London",
        region: "London",
      },
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
// Create a conversation for the agent interaction
const conversation = await openAIClient.conversations.create();
console.log(`Created conversation (id: ${conversation.id})`);
// Send a query to search the web
console.log("\nSending web search query...");
const response = await openAIClient.responses.create(
  {
    conversation: conversation.id,
    input: "Show me the latest London Underground service updates",
  },
  {
    body: { agent: { name: agent.name, type: "agent_reference" } },
  },
);
console.log(`Response: ${response.output_text}`);

Полный пример кода смотрите в agentWebSearch.ts.

Компьютерное использование (предварительный просмотр)

Дать агентам возможность напрямую взаимодействовать с компьютерными системами для автоматизации задач и операций с системами:

const agent = await project.agents.createVersion("ComputerUseAgent", {
  kind: "prompt" as const,
  model: deploymentName,
  instructions: `
You are a computer automation assistant.

Be direct and efficient. When you reach the search results page, read and describe the actual search result titles and descriptions you can see.
    `.trim(),
  tools: [
    {
      type: "computer_use_preview",
      display_width: 1026,
      display_height: 769,
      environment: "windows" as const,
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

После вызова responses.create()обработка ответа в цикле взаимодействия. Обрабатывайте computer_call выходные элементы и предоставляйте скриншоты по computer_call_outputcomputer_screenshot типу для продолжения взаимодействия.

Полный пример кода смотрите в agentComputerUse.ts.

Протокол контекста модели (MCP)

Интегрируйте MCP-серверы для расширения возможностей агентов с помощью стандартизированных инструментов и ресурсов. Документация по OpenAI

const openAIClient = project.getOpenAIClient();
const agent = await project.agents.createVersion("agent-mcp", {
  kind: "prompt",
  model: deploymentName,
  instructions:
    "You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
  tools: [
    {
      type: "mcp",
      server_label: "api-specs",
      server_url: "https://gitmcp.io/Azure/azure-rest-api-specs",
      require_approval: "always",
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
// Create a conversation thread to maintain context across multiple interactions
console.log("\nCreating conversation...");
const conversation = await openAIClient.conversations.create();
console.log(`Created conversation (id: ${conversation.id})`);
// Send initial request that will trigger the MCP tool to access Azure REST API specs
// This will generate an approval request since requireApproval="always"
console.log("\nSending request that will trigger MCP approval...");
const response = await openAIClient.responses.create(
  {
    conversation: conversation.id,
    input: "Please summarize the Azure REST API specifications Readme",
  },
  {
    body: { agent: { name: agent.name, type: "agent_reference" } },
  },
);

После вызова responses.create()проверьте наличие mcp_approval_request элементов в выходе ответа. Отправьте с McpApprovalResponse решением о одобрении, чтобы агент мог продолжить свою работу.

Полный пример кода смотрите в agentMcp.ts.

OpenAPI

Вызывать внешние API, определённые спецификациями OpenAPI, без дополнительного клиентского кода. Документация по OpenAI

const weatherSpecPath = path.resolve(__dirname, "../assets", "weather_openapi.json");
const agent = await project.agents.createVersion("MyOpenApiAgent", {
  kind: "prompt",
  model: deploymentName,
  instructions:
    "You are a helpful assistant that can call external APIs defined by OpenAPI specs to answer user questions. When calling the weather tool, always include the query parameter format=j1.",
  tools: [
    {
      type: "openapi",
      openapi: {
        name: "get_weather",
        description: "Retrieve weather information for a location using wttr.in",
        spec: weatherSpecPath,
        auth: { type: "anonymous" },
      },
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Полный пример кода смотрите в agentOpenApi.ts.

Функциональный инструмент

Определить пользовательские функции, позволяющие агентам взаимодействовать с внешними API, базами данных или логикой приложений. Документация по OpenAI

/**
 * Define a function tool for the model to use
 */
const funcTool = {
  type: "function" as const,
  function: {
    name: "get_horoscope",
    description: "Get today's horoscope for an astrological sign.",
    strict: true,
    parameters: {
      type: "object",
      properties: {
        sign: {
          type: "string",
          description: "An astrological sign like Taurus or Aquarius",
        },
      },
      required: ["sign"],
      additional_properties: false,
    },
  },
};
const agent = await project.agents.createVersion("function-tool-agent", {
  kind: "prompt",
  model: deploymentName,
  instructions: "You are a helpful assistant that can use function tools.",
  tools: [funcTool],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

После вызова responses.create()обработайте function_call элементы из ответа, выполните логику функции с предоставленными аргументами и отправьте обратно FunctionCallOutput с результатами.

Полный пример кода смотрите в agentFunctionTool.ts.

• Инструмент поиска памяти (предварительный просмотр)

Инструмент хранения памяти добавляет память агенту, позволяя модели ИИ агента искать прошлую информацию, связанную с текущим пользовательским запросом.

Это название модели, используемой для создания векторных вложений для хранения и поиска embeddingModelDeployment памяти.

const memoryStoreName = "AgentMemoryStore";
const embeddingModelDeployment =
  process.env["MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME"] || "<embedding model>";
const scope = "user_123";
const memoryStore = await project.beta.memoryStores.create(
  memoryStoreName,
  {
    kind: "default",
    chat_model: deploymentName,
    embedding_model: embeddingModelDeployment,
    options: {
      user_profile_enabled: true,
      chat_summary_enabled: true,
    },
  },
  {
    description: "Memory store for agent conversations",
  },
);
console.log(
  `Created memory store: ${memoryStore.name} (${memoryStore.id}) using chat model '${deploymentName}'`,
);
// Create an agent that will use the Memory Search tool
const agent = await project.agents.createVersion("MemorySearchAgent", {
  kind: "prompt",
  model: deploymentName,
  instructions:
    "You are a helpful assistant that remembers user preferences using the memory search tool.",
  tools: [
    {
      type: "memory_search_preview",
      memory_store_name: memoryStore.name,
      scope,
      update_delay: 1, // wait briefly after conversation inactivity before updating memories
    },
  ],
});

Полный пример кода смотрите в agentMemorySearch.ts.

Connection-Based Инструменты

Эти инструменты требуют настройки соединений в вашем проекте AI Foundry и использования projectConnectionId.

Поиск с использованием ИИ Azure

Интегрируйте с индексами Поиск с использованием ИИ Azure для мощного поиска знаний и семантического поиска:

const aiSearchConnectionId = process.env["AI_SEARCH_CONNECTION_ID"] || "";
const aiSearchIndexName = process.env["AI_SEARCH_INDEX_NAME"] || "";
const agent = await project.agents.createVersion("MyAISearchAgent", {
  kind: "prompt",
  model: deploymentName,
  instructions:
    "You are a helpful assistant. You must always provide citations for answers using the tool and render them as: `[message_idx:search_idx†source]`.",
  tools: [
    {
      type: "azure_ai_search",
      azure_ai_search: {
        indexes: [
          {
            project_connection_id: aiSearchConnectionId,
            index_name: aiSearchIndexName,
            query_type: "simple",
          },
        ],
      },
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Полный пример кода смотрите в agentAiSearch.ts.

Заземление Bing

Ответы наземных агентов с результатами поиска в интернете в реальном времени от Bing для предоставления информации up-to-дата:

const bingProjectConnectionId = process.env["BING_GROUNDING_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("MyBingGroundingAgent", {
  kind: "prompt",
  model: deploymentName,
  instructions: "You are a helpful assistant.",
  tools: [
    {
      type: "bing_grounding",
      bing_grounding: {
        search_configurations: [
          {
            project_connection_id: bingProjectConnectionId,
          },
        ],
      },
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Полный пример кода смотрите в agentBingGrounding.ts.

Пользовательский поиск Bing (Предварительный просмотр)

Используйте специально настроенные поисковые экземпляры Bing для результатов поиска по домену или фильтрации:

const bingCustomSearchProjectConnectionId = process.env["BING_CUSTOM_SEARCH_CONNECTION_ID"] || "";
const bingCustomSearchInstanceName = process.env["BING_CUSTOM_SEARCH_INSTANCE_NAME"] || "";
const agent = await project.agents.createVersion("MyAgent", {
  kind: "prompt",
  model: deploymentName,
  instructions:
    "You are a helpful agent that can use Bing Custom Search tools to assist users. Use the available Bing Custom Search tools to answer questions and perform tasks.",
  tools: [
    {
      type: "bing_custom_search_preview",
      bing_custom_search_preview: {
        search_configurations: [
          {
            project_connection_id: bingCustomSearchProjectConnectionId,
            instance_name: bingCustomSearchInstanceName,
          },
        ],
      },
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Полный пример кода смотрите в agentBingCustomSearch.ts.

Microsoft Fabric (Превью)

Подключитесь к Microsoft Fabric и отправьте к нему запрос:

const fabricProjectConnectionId = process.env["FABRIC_PROJECT_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("MyFabricAgent", {
  kind: "prompt",
  model: deploymentName,
  instructions: "You are a helpful assistant.",
  tools: [
    {
      type: "fabric_dataagent_preview",
      fabric_dataagent_preview: {
        project_connections: [
          {
            project_connection_id: fabricProjectConnectionId,
          },
        ],
      },
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Полный пример кода смотрите в agentFabric.ts.

Майкрософт SharePoint (Превью)

Доступ и поиск документов, списков и сайтов SharePoint для интеграции корпоративных знаний:

const sharepointProjectConnectionId = process.env["SHAREPOINT_PROJECT_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("MyAgent", {
  kind: "prompt",
  model: deploymentName,
  instructions:
    "You are a helpful agent that can use SharePoint tools to assist users. Use the available SharePoint tools to answer questions and perform tasks.",
  // Define SharePoint tool that searches SharePoint content
  tools: [
    {
      type: "sharepoint_grounding_preview",
      sharepoint_grounding_preview: {
        project_connections: [
          {
            project_connection_id: sharepointProjectConnectionId,
          },
        ],
      },
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Полный пример кода смотрите в agentSharepoint.ts.

Автоматизация браузера (предварительный просмотр)

Автоматизируйте взаимодействие браузера для веб-скрейпинга, тестирования и взаимодействия с веб-приложениями:

const browserAutomationProjectConnectionId = process.env["BROWSER_AUTOMATION_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("MyAgent", {
  kind: "prompt",
  model: deploymentName,
  instructions: `You are an Agent helping with browser automation tasks.
              You can answer questions, provide information, and assist with various tasks
              related to web browsing using the Browser Automation tool available to you.`,
  // Define Browser Automation tool
  tools: [
    {
      type: "browser_automation_preview",
      browser_automation_preview: {
        connection: {
          project_connection_id: browserAutomationProjectConnectionId,
        },
      },
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Смотрите полный пример кода в agentBrowserAutomation.ts.

MCP с Project соединением

Интеграция с MCP с использованием проектно-специфических соединений для доступа к подключённым серверам MCP:

const mcpProjectConnectionId = process.env["MCP_PROJECT_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("agent-mcp-connection-auth", {
  kind: "prompt",
  model: deploymentName,
  instructions: "Use MCP tools as needed",
  tools: [
    {
      type: "mcp",
      server_label: "api-specs",
      server_url: "https://api.githubcopilot.com/mcp",
      require_approval: "always",
      project_connection_id: mcpProjectConnectionId,
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Полный пример кода смотрите в agentMcpConnectionAuth.ts.

Агент-агент (A2A) (Предварительный просмотр)

Обеспечить многоагентную кооперацию, при которой агенты могут общаться и делегировать задачи другим специализированным агентам:

const a2aProjectConnectionId = process.env["A2A_PROJECT_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("MyA2AAgent", {
  kind: "prompt",
  model: deploymentName,
  instructions: "You are a helpful assistant.",
  // Define A2A tool for agent-to-agent communication
  tools: [
    {
      type: "a2a_preview",
      project_connection_id: a2aProjectConnectionId,
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Смотрите полный пример кода в agentAgentToAgent.ts.

OpenAPI с Project соединением

Вызовите внешние API, определённые спецификациями OpenAPI, с помощью аутентификации соединения проекта:

const tripAdvisorProjectConnectionId = process.env["TRIPADVISOR_PROJECT_CONNECTION_ID"] || "";
function loadOpenApiSpec(specPath: string): unknown {
  if (!fs.existsSync(specPath)) {
    throw new Error(`OpenAPI specification not found at: ${specPath}`);
  }
  try {
    const data = fs.readFileSync(specPath, "utf-8");
    return JSON.parse(data);
  } catch (error) {
    throw new Error(`Failed to read or parse OpenAPI specification at ${specPath}: ${error}`);
  }
}
const tripAdvisorSpecPath = path.resolve(__dirname, "../assets", "tripadvisor_openapi.json");
const tripAdvisorSpec = loadOpenApiSpec(tripAdvisorSpecPath);
const agent = await project.agents.createVersion("MyOpenApiConnectionAgent", {
  kind: "prompt",
  model: deploymentName,
  instructions:
    "You are a travel assistant that consults the TripAdvisor Content API via project connection to answer user questions about locations.",
  tools: [
    {
      type: "openapi",
      openapi: {
        name: "get_tripadvisor_location_details",
        description:
          "Fetch TripAdvisor location details, reviews, or photos using the Content API via project connection auth.",
        spec: tripAdvisorSpec,
        auth: {
          type: "project_connection",
          security_scheme: {
            project_connection_id: tripAdvisorProjectConnectionId,
          },
        },
      },
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Полный пример кода смотрите в agentOpenApiConnectionAuth.ts.

Полные рабочие примеры всех инструментов смотрите в каталоге samples-dev.

Evaluation

Клиентская библиотека Azure AI Project Evaluation предоставляет количественные, с помощью искусственного интеллекта метрики качества и безопасности для оценки производительности и оценки моделей LLM, приложений GenAI и агентов. Метрики определяются как оценщики. Встроенные или индивидуальные оценщики могут предоставить всестороннюю оценочную аналитику.

Код ниже показывает некоторые операции оценки. Полный список образцов можно найти в папке «оценки» в package samples

const openAIClient = project.getOpenAIClient();
const dataSourceConfig = {
  type: "custom" as const,
  item_schema: {
    type: "object",
    properties: { query: { type: "string" } },
    required: ["query"],
  },
  include_sample_schema: true,
};
const evalObject = await openAIClient.evals.create({
  name: "Agent Evaluation",
  data_source_config: dataSourceConfig,
  testing_criteria: [
    {
      type: "azure_ai_evaluator",
      name: "violence_detection",
      evaluator_name: "builtin.violence",
      data_mapping: { query: "{{item.query}}", response: "{{item.response}}" },
    } as any,
  ],
});
console.log(`Evaluation created (id: ${evalObject.id}, name: ${evalObject.name})`);

Полный пример кода см. в agentEvaluation.ts.

Операции по развертыванию

В коде ниже показаны некоторые операции развертывания, которые позволяют перечислять модели ИИ, развернутые в ваших проектах Майкрософт Foundry. Эти модели можно увидеть во вкладке «Модели + конечные точки» в вашем Майкрософт Foundry Project. Полные сэмплы можно найти в папке "deployment" в package samples.

import { ModelDeployment } from "@azure/ai-projects";

const modelPublisher = process.env["MODEL_PUBLISHER"] || "<model publisher>";
console.log("List all deployments:");
const deployments: ModelDeployment[] = [];
const properties: Array<Record<string, string>> = [];

for await (const deployment of project.deployments.list()) {
  // Check if this is a ModelDeployment (has the required properties)
  if (
    deployment.type === "ModelDeployment" &&
    "modelName" in deployment &&
    "modelPublisher" in deployment &&
    "modelVersion" in deployment
  ) {
    deployments.push(deployment);
    properties.push({
      name: deployment.name,
      modelPublisher: deployment.modelPublisher,
      modelName: deployment.modelName,
    });
  }
}
console.log(`Retrieved deployments: ${JSON.stringify(properties, null, 2)}`);

// List all deployments by a specific model publisher (assuming we have one from the list)
console.log(`List all deployments by the model publisher '${modelPublisher}':`);
const filteredDeployments: ModelDeployment[] = [];
for await (const deployment of project.deployments.list({
  modelPublisher,
})) {
  // Check if this is a ModelDeployment
  if (
    deployment.type === "ModelDeployment" &&
    "modelName" in deployment &&
    "modelPublisher" in deployment &&
    "modelVersion" in deployment
  ) {
    filteredDeployments.push(deployment);
  }
}
console.log(
  `Retrieved ${filteredDeployments.length} deployments from model publisher '${modelPublisher}'`,
);

// Get a single deployment by name
if (deployments.length > 0) {
  const deploymentName = deployments[0].name;
  console.log(`Get a single deployment named '${deploymentName}':`);
  const singleDeployment = await project.deployments.get(deploymentName);
  console.log(`Retrieved deployment: ${JSON.stringify(singleDeployment, null, 2)}`);
}

Операции с подключениями

В коде ниже показаны некоторые операции Connection, которые позволяют перечислять ресурсы Azure, подключённые к вашим проектам Майкрософт Foundry. Эти соединения можно увидеть в разделе «Центр управления», во вкладке «Связанные ресурсы» в вашем Майкрософт Foundry Project. Полные сэмплы можно найти в папке "connections" в package samples.

import { Connection } from "@azure/ai-projects";

// List the details of all the connections
const connections: Connection[] = [];
const connectionNames: string[] = [];
for await (const connection of project.connections.list()) {
  connections.push(connection);
  connectionNames.push(connection.name);
}
console.log(`Retrieved connections: ${connectionNames}`);

// Get the details of a connection, without credentials
const connectionName = connections[0].name;
const connection = await project.connections.get(connectionName);
console.log(`Retrieved connection ${JSON.stringify(connection, null, 2)}`);

const connectionWithCredentials = await project.connections.getWithCredentials(connectionName);
console.log(
  `Retrieved connection with credentials ${JSON.stringify(connectionWithCredentials, null, 2)}`,
);

// List all connections of a specific type
const azureAIConnections: Connection[] = [];
for await (const azureOpenAIConnection of project.connections.list({
  connectionType: "AzureOpenAI",
  defaultConnection: true,
})) {
  azureAIConnections.push(azureOpenAIConnection);
}
console.log(`Retrieved ${azureAIConnections.length} Azure OpenAI connections`);

// Get the details of a default connection
const defaultConnection = await project.connections.getDefault("AzureOpenAI", {
  includeCredentials: true,
});
console.log(`Retrieved default connection ${JSON.stringify(defaultConnection, null, 2)}`);

Операции с набором данных

В приведенном ниже коде показаны некоторые операции с набором данных. Полные сэмплы можно найти в папке "datasets" в package samples.

import { DatasetVersionUnion } from "@azure/ai-projects";

const VERSION1 = "1.0";
const VERSION2 = "2.0";
const VERSION3 = "3.0";

// sample files to use in the demonstration
const sampleFolder = "sample_folder";
// Create a unique dataset name for this sample run
const datasetName = `sample-dataset-basic`;
console.log("Upload a single file and create a new Dataset to reference the file.");
console.log("Here we explicitly specify the dataset version.");

const dataset1 = await project.datasets.uploadFile(
  datasetName,
  VERSION1,
  path.join(__dirname, sampleFolder, "sample_file1.txt"),
);
console.log("Dataset1 created:", JSON.stringify(dataset1, null, 2));

const credential = project.datasets.getCredentials(dataset1.name, dataset1.version, {});
console.log("Credential for the dataset:", credential);
console.log(
  "Upload all files in a folder (including subfolders) to the existing Dataset to reference the folder.",
);
console.log("Here again we explicitly specify a new dataset version");
const dataset2 = await project.datasets.uploadFolder(
  datasetName,
  VERSION2,
  path.join(__dirname, sampleFolder),
);
console.log("Dataset2 created:", JSON.stringify(dataset2, null, 2));
console.log(
  "Upload a single file to the existing dataset, while letting the service increment the version",
);
const dataset3 = await project.datasets.uploadFile(
  datasetName,
  VERSION3,
  path.join(__dirname, sampleFolder, "sample_file2.txt"),
);
console.log("Dataset3 created:", JSON.stringify(dataset3, null, 2));

console.log("Get an existing Dataset version `1`:");
const datasetVersion1 = await project.datasets.get(datasetName, VERSION1);
console.log("Dataset version 1:", JSON.stringify(datasetVersion1, null, 2));
console.log(`Listing all versions of the Dataset named '${datasetName}':`);
const datasetVersions = project.datasets.listVersions(datasetName);
for await (const version of datasetVersions) {
  console.log("List versions:", version);
}
console.log("List latest versions of all Datasets:");
const latestDatasets = project.datasets.list();
for await (const dataset of latestDatasets) {
  console.log("List datasets:", dataset);
}
// List the details of all the datasets
const datasets = project.datasets.listVersions(datasetName);
const allDatasets: DatasetVersionUnion[] = [];
for await (const dataset of datasets) {
  allDatasets.push(dataset);
}
console.log(`Retrieved ${allDatasets.length} datasets`);
console.log("Delete all Datasets created above:");
await project.datasets.delete(datasetName, VERSION1);
await project.datasets.delete(datasetName, VERSION2);
await project.datasets.delete(datasetName, dataset3.version);
console.log("All specified Datasets have been deleted.");

Операции с файлами

В приведенном ниже коде показаны некоторые операции с файлами с использованием клиента OpenAI, которые позволяют загружать, извлекать, перечислять и удалять файлы. Эти операции полезны для работы с файлами, которые можно использовать для тонкой настройки и других операций модели ИИ. Полные сэмплы можно найти в папке "files" в package samples.

const openAIClient = project.getOpenAIClient();
console.log("Uploading file");
const created = await openAIClient.files.create({
  file: fs.createReadStream(filePath),
  purpose: "fine-tune",
});
console.log(`Uploaded file with ID: ${created.id}`);
const uploadedFile = await openAIClient.files.retrieve(created.id);
console.log("Processed file metadata:\n", JSON.stringify(uploadedFile, null, 2));
console.log(`Retrieving file content with ID: ${uploadedFile.id}`);
const contentResponse = await openAIClient.files.content(uploadedFile.id);
const buf = Buffer.from(await contentResponse.arrayBuffer());
console.log(buf.toString("utf-8"));
// 4) List all files
console.log("Listing all files:");
const filesList = await openAIClient.files.list();
for (const f of filesList.data ?? []) {
  console.log(JSON.stringify(f));
}
// 5) Delete the file
console.log(`Deleting file with ID: ${uploadedFile.id}`);
const deleted = await openAIClient.files.delete(uploadedFile.id);
console.log(
  `Successfully deleted file: ${deleted?.id || uploadedFile.id}, deleted=${String(deleted?.deleted ?? true)}`,
);

Операции с индексами

В приведенном ниже коде показаны некоторые операции с индексами. Полные образцы можно найти в папке "indexes" в package samples.

import { AzureAISearchIndex } from "@azure/ai-projects";

const indexName = "sample-index";
const version = "1";
const azureAIConnectionConfig: AzureAISearchIndex = {
  name: indexName,
  type: "AzureSearch",
  version,
  indexName,
  connectionName: "sample-connection",
};

// Create a new Index
const newIndex = await project.indexes.createOrUpdate(indexName, version, azureAIConnectionConfig);
console.log("Created a new Index:", newIndex);
console.log(`Get an existing Index version '${version}':`);
const index = await project.indexes.get(indexName, version);
console.log(index);
console.log(`Listing all versions of the Index named '${indexName}':`);
const indexVersions = project.indexes.listVersions(indexName);
for await (const indexVersion of indexVersions) {
  console.log(indexVersion);
}
console.log("List all Indexes:");
const allIndexes = project.indexes.list();
for await (const i of allIndexes) {
  console.log("Index:", i);
}
console.log("Delete the Index versions created above:");
await project.indexes.delete(indexName, version);

Операции тонкой настройки

Код ниже показывает, как создавать задания для тонкой настройки с помощью клиента OpenAI. Эти операции поддерживают различные методы тонкой настройки, такие как Supervised Fine-Tuning (SFT), Reinforcement Fine-Tuning (RFT) и Direct Performance Optimization (DPO). Полные сэмплы можно найти в папке «finetuning» в package samples.

import { JobCreateParams } from "openai/resources/fine-tuning/jobs";

const trainingFilePath = "training_data_path.jsonl";
const validationFilePath = "validation_data_path.jsonl";
const openAIClient = project.getOpenAIClient();
// 1) Create the training and validation files
const trainingFile = await openAIClient.files.create({
  file: fs.createReadStream(trainingFilePath),
  purpose: "fine-tune",
});
console.log(`Uploaded file with ID: ${trainingFile.id}`);
const validationFile = await openAIClient.files.create({
  file: fs.createReadStream(validationFilePath),
  purpose: "fine-tune",
});
console.log(`Uploaded file with ID: ${validationFile.id}`);
// 2) Wait for the files to be processed
await openAIClient.files.waitForProcessing(trainingFile.id);
await openAIClient.files.waitForProcessing(validationFile.id);
console.log("Files processed.");
// 3) Create a supervised fine-tuning job
const fineTuningJob = await openAIClient.fineTuning.jobs.create({} as JobCreateParams, {
  body: {
    trainingType: "Standard",
    training_file: trainingFile.id,
    validation_file: validationFile.id,
    model: deploymentName,
    method: {
      type: "supervised",
      supervised: {
        hyperparameters: {
          n_epochs: 3,
          batch_size: 1,
          learning_rate_multiplier: 1.0,
        },
      },
    },
  },
});
console.log("Created fine-tuning job:\n", JSON.stringify(fineTuningJob));

Трассировка

Заметка: Функция трассировки находится в предварительной предварительной версии и может быть изменена. Диапазоны, атрибуты и события могут быть изменены в будущих версиях.

Вы можете добавить ресурс Application Insights Azure в свой проект Майкрософт Foundry. Смотрите вкладку Tracing в вашем проекте Майкрософт Foundry. Если она включена, вы можете получить строка подключения Application Insights, настроить клиент AI Projects и наблюдать полный путь выполнения через Azure Monitor. Как правило, вы можете начать трассировку до создания клиента или агента.

Installation

npm install @azure/monitor-opentelemetry@^1.14.2 @opentelemetry/api@^1.9.0

Как включить трассировку

Вот пример кода, который показывает, как включить трассировку Azure Monitor:

import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";

const TELEMETRY_CONNECTION_STRING = process.env["TELEMETRY_CONNECTION_STRING"];
const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString: TELEMETRY_CONNECTION_STRING,
  },
};
useAzureMonitor(options);

См. полный пример кода в remoteTelemetry.ts.

Устранение неполадок

Исключения

Клиентские методы, которые вызывают службы, вызывают RestError для ответа кода состояния HTTP без успешного выполнения из службы. code исключения будет содержать код состояния HTTP-ответа. error.message исключения содержит подробное сообщение, которое может оказаться полезным при диагностике проблемы:

import { isRestError } from "@azure/core-rest-pipeline";

try {
  const result = await project.connections.list();
} catch (e) {
  if (isRestError(e)) {
    console.log(`Status code: ${e.code}`);
    console.log(e.message);
  } else {
    console.error(e);
  }
}

Например, если указать неправильные учетные данные:

Status code: 401 (Unauthorized)
Operation returned an invalid status 'Unauthorized'

проблемы с отчетами

Чтобы сообщить о проблемах с клиентской библиотекой или запросить дополнительные функции, пожалуйста, откройте GitHub выпуск здесь

Дальнейшие действия

Посмотрите папку package samples с полностью загруженным кодом.

участие

Этот проект приветствует взносы и предложения. Большинство вкладов требуют, чтобы вы согласились с соглашением о лицензии участника (CLA), заявив, что у вас есть право, и на самом деле, предоставьте нам права на использование вашего вклада. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на вытягивание бот CLA автоматически определяет, нужно ли предоставить соглашение об уровне обслуживания и украсить pr соответствующим образом (например, метка, комментарий). Просто следуйте инструкциям, предоставленным ботом. Это необходимо сделать только один раз во всех репозиториях с помощью нашего CLA.

В этом проекте принят Майкрософт Open Source Code of Conduct. Дополнительные сведения см. в разделе "Часто задаваемые вопросы о поведении" или opencode@microsoft.com с дополнительными вопросами или комментариями.