Freigeben über

Azure AI Projects client library for JavaScript - version 2.0.1

Die AI-Projekte-Clientbibliothek (in der Vorschau) ist Teil des Microsoft Foundry SDK und bietet einfachen Zugriff auf Ressourcen in Ihrem Microsoft Foundry Projekt. Verwenden Sie es zu folgenden Zwecken:

  • Erstellen und führen Sie Agents mithilfe der .agents Eigenschaft auf dem Client aus.
  • Verbessern Sie Agenten mit spezialisierten Werkzeugen:
    • Agent Speichersuche (Vorschau)
    • Agent-zu-Agent (A2A) (Vorschau)
    • Azure AI Search
    • Bing Benutzerdefinierte Suche (Vorschau)
    • Bing-Verankerung
    • Browser-Automatisierung (Vorschau)
    • Codedolmetscher
    • Computernutzung (Vorschau)
    • Dateisuche
    • Funktionswerkzeug
    • Bilderzeugung
    • Microsoft Fabric (Vorschau)
    • Modellkontextprotokoll (MCP)
    • OpenAPI
    • Microsoft SharePoint (Vorschau)
    • Websuche (Vorschau)
  • Erhalten Sie einen OpenAI-Client mit der Methode .getOpenAIClient. , um Antworten, Gespräche, Bewertungen und FineTuning-Operationen mit Ihrem Agenten durchzuführen.
  • Verwalten Sie Speicherspeicher (Vorschau) für Agentenkonversationen und nutzen Sie die Operationen .beta.memoryStores .
  • Entdecken Sie zusätzliche Bewertungstools (einige in der Vorschau), um die Leistung Ihrer generativen KI-Anwendung mithilfe der .evaluationRules, .beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, und .beta.schedules Operationen zu bewerten.
  • Führen Sie Red-Team-Scans (Vorschau) durch , um Risiken im Zusammenhang mit Ihrer generativen KI-Anwendung mithilfe der Operationen zu .beta.redTeams identifizieren.
  • Feinabstimmung KI modelliert deine Daten.
  • Listen Sie KI-Modelle auf, die in Ihrem Foundry-Projekt mithilfe der .deployments Vorgänge bereitgestellt wurden.
  • Enumeriere verbundene Azure Ressourcen in deinem Foundry-Projekt mit den .connections Operationen.
  • Laden Sie Dokumente hoch und erstellen Sie Datensätze, um sie mithilfe der .datasets Vorgänge zu referenzieren.
  • Erstellen und Auflisten von Suchindizes mithilfe der .indexes Vorgänge.

Die Clientbibliothek verwendet die Version v1 der REST-APIs der Microsoft Foundry-Datenebene.

Produktdokumentation | Samples | Package (npm) | API-Referenzdokumentation | SDK Quellcode

Inhaltsverzeichnis

Erste Schritte

Voraussetzung

  • LTS-Versionen von Node.js
  • Ein Azure Abonnement.
  • Ein Projekt in Microsoft Foundry.
  • Die Projektendpunkt-URL des Formulars https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name. Sie finden Sie auf Ihrer Microsoft Foundry Project Übersichtsseite. Im Folgenden nehmen wir an, dass die Umgebungsvariable AZURE_AI_PROJECT_ENDPOINT so definiert wurde, dass sie diesen Wert hält.

Autorisierung

  • Eine Entra-ID ist erforderlich, um den Client zu authentifizieren. Ihre Anwendung benötigt ein Objekt, das die TokenCredential Schnittstelle implementiert. Codebeispiele hier verwenden DefaultAzureCredential. Um dies zu erreichen, benötigen Sie Folgendes:
    • Eine angemessene Rollenzuweisung. siehe Rollenbasierte Zugriffskontrolle im Microsoft Foundry Portal. Die zugewiesene Rolle kann über den Tab "Access Control (IAM)" in Ihrer Azure AI Project Ressource im Azure-Portal erfolgen.
    • Azure CLI installiert.
    • Du bist in deinem Azure Konto eingeloggt, indem du az login ausführst.
    • Beachten Sie, dass bei mehreren Azure-Abonnements das Abonnement, das Ihre Azure AI Project Ressource enthält, Ihr Standardabonnement sein muss. Führen Sie az account list --output table aus, um ihr gesamtes Abonnement auflisten und zu sehen, welche Standardeinstellung ist. Führen Sie az account set --subscription "Your Subscription ID or Name" aus, um Ihr Standardabonnement zu ändern.

Installieren des Pakets

npm install @azure/ai-projects dotenv

Zentrale Konzepte

Erstellen und authentifizieren Sie den Client mit der Entra-ID

Die Entra-ID ist derzeit die einzige Authentifizierungsmethode, die vom Client unterstützt wird.

