Bibliothèque client Azure AI Projects pour JavaScript - version 2.0.1

La bibliothèque client AI Projects (en aperçu) fait partie du SDK Microsoft Foundry et offre un accès facile aux ressources de votre Microsoft Foundry Project. Utilisez-le pour :

• Créez et exécutez des agents à l’aide de la .agents propriété sur le client.

• Améliorez les agents avec des outils spécialisés :
  • Recherche de mémoire d’agent (Aperçu)
  • Agent-à-agent (A2A) (Aperçu)
  • Azure AI Search
  • Recherche personnalisée Bing (Aperçu)
  • Bing Grounding
  • Automatisation du navigateur (Aperçu)
  • Interpréteur de code
  • Utilisation de l’ordinateur (Aperçu)
  • Recherche de fichiers
  • Outil de fonction
  • Génération d’images
  • Microsoft Fabric (Aperçu)
  • Protocole de Contexte Modèle (MCP)
  • OpenAPI
  • Microsoft SharePoint (Aperçu)
  • Recherche Web (Aperçu)

• Obtenez un client OpenAI utilisant cette .getOpenAIClient. méthode pour exécuter des réponses, des conversations, des évaluations et des opérations de fineTuning avec votre agent.

• Gérer les mémoires (aperçu) pour les conversations Agent, en utilisant les .beta.memoryStores opérations.
• Explorez d’autres outils d’évaluation (certains en aperçu) pour évaluer la performance de votre application d’IA générative, en utilisant les .evaluationRules, .beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, et .beta.schedules les opérations.
• Effectuez des analyses de l’équipe rouge (aperçu) pour identifier les risques liés à votre application d’IA générative, en utilisant les .beta.redTeams opérations.
• Affiner Modèles d’IA sur vos données.

• Énumérez les modèles d’IA déployés dans votre projet de fonderie à l’aide des .deployments opérations.
• Énumérez les ressources Azure connectées dans votre projet Foundry en utilisant les opérations .connections.
• Téléchargez des documents et créez des jeux de données pour les référencer à l’aide des .datasets opérations.
• Créez et énumérez des index de recherche à l’aide des .indexes opérations.

La bibliothèque cliente utilise la version v1 des API REST du plan de données Microsoft Foundry.

Documentation produit | Samples | Package (npm) | API documentation de référence | SDK

Table des matières

• Premiers pas
  • Prerequisite
  • Autorisation
  • Installer le package
• Concepts clés
  • créer et authentifier le client
  • Groupes d’opérations d’aperçu et drapeaux de fonctionnalités d’opt-in
• Exemples
  • Exécution d’opérations de réponses à l’aide du client OpenAI
  • Exécution d’opérations de l’Agent
  • Utilisation des outils Agent
    • Outils intégrés
    • Connection-Based Outils
  • Opérations d’évaluation
  • Opérations de déploiements
  • Opérations de connexions
  • Opérations sur les ensembles de données
  • Opérations sur les fichiers
  • Opérations d’indexation
  • Opérations d’ajustement fin
• Suivi
  • Installation
  • Comment activer le traçage
• Résolution des problèmes
  • Exceptions
  • Les problèmes de création de rapports
• Étapes suivantes
• contribution

Premiers pas

Prérequis

• Versions LTS de Node.js
• Un abonnement Azure.
• Un projet dans Microsoft Foundry.
• L’URL du point de terminaison du projet du formulaire https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name. Vous pouvez le trouver sur votre page d’aperçu du projet Microsoft Foundry. Ci-dessous, nous supposerons que la variable AZURE_AI_PROJECT_ENDPOINT d’environnement a été définie pour maintenir cette valeur.

Autorisation

• Un identifiant Entra est nécessaire pour authentifier le client. Votre application a besoin d’un objet qui implémente l’interface TokenCredential. Des exemples de code ici utilisent DefaultAzureCredential. Pour travailler, vous aurez besoin des éléments suivants :
  • Un rôle approprié. voir Contrôle d’accès basé sur les rôles dans le portail Microsoft Foundry. Le rôle attribué peut être effectué via l’onglet « Access Control (IAM) » de votre ressource Azure AI Project dans le portail Azure.
  • Azure CLI installé.
  • Vous êtes connecté à votre compte Azure en lançant az login.
  • Notez que si vous avez plusieurs abonnements Azure, l’abonnement contenant votre ressource Azure AI Project doit être votre abonnement par défaut. Exécutez az account list --output table pour répertorier l’ensemble de votre abonnement et voir lequel est la valeur par défaut. Exécutez az account set --subscription "Your Subscription ID or Name" pour modifier votre abonnement par défaut.

