Delen via

Azure AI Projects client library for JavaScript - versie 2.0.1

De AI Projects clientbibliotheek (in preview) maakt deel uit van de Microsoft Foundry SDK en biedt gemakkelijke toegang tot bronnen in je Microsoft Foundry Project. Gebruik deze voor het volgende:

  • Creëer en voer agenten uit met behulp van de .agents eigenschap op de client.
  • Verbeter makelaars met gespecialiseerde tools:
    • Agent Geheugenzoekopdracht (Preview)
    • Agent-tot-Agent (A2A) (Preview)
    • Azure AI Search
    • Bing Aangepaste Zoekopdracht (Voorbeeld)
    • Bing Grounding
    • Browserautomatisering (Voorbeeld)
    • Code-interpreter
    • Computergebruik (Preview)
    • Zoeken naar bestanden
    • Functiegereedschap
    • Beeldgeneratie
    • Microsoft Fabric (Preview)
    • Model Context Protocol (MCP)
    • OpenAPI
    • Microsoft SharePoint (Preview)
    • Webzoekopdracht (Preview)
  • Krijg een OpenAI-client die de .getOpenAIClient. methode gebruikt om antwoorden, gesprekken, evaluaties en finetuning-operaties met je agent uit te voeren.
  • Beheer geheugenopslagen (preview) voor agentgesprekken, met behulp van de operaties .beta.memoryStores .
  • Verken aanvullende evaluatietools (sommige in preview) om de prestaties van je generatieve AI-applicatie te beoordelen, met behulp van de .evaluationRules, .beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, en .beta.schedules operaties.
  • Voer Red Team-scans uit (preview) om risico's te identificeren die samenhangen met je generatieve AI-applicatie, met behulp van de operaties .beta.redTeams .
  • Fijne afstemming AI modelleert op je data.
  • Sommen AI-modellen op die zijn geïmplementeerd in uw Foundry-project met behulp van de .deployments bewerkingen.
  • Enumereer verbonden Azure bronnen in je Foundry-project met behulp van de .connections operaties.
  • Upload documenten en maak datasets om ernaar te verwijzen met behulp van de .datasets bewerkingen.
  • Maak en inventariseer zoekindexen met behulp van de .indexes bewerkingen.

De clientbibliotheek maakt gebruik v1 van de versie van de REST API's van het Microsoft Foundry-gegevensvlak.

Productdocumentatie | Samples | Package (npm) | API referentiedocumentatie | SDK broncode

Inhoudsopgave

Aan de slag

vereiste

  • LTS-versies van Node.js
  • Een Azure abonnement.
  • Een project in Microsoft Foundry.
  • De project-eindpunt-URL van het formulier https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name. Het is te vinden op je overzichtspagina van het Microsoft Foundry Project. Hieronder gaan we ervan uit dat de omgevingsvariabele AZURE_AI_PROJECT_ENDPOINT zo gedefinieerd is dat deze waarde wordt gehouden.

Autorisatie

  • Een Entra-ID is nodig om de client te authenticeren. Uw toepassing heeft een object nodig waarmee de interface TokenCredential wordt geïmplementeerd. Codevoorbeelden hier gebruiken DefaultAzureCredential. Om dat te kunnen doen, hebt u het volgende nodig:
    • Een passende rolverdeling. zie Rolgebaseerde toegangscontrole in het Microsoft Foundry-portaal. De toegewezen rol kan worden gedaan via het tabblad "Access Control (IAM)" van je Azure AI Project-resource in het Azure-portaal.
    • Azure CLI geïnstalleerd.
    • Je bent ingelogd op je Azure-account door az login te draaien.
    • Let op: als je meerdere Azure-abonnementen hebt, moet het abonnement dat je Azure AI Project-resource bevat je standaardabonnement zijn. Voer az account list --output table uit om al uw abonnement weer te geven en te zien welke standaard is. Voer az account set --subscription "Your Subscription ID or Name" uit om uw standaardabonnement te wijzigen.

Het pakket installeren

npm install @azure/ai-projects dotenv

belangrijke concepten

Maak de client aan en authenticiseer deze met een Entra-ID

Entra ID is momenteel de enige authenticatiemethode die door de client wordt ondersteund.

