Azure AI Projects biblioteka kliencka dla JavaScript - wersja 2.3.1

Biblioteka klienta AI Projects (w podglądzie) jest częścią SDK Microsoft Foundry i zapewnia łatwy dostęp do zasobów w Twoim Microsoft Foundry Project. Jego zastosowania to:

• Tworzenie i uruchamianie.agents agentów przy użyciu właściwości na kliencie.

• Wzmocnij agentów specjalistycznymi narzędziami:
  • Wyszukiwanie pamięci agenta (Zapowiedź)
  • Agent-to-Agent (A2A) (Zapowiedź)
  • Wyszukiwanie AI platformy Azure
  • Bing Custom Search (Podgląd)
  • Uziemienie Bing
  • Automatyzacja przeglądarki (Podgląd)
  • Interpreter kodów
  • Korzystanie z komputera (Zapowiedź)
  • Wyszukiwanie plików
  • Narzędzie funkcji
  • Generowanie obrazu
  • Microsoft Fabric (Podgląd)
  • Protokół MCP (Model Context Protocol)
  • Interfejs OpenAPI
  • Microsoft SharePoint (Zapowiedź)
  • Wyszukiwanie w sieci (Podgląd)

• Zdobądź klienta OpenAI , który pozwala .getOpenAIClient. uruchamiać operacje odpowiedzi, rozmów, ocen i fineTuningu z agentem.

• Zarządzaj sesjami i plikami agentów beta (podgląd ) za pomocą operacji .beta.agents .
• Zarządzanie umiejętnościami (podgląd) dla możliwości wielokrotnego użytku agenta, korzystając z operacji .beta.skills .
• Zarządzanie skrzynkami narzędzi (podgląd) do grupowania narzędzi w kolekcje wielokrotnego użytku, korzystając z operacji .beta.toolboxes .
• Zarządzanie pamięcią (podgląd) dla rozmów agentów, korzystając z operacji .beta.memoryStores .
• Zarządzanie procedurami (podgląd) do planowania i wysyłania zautomatyzowanych przepływów pracy, korzystając z operacji .beta.routines .
• Zarządzaj wersjami modeli (podgląd ) do tworzenia, aktualizacji i zarządzania niestandardowymi wersjami modeli, korzystając z operacji .beta.models .
• Poznaj dodatkowe narzędzia do oceny (niektóre w wersji podglądowej), aby ocenić wydajność swojej aplikacji generatywnej AI, korzystając z , .evaluationRules.beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, i .beta.schedules operacji.
• Uruchom skany Red Team (podgląd), aby zidentyfikować ryzyka związane z Twoją generatywną aplikacją AI, korzystając z operacji .beta.redTeams .
• Dostosować Modele AI na Twoich danych.

• Enumerate AI Models wdrożone w twojej Foundry Project z wykorzystaniem operacji .deployments.
• Enumeruj powiązane Azure zasoby w swoim projekcie Foundry, używając operacji .connections.
• Przekaż dokumenty i utwórz zestawy danych, aby odwoływać się do nich przy użyciu .datasets operacji.
• Tworzenie i wyliczanie indeksów wyszukiwania przy użyciu .indexes operacji.

Biblioteka klienta korzysta z wersji v1 API REST Microsoft Foundry data plane.

Dokumentacja produktu | Samples | Package (npm) | API referencyjna dokumentacja | SDK kod źródłowy

Spis treści

• Rozpoczęcie pracy
  • Prerequisite
  • Autoryzacja
  • Instalowanie pakietu
• Kluczowe pojęcia
  • Tworzenie i uwierzytelnianie klienta
  • Podgląd grup operacyjnych i flagi funkcji opt-in
• Examples
  • Wykonywanie operacji odpowiedzi przy użyciu klienta OpenAI
  • Wykonywanie operacji agenta
  • Korzystanie z narzędzi Agent
    • Wbudowane narzędzia
    • Connection-Based Narzędzia
  • Operacje ewaluacyjne
  • Operacje wdrożeń
  • Operacje połączeń
  • Operacje na zbiorach danych
  • Operacje na plikach
  • Operacje na indeksach
  • Operacje precyzyjnego strojenia
  • Operacje sesji agentów beta (podgląd)
  • Operacje umiejętności (zapowiedź)
  • Operacje w skrzynkach narzędzi (podgląd)
