Azure AI Projects klientbibliotek för JavaScript - version 2.0.1

AI Projects klientbibliotek (i förhandsvisning) är en del av Microsoft Foundry SDK och ger enkel tillgång till resurser i ditt Microsoft Foundry Project. Använd portalen om du vill:

• Skapa och kör agenter med hjälp av .agents egenskapen på klienten.

• Förbättra mäklare med specialiserade verktyg:
  • Agent Minnessökning (Förhandsgranskning)
  • Agent-till-agent (A2A) (Förhandsvisning)
  • Azure AI Search
  • Bing anpassad sökning (Förhandsgranskning)
  • Grundläggning i Bing
  • Webbläsarautomatisering (Förhandsgranskning)
  • Kodtolkare
  • Datoranvändning (Förhandsgranskning)
  • Filsökning
  • Funktionsverktyg
  • Bildgenerering
  • Microsoft Fabric (Förhandsgranskning)
  • McP (Model Context Protocol)
  • OpenAPI
  • Microsoft SharePoint (Förhandsgranskning)
  • Webbsökning (Förhandsvisning)

• Skaffa en OpenAI-klient som använder metoden .getOpenAIClient. för att köra svar, konversationer, utvärderingar och finjusteringsoperationer med din agent.

• Hantera minneslagringar (förhandsgranskning) för agentkonversationer med hjälp av operationerna .beta.memoryStores .
• Utforska ytterligare utvärderingsverktyg (vissa i förhandsvisning) för att bedöma prestandan hos din generativa AI-applikation, med hjälp av .evaluationRules, .beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, och .beta.schedules operationer.
• Kör Red Team-skanningar (förhandsgranskning) för att identifiera risker kopplade till din generativa AI-applikation, med hjälp av operationerna .beta.redTeams .
• Finjustering AI-modeller på dina data.

• Räkna upp AI-modeller som distribueras till ditt Foundry-projekt med hjälp av åtgärderna .deployments .
• Räkna upp anslutna Azure resurser i ditt Foundry-projekt med hjälp av .connections-operationerna.
• Ladda upp dokument och skapa datauppsättningar för att referera till dem med hjälp av åtgärderna .datasets .
• Skapa och räkna upp sökindex med hjälp av åtgärderna .indexes .

Klientbiblioteket använder en version v1 av REST-API:erna för Microsoft Foundry-dataplanet.

Produktdokumentation | Samples | Package (npm) | API referensdokumentation | SDK källkod

Innehållsförteckning

• Komma igång
  • Prerequisite
  • Behörighet
  • Installera paketet
• Viktiga begrepp
  • Skapa och autentisera klienten
  • Förhandsgranskning av operationsgrupper och opt-in-funktionsflaggor
• Exempel
  • Utföra svarsoperationer med OpenAI-klienten
  • Utföra agentåtgärder
  • Användning av agentverktyg
    • Inbyggda verktyg
    • Connection-Based Verktyg
  • Utvärderingsoperationer
  • Åtgärder för distributioner
  • Åtgärder för anslutningar
  • Åtgärder för datauppsättning
  • Åtgärder för filer
  • Indexerar åtgärder
  • Finjusteringsoperationer
• Spårning
  • Installation
  • Hur man aktiverar spårning
• Felsökning
  • undantag
  • Rapporteringsproblem
• Nästa steg
• bidra med

Komma igång

Förutsättning

• LTS-versioner av Node.js
• Ett Azure abonnemang.
• Ett projekt i Microsoft Foundry.
• Projektets endpoint-URL av formen https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name. Den finns på din översiktssida för Microsoft Foundry Project. Nedan antar vi att miljövariabeln AZURE_AI_PROJECT_ENDPOINT definierades för att hålla detta värde.

Behörighet