Um ein zu AIProjectsClienterstellen, kann das projectEndpoint von projectEndpoint abgerufen werden. Im Folgenden gehen wir davon aus, dass die Umgebungsvariable AZURE_AI_PROJECT_ENDPOINT so definiert wurde, dass sie diesen Wert enthält:

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

Vorschau-Operationsgruppen und opt-in-Feature-Flags

Einige Vorschauoperationen erfordern eine explizite foundryFeatures Opt-in-Flagge. Beispiel:

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

Vorschau-Operationsgruppen umfassen .beta.memoryStores, .beta.evaluationTaxonomies, , .beta.evaluators, .beta.insights, .beta.schedulesund .beta.redTeams.

Beispiele

Ausführen von Antwortoperationen mit dem OpenAI-Client

Ihr Microsoft Foundry-Projekt könnte ein oder mehrere KI-Modelle eingebaut haben. Diese könnten OpenAI-Modelle, Microsoft-Modelle oder Modelle anderer Anbieter sein. Verwenden Sie den folgenden Code, um eine authentifizierte OpenAI aus dem openai-Paket abzurufen und einen Aufruf zur Chatvervollständigung auszuführen.

Führen Sie den folgenden Code aus. Hier gehen wir davon aus, dass deploymentName (str) definiert ist. Es handelt sich um den Bereitstellungsnamen eines KI-Modells in Ihrem Foundry-Projekt. Wie auf der Registerkarte "Modelle + Endpunkte" in der Spalte "Name" gezeigt.

Siehe den Ordner "responses" im Package Samples für weitere Beispiele, einschließlich Streaming-Antworten.

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

Ausführen von Agentenvorgängen

Mit der .agents Eigenschaft auf der AIProjectsClient erhalten Sie Zugriff auf alle Agent-Vorgänge. Agents verwenden eine Erweiterung des OpenAI Responses-Protokolls, sodass Sie wahrscheinlich einen OpenAI Client dazu bringen müssen, Agent-Vorgänge auszuführen, wie im folgenden Beispiel gezeigt.

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

Verwendung von Agent-Tools

Agenten können mit spezialisierten Werkzeugen für verschiedene Funktionen verbessert werden. Werkzeuge sind nach ihren Verbindungsanforderungen organisiert:

Eingebaute Werkzeuge

Diese Werkzeuge funktionieren sofort, ohne externe Verbindungen zu benötigen.

Codedolmetscher

Schreiben und ausführen Sie Javascript-Code in einer Sandbox-Umgebung, verarbeiten Sie Dateien und arbeiten Sie mit unterschiedlichen Datenformaten. OpenAI-Dokumentation

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

Siehe den vollständigen Beispielcode in agentCodeInterpreter.ts.

Dateisuche

Integriertes RAG (Retrieval-Augmented Generation)-Tool zur Verarbeitung und Durchsuchung von Dokumenten mit Vektorspeichern zur Wissensabruf. OpenAI-Dokumentation

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

Siehe den vollständigen Beispielcode in agentFileSearchStream.ts.

Bilderzeugung

Generiere Bilder basierend auf Textprompts mit anpassbaren Auflösungs-, Qualitäts- und Stileinstellungen:

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

Nach dem Anruf responses.create()können Sie die Datei mit der zurückgegebenen Antwort herunterladen:

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

Websuche (Vorschau)

Führen Sie allgemeine Websuchen durch, um aktuelle Informationen aus dem Internet abzurufen. OpenAI-Dokumentation

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

Siehe den vollständigen Beispielcode in agentWebSearch.ts.

Computernutzung (Vorschau)

Ermöglichen Sie Agenten, direkt mit Computersystemen für Aufgabenautomatisierung und Systembetrieb zu interagieren:

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

Nach dem Aufruf responses.create(), verarbeiten Sie die Antwort in einer Interaktionsschleife. Verwalten Sie computer_call Ausgabeobjekte und liefern Sie Screenshots wie computer_call_output mit computer_screenshot Typ, um die Interaktion fortzusetzen.

Siehe den vollständigen Beispielcode in agentComputerUse.ts.

Modellkontextprotokoll (MCP)

Integrieren Sie MCP-Server, um die Fähigkeiten der Agenten mit standardisierten Werkzeugen und Ressourcen zu erweitern. OpenAI-Dokumentation

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

Nach dem Anruf responses.create()prüfen Sie, ob mcp_approval_request die Antworten in der Antwortausgabe enthalten sind. Senden Sie die Entscheidung mit Ihrer Zustimmung zurück McpApprovalResponse , damit der Makler seine Arbeit fortsetzen kann.

Siehe den vollständigen Beispielcode in agentMcp.ts.

OpenAPI

Rufen Sie externe APIs auf, die durch OpenAPI-Spezifikationen definiert sind, ohne zusätzlichen clientseitigen Code. OpenAI-Dokumentation

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