• Śledzenie
  • Eksperymentalna bramka cech
  • Zaczynam z odrysowującą pracą
  • Installation
  • Jak włączyć śledzenie
  • Umożliwienie nagrywania treści
  • Umożliwianie propagacji kontekstu śladowego
• Troubleshooting
  • Wyjątki
  • problemy z raportowaniem
• Następne kroki
• współtworzenia

Rozpoczęcie pracy

wymagania wstępne

• Wersje LTS systemu Node.js
• Subskrypcja Azure .
• Projekt w Microsoft Foundry.
• URL końcowy projektu w postaci https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name. Można go znaleźć na stronie przeglądowej Microsoft Foundry Project. Poniżej założymy, że zmienna FOUNDRY_PROJECT_ENDPOINT środowiskowa została zdefiniowana tak, aby zawierała tę wartość.

Autoryzacja

• Do uwierzytelnienia klienta potrzebne jest Entra ID. Aplikacja wymaga obiektu, który implementuje interfejs TokenCredential. Przykłady kodu tutaj używają DefaultAzureCredential. Aby uzyskać to działanie, potrzebne będą następujące elementy:
  • Odpowiednie przydziały roli. zobacz Kontrola dostępu oparta na rolach w portalu Microsoft Foundry. Przypisaną rolę można wybrać za pomocą zakładki "Access Control (IAM)" w zasobu Azure AI Project w portalu Azure.
  • Azure CLI zainstalowany.
  • Zalogujesz się na swoje konto Azure, uruchamiając az login.
  • Pamiętaj, że jeśli masz wiele subskrypcji Azure, subskrypcja zawierająca Twój zasób Azure AI Project musi być Twoją domyślną subskrypcją. Uruchom az account list --output table, aby wyświetlić listę wszystkich subskrypcji i zobaczyć, która z nich jest domyślna. Uruchom az account set --subscription "Your Subscription ID or Name", aby zmienić domyślną subskrypcję.

Instalowanie pakietu

npm install @azure/ai-projects dotenv

Kluczowe pojęcia

Utworzenie i uwierzytelnienie klienta za pomocą Entra ID

Entra ID jest obecnie jedyną metodą uwierzytelniania obsługiwaną przez klienta.

Aby skonstruować AIProjectsClientobiekt , można go projectEndpoint pobrać z projectEndpoint. Poniżej założymy, że zmienna FOUNDRY_PROJECT_ENDPOINT środowiskowa została zdefiniowana do przechowywania tej wartości:

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

Podgląd grup operacyjnych i flagi funkcji opt-in

Niektóre operacje podglądowe wymagają wyraźnego foundryFeatures podpisu zgody na zgłoszenie (opt-in). Przykład:

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

Grupy operacji podglądowych obejmują .beta.agents, .beta.skills, .beta.toolboxes, .beta.memoryStores, .beta.routines.beta.models.beta.evaluationTaxonomies.beta.evaluators.beta.insights, , .beta.schedulesoraz ..beta.redTeams

Przykłady

Wykonywanie operacji odpowiedzi przy użyciu klienta OpenAI

Twój projekt Microsoft Foundry może mieć wdrożony jeden lub więcej modeli AI. Mogą to być modele OpenAI, modele Microsoft lub modele innych dostawców. Użyj poniższego kodu, aby uzyskać uwierzytelniony OpenAI z pakietu openai i wykonać wywołanie uzupełniania czatu.

Uruchom poniższy kod. Tutaj zakładamy, że deploymentName (str) jest zdefiniowane. To nazwa wdrożenia modelu AI w Twoim Foundry Project. Jak pokazano na karcie "Modele + punkty końcowe" w kolumnie "Nazwa".

Zobacz folder "responses" w package samples aby zobaczyć dodatkowe przykłady, w tym odpowiedzi streamingowe.

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

Wykonywanie operacji agenta

Właściwość .agents na stronie AIProjectsClient zapewnia dostęp do wszystkich operacji agenta. Agenci korzystają z rozszerzenia protokołu OpenAI Responses, więc prawdopodobnie będziesz musiał uzyskać OpenAI klienta do wykonywania operacji agenta, jak pokazano w poniższym przykładzie.

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