Om een AIProjectsClientte maken, kan de projectEndpoint worden opgehaald uit projectEndpoint. Hieronder gaan we ervan uit dat de omgevingsvariabele AZURE_AI_PROJECT_ENDPOINT is gedefinieerd om deze waarde vast te houden:

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

Voorbeeldoperatiegroepen en opt-in functievlaggen

Sommige preview-operaties vereisen een expliciete foundryFeatures opt-in vlag. Voorbeeld:

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

Voorbeeldoperatiegroepen omvatten .beta.memoryStores, .beta.evaluationTaxonomies, , .beta.evaluators, .beta.insights, .beta.schedulesen .beta.redTeams.

Voorbeelden

Reactiebewerkingen uitvoeren met behulp van de OpenAI-client

Je Microsoft Foundry-project kan een of meer AI-modellen hebben geïmplementeerd. Dit kunnen OpenAI-modellen, Microsoft-modellen of modellen van andere aanbieders zijn. Gebruik de onderstaande code om een geverifieerde OpenAI uit het openai-pakket te halen en een chatvoltooiingsgesprek uit te voeren.

Voer de onderstaande code uit. Hier gaan we ervan uit dat deploymentName (str) is gedefinieerd. Het is de implementatienaam van een AI-model in uw Foundry Project. Zoals weergegeven op het tabblad "Modellen + eindpunten", onder de kolom "Naam".

Zie de map "responses" in de package samples voor extra samples, inclusief streaming-reacties.

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

Uitvoeren van agentbewerkingen

Het .agents pand aan de AIProjectsClient geeft u toegang tot alle Agent-operaties. Agents gebruiken een uitbreiding van het OpenAI Responses-protocol, dus u zult waarschijnlijk een OpenAI client nodig hebben om Agent-bewerkingen uit te voeren, zoals weergegeven in het onderstaande voorbeeld.

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

Gebruik van agenttools

Agenten kunnen worden verbeterd met gespecialiseerde hulpmiddelen voor diverse mogelijkheden. Gereedschappen zijn georganiseerd op basis van hun verbindingsvereisten:

Ingebouwde tools

Deze tools werken direct zonder externe verbindingen te vereisen.

Code-interpreter

Schrijf en voer Javascript-code uit in een sandbox-omgeving, verwerk bestanden en werk met diverse dataformaten. Documentatie voor 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}`);

Bekijk de volledige voorbeeldcode in agentCodeInterpreter.ts.

Bestand Zoeken

Ingebouwde RAG (Retrieval-Augmented Generation) tool om documenten te verwerken en te doorzoeken met behulp van vectorarchieven voor kennisopvraging. Documentatie voor 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})`);

Bekijk de volledige voorbeeldcode in agentFileSearchStream.ts.

Beeldgeneratie

Genereer afbeeldingen op basis van tekstprompts met aanpasbare resolutie-, kwaliteits- en stijlinstellingen:

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

Na het bellen responses.create()kun je het bestand downloaden met het teruggegeven antwoord:

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

Webzoekopdracht (Preview)

Voer algemene webzoekopdrachten uit om actuele informatie van het internet op te halen. Documentatie voor 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}`);

Bekijk de volledige voorbeeldcode in agentWebSearch.ts.

Computergebruik (Preview)

Stel agenten in staat om direct met computersystemen te communiceren voor taakautomatisering en systeemoperaties:

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

Na het aanroepen responses.create(), verwerk het antwoord in een interactielus. Behandel computer_call uitvoeritems en geef screenshots zoals computer_call_outputcomputer_screenshot type om de interactie voort te zetten.

Bekijk de volledige voorbeeldcode in agentComputerUse.ts.

Model Context Protocol (MCP)

Integreer MCP-servers om agentmogelijkheden uit te breiden met gestandaardiseerde tools en middelen. Documentatie voor 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" } },
  },
);

Na het bellen responses.create()controleer je op mcp_approval_request items in de responsoutput. Stuur met je goedkeuring een beslissing terug McpApprovalResponse zodat de makelaar zijn werk kan voortzetten.

Bekijk de volledige voorbeeldcode in agentMcp.ts.

OpenAPI

Roep externe API's aan die zijn gedefinieerd door OpenAPI-specificaties zonder extra client-side code. Documentatie voor 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})`);