Siehe den vollständigen Beispielcode in agentOpenApi.ts.

Funktionswerkzeug

Definieren Sie benutzerdefinierte Funktionen, die es Agenten ermöglichen, mit externen APIs, Datenbanken oder Anwendungslogik zu interagieren. OpenAI-Dokumentation

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

Nach dem Aufruf responses.create()verarbeitet α die function_call Elemente aus der Antwortausgabe, führt eure Funktionslogik mit den bereitgestellten Argumenten aus und sendet die Ergebnisse zurück FunctionCallOutput .

Siehe den vollständigen Beispielcode in agentFunctionTool.ts.

  • Speichersuchwerkzeug (Vorschau)

Das Memory Store Tool fügt einem Agenten Speicher hinzu, sodass das KI-Modell des Agenten nach vergangenen Informationen im Zusammenhang mit dem aktuellen Benutzerprompt suchen kann.

Dies embeddingModelDeployment ist der Name des Modells, das zur Erstellung von Vektor-Embeddings zum Speicheren und Durchsuchen von Speicher verwendet wird.

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

Siehe den vollständigen Beispielcode in agentMemorySearch.ts.

Connection-Based Werkzeuge

Diese Werkzeuge erfordern die Konfiguration von Verbindungen in Ihrem KI-Foundry-Projekt und der Nutzung projectConnectionIdvon .

Azure AI Search

Integration mit Azure AI Search-Indizes für leistungsstarke Wissensabruf- und semantische Suchfunktionen:

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

Siehe den vollständigen Beispielcode in agentAiSearch.ts.

Bing-Erdung

Bodenagenten antworten mit Echtzeit-Websuchergebnissen von Bing, um up-toDatumsinformationen bereitzustellen:

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

Siehe den vollständigen Beispielcode in agentBingGrounding.ts.

Bing Benutzerdefinierte Suche (Vorschau)

Verwenden Sie benutzerdefinierte Bing-Suchinstanzen für domänenspezifische oder gefilterte Websuchergebnisse:

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

Siehe den vollständigen Beispielcode in agentBingCustomSearch.ts.

Microsoft Fabric (Vorschau)

Verbinden Sie sich mit und fragen Sie Microsoft Fabric ab:

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

Siehe den vollständigen Beispielcode in agentFabric.ts.

Microsoft SharePoint (Vorschau)

Zugriff auf und Durchsuchung von SharePoint-Dokumenten, Listen und Seiten für die Integration von Unternehmenswissen:

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

Siehe den vollständigen Beispielcode in agentSharepoint.ts.

Browser-Automatisierung (Vorschau)

Automatisieren Sie Browser-Interaktionen für Webscraping, Testing und Interaktion mit Webanwendungen:

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

Siehe den vollständigen Beispielcode in agentBrowserAutomation.ts.

MCP mit Project Connection

MCP-Integration über projektspezifische Verbindungen zum Zugriff auf verbundene MCP-Server:

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

Siehe den vollständigen Beispielcode in agentMcpConnectionAuth.ts.

Agent-zu-Agent (A2A) (Vorschau)

Ermöglichen Sie die Zusammenarbeit mit mehreren Agenten, bei der Agenten kommunizieren und Aufgaben an andere spezialisierte Agenten delegieren können:

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

Siehe den vollständigen Beispielcode in agentAgentToAgent.ts.

OpenAPI mit Projektverbindung

Rufen Sie externe APIs auf, die durch OpenAPI-Spezifikationen definiert sind, mittels Projektverbindungsauthentifizierung:

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

Siehe den vollständigen Beispielcode in agentOpenApiConnectionAuth.ts.

Für vollständige funktionierende Beispiele aller Werkzeuge siehe das Verzeichnis samples-dev.

Evaluation

Die Bewertung in der Client-Bibliothek von Azure AI Project liefert quantitative, KI-unterstützte Qualitäts- und Sicherheitskennzahlen, um die Leistung zu bewerten und LLM-Modelle, GenAI-Anwendungen und Agenten zu evaluieren. Metriken werden als Evaluatoren definiert. Eingebaute oder individuelle Evaluatoren können umfassende Bewertungseinblicke liefern.

Der untenstehende Code zeigt einige Evaluationsoperationen. Die vollständige Liste der Proben findet sich im Ordner "Evaluations" im 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})`);

Siehe den vollständigen Beispielcode in agentEvaluation.ts.

Vorgänge für Bereitstellungen

Der folgende Code zeigt einige Bereitstellungsvorgänge, mit denen Sie die KI-Modelle auflisten können, die in Ihren Microsoft Foundry-Projekten bereitgestellt werden. Diese Modelle werden auf der Registerkarte "Modelle + Endpunkte" in Ihrem Microsoft Foundry-Projekt angezeigt. Vollständige Samples finden Sie im Ordner "deployment" im 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)}`);
}