Korzystanie z narzędzi Agent

Agentów można ulepszać specjalistycznymi narzędziami do różnych możliwości. Narzędzia są uporządkowane według wymagań dotyczących połączenia:

Wbudowane narzędzia

Te narzędzia działają natychmiast bez konieczności korzystania z zewnętrznych połączeń.

Interpreter kodów

Pisz i uruchamiaj kod Javascript w środowisku sandboxowym, przetwarzaj pliki i pracuj z różnorodnymi formatami danych. Dokumentacja interfejsu 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}`);

Zobacz pełny przykładowy kod w agentCodeInterpreter.ts.

wyszukiwanie plików

Wbudowane narzędzie RAG (Retrieval-Augmented Generation) do przetwarzania i przeszukiwania dokumentów z wykorzystaniem pamięci wektorowej do wyszukiwania wiedzy. Dokumentacja interfejsu 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})`);

Zobacz pełny przykładowy kod w agentFileSearchStream.ts.

Generowanie obrazów

Generuj obrazy na podstawie podpowiedzi tekstowych z konfigurowalną rozdzielczością, jakością i ustawieniami 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 wywołaniu responses.create()możesz pobrać plik, korzystając z odpowiedzi:

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

Wyszukiwanie w sieci (Podgląd)

Przeprowadzaj ogólne wyszukiwania w sieci, aby uzyskać aktualne informacje z internetu. Dokumentacja interfejsu 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}`);

Zobacz pełny przykładowy kod w agentWebSearch.ts.

Korzystanie z komputera (Zapowiedź)

Umożliwienie agentom bezpośredniej interakcji z systemami komputerowymi w celu automatyzacji zadań i operacji systemowych:

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 wywołaniu responses.create(), przetwarzaj odpowiedź w pętli interakcji. Obsługuj elementy wyjściowe i udostępniaj computer_call zrzuty ekranu w formie computer_call_output typu computer_screenshot , aby kontynuować interakcję.

Zobacz pełny przykładowy kod w agentComputerUse.ts.

Protokół MCP (Model Context Protocol)

Integruj serwery MCP, aby rozszerzyć możliwości agentów za pomocą standaryzowanych narzędzi i zasobów. Dokumentacja interfejsu 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 wywołaniu responses.create(), sprawdź elementy mcp_approval_request w wyjściu odpowiedzi. Odesłać McpApprovalResponse z decyzją o zatwierdzeniu, aby agent mógł kontynuować pracę.

Zobacz pełny przykładowy kod w agentMcp.ts.

OpenAPI

Wywołaj zewnętrzne API zdefiniowane przez specyfikacje OpenAPI bez dodatkowego kodu po stronie klienta. Dokumentacja interfejsu 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})`);

Zobacz pełny przykładowy kod w agentOpenApi.ts.

Narzędzie funkcji

Zdefiniuj niestandardowe funkcje pozwalające agentom na interakcję z zewnętrznymi API, bazami danych lub logiką aplikacji. Dokumentacja interfejsu 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 wywołaniu responses.create(), przetwarzaj function_call elementy z wyjścia odpowiedzi, wykonaj logikę funkcji z podanymi argumentami i wysyłaj z nimi FunctionCallOutput wyniki.

Zobacz pełny przykładowy kod w agentFunctionTool.ts.

• Narzędzie do wyszukiwania pamięci (Podgląd)

Narzędzie Memory Store dodaje Pamięć do Agenta, umożliwiając modelu AI Agenta wyszukiwanie informacji z przeszłości związanych z aktualnym promptem użytkownika.

To embeddingModelDeployment nazwa modelu używanego do tworzenia osadzeń wektorowych do przechowywania i wyszukiwania pamięci.

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

Zobacz pełny przykładowy kod w agentMemorySearch.ts.

Connection-Based Narzędzia

Te narzędzia wymagają konfiguracji połączeń w projekcie AI Foundry i używania projectConnectionId.

Wyszukiwanie AI platformy Azure

Integruj się z indeksami Wyszukiwanie AI platformy Azure dla potężnych możliwości wyszukiwania wiedzy i wyszukiwania semantycznego:

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