Bekijk de volledige voorbeeldcode in agentOpenApi.ts.

Functiegereedschap

Definieer aangepaste functies waarmee agenten kunnen interageren met externe API's, databases of applicatielogica. Documentatie voor 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})`);

Na het aanroepen responses.create()van , verwerk function_call items uit responsoutput, voer je functielogica uit met de geleverde argumenten en stuur terug FunctionCallOutput met de resultaten.

Bekijk de volledige voorbeeldcode in agentFunctionTool.ts.

  • Geheugenzoektool (Voorbeeld)

De Memory Store Tool voegt Memory toe aan een agent, waardoor het AI-model van de agent kan zoeken naar eerdere informatie die verband houdt met de huidige gebruikersprompt.

Dit is embeddingModelDeployment de naam van het model dat wordt gebruikt om vector-embeddings te maken voor het opslaan en doorzoeken van geheugens.

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

Bekijk de volledige voorbeeldcode in agentMemorySearch.ts.

Connection-Based Hulpmiddelen

Deze tools vereisen het configureren van verbindingen in je AI Foundry-project en gebruik projectConnectionId.

Azure AI Search

Integreer met Azure AI Search-indexen voor krachtige kennisopvraging en semantische zoekmogelijkheden:

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

Bekijk de volledige voorbeeldcode in agentAiSearch.ts.

Bing Aarding

Grondagenten reageren met realtime webzoekresultaten van Bing om up-to-datuminformatie te geven:

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

Bekijk de volledige voorbeeldcode in agentBingGrounding.ts.

Bing Aangepaste Zoekopdracht (Voorbeeld)

Gebruik aangepaste Bing-zoekinstanties voor domeinspecifieke of gefilterde webzoekresultaten:

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

Bekijk de volledige voorbeeldcode in agentBingCustomSearch.ts.

Microsoft Fabric (Preview)

Verbind met en vraag naar Microsoft Fabric:

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

Bekijk de volledige voorbeeldcode in agentFabric.ts.

Microsoft SharePoint (Preview)

Toegang en doorzoek SharePoint-documenten, lijsten en sites voor integratie van enterprise kennis:

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

Bekijk de volledige voorbeeldcode in agentSharepoint.ts.

Browserautomatisering (Voorbeeld)

Automatiseer browserinteracties voor webscraping, testen en interactie met webapplicaties:

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

Bekijk de volledige voorbeeldcode in agentBrowserAutomation.ts.

MCP met Project Connection

MCP-integratie met projectspecifieke verbindingen voor toegang tot verbonden MCP-servers:

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

Bekijk de volledige voorbeeldcode in agentMcpConnectionAuth.ts.

Agent-tot-Agent (A2A) (Preview)

Mogelijk maken samenwerking tussen meerdere agenten mogelijk waarbij agenten kunnen communiceren en taken kunnen delegeren aan andere gespecialiseerde agenten:

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

Bekijk de volledige voorbeeldcode in agentAgentToAgent.ts.

OpenAPI met projectverbinding

Roep externe API's aan die zijn gedefinieerd door OpenAPI-specificaties met behulp van projectconnectie-authenticatie:

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

Bekijk de volledige voorbeeldcode in agentOpenApiConnectionAuth.ts.

Voor volledige werkende voorbeelden van alle tools, zie de directory samples-dev.

Evaluatie

Evaluatie in de clientbibliotheek van Azure AI Project biedt kwantitatieve, door AI ondersteunde kwaliteits- en veiligheidsindicatoren om prestaties te beoordelen en LLM-modellen, GenAI-applicaties en agenten te evalueren. Metrics worden gedefinieerd als evaluators. Ingebouwde of op maat gemaakte evaluators kunnen uitgebreide evaluatie-inzichten bieden.

De onderstaande code toont enkele evaluatiebewerkingen. De volledige lijst van voorbeelden is te vinden in de map "evaluaties" in de 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})`);

Bekijk de volledige voorbeeldcode in agentEvaluation.ts.

Implementaties operaties

De onderstaande code toont enkele implementatiebewerkingen, waarmee u de AI-modellen kunt opsommen die zijn geïmplementeerd in uw Microsoft Foundry-projecten. Deze modellen zijn te zien op het tabblad "Modellen + eindpunten" in uw Microsoft Foundry-project. Volledige voorbeelden zijn te vinden onder de map "deployment" in de 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)}`);
}