• Ett Entra-ID behövs för att autentisera klienten. Programmet behöver ett objekt som implementerar TokenCredential--gränssnittet. Kodexempel här använder DefaultAzureCredential. För att få det att fungera behöver du:
  • En lämplig rollfördelning. se Rollbaserad åtkomstkontroll i Microsoft Foundry-portalen. Rollen som tilldelas kan göras via fliken "Access Control (IAM)" i din Azure AI-projektresurs i Azure-portalen.
  • Azure CLI installerat.
  • Du är inloggad på ditt Azure-konto genom att köra az login.
  • Observera att om du har flera Azure-prenumerationer måste prenumerationen som innehåller din Azure AI Project-resurs vara din standardprenumeration. Kör az account list --output table för att visa en lista över alla prenumerationer och se vilken som är standard. Kör az account set --subscription "Your Subscription ID or Name" för att ändra din standardprenumeration.

Installera paketet

npm install @azure/ai-projects dotenv

Viktiga begrepp

Skapa och autentisera klienten med Entra-ID

Entra ID är den enda autentiseringsmetoden som för närvarande stöds av klienten.

För att skapa en AIProjectsClientkan du projectEndpoint hämta från projectEndpoint. Nedan antar vi att miljövariabeln AZURE_AI_PROJECT_ENDPOINT har definierats för att innehålla det här värdet:

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

Förhandsgranskning av operationsgrupper och opt-in-funktionsflaggor

Vissa förhandsgranskningsoperationer kräver en explicit foundryFeatures opt-in-flagga. Som exempel:

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

Förhandsgranskningsoperationsgrupper inkluderar .beta.memoryStores, .beta.evaluationTaxonomies, , .beta.evaluators, .beta.insights, .beta.schedulesoch .beta.redTeams.

Exempel

Utföra svarsoperationer med OpenAI-klienten

Ditt Microsoft Foundry-projekt kan ha en eller flera AI-modeller implementerade. Dessa kan vara OpenAI-modeller, Microsoft-modeller eller modeller från andra leverantörer. Använd koden nedan för att hämta en autentiserad OpenAI från openai-paketet och köra ett chattavslutningsanrop.

Kör koden nedan. Här antar vi att deploymentName (str) är definierat. Det är distributionsnamnet för en AI-modell i ditt Foundry-projekt. Som du ser på fliken "Modeller + slutpunkter" under kolumnen "Namn".

Se mappen "responses" i package samples för ytterligare exempel, inklusive strömmande svar.

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

Utföra agentåtgärder

Egenskapen .agents på ger AIProjectsClient dig tillgång till alla agentåtgärder. Agenter använder ett tillägg av OpenAI Responses-protokollet, så du kommer sannolikt att behöva få en OpenAI klient att utföra agentoperationer, som visas i exemplet nedan.

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

Användning av agentverktyg

Agenter kan förbättras med specialiserade verktyg för olika funktioner. Verktygen är organiserade efter sina anslutningskrav:

Inbyggda verktyg

Dessa verktyg fungerar omedelbart utan att kräva externa anslutningar.

Kodtolkare

Skriv och kör Javascript-kod i en sandboxad miljö, bearbeta filer och arbeta med olika dataformat. Dokumentation om 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}`);

Se hela exempelkoden i agentCodeInterpreter.ts.

Filsökning

Inbyggt RAG (Retrieval-Augmented Generation)-verktyg för att bearbeta och söka bland dokument med hjälp av vektorlager för kunskapshämtning. Dokumentation om 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})`);

Se hela exempelkoden i agentFileSearchStream.ts.

Bildgenerering

Generera bilder baserat på textpromptar med anpassningsbara inställningar för upplösning, kvalitet och stil:

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

Efter att ha anropat responses.create(), kan du ladda ner filen med det returnerade svaret:

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

Webbsökning (Förhandsvisning)