Zobacz pełny przykładowy kod w agentAiSearch.ts.

Podstawy Binga

Odpowiedzi agentów naziemnych z wynikami wyszukiwania w czasie rzeczywistym z Bing, dostarczające informacje o up-to-dacie:

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

Zobacz pełny przykładowy kod w agentBingGrounding.ts.

Bing Custom Search (Podgląd)

Używaj niestandardowo skonfigurowanych instancji wyszukiwania Bing dla wyników wyszukiwania danych w konkretnych domenach lub filtrowanych w sieci:

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

Zobacz pełny przykładowy kod w agentBingCustomSearch.ts.

Microsoft Fabric (Podgląd)

Połącz się i zapytaj 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})`);

Zobacz pełny przykładowy kod w agentFabric.ts.

Microsoft SharePoint (Podgląd)

Dostęp i wyszukiwanie dokumentów, list i stron SharePoint w celu integracji wiedzy korporacyjnej:

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

Zobacz pełny przykładowy kod w agentSharepoint.ts.

Automatyzacja przeglądarki (Podgląd)

Automatyzuj interakcje przeglądarki w zakresie pobierania danych, testowania i interakcji z aplikacjami webowymi:

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

Zobacz pełny przykładowy kod w agentBrowserAutomation.ts.

MCP z Project Connection

Integracja MCP z wykorzystaniem połączeń specyficznych dla projektu do dostępu do połączonych serwerów MCP:

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

Zobacz pełny przykładowy kod w agentMcpConnectionAuth.ts.

Agent-to-Agent (A2A) (Zapowiedź)

Umożliwienie współpracy wieloagentowej, gdzie agenci mogą komunikować się i delegować zadania innym wyspecjalizowanym agentom:

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

Zobacz pełny przykładowy kod w agentAgentToAgent.ts.

OpenAPI z Project Connection

Wywołaj zewnętrzne API zdefiniowane przez specyfikacje OpenAPI za pomocą uwierzytelniania połączenia 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})`);

Zobacz pełny przykładowy kod w agentOpenApiConnectionAuth.ts.

Pełne przykłady pracy wszystkich narzędzi można znaleźć w katalogu samples-dev.

Evaluation

Ocena w bibliotece klienta Azure AI Project dostarcza ilościowych, wspieranych przez AI metryk jakości i bezpieczeństwa do oceny wydajności oraz oceny modeli LLM, aplikacji GenAI i agentów. Metryki definiuje się jako ewaluatorów. Wbudowani lub niestandardowi ewaluatorzy mogą dostarczyć kompleksowych informacji o ocenie.

Poniższy kod pokazuje niektóre operacje ewaluacyjne. Pełną listę próbek można znaleźć w folderze "evaluations" w 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})`);

Zobacz pełny przykładowy kod w agentEvaluation.ts.

Operacje wdrożeń

Poniższy kod pokazuje niektóre operacje wdrożeń, które pozwalają wymienić modele AI wdrożone w Twoich projektach Microsoft Foundry. Modele te można zobaczyć w zakładce "Modele + punkty końcowe" w Microsoft Foundry Project. Pełne próbki można znaleźć w folderze "deployment" w 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)}`);
}

Operacje połączeń

Poniższy kod pokazuje niektóre operacje Connection, które pozwalają wypisać zasoby Azure powiązane z Twoimi projektami Microsoft Foundry. Te połączenia można zobaczyć w "Management Center" w zakładce "Connected resources" w Microsoft Foundry Project. Pełne próbki można znaleźć w folderze "connections" w 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)}`);

Operacje na zbiorach danych

Poniższy kod przedstawia niektóre operacje zestawu danych. Pełne próbki można znaleźć w folderze "datasets" w 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.");

Operacje na plikach

Poniższy kod przedstawia niektóre operacje na plikach przy użyciu klienta OpenAI, które umożliwiają przekazywanie, pobieranie, wyświetlanie i usuwanie plików. Te operacje są przydatne do pracy z plikami, które mogą być używane do dostrajania i innych operacji modelu AI. Pełne próbki można znaleźć w folderze "files" w 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)}`,
);

Operacje na indeksach

Poniższy kod przedstawia niektóre operacje indeksów. Pełne próbki można znaleźć w folderze "indexes" w 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);