Installer le package

npm install @azure/ai-projects dotenv

Concepts clés

Créez et authentifiez le client avec Entra ID

Entra ID est la seule méthode d’authentification prise en charge actuellement par le client.

Pour construire un AIProjectsClient, vous pouvez extraire le projectEndpoint à partir de projectEndpoint. Ci-dessous, nous supposerons que la variable AZURE_AI_PROJECT_ENDPOINT d’environnement a été définie pour contenir cette valeur :

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

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

Groupes d’opérations d’aperçu et drapeaux de fonctionnalités d’opt-in

Certaines opérations d’aperçu nécessitent un drapeau explicite foundryFeatures d’adhésion. Par exemple:

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

Les groupes d’opérations d’aperçu incluent .beta.memoryStores, .beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, .beta.schedules, et .beta.redTeams.

Exemples

Exécution d’opérations de réponses à l’aide du client OpenAI

Votre projet Microsoft Foundry peut avoir un ou plusieurs modèles d’IA déployés. Il peut s’agir de modèles OpenAI, de modèles Microsoft ou de modèles d’autres fournisseurs. Utilisez le code ci-dessous pour obtenir un OpenAI authentifié à partir du package openai et exécuter un appel de complétion de chat.

Exécutez le code ci-dessous. Ici, nous supposons que deploymentName (str) est défini. Il s’agit du nom de déploiement d’un modèle d’IA dans votre projet Foundry. Comme indiqué dans l’onglet « Modèles + points de terminaison », sous la colonne « Nom ».

Voir le dossier « réponses » dans le package samples pour des exemples supplémentaires, y compris les réponses en streaming.

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));

Exécution d’opérations de l’Agent

La .agents propriété sur le vous donne accès à toutes les opérations de l’Agent AIProjectsClient . Les agents utilisent une extension du protocole OpenAI Responses, de sorte que vous devrez probablement demander à un client d’effectuer des OpenAI opérations d’agent, comme le montre l’exemple ci-dessous.

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");

Utilisation des outils Agent

Les agents peuvent être améliorés avec des outils spécialisés pour diverses fonctionnalités. Les outils sont organisés selon leurs besoins de connexion :

Outils intégrés

Ces outils fonctionnent immédiatement sans nécessiter de connexions externes.

Interpréteur de code

Écrire et exécuter du code Javascript dans un environnement en boîte à sable, traiter des fichiers et travailler avec divers formats de données. Documentation 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}`);

Voir le code d’exemple complet dans agentCodeInterpreter.ts.

Recherche de fichiers

Outil RAG (générationRetrieval-Augmented) intégré pour traiter et rechercher des documents via des magasins vectoriels pour la recherche de connaissances. Documentation 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})`);

Voir le code d’exemple complet dans agentFileSearchStream.ts.

Génération d’images

Générez des images à partir d’invites textuelles avec des réglages personnalisables de résolution, de qualité et de style :

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})`);

Après avoir appelé responses.create(), vous pouvez télécharger le fichier en utilisant la réponse retournée :

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.");
}

Recherche Web (Aperçu)

Effectuez des recherches générales sur le web pour obtenir des informations actuelles sur Internet. Documentation 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}`);

Voir le code d’exemple complet dans agentWebSearch.ts.

Utilisation de l’ordinateur (Aperçu)

Permettre aux agents d’interagir directement avec les systèmes informatiques pour l’automatisation des tâches et les opérations système :

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})`);

Après avoir appelé responses.create(), traite la réponse dans une boucle d’interaction. Gérez computer_call les éléments de sortie et fournissez des captures d’écran comme computer_call_output le computer_screenshot type pour poursuivre l’interaction.

Voir le code d’exemple complet dans agentComputerUse.ts.

Protocole de Contexte de Modèle (MCP)

Intégrez les serveurs MCP pour étendre les capacités des agents avec des outils et ressources standardisés. Documentation 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" } },
  },
);

Après avoir appelé responses.create(), vérifiez s’il y a mcp_approval_request des éléments dans la sortie de la réponse. Renvoyez McpApprovalResponse votre décision d’approbation permettant à l’agent de poursuivre son travail.

Voir le code d’exemple complet dans agentMcp.ts.

OpenAPI

Appelez des API externes définies par les spécifications OpenAPI sans code client supplémentaire. Documentation 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})`);