Verbindingen bewerkingen

De onderstaande code toont enkele verbindingsbewerkingen, waarmee je de Azure-bronnen kunt opsommen die verbonden zijn met je Microsoft Foundry-projecten. Deze verbindingen zijn te zien in het "Management Center", op het tabblad "Verbonden resources" in uw Microsoft Foundry-project. Volledige samples zijn te vinden in de map "connections" in de 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)}`);

Bewerkingen van gegevenssets

De onderstaande code toont enkele bewerkingen van de gegevensset. Volledige samples zijn te vinden in de map "datasets" in de 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.");

Bestanden bewerkingen

De onderstaande code toont enkele bestandsbewerkingen met behulp van de OpenAI-client, waarmee u bestanden kunt uploaden, ophalen, weergeven en verwijderen. Deze bewerkingen zijn handig voor het werken met bestanden die kunnen worden gebruikt voor finetuning en andere AI-modelbewerkingen. Volledige samples zijn te vinden in de map "files" in de 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)}`,
);

Bewerkingen van indexen

De onderstaande code toont enkele indexbewerkingen. Volledige samples zijn te vinden in de map "indexes" in de 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);

Het verfijnen van operaties

De onderstaande code laat zien hoe je fine-tuning jobs kunt maken met de OpenAI-client. Deze bewerkingen ondersteunen diverse fijnafstellingstechnieken zoals Supervised Fine-Tuning (SFT), Reinforcement Fine-Tuning (RFT) en Direct Performance Optimization (DPO). Volledige samples zijn te vinden in de map "finetuning" in de 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));

tracering

Notitie: De traceringsfunctionaliteit bevindt zich in een voorlopige preview en kan worden gewijzigd. Spans, attributen en gebeurtenissen kunnen in toekomstige versies worden gewijzigd.

Je kunt een Application Insights Azure-bron toevoegen aan je Microsoft Foundry-project. Zie het tabblad Tracering in uw Microsoft Foundry-project. Als die ingeschakeld was, kun je de Application Insights-connection string krijgen, je AI Projects-client configureren en het volledige uitvoeringspad via Azure Monitor observeren. Meestal wilt u beginnen met traceren voordat u een klant of agent maakt.

Installation

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

Hoe je traceren inschakelt

Hier is een codevoorbeeld dat laat zien hoe je Azure Monitor-tracing inschakelt:

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

Bekijk de volledige voorbeeldcode in remoteTelemetry.ts.

Problemen oplossen

Uitzonderingen

Clientmethoden waarmee serviceaanroepen worden uitgevoerd, genereren een RestError- voor een niet-geslaagd HTTP-statuscodeantwoord van de service. De code van de uitzondering bevat de HTTP-antwoordstatuscode. De error.message van de uitzondering bevat een gedetailleerd bericht dat nuttig kan zijn bij het diagnosticeren van het probleem:

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

Als u bijvoorbeeld onjuiste referenties opgeeft:

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

problemen melden

Om problemen met de clientbibliotheek te melden of extra functies aan te vragen, open dan een GitHub issue here

Volgende stappen 

Bekijk de map package samples, die volledig uitvoerbare code bevat.

bijdragen

Dit project verwelkomt bijdragen en suggesties. Voor de meeste bijdragen moet u akkoord gaan met een Licentieovereenkomst voor inzenders (CLA) waarin wordt aangegeven dat u het recht hebt om, en daadwerkelijk, ons de rechten te verlenen om uw bijdrage te gebruiken. Ga naar https://cla.microsoft.comvoor meer informatie.

Wanneer u een pull-aanvraag indient, bepaalt een CLA-bot automatisch of u een CLA moet opgeven en de pull-aanvraag op de juiste wijze moet inrichten (bijvoorbeeld label, opmerking). Volg gewoon de instructies van de bot. U hoeft dit slechts eenmaal te doen voor alle opslagplaatsen met behulp van onze CLA.

Dit project onderschrijft de Microsoft Open Source gedragscode. Zie de veelgestelde vragen over gedragscodes voor meer informatie of neem contact op met opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

  • Last updated on