Operacje dostrajania

Poniższy kod pokazuje, jak tworzyć zadania precyzyjne za pomocą klienta OpenAI. Operacje te wspierają różne techniki precyzyjnego dostrojenia, takie jak Fine-Tuning nadzorowane (SFT), Fine-Tuning wzmacniania (RFT) oraz optymalizacja wydajności bezpośredniej (DPO). Pełne próbki można znaleźć w folderze "finetuning" w 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));

Operacje sesji agentów beta (podgląd)

Operacje pozwalają .beta.agents zarządzać sesjami agentów i plikami sesji dla hostowanych agentów. Sesje zapewniają izolowane środowiska sandboxowe do interakcji z agentami.

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

const agentName = "MyBetaAgent";
// Create a session for the agent
const versionIndicator: VersionRefIndicator = {
  type: "version_ref",
  agent_version: "1.0",
};
const session = await project.beta.agents.createSession(agentName, 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)`);

Zobacz pełny przykładowy kod w betaAgents.ts.

Operacje umiejętności (zapowiedź)

Operacje pozwalają .beta.skills tworzyć i zarządzać umiejętnościami wielokrotnego użytku, które definiują możliwości agentów.

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

Zobacz pełny przykładowy kod w skillBasic.ts.

Operacje w skrzynkach narzędzi (podgląd)

Operacje pozwalają .beta.toolboxes tworzyć i zarządzać zestawami narzędzi — wielokrotnego użytku zbiorami narzędzi, które można udostępniać między agentami.

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.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.toolboxes.get(toolboxName);
console.log(`Retrieved toolbox: ${fetched.name} (${fetched.id})`);

Zobacz pełny przykładowy kod w toolboxesCrud.ts.

Śledzenie

Eksperymentalna bramka cech

Ważne: Instrumentacja do śledzenia GenAI to eksperymentalna funkcja podglądu. Zakresy, atrybuty i zdarzenia mogą być modyfikowane w przyszłych wersjach. Aby go użyć, musisz wyraźnie się zgłosić, przekazując tracingOptions z przy experimental: true konstruowaniu AIProjectClient, lub ustawiając zmienną środowiskową:

AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true

Włącz tę funkcję dopiero po zapoznaniu się z wymaganiami i zrozumieniu, że zachowanie śledzenia może ulec zmianie w przyszłych wersjach.

Zaczynam z odrysowującą pracą

Możesz dodać zasób Application Insights Azure do swojego projektu Microsoft Foundry. Jeśli taki był włączony, możesz pobrać parametry połączenia Application Insights, skonfigurować klienta AI Projects i obserwować ślady w Azure Monitor. Zazwyczaj warto rozpocząć śledzenie przed utworzeniem klienta lub agenta.

Installation

Aby wysłać trasy do Azure Monitor:

npm install @azure/monitor-opentelemetry @opentelemetry/api

Aby wydrukować ślady do konsoli (przydatne przy lokalnym rozwoju):

npm install @opentelemetry/sdk-trace-node @opentelemetry/api

Jak włączyć śledzenie

Śledzenie jest możliwe poprzez przekazanie do tracingOptionsAIProjectClient konstruktora. Jeśli tracingOptions nie jest udostępniony, śledzenie GenAI jest całkowicie wyłączone i nie są emitowane żadne rozpinania ani metryki GenAI. To ustawienie kontroluje wyłącznie śledzenie specyficzne dla GenAI (zakres konwencji semantycznych dla wywołań modeli, operacji agentów, użycia tokenów itp.). Konfiguracja śledzenia dotyczy wszystkich operacji wykonywanych przez tę konkretną instancję klienta, w tym operacji agenta oraz każdego klienta OpenAI uzyskanego za pomocą project.getOpenAIClient(). Różne instancje klienta mogą mieć niezależne konfiguracje śledzenia.

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

const endpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
const credential = new DefaultAzureCredential();

// Tracing enabled
const project = new AIProjectClient(endpoint, credential, {
  tracingOptions: { experimental: true },
});

// Tracing disabled (default — no tracingOptions passed)
const projectNoTrace = new AIProjectClient(endpoint, credential);

console.log(project, projectNoTrace);

Przekazywanie tracingOptions: {} (pusty obiekt) umożliwia również śledzenie — w takim przypadku wszystkie indywidualne ustawienia są rozwiązywane na podstawie odpowiadających im zmiennych środowiskowych.

Obiekt przyjmuje tracingOptions następujące właściwości:

Każda opcja jest rozstrzygana według następującej kolejności precedencji:

1. Wartość jawna w tracingOptions (najwyższy priorytet)
2. Zmienna środowiskowa (sprawdzana, gdy opcja jest pomijana/niezdefiniowana)
3. Wartość domyślna (używana, gdy żadna z nich nie jest ustawiona lub zmienna środowiskowa nie może być odczytana)

Uwaga: Ponieważ wszystkie cechy śledzenia są obecnie eksperymentalne, experimental: true muszą być również ustawione (jawnie lub za pomocą zmiennej środowiskowej), aby dowolne rozpiętości zostały emitowane.

Azure Monitor tracing

Oto przykład kodu pokazujący, jak włączyć śledzenie w Azure Monitor:

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

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
// Configure Azure Monitor tracing (must be done before creating the client)
const connectionString =
  process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<connection string>";
useAzureMonitor({
  azureMonitorExporterOptions: { connectionString },
  samplingRatio: 1,
  tracesPerSecond: 0,
});
// Create client with tracing enabled (experimental)
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential(), {
  tracingOptions: {
    experimental: true,
    contentRecording: false,
    traceContextPropagation: true,
  },
});

Możesz także chcieć stworzyć rozstęp dla swojego scenariusza:

import { trace, context } from "@opentelemetry/api";

const tracer = trace.getTracer("MyScenario");
const span = tracer.startSpan("myOperation");
const ctx = trace.setSpan(context.active(), span);
await context.with(ctx, async () => {
  // Your agent operations here
});
span.end();

Zobacz pełny przykładowy kod w agentBasicWithAzureMonitorTracing.ts.

Śledzenie konsoli

Do lokalnego rozwoju możesz drukować ścieżki na konsoli:

import {
  NodeTracerProvider,
  SimpleSpanProcessor,
  ConsoleSpanExporter,
} from "@opentelemetry/sdk-trace-node";
import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

// Set up OpenTelemetry with a console exporter (must be done before creating the client)
const provider = new NodeTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
});
provider.register();
// Create client with tracing enabled (experimental)
const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential(), {
  tracingOptions: {
    experimental: true,
    contentRecording: false,
    traceContextPropagation: true,
  },
});

Zobacz pełny przykładowy kod w agentBasicWithConsoleTracing.ts.

Umożliwienie nagrywania treści

Rejestrowanie treści kontroluje, czy zawartość wiadomości i szczegóły wywołań narzędzi (takie jak parametry i wartości zwrotne) są rejestrowane w śladach. Dane te mogą zawierać wrażliwe informacje użytkowników.

Aby umożliwić nagrywanie treści, przekaż contentRecording: true podczas tracingOptions tworzenia klienta lub ustaw zmienną OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT środowiskową na .true Domyślne nagrywanie treści jest ustawione na false.

Umożliwianie propagacji kontekstu śladowego

Propagacja kontekstu śledzenia pozwala na korelację obszarów po stronie klienta z obszarami serwerowymi z Azure, OpenAI i innych usług Azure. Po włączeniu SDK automatycznie wstrzykuje nagłówki W3C Trace Context (traceparent i tracestate) do żądań HTTP wysyłanych przez klientów OpenAI uzyskanych przez project.getOpenAIClient().

Zapewnia to, że wszystkie operacje w rozproszonym śladzie dzielą ten sam identyfikator śledzenia, zapewniając end-to-end widoczność aplikacji i usług Azure w backendzie obserwacji.

Propagacja kontekstu śledzenia jest domyślnie włączona. Aby ją wyłączyć, przekaż traceContextPropagation: false podczas tracingOptions budowy klienta lub ustaw zmienną AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION środowiskową na .false

Ważne kwestie bezpieczeństwa i prywatności:

• ID śledzenia: Gdy propagacja kontekstu śledzenia jest włączona, identyfikatory śledzenia są wysyłane do Azure OpenAI i innych zewnętrznych usług.
• Korelacja żądań: Identyfikatory śledzenia pozwalają usługom Azure korelować żądania z tej samej sesji lub użytkownika pomiędzy wieloma wywołaniami API, co może mieć znaczenie dla prywatności w zależności od Twojego zastosowania.

Włączaj propagację kontekstu śledzenia tylko po dokładnym przeanalizowaniu wymagań dotyczących obserwowalności, prywatności i bezpieczeństwa.

Rozwiązywanie problemów

Wyjątki

Metody klienta, które tworzą wywołania usługi, zgłaszają resterror odpowiedzi kodu stanu HTTP z usługi. code wyjątku będzie przechowywać kod stanu odpowiedzi HTTP. error.message wyjątku zawiera szczegółowy komunikat, który może być przydatny podczas diagnozowania problemu:

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

Na przykład w przypadku podania nieprawidłowych poświadczeń:

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

problemy z raportowaniem

Aby zgłosić problemy z biblioteką klienta lub poprosić o dodatkowe funkcje, prosimy o otwarcie GitHub numeru tutaj

Następne kroki

Spójrz na folder package samples, zawierający w pełni uruchomiony kod.

Regeneracja z TypeSpec (otrzymywacze)

Ten pakiet jest generowany ze specyfikacji TypeSpec w Azure/azure-rest-api-specs. Cały przepływ pracy jest zakodowany jako sześć umiejętności w ramach .github/skills/ i może być sterowany end-to-end przez zadanie GitHub Copilot agenta kodującego.

Aby wysłać regen jako zadanie agenta chmurowego, uruchom z tego katalogu:

pwsh -NoProfile -File ./scripts/start-cloud-regen.ps1                     # latest commit on feature/foundry-release
pwsh -NoProfile -File ./scripts/start-cloud-regen.ps1 -TspCommit <sha>    # pin a specific commit
pwsh -NoProfile -File ./scripts/start-cloud-regen.ps1 -DryRun             # render the prompt locally, do not dispatch
pwsh -NoProfile -File ./scripts/start-cloud-regen.ps1 -Repo myuser/azure-sdk-for-js -Follow   # smoke-test on a fork

Na Windows wywoływanie skryptu bezpośrednio (np. ./scripts/start-cloud-regen.ps1) może być zablokowane przez domyślną politykę wykonywania Restricted. Powyższa forma pwsh -NoProfile -File ... to omija. Alternatywnie, uruchom Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned raz, aby umożliwić lokalne skrypty.

Prerequisites:

• gh CLI zainstalowało i uwierzytelniło (gh auth login) względem docelowego repozytorium. Podkomenda agent-task jest w podglądzie i wymaga niedawnego gh.
• Członkostwo w organizacji z włączonym agentem kodowania GitHub Copilot dla repozytorium docelowego.
• Push access do docelowego repozytorium (agent chmurowy używa własnej tożsamości aplikacji GitHub, aby wypchnąć i otworzyć draft PR).

Zastrzeżenie: wysłany prompt pnpm install --filter @azure/ai-projects... uruchamia się i pnpm --filter @azure/ai-projects... build inline na początku zadania. Jeśli sandbox agenta chmurowego zablokuje te wywołania sieciowe, zadanie nie przestanie się konfigurować; w takim przypadku uruchom umiejętności lokalnie lub skoordynuj z zespołem budującym SDK, aby dodać centralnie zarządzany copilot-setup-steps.yml workflow na korzu repozytorium.

współtworzenia

Ten projekt z zadowoleniem przyjmuje wkład i sugestie. Większość kontrybucja wymaga zgody na umowę licencyjną współautora (CLA), deklarując, że masz prawo, a w rzeczywistości przyznaj nam prawa do korzystania z twojego wkładu. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia bot CLA automatycznie określi, czy musisz podać cla i odpowiednio ozdobić żądanie ściągnięcia (np. etykieta, komentarz). Po prostu postępuj zgodnie z instrukcjami dostarczonymi przez bota. Należy to zrobić tylko raz we wszystkich repozytoriach przy użyciu naszego CLA.

Projekt ten przyjął Microsoft Kodeks Postępowania Open Source . Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com z dodatkowymi pytaniami lub komentarzami.