Azure AI Projects klientská knihovna pro JavaScript - verze 2.1.1

Knihovna klientů AI Projects (v náhledu) je součástí Microsoft Foundry SDK a poskytuje snadný přístup k zdrojům ve vašem Microsoft Foundry Project. Použijte ji k následujícím akcím:

• Vytvořte a spusťte agenty.agents pomocí vlastnosti v klientovi.

• Vylepšujte agenty pomocí specializovaných nástrojů:
  • Vyhledávání v paměti agenta (Náhled)
  • Agent-to-Agent (A2A) (Náhled)
  • Azure AI Vyhledávač
  • Bing Custom Search (Náhled)
  • Zemnění Bingu
  • Automatizace prohlížeče (náhled)
  • Interpretátor kódu
  • Používání počítače (Náhled)
  • Hledání souborů
  • Nástroj funkce
  • Generování obrázků
  • Microsoft Fabric (Náhled)
  • Protokol modelového kontextu (MCP)
  • OpenAPI
  • Microsoft SharePoint (Ukázka)
  • Webové vyhledávání (Náhled)

• Pořiďte si OpenAI klienta s touto metodou .getOpenAIClient. pro spouštění operací Responses, Conversations, Evals a FineTuning s vaším agentem.

• Spravujte beta agentní relace a soubory (náhled ) pomocí .beta.agents operací.
• Spravujte dovednosti (preview) pro znovupoužitelné schopnosti agentů pomocí .beta.skills operací.
• Spravovat toolboxy (preview) pro seskupování nástrojů do znovupoužitelných kolekcí pomocí .beta.toolboxes operací.
• Spravovat paměťové úložiště (náhled) pro konverzace agentů pomocí .beta.memoryStores operací.
• Prozkoumejte další hodnotící nástroje (některé v náhledu), abyste mohli zhodnotit výkon své generativní AI aplikace .evaluationRulespomocí operací , .beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, , ..beta.schedules
• Spusť Red Team skeny (náhled) k identifikaci rizik spojených s vaší generativní AI aplikací pomocí .beta.redTeams operací.
• Vyladit AI modeluje vaše data.

• Enumerate AI Models nasazené ve vašem Foundry Project pomocí operací .deployments.
• Enumerujte propojené Azure zdroje ve svém projektu Foundry pomocí operací .connections.
• Nahrajte dokumenty a vytvořte datové sady , abyste na ně mohli odkazovat .datasets pomocí operací.
• Pomocí těchto operací vytvořte a vytvořte výčet vyhledávacích indexů.indexes.

Klientská knihovna používá verzi v1 REST API Microsoft Foundry data plane.

Dokumentace produktu | Samples | Package (npm) | API reference documentation | SDK zdrojový kód

Obsah

• Začínáme
  • Předpoklad
  • Authorization
  • Instalace balíčku
• Klíčové koncepty
  • Vytvoření a ověření klientského
  • Skupiny operací pro náhled a příznaky funkce pro přihlášení
• Příklady
  • Provádění operací odpovědí pomocí klienta OpenAI
  • Provádění operací agenta
  • Použití nástrojů Agent
    • Vestavěné nástroje
    • Connection-Based Nástroje
  • Evaluační operace
  • Operace nasazení
  • Operace připojení
  • Operace s datovými sadami
  • Operace se soubory
  • Indexuje operace
  • Operace jemného ladění
  • Beta agentní relace (náhled)
  • Operace dovedností (náhled)
  • Operace s nástrojovými schránkami (náhled)
• trasování
  • Installation
  • Jak povolit trasování
• Troubleshooting
  • Exceptions
  • problémy s generováním sestav
• Další kroky
• přispívání

Začínáme

Předpoklad

• LTS verze Node.js
• Předplatné Azure.
• Projekt projekt ve Microsoft Foundry.
• URL koncového bodu projektu ve tvaru https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name. Najdete ho na stránce s přehledem Microsoft Foundry Project. Níže předpokládáme, že proměnná FOUNDRY_PROJECT_ENDPOINT prostředí byla definována tak, aby tuto hodnotu držela.