Voir le code d’exemple complet dans agentOpenApi.ts.

Outil de fonction

Définir des fonctions personnalisées permettant aux agents d’interagir avec des API externes, des bases de données ou de la logique applicative. Documentation 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})`);

Après avoir appelé responses.create(), traite function_call les éléments de la sortie de la réponse, exécute la logique de la fonction avec les arguments fournis, puis renvoie FunctionCallOutput les résultats.

Voir le code d’exemple complet dans agentFunctionTool.ts.

• Outil de recherche de mémoire (Aperçu)

L’outil de stockage de mémoire ajoute la mémoire à un agent, permettant au modèle IA de l’agent de rechercher des informations passées liées à la demande utilisateur actuelle.

Le embeddingModelDeployment nom du modèle utilisé pour créer des embeddings vectoriels pour stocker et rechercher des mémoires.

const memoryStoreName = "AgentMemoryStore";
const embeddingModelDeployment =
  process.env["AZURE_AI_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
    },
  ],
});

Voir le code d’exemple complet dans agentMemorySearch.ts.

Connection-Based Outils

Ces outils nécessitent de configurer les connexions dans votre projet AI Foundry et d’utiliser projectConnectionId.

Recherche d’IA Azure

Intégrez les index Azure AI Search pour des capacités puissantes de recherche de connaissances et de recherche sémantique :

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})`);

Voir le code d’exemple complet dans agentAiSearch.ts.

Fondation Bing

Réponses des agents au sol avec des résultats de recherche web en temps réel de Bing pour fournir des informations up-todate :

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})`);

Voir le code d’exemple complet dans agentBingGrounding.ts.

Recherche personnalisée Bing (Aperçu)

Utilisez des instances de recherche Bing configurées sur mesure pour des résultats web spécifiques à un domaine ou filtrés :

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})`);

Voir le code d’exemple complet dans agentBingCustomSearch.ts.

Microsoft Fabric (Aperçu)

Connectez-vous à Microsoft Fabric et interrogez :

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})`);

Voir le code d’exemple complet dans agentFabric.ts.

Microsoft SharePoint (Aperçu)

Accédez et recherchez les documents, listes et sites SharePoint pour l’intégration des connaissances d’entreprise :

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})`);

Voir le code d’exemple complet dans agentSharepoint.ts.

Automatisation du navigateur (Aperçu)

Automatisez les interactions des navigateurs pour le web scraping, les tests et l’interaction avec des applications web :

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})`);

Voir le code d’exemple complet dans agentBrowserAutomation.ts.

MCP avec Project Connection

Intégration MCP en utilisant des connexions spécifiques au projet pour accéder aux serveurs MCP connectés :

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})`);

Voir le code d’exemple complet dans agentMcpConnectionAuth.ts.

Agent-à-agent (A2A) (Aperçu)

Permettre la collaboration multi-agents où les agents peuvent communiquer et déléguer des tâches à d’autres agents spécialisés :

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})`);

Voir le code d’exemple complet dans agentAgentToAgent.ts.

OpenAPI avec connexion au projet

Appelez les API externes définies par les spécifications OpenAPI en utilisant l’authentification de connexion de projet :

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})`);

Voir le code d’exemple complet dans agentOpenApiConnectionAuth.ts.

Pour des exemples complets fonctionnels de tous les outils, voir le dossier samples-dev.

Evaluation

L’évaluation dans la bibliothèque client Azure AI Project fournit des indicateurs quantitatifs de qualité et de sécurité assistés par l’IA pour évaluer la performance et évaluer les modèles LLM, les applications GenAI et les agents. Les métriques sont définies comme des évaluateurs. Les évaluateurs intégrés ou personnalisés peuvent fournir des analyses complètes.