Vorgänge "Verbindungen"

Der untenstehende Code zeigt einige Verbindungsoperationen, mit denen Sie die Azure-Ressourcen aufzählen können, die mit Ihren Microsoft Foundry-Projekten verbunden sind. Diese Verbindungen können im "Management Center", auf der Registerkarte "Verbundene Ressourcen" in Ihrem Microsoft Foundry-Projekt eingesehen werden. Vollständige Proben finden Sie im Ordner "Connections" im 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)}`);

Vorgänge mit Datasets

Der folgende Code zeigt einige Dataset-Vorgänge. Vollständige Samples finden Sie im Ordner "datasets" im 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.");

Vorgänge mit Dateien

Der folgende Code zeigt einige Dateien-Operationen mit dem OpenAI-Client, die es Ihnen ermöglichen, Dateien hochzuladen, abzurufen, aufzulisten und zu löschen. Diese Vorgänge sind nützlich für die Arbeit mit Dateien, die für die Feinabstimmung und andere KI-Modelloperationen verwendet werden können. Vollständige Samples finden Sie im Ordner "files" im 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)}`,
);

Operationen bei Indizes

Der folgende Code zeigt einige Indexes-Vorgänge. Vollständige Samples finden Sie im Ordner "indexes" im 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);

Feinabstimmungsbetriebsabläufe

Der untenstehende Code zeigt, wie man Feinabstimmungsjobs mit dem OpenAI-Client erstellt. Diese Operationen unterstützen verschiedene Feinabstimmungstechniken wie Supervised Fine-Tuning (SFT), Reinforcement Fine-Tuning (RFT) und Direct Performance Optimization (DPO). Vollständige Samples finden Sie im Ordner "finetuning" im 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));

Ablaufverfolgung

Anmerkung: Die Ablaufverfolgungsfunktion befindet sich in der Vorabvorschau und kann sich noch ändern. Spannen, Attribute und Ereignisse können in zukünftigen Versionen geändert werden.

Sie können eine Application Insights Azure-Ressource zu Ihrem Microsoft Foundry-Projekt hinzufügen. Weitere Informationen finden Sie auf der Registerkarte Ablaufverfolgung in Ihrem Microsoft Foundry-Projekt. Wenn einer aktiviert war, kannst du die Application Insights-connection string erhalten, deinen AI Projects-Client konfigurieren und den vollständigen Ausführungspfad über Azure Monitor beobachten. In der Regel empfiehlt es sich, mit der Ablaufverfolgung zu beginnen, bevor Sie einen Client oder Agenten erstellen.

Installation

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

Wie man das Nachverfolgen aktiviert

Hier ist ein Codebeispiel, das zeigt, wie man Azure Monitor-Tracing aktiviert:

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

Siehe den vollständigen Beispielcode in remoteTelemetry.ts.

Problembehandlung

Ausnahmen

Clientmethoden, die Dienstaufrufe ausführen, lösen eine RestError- für eine nicht erfolgreiche HTTP-Statuscodeantwort des Diensts aus. Die code der Ausnahme enthält den HTTP-Antwortstatuscode. Die error.message der Ausnahme enthält eine detaillierte Meldung, die bei der Diagnose des Problems hilfreich sein kann:

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

Wenn Sie beispielsweise falsche Anmeldeinformationen angeben:

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

Melden von Problemen

Um Probleme mit der Client-Bibliothek zu melden oder zusätzliche Funktionen anzufordern, öffnen Sie bitte eine GitHub Ausgabe hier

Nächste Schritte

Schau dir den Ordner package samples an, der vollständig ausführbaren Code enthält.

Beitragender

Dieses Projekt begrüßt Beiträge und Vorschläge. Die meisten Beiträge erfordern, dass Sie einem Mitwirkenden-Lizenzvertrag (CLA) zustimmen, der erklärt, dass Sie das Recht haben, uns tatsächlich die Rechte zur Nutzung Ihres Beitrags zu gewähren. Weitere Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie eine Pullanfrage einreichen, bestimmt ein CLA-Bot automatisch, ob Sie eine CLA bereitstellen und die PR entsprechend dekorieren müssen (z. B. Bezeichnung, Kommentar). Folgen Sie einfach den Anweisungen des Bots. Sie müssen dies nur einmal über alle Reposs hinweg tun, indem Sie unsereN CLA verwenden.

Dieses Projekt hat den Microsoft Open Source Code of Conductübernommen. Weitere Informationen finden Sie im Code of Conduct FAQ oder wenden Sie sich an opencode@microsoft.com mit weiteren Fragen oder Kommentaren.

  • Last updated on