Gör allmänna webbsökningar för att hämta aktuell information från internet. Dokumentation om 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}`);

Se hela exempelkoden i agentWebSearch.ts.

Datoranvändning (Förhandsgranskning)

Möjliggöra för agenter att interagera direkt med datasystem för uppgiftsautomatisering och systemdrift:

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

Efter anrop responses.create(), bearbeta svaret i en interaktionsloop. Hantera computer_call utdata och visa skärmdumpar som computer_call_output med computer_screenshot typ för att fortsätta interaktionen.

Se hela exempelkoden i agentComputerUse.ts.

McP (Model Context Protocol)

Integrera MCP-servrar för att utöka agenternas kapacitet med standardiserade verktyg och resurser. Dokumentation om 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" } },
  },
);

Efter att ha ringt responses.create(), kontrollera om det finns poster mcp_approval_request i svarsutdatan. Skicka tillbaka McpApprovalResponse med ditt godkännande beslut för att låta agenten fortsätta sitt arbete.

Se hela exempelkoden i agentMcp.ts.

OpenAPI

Anropa externa API:er definierade av OpenAPI-specifikationer utan ytterligare klientkod. Dokumentation om 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})`);

Se hela exempelkoden i agentOpenApi.ts.

Funktionsverktyg

Definiera anpassade funktioner som tillåter agenter att interagera med externa API:er, databaser eller applikationslogik. Dokumentation om 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})`);

Efter att ha anropat responses.create(), bearbeta function_call objekt från svarsutdata, kör din funktionslogik med de angivna argumenten och skicka tillbaka FunctionCallOutput med resultaten.

Se hela exempelkoden i agentFunctionTool.ts.

• Minnessökverktyg (Förhandsgranskning)

Memory Store Tool lägger till minne till en agent, vilket gör att agentens AI-modell kan söka efter tidigare information relaterad till den aktuella användarprompten.

Det är embeddingModelDeployment namnet på modellen som används för att skapa vektorinbäddningar för lagring och sökning i minnen.

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

Se hela exempelkoden i agentMemorySearch.ts.

Connection-Based Verktyg

Dessa verktyg kräver att du konfigurerar anslutningar i ditt AI Foundry-projekt och använder projectConnectionId.

Azure AI Search

Integrera med Azure AI Search-index för kraftfulla kunskapssöknings- och semantiska sökningsfunktioner:

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

Se hela exempelkoden i agentAiSearch.ts.

Grundläggning i Bing

Markagenter svarar med realtidssökresultat från Bing för att ge up-to-datuminformation:

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

Se hela exempelkoden i agentBingGrounding.ts.

Bing anpassad sökning (Förhandsgranskning)

Använd anpassade Bing-sökinstanser för domänspecifika eller filtrerade webbsökresultat:

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

Se hela exempelkoden i agentBingCustomSearch.ts.

Microsoft Fabric (Förhandsvisning)

Koppla upp dig till och fråga 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})`);

Se hela exempelkoden i agentFabric.ts.

Microsoft SharePoint (Förhandsgranskning)

Få tillgång till och sök i SharePoint-dokument, listor och webbplatser för företagskunskapsintegration:

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

Se hela exempelkoden i agentSharepoint.ts.

Webbläsarautomatisering (Förhandsgranskning)

Automatisera webbläsarinteraktioner för webbskraping, testning och interaktion med webbapplikationer:

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

Se hela exempelkoden i agentBrowserAutomation.ts.

MCP med Project Connection

MCP-integration med projektspecifika anslutningar för att komma åt anslutna MCP-servrar:

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

Se hela exempelkoden i agentMcpConnectionAuth.ts.

Agent-till-agent (A2A) (Förhandsvisning)

Möjliggöra samarbete mellan flera agenter där agenter kan kommunicera och delegera uppgifter till andra specialiserade agenter:

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

Se hela exempelkoden i agentAgentToAgent.ts.

OpenAPI med projektanslutning

Anropa externa API:er definierade av OpenAPI-specifikationer med hjälp av projektanslutningsautentisering:

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

Se hela exempelkoden i agentOpenApiConnectionAuth.ts.

För kompletta fungerande exempel på alla verktyg, se katalogen samples-dev.

Evaluation

Utvärdering i Azure AI-projektets klientbibliotek tillhandahåller kvantitativa, AI-assisterade kvalitets- och säkerhetsmått för att bedöma prestanda och utvärdera LLM-modeller, GenAI-applikationer och agenter. Mätvärden definieras som utvärderare. Inbyggda eller anpassade utvärderare kan ge omfattande utvärderingsinsikter.

Koden nedan visar några utvärderingsoperationer. Fullständig lista över prover finns under mappen "evaluations" i 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})`);

Se hela exempelkoden i agentEvaluation.ts.

Åtgärder för distributioner

Koden nedan visar några distributionsåtgärder som gör att du kan räkna upp de AI-modeller som distribueras till dina Microsoft Foundry Projects. Dessa modeller kan visas på fliken "Modeller + slutpunkter" i ditt Microsoft Foundry-projekt. Fullständiga prover finns under mappen "deployment" i 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)}`);
}

Åtgärder för anslutningar

Koden nedan visar några anslutningsoperationer, som låter dig räkna upp Azure-resurser kopplade till dina Microsoft Foundry-projekt. Dessa anslutningar kan ses i "Management Center" på fliken "Anslutna resurser" i ditt Microsoft Foundry-projekt. Fullständiga prover finns under mappen "connections" i 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)}`);

Åtgärder för datauppsättning

Koden nedan visar några Dataset-åtgärder. Fullständiga prover finns under mappen "datasets" i 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.");

Åtgärder för filer

Koden nedan visar några filoperationer med hjälp av OpenAI-klienten, som låter dig ladda upp, hämta, lista och ta bort filer. Dessa åtgärder är användbara för att arbeta med filer som kan användas för finjustering och andra AI-modellåtgärder. Fullständiga prover finns under mappen "files" i 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)}`,
);

Indexerar åtgärder

Koden nedan visar några indexåtgärder. Fullständiga prover finns under mappen "indexes" i 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);

Finjusteringsåtgärder

Koden nedan visar hur man skapar finjusteringsjobb med OpenAI-klienten. Dessa operationer stödjer olika finjusteringstekniker som Supervised Fine-Tuning (SFT), Reinforcement Fine-Tuning (RFT) och Direct Performance Optimization (DPO). Fullständiga prover finns under mappen "finetuning" i 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));

Spårning

Not: Spårningsfunktionen är i preliminär förhandsversion och kan komma att ändras. Intervall, attribut och händelser kan komma att ändras i framtida versioner.

Du kan lägga till en Application Insights Azure-resurs till ditt Microsoft Foundry-projekt. Se fliken Spårning i ditt Microsoft Foundry-projekt. Om en sådan var aktiverad kan du hämta Application Insights-connection string, konfigurera din AI Projects-klient och följa hela exekveringsvägen via Azure Monitor. Vanligtvis kanske du vill börja spåra innan du skapar en klient eller agent.

Installation

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

Hur man aktiverar spårning

Här är ett kodexempel som visar hur man aktiverar Azure Monitor-spårning:

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

Se hela exempelkoden i remoteTelemetry.ts.

Felsökning

undantag

Klientmetoder som gör tjänstanrop skapar en RestError- för ett HTTP-statuskodsvar som inte lyckas från tjänsten. Undantagets code innehåller HTTP-svarsstatuskoden. Undantagets error.message innehåller ett detaljerat meddelande som kan vara till hjälp vid diagnostisering av problemet:

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

När du till exempel anger fel autentiseringsuppgifter:

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

Rapporteringsproblem

För att rapportera problem med klientbiblioteket eller begära ytterligare funktioner, vänligen öppna ett GitHub problem här

Nästa steg

Titta på mappen package samples, som innehåller fullt körbar kod.

bidra med

Det här projektet välkomnar bidrag och förslag. De flesta bidrag kräver att du godkänner ett licensavtal för deltagare (CLA) som förklarar att du har rätt att, och faktiskt gör det, ge oss rätten att använda ditt bidrag. Mer information finns i https://cla.microsoft.com.

När du skickar en pull-begäran avgör en CLA-robot automatiskt om du behöver tillhandahålla ett CLA och dekorera PR på rätt sätt (t.ex. etikett, kommentar). Följ bara anvisningarna från roboten. Du behöver bara göra detta en gång för alla lagringsplatser med vår CLA.

Det här projektet har antagit Microsoft Open Source Code of Conduct (Microsofts regler för uppförande för öppen källkod). Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.