Le code ci-dessous montre quelques opérations d’évaluation. La liste complète des échantillons se trouve dans le dossier « évaluations » dans le <échantillons >emballage c0

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})`);

Voir le code d’exemple complet dans agentEvaluation.ts.

Opérations de déploiements

Le code ci-dessous montre quelques opérations de déploiement, qui vous permettent d’énumérer les modèles d’IA déployés dans vos projets Microsoft Foundry. Ces modèles peuvent être consultés dans l’onglet « Modèles + points de terminaison » de votre projet Microsoft Foundry. Des échantillons complets se trouvent dans le dossier « deployment » dans les échantillons packages.

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)}`);
}

Opérations de connexions

Le code ci-dessous présente quelques opérations de connexion, qui vous permettent d’énumérer les ressources Azure connectées à vos projets Microsoft Foundry. Ces connexions sont visibles dans le « Centre de gestion », dans l’onglet « Ressources connectées » de votre projet Microsoft Foundry. Les échantillons complets se trouvent dans le dossier « connections » dans le 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)}`);

Opérations sur les ensembles de données

Le code ci-dessous montre certaines opérations de jeu de données. Des échantillons complets se trouvent dans le dossier « datasets » dans le 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.");

Opérations sur les fichiers

Le code ci-dessous montre certaines opérations Files à l’aide du client OpenAI, qui vous permettent de télécharger, récupérer, répertorier et supprimer des fichiers. Ces opérations sont utiles pour travailler avec des fichiers qui peuvent être utilisés pour le réglage fin et d’autres opérations de modèle d’IA. Des échantillons complets se trouvent dans le dossier « fichiers » dans le 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)}`,
);

Opérations d’indexation

Le code ci-dessous montre quelques opérations d’index. Des échantillons complets se trouvent dans le dossier « index » dans le 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);

Opérations de réglage précis

Le code ci-dessous montre comment créer des tâches d’ajustement fin à l’aide du client OpenAI. Ces opérations supportent diverses techniques d’ajustement fin telles que le Fine-Tuning supervisé (SFT), le Fine-Tuning de renforcement (RFT) et l’optimisation directe de performance (DPO). Les échantillons complets se trouvent dans le dossier « finetuning » dans le <échantillons >c0.

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));

Suivi

Note: La fonctionnalité de traçage en est à l’état d’aperçu préliminaire et est susceptible d’être modifiée. Les spans, les attributs et les événements peuvent être modifiés dans les versions ultérieures.

Vous pouvez ajouter une ressource Application Insights Azure à votre projet Microsoft Foundry. Consultez l’onglet Suivi dans votre projet Microsoft Foundry. Si l’une d’elles est activée, vous pouvez obtenir la connection string Application Insights, configurer votre client AI Projects, et observer le chemin d’exécution complet via Azure Monitor. En règle générale, vous pouvez commencer le suivi avant de créer un client ou un agent.

Installation

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

Comment activer le traçage

Voici un exemple de code qui montre comment activer le traçage 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);

Voir le code d’exemple complet dans remoteTelemetry.ts.

résolution des problèmes

Exceptions

Les méthodes clientes qui effectuent des appels de service déclenchent une RestError pour une réponse de code d’état HTTP non réussie du service. La code de l’exception contiendra le code d’état de la réponse HTTP. Le error.message de l’exception contient un message détaillé qui peut être utile pour diagnostiquer le problème :

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);
  }
}

Par exemple, lorsque vous fournissez des informations d’identification incorrectes :

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

Les problèmes de création de rapports

Pour signaler des problèmes avec la bibliothèque client ou demander des fonctionnalités supplémentaires, veuillez ouvrir un problème GitHub ici

Étapes suivantes

Jetez un œil au dossier package samples, contenant du code entièrement exécutable.

contribution

Ce projet accueille les contributions et suggestions. La plupart des contributions vous obligent à accepter un contrat de licence contributeur (CLA) déclarant que vous avez le droit, et en fait, de nous accorder les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Lorsque vous envoyez une demande de tirage( pull request), un bot CLA détermine automatiquement si vous devez fournir un CLA et décorer correctement la demande de tirage (par exemple, étiquette, commentaire). Suivez simplement les instructions fournies par le bot. Vous n’aurez besoin de le faire qu’une seule fois sur tous les dépôts à l’aide de notre CLA.

Ce projet a adopté le Code de conduite Open Source Microsoft. Pour plus d’informations, consultez la FAQ sur le code de conduite ou contactez opencode@microsoft.com avec toutes les questions ou commentaires supplémentaires.