Autorizace

• Pro autentizaci klienta je potřeba Entra ID. Vaše aplikace potřebuje objekt, který implementuje rozhraní TokenCredential. Ukázky kódu zde používají DefaultAzureCredential. Abyste mohli pracovat, budete potřebovat:
  • Vhodné přiřazení role. viz Řízení přístupu založené na rolích v Microsoft portálu Foundry. Přiřazenou roli lze nastavit přes záložku "Access Control (IAM)" ve vašem Azure AI Project zdroji v portálu Azure.
  • Azure CLI nainstalován.
  • Do svého Azure účtu jste přihlášeni spuštěním az login.
  • Všimněte si, že pokud máte více Azure odběrů, musí být výchozí předplatné to, které obsahuje váš Azure AI Project zdroj. Spuštěním az account list --output table zobrazte seznam všech vašich předplatných a podívejte se, která z nich je výchozí. Spuštěním az account set --subscription "Your Subscription ID or Name" změňte výchozí předplatné.

Instalace balíčku

npm install @azure/ai-projects dotenv

klíčové koncepty

Vytvořte a ověřte klienta pomocí Entra ID

Entra ID je jediná autentizační metoda, kterou klient v tuto chvíli podporuje.

Chcete-li vytvořit AIProjectsClient, lze je projectEndpoint načíst z projectEndpoint. Níže budeme předpokládat, že proměnná FOUNDRY_PROJECT_ENDPOINT prostředí byla definována tak, aby obsahovala tuto hodnotu:

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

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

Skupiny operací pro náhled a příznaky funkce pro přihlášení

Některé preview operace vyžadují explicitní foundryFeatures opt-in flag. Například:

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

Skupiny operací náhledu zahrnují .beta.agents, .beta.skills, .beta.toolboxes, .beta.memoryStores.beta.evaluationTaxonomies, , .beta.evaluators, .beta.insights, , .beta.schedulesa ..beta.redTeams

Příklady

Provádění operací odpovědí pomocí klienta OpenAI

Váš projekt Microsoft Foundry může mít nasazený jeden nebo více AI modelů. Mohou to být modely OpenAI, modely Microsoft nebo modely od jiných poskytovatelů. Pomocí níže uvedeného kódu získejte ověřenou OpenAI z balíčku openai a spusťte volání dokončení chatu.

Spusťte níže uvedený kód. Zde předpokládáme, že deploymentName je definováno (str). Je to název nasazení AI modelu ve vašem Foundry Project. Jak je znázorněno na kartě "Modely + koncové body" ve sloupci "Název".

Další ukázky včetně streamovaných odpovědí najdete ve složce "responses" v sekci package samples

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

Provádění operací agenta

Vlastnost .agents na kartě poskytuje přístup ke všem operacím agenta AIProjectsClient . Agenti používají rozšíření protokolu OpenAI Responses, takže pravděpodobně budete muset přimět OpenAI klienta, aby prováděl operace agenta, jak je znázorněno v příkladu níže.

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

Použití nástrojů Agent

Agenty lze vylepšit specializovanými nástroji pro různé schopnosti. Nástroje jsou organizovány podle požadavků na připojení:

Vestavěné nástroje

Tyto nástroje fungují okamžitě, aniž by vyžadovaly externí připojení.

interpretu kódu

Píšte a spousťte Javascriptový kód v sandboxovém prostředí, zpracováváte soubory a pracujte s různými datovými formáty. Dokumentace k 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}`);

Celý ukázkový kód najdete v agentCodeInterpreter.ts.

hledání souborů

Vestavěný nástroj RAG (Retrieval-Augmented Generation) pro zpracování a vyhledávání dokumentů pomocí vektorových úložišť pro vyhledávání znalostí. Dokumentace k 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})`);

Celý ukázkový kód najdete v agentFileSearchStream.ts.

Generování obrazu

Generujte obrázky na základě textových podnětů s přizpůsobitelným rozlišením, kvalitou a nastavením stylu:

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

Po zavolání responses.create()si můžete soubor stáhnout pomocí vrácené odpovědi:

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

Webové vyhledávání (Náhled)

Provádějte obecné vyhledávání na internetu, abyste získali aktuální informace z internetu. Dokumentace k 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}`);

Celý ukázkový kód najdete v agentWebSearch.ts.

Používání počítače (Náhled)

Umožnit agentům přímou interakci s počítačovými systémy pro automatizaci úkolů a provoz systému:

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

Po zavolání responses.create(), zpracuj odpověď v interakční smyčce. Zvládejte výstupní položky a poskytujte computer_call screenshoty podle computer_call_outputcomputer_screenshot typu pro pokračování interakce.

Celý ukázkový kód najdete v agentComputerUse.ts.

Protokol modelového kontextu (MCP)

Integrujte MCP servery pro rozšíření schopností agentů pomocí standardizovaných nástrojů a zdrojů. Dokumentace k 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" } },
  },
);

Po zavolání responses.create()zkontrolujte mcp_approval_request položky ve výstupu odpovědi. Pošlete zpět McpApprovalResponse s rozhodnutím o schválení, aby makléř mohl pokračovat ve své práci.

Celý ukázkový kód najdete v agentMcp.ts.

OpenAPI

Volejte externí API definovaná specifikacemi OpenAPI bez dalšího klientského kódu. Dokumentace k 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})`);

Celý ukázkový kód najdete v agentOpenApi.ts.

Nástroj funkce

Definujte vlastní funkce, které umožňují agentům interagovat s externími API, databázemi nebo aplikační logikou. Dokumentace k 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})`);

Po zavolání responses.create(), zpracuj function_call položky z výstupu odpovědi, spusťte logiku funkce s poskytnutými argumenty a pošlete FunctionCallOutput zpět s výsledky.

Celý ukázkový kód najdete v agentFunctionTool.ts.

• Nástroj pro vyhledávání v paměti (Náhled)

Nástroj Memory Store Tool přidává paměť agentovi, což umožňuje AI modelu agenta vyhledávat informace z minulosti související s aktuálním uživatelským promptem.

Je embeddingModelDeployment název modelu používaného k vytváření vektorových embeddingů pro ukládání a vyhledávání pamětí.

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

Celý ukázkový kód najdete v agentMemorySearch.ts.

Connection-Based Nástroje

Tyto nástroje vyžadují konfiguraci propojení ve vašem projektu AI Foundry a používají projectConnectionId.

Azure AI Vyhledávač

Integrujte s indexy Azure AI Vyhledávač pro výkonné možnosti vyhledávání znalostí a sémantického vyhledávání:

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

Celý ukázkový kód najdete v agentAiSearch.ts.

Zemnění Bingu

Odpovědi pozemních agentů s výsledky vyhledávání na webu v reálném čase z Bingu pro poskytnutí informací o up-todatu:

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

Celý ukázkový kód najdete v agentBingGrounding.ts.

Bing Custom Search (Náhled)

Použijte speciálně konfigurované instance vyhledávání Bing pro doménově specifické nebo filtrované webové výsledky:

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

Celý ukázkový kód najdete v agentBingCustomSearch.ts.

Microsoft Fabric (Náhled)

Připojte se k Microsoft Fabric a dotazujte se:

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

Celý ukázkový kód najdete v agentFabric.ts.

Microsoft SharePoint (Náhled)

Přístup a vyhledávání v dokumentech, seznamech a stránkách SharePoint pro integraci podnikových znalostí:

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

Celý ukázkový kód najdete v agentSharepoint.ts.

Automatizace prohlížeče (náhled)

Automatizujte interakce prohlížečů pro webscraping, testování a interakci s webovými aplikacemi:

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

Celý ukázkový kód najdete v agentBrowserAutomation.ts.

MCP s Project Connection

Integrace MCP pomocí projektově specifických připojení pro přístup k připojeným MCP serverům:

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

Celý ukázkový kód najdete v agentMcpConnectionAuth.ts.

Agent-to-Agent (A2A) (Náhled)

Umožnit spolupráci s více agenty, kde agenti mohou komunikovat a delegovat úkoly na jiné specializované agenty:

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

Celý ukázkový kód najdete v agentAgentToAgent.ts.

OpenAPI s Project Connection

Volejte externí API definovaná specifikacemi OpenAPI pomocí autentizace připojení k projektu:

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

Celý ukázkový kód najdete v agentOpenApiConnectionAuth.ts.

Pro kompletní pracovní příklady všech nástrojů viz adresář samples-dev.

Evaluation

Evalvace v klientské knihovně Azure AI Project poskytuje kvantitativní, AI-asistované metriky kvality a bezpečnosti pro hodnocení výkonu a hodnocení LLM modelů, aplikací GenAI a agentů. Metriky jsou definovány jako hodnotitelé. Vestavění nebo na míru vybavení hodnotitelé mohou poskytnout komplexní hodnotící poznatky.

Níže uvedený kód ukazuje některé evaluační operace. Úplný seznam vzorků lze nalézt ve složce "evaluations" v sekci 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})`);

Celý ukázkový kód najdete v agentEvaluation.ts.

Operace nasazení

Níže uvedený kód ukazuje některé operace Deployments, které vám umožní vyjmenovat AI modely nasazené ve vašich Microsoft Foundry Projects. Tyto modely lze vidět v záložce "Modely + koncové body" ve vašem Microsoft Foundry Project. Plné vzorky lze nalézt ve složce "deployment" v 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)}`);
}

Operace připojení

Níže uvedený kód ukazuje některé operace Connection, které vám umožní vyjmenovat Azure Resources propojené s vašimi Microsoft Foundry Projects. Tato spojení jsou vidět v "Management Center" v záložce "Connected resources" ve vašem Microsoft Foundry Project. Plné vzorky lze nalézt ve složce "connections" v 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)}`);

Operace s datovými sadami

Následující kód ukazuje některé operace s datovou sadou. Plné vzorky lze nalézt ve složce "datasets" v 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.");

Operace se soubory

Níže uvedený kód ukazuje některé operace se soubory pomocí klienta OpenAI, které vám umožňují nahrávat, načítat, vypsávat a odstraňovat soubory. Tyto operace jsou užitečné pro práci se soubory, které lze použít pro jemné doladění a další operace s modelem AI. Plné vzorky lze nalézt ve složce "files" v 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)}`,
);

Indexuje operace

Následující kód ukazuje některé operace indexů. Plné ukázky lze nalézt ve složce "indexes" v 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);

Dolaďovací operace

Níže uvedený kód ukazuje, jak vytvářet jemné ladění úloh pomocí klienta OpenAI. Tyto operace podporují různé techniky doladění, jako je supervised Fine-Tuning (SFT), Reinforcement Fine-Tuning (RFT) a Direct Performance Optimization (DPO). Plné samplování lze nalézt ve složce "finetuning" v 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));

Beta agentní relace (náhled)

Operace .beta.agents umožňují spravovat relace agentů a soubory relací pro hostované agenty. Relace poskytují izolovaná sandboxová prostředí pro interakce s agenty.

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

const agentName = "MyBetaAgent";
const isolationKey = "sample-isolation-key";
// Create a session for the agent
const versionIndicator: VersionRefIndicator = {
  type: "version_ref",
  agent_version: "1.0",
};
const session = await project.beta.agents.createSession(agentName, isolationKey, versionIndicator);
console.log(`Session created: ${session.agent_session_id}`);
// Upload a file to the session sandbox
const filePath = "/sandbox/hello.txt";
const fileContent = new TextEncoder().encode("Hello from the beta agents sample!");
const uploadResult = await project.beta.agents.uploadSessionFile(
  agentName,
  session.agent_session_id,
  filePath,
  fileContent,
);
console.log(`Uploaded file: ${uploadResult.path} (${uploadResult.bytes_written} bytes)`);

Celý ukázkový kód najdete v betaAgents.ts.

Operace dovedností (náhled)

Operace .beta.skills vám umožní vytvářet a spravovat znovupoužitelné dovednosti, které definují schopnosti agentů.

const skillName = "sample-skill";
// Create a new skill
const created = await project.beta.skills.create(skillName, {
  description: "Example skill created by the @azure/ai-projects sample.",
  instructions: "You are a helpful assistant that answers questions concisely.",
  metadata: { owner: "sample" },
});
console.log(`Skill created: ${created.name} (id: ${created.skill_id})`);
// Retrieve the skill
const fetched = await project.beta.skills.get(skillName);
console.log(`Retrieved skill: ${fetched.name} (id: ${fetched.skill_id})`);

Celý ukázkový kód najdete v skillBasic.ts.

Operace s nástrojovými schránkami (náhled)

Operace .beta.toolboxes vám umožňují vytvářet a spravovat toolboxy — znovupoužitelné kolekce nástrojů, které lze sdílet mezi agenty.

import { ToolUnion, MCPTool } from "@azure/ai-projects";

const toolboxName = "mcp";
// Define tools for the toolbox
const tools: ToolUnion[] = [
  {
    type: "mcp",
    server_label: "api_specs",
    server_url: "https://github.com/Azure/azure-rest-api-specs",
    require_approval: "never",
  } satisfies MCPTool,
];
// Create a new toolbox version
const created = await project.beta.toolboxes.createVersion(toolboxName, tools, {
  description: "Example toolbox created by the @azure/ai-projects sample.",
  metadata: { status: "created" },
});
console.log(`Toolbox: ${created.name} (tools: ${created.tools.length})`);
// Retrieve the toolbox
const fetched = await project.beta.toolboxes.get(toolboxName);
console.log(`Retrieved toolbox: ${fetched.name} (${fetched.id})`);

Celý ukázkový kód najdete v toolboxesCrud.ts.

trasování

Poznámka: Funkce trasování je v předběžném náhledu a může se změnit. Rozsahy, atributy a události mohou být v budoucích verzích upraveny.

Do svého projektu Microsoft Foundry můžete přidat resource Application Insights Azure. Podívejte se na záložku Trasování ve vašem projektu Microsoft Foundry. Pokud byl povolen, můžete získat Application Insights připojovací řetězec, nakonfigurovat svého AI Projects klienta a sledovat celou cestu provedení přes Azure Monitor. Obvykle můžete chtít začít s trasováním před vytvořením klienta nebo agenta.

Installation

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

Jak povolit trasování

Zde je ukázka kódu, která ukazuje, jak povolit sledování v Azure Monitor:

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

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

Celý ukázkový kód najdete v remoteTelemetry.ts.

Řešení problémů

Výjimky

Klientské metody, které volání služby vyvolávají RestError pro odpověď stavového kódu HTTP bez úspěchu ze služby. code výjimky bude obsahovat stavový kód odpovědi HTTP. error.message výjimky obsahuje podrobnou zprávu, která může být užitečná při diagnostice problému:

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

Pokud například zadáte nesprávné přihlašovací údaje:

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

problémy s generováním sestav

Pro nahlášení problémů s klientskou knihovnou nebo žádost o další funkce otevřete prosím GitHub číslo zde

Další kroky

Podívejte se na složku package samples, která obsahuje plně běžný kód.

přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která deklaruje, že máte právo a ve skutečnosti nám udělíte práva k používání vašeho příspěvku. Podrobnosti najdete na adrese https://cla.microsoft.com.

Když odešlete žádost o přijetí změn, robot CLA automaticky určí, jestli potřebujete poskytnout CLA, a odpovídajícím způsobem vyzdobit žádost o přijetí změn (např. popisek, komentář). Stačí postupovat podle pokynů poskytovaných robotem. Stačí to udělat jen jednou napříč všemi úložištěmi pomocí naší cla.

Tento projekt přijal Microsoft Open Source Code of Conduct. Další informace najdete v nejčastějších dotazech k kodexu chování nebo se obraťte na opencode@microsoft.com s dalšími dotazy nebo komentáři.