Pustaka klien Azure AI Projects untuk JavaScript - versi 2.3.1

Pustaka klien Proyek AI (dalam pratinjau) adalah bagian dari Microsoft Foundry SDK, dan menyediakan akses mudah ke sumber daya di Microsoft Foundry Project Anda. Gunakan untuk:

• Buat dan jalankan Agen menggunakan .agents properti pada klien.

• Tingkatkan Agen dengan alat khusus:
  • Pencarian Memori Agen (Pratinjau)
  • Agen-ke-Agen (A2A) (Pratinjau)
  • Pencarian Azure AI
  • Pencarian Kustom Bing (Pratinjau)
  • Pembumian Bing
  • Otomatisasi Browser (Pratinjau)
  • Penerjemah Kode
  • Penggunaan Komputer (Pratinjau)
  • Pencarian File
  • Alat Fungsi
  • Pembuatan Gambar
  • Microsoft Fabric (Pratinjau)
  • Protokol Konteks Model (MCP)
  • OpenAPI
  • Microsoft SharePoint (Pratinjau)
  • Penelusuran Web (Pratinjau)

• Dapatkan klien OpenAI menggunakan metode untuk .getOpenAIClient. menjalankan operasi Respons, Percakapan, Eval, dan FineTuning dengan Agen Anda.

• Kelola sesi dan file agen beta (pratinjau) menggunakan .beta.agents operasi.
• Kelola keterampilan (pratinjau) untuk kemampuan agen yang dapat digunakan kembali, menggunakan .beta.skills operasi.
• Kelola kotak alat (pratinjau) untuk mengelompokkan alat ke dalam koleksi yang dapat digunakan kembali, menggunakan .beta.toolboxes operasi.
• Kelola penyimpanan memori (pratinjau) untuk percakapan Agen, menggunakan .beta.memoryStores operasi.
• Kelola rutinitas (pratinjau) untuk menjadwalkan dan mengirimkan alur kerja otomatis, menggunakan .beta.routines operasi.
• Kelola versi model (pratinjau) untuk membuat, memperbarui, dan mengelola versi model kustom, menggunakan .beta.models operasi.
• Jelajahi alat evaluasi tambahan (beberapa dalam pratinjau) untuk menilai performa aplikasi AI generatif Anda, menggunakan .evaluationRules, .beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, dan .beta.schedules operasi.
• Jalankan pemindaian Tim Merah (pratinjau) untuk mengidentifikasi risiko yang terkait dengan aplikasi AI generatif Anda, menggunakan .beta.redTeams operasi.
• Penyetelan halus Model AI pada data Anda.

• Enumerate AI Models yang disebarkan ke Project Foundry Anda menggunakan operasi .deployments.
• Hitung sumber daya Azure yang terhubung dalam proyek Foundry Anda menggunakan operasi .connections.
• Unggah dokumen dan buat Himpunan Data untuk mereferensikannya menggunakan .datasets operasi.
• Membuat dan menghitung Indeks Pencarian menggunakan .indexes operasi.

Pustaka klien menggunakan versi v1 dari Microsoft Foundry data plane REST APIs.

Dokumentasi produk | Sampel | Paket (npm) | Dokumentasi referensi API | Kode sumber SDK

Daftar isi

• Panduan Memulai
  • Prasyarat
  • Otorisasi
  • Instal paket
• Konsep Utama
  • Membuat dan mengautentikasi klien
  • Pratinjau grup operasi dan bendera fitur keikutsertaan
• Examples
  • Melakukan operasi Respons menggunakan klien OpenAI
  • Melakukan operasi Agen
  • Menggunakan alat Agen
    • Alat Bawaan
    • AlatConnection-Based
  • Operasi evaluasi
  • Operasi penyebaran
  • Operasi koneksi
  • Operasi himpunan data
  • Operasi file
  • Operasi indeks
  • Operasi penyempurnaan
  • Operasi sesi agen beta (pratinjau)
  • Operasi keterampilan (pratinjau)
  • Operasi kotak alat (pratinjau)
• Pelacakan
  • Gerbang fitur eksperimental
  • Memulai dengan pelacakan
  • Penginstalan
  • Cara mengaktifkan pelacakan
  • Mengaktifkan perekaman konten
  • Mengaktifkan propagasi konteks pelacakan
• Pemecahan masalah
  • Pengecualian
  • masalah Pelaporan
• Langkah berikutnya
• Berkontribusi

Panduan Memulai

Prasyarat

• Versi LTS dari Node.js
• Langganan Azure.
• Sebuah proyek di Microsoft Foundry.
• URL titik akhir proyek formulir https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name. Ini dapat ditemukan di halaman gambaran umum Microsoft Foundry Project Anda. Di bawah ini kita akan mengasumsikan variabel FOUNDRY_PROJECT_ENDPOINT lingkungan didefinisikan untuk menahan nilai ini.

Otorisasi

• Entra ID diperlukan untuk mengautentikasi klien. Aplikasi Anda memerlukan objek yang mengimplementasikan antarmuka TokenCredential . Contoh kode di sini menggunakan DefaultAzureCredential. Untuk mendapatkan pekerjaan itu, Anda akan membutuhkan:
  • Penugasan peran yang sesuai. lihat Kontrol akses berbasis peran di portal Microsoft Foundry. Peran yang ditetapkan dapat dilakukan melalui tab "Access Control (IAM)" dari sumber daya Azure AI Project Anda di portal Azure.
  • Azure CLI diinstal.
  • Anda masuk ke akun Azure Anda dengan menjalankan az login.
  • Perhatikan bahwa jika Anda memiliki beberapa langganan Azure, langganan yang berisi sumber daya Azure AI Project Anda harus menjadi langganan default Anda. Jalankan az account list --output table untuk mencantumkan semua langganan Anda dan melihat langganan mana yang merupakan default. Jalankan az account set --subscription "Your Subscription ID or Name" untuk mengubah langganan default Anda.

Instal paket

npm install @azure/ai-projects dotenv

Konsep Utama

Buat dan autentikasi klien dengan Entra ID

Entra ID adalah satu-satunya metode otentikasi yang didukung saat ini oleh klien.

Untuk membuat AIProjectsClient, dapat projectEndpoint diambil dari projectEndpoint. Di bawah ini kita akan mengasumsikan variabel FOUNDRY_PROJECT_ENDPOINT lingkungan didefinisikan untuk menyimpan nilai ini:

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

Pratinjau grup operasi dan bendera fitur keikutsertaan

Beberapa operasi pratinjau memerlukan bendera keikutsertaan eksplisit.foundryFeatures Contohnya:

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

Grup operasi pratinjau termasuk .beta.agents, .beta.skills, .beta.toolboxes.beta.memoryStores.beta.routines.beta.models.beta.evaluationTaxonomies.beta.evaluators.beta.insights.beta.schedules.beta.redTeams,

Examples

Melakukan operasi Respons menggunakan klien OpenAI

Proyek Microsoft Foundry Anda mungkin memiliki satu atau beberapa model AI yang disebarkan. Ini bisa berupa model OpenAI, model Microsoft, atau model dari penyedia lain. Gunakan kode di bawah ini untuk mendapatkan OpenAI yang diautentikasi dari paket openai , dan jalankan panggilan penyelesaian obrolan.

Jalankan kode di bawah ini. Di sini kita berasumsi deploymentName (str) didefinisikan. Ini adalah nama penyebaran model AI di Foundry Project Anda. Seperti yang ditunjukkan di tab "Model + titik akhir", di bawah kolom "Nama".

Lihat folder "respons" di package samples untuk sampel tambahan, termasuk respons streaming.

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

Melakukan operasi Agen

.agents Properti di memberi AIProjectsClient Anda akses ke semua operasi Agen. Agen menggunakan ekstensi protokol OpenAI Responses, jadi Anda mungkin perlu meminta OpenAI klien untuk melakukan operasi Agen, seperti yang ditunjukkan pada contoh di bawah ini.

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

Menggunakan alat Agen

Agen dapat ditingkatkan dengan alat khusus untuk berbagai kemampuan. Alat diatur berdasarkan persyaratan koneksinya:

Alat Bawaan

Alat-alat ini bekerja segera tanpa memerlukan koneksi eksternal.

Penerjemah Kode

Tulis dan jalankan kode Javascript di lingkungan kotak pasir, proses file, dan bekerja dengan beragam format data. Dokumentasi 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}`);

Lihat kode sampel lengkap di agentCodeInterpreter.ts.

Pencarian File

Alat RAG (Retrieval-Augmented Generation) bawaan untuk memproses dan mencari dokumen menggunakan toko vektor untuk pengambilan pengetahuan. Dokumentasi 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})`);

Lihat kode sampel lengkap dalam agentFileSearchStream.ts.

Pembuatan Gambar

Hasilkan gambar berdasarkan perintah teks dengan pengaturan resolusi, kualitas, dan gaya yang dapat disesuaikan:

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

Setelah memanggil responses.create(), Anda dapat mengunduh file menggunakan respons yang dikembalikan:

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

Penelusuran Web (Pratinjau)

Lakukan pencarian web umum untuk mengambil informasi terkini dari internet. Dokumentasi 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}`);

Lihat kode sampel lengkap di agentWebSearch.ts.

Penggunaan Komputer (Pratinjau)

Memungkinkan agen untuk berinteraksi langsung dengan sistem komputer untuk otomatisasi tugas dan operasi sistem:

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

Setelah memanggil responses.create(), memproses respons dalam perulangan interaksi. Tangani computer_call item output dan berikan tangkapan layar seperti computer_call_output jenis computer_screenshot untuk melanjutkan interaksi.

Lihat kode sampel lengkap dalam agentComputerUse.ts.

Protokol Konteks Model (MCP)

Integrasikan server MCP untuk memperluas kemampuan agen dengan alat dan sumber daya standar. Dokumentasi 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" } },
  },
);

Setelah memanggil responses.create(), periksa mcp_approval_request item dalam output respons. Kirim kembali McpApprovalResponse dengan keputusan persetujuan Anda untuk mengizinkan agen melanjutkan pekerjaannya.

Lihat kode sampel lengkap di agentMcp.ts.

OpenAPI

Panggil API eksternal yang ditentukan oleh spesifikasi OpenAPI tanpa kode sisi klien tambahan. Dokumentasi 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})`);

Lihat kode sampel lengkap dalam agentOpenApi.ts.

Alat Fungsi

Tentukan fungsi kustom yang memungkinkan agen berinteraksi dengan API eksternal, database, atau logika aplikasi. Dokumentasi 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})`);

Setelah memanggil responses.create(), memproses function_call item dari output respons, jalankan logika fungsi Anda dengan argumen yang disediakan, dan kirim kembali FunctionCallOutput dengan hasilnya.

Lihat kode sampel lengkap dalam agentFunctionTool.ts.

• Alat Pencarian Memori (Pratinjau)

Alat Penyimpanan Memori menambahkan Memori ke Agen, memungkinkan model AI Agen untuk mencari informasi masa lalu yang terkait dengan permintaan pengguna saat ini.

Ini embeddingModelDeployment adalah nama model yang digunakan untuk membuat penyematan vektor untuk menyimpan dan mencari memori.

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

Lihat kode sampel lengkap dalam agentMemorySearch.ts.

AlatConnection-Based

Alat-alat ini memerlukan konfigurasi koneksi dalam proyek AI Foundry Anda dan menggunakan projectConnectionId.

Pencarian Azure AI

Integrasikan dengan indeks Pencarian Azure AI untuk pengambilan pengetahuan yang andal dan kemampuan pencarian semantik:

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

Lihat kode sampel lengkap di agentAiSearch.ts.

Pembumian Bing

Tanggapan agen darat dengan hasil pencarian web real-time dari Bing untuk memberikan informasi tanggal up-to:

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

Lihat kode sampel lengkap dalam agentBingGrounding.ts.

Pencarian Kustom Bing (Pratinjau)

Gunakan instans pencarian Bing yang dikonfigurasi khusus untuk hasil pencarian web khusus domain atau yang difilter:

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

Lihat kode sampel lengkap dalam agentBingCustomSearch.ts.

Microsoft Fabric (Pratinjau)

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

Lihat kode sampel lengkap dalam agentFabric.ts.

Microsoft SharePoint (Pratinjau)

Mengakses dan mencari dokumen, daftar, dan situs SharePoint untuk integrasi pengetahuan perusahaan:

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

Lihat kode sampel lengkap dalam agentSharepoint.ts.

Otomatisasi Browser (Pratinjau)

Otomatiskan interaksi browser untuk pengikisan web, pengujian, dan interaksi dengan aplikasi web:

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

Lihat kode sampel lengkap dalam agentBrowserAutomation.ts.

MCP dengan Koneksi Project

Integrasi MCP menggunakan koneksi khusus proyek untuk mengakses server MCP yang terhubung:

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

Lihat kode sampel lengkap dalam agentMcpConnectionAuth.ts.

Agen-ke-Agen (A2A) (Pratinjau)

Aktifkan kolaborasi multi-agen di mana agen dapat berkomunikasi dan mendelegasikan tugas ke agen khusus lainnya:

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

Lihat kode sampel lengkap dalam agentAgentToAgent.ts.

OpenAPI dengan Koneksi Project

Panggil API eksternal yang ditentukan oleh spesifikasi OpenAPI menggunakan autentikasi koneksi proyek:

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

Lihat kode sampel lengkap di agentOpenApiConnectionAuth.ts.

Untuk contoh kerja lengkap dari semua alat, lihat direktori samples-dev.

Penilaian

Evaluasi di pustaka klien Azure AI Project menyediakan metrik kualitas dan keamanan kuantitatif yang dibantu AI untuk menilai performa dan Mengevaluasi Model LLM, Aplikasi GenAI, dan Agen. Metrik didefinisikan sebagai evaluator. Evaluator bawaan atau kustom dapat memberikan wawasan evaluasi yang komprehensif.

Kode di bawah ini menunjukkan beberapa operasi evaluasi. Daftar lengkap sampel dapat ditemukan di bawah folder "evaluasi" di 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})`);

Lihat kode sampel lengkap di agentEvaluation.ts.

Operasi penyebaran

Kode di bawah ini menunjukkan beberapa operasi Penyebaran, yang memungkinkan Anda menghitung model AI yang disebarkan ke Proyek Microsoft Foundry Anda. Model-model ini dapat dilihat di tab "Model + titik akhir" di Microsoft Foundry Project Anda. Sampel lengkap dapat ditemukan di bawah folder "deployment" di 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)}`);
}

Operasi koneksi

Kode di bawah ini menunjukkan beberapa operasi Koneksi, yang memungkinkan Anda menghitung Sumber Daya Azure yang terhubung ke Proyek Microsoft Foundry Anda. Koneksi ini dapat dilihat di "Pusat Manajemen", di tab "Sumber daya yang terhubung" di Microsoft Foundry Project Anda. Sampel lengkap dapat ditemukan di bawah folder "koneksi" di 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)}`);

Operasi himpunan data

Kode di bawah ini menunjukkan beberapa operasi Himpunan Data. Sampel lengkap dapat ditemukan di bawah folder "himpunan data" di 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.");

Operasi file

Kode di bawah ini menunjukkan beberapa operasi File menggunakan klien OpenAI, yang memungkinkan Anda mengunggah, mengambil, mencantumkan, dan menghapus file. Operasi ini berguna untuk bekerja dengan file yang dapat digunakan untuk penyempurnaan dan operasi model AI lainnya. Sampel lengkap dapat ditemukan di bawah folder "file" di 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)}`,
);

Operasi indeks

Kode di bawah ini menunjukkan beberapa operasi Indeks. Sampel lengkap dapat ditemukan di bawah folder "indeks" di 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);

Operasi penyempurnaan

Kode di bawah ini menunjukkan cara membuat pekerjaan penyempurnaan menggunakan klien OpenAI. Operasi ini mendukung berbagai teknik penyempurnaan seperti Supervised Fine-Tuning (SFT), Reinforcement Fine-Tuning (RFT), dan Direct Performance Optimization (DPO). Sampel lengkap dapat ditemukan di bawah folder "finetuning" di 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));

Operasi sesi agen beta (pratinjau)

Operasi ini .beta.agents memungkinkan Anda mengelola sesi agen dan file sesi untuk agen yang dihosting. Sesi menyediakan lingkungan kotak pasir terisolasi untuk interaksi agen.

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

Lihat kode sampel lengkap di betaAgents.ts.

Operasi keterampilan (pratinjau)

Operasi memungkinkan .beta.skills Anda membuat dan mengelola keterampilan yang dapat digunakan kembali yang menentukan kemampuan agen.

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

Lihat kode sampel lengkap di skillBasic.ts.

Operasi kotak alat (pratinjau)

Operasi ini .beta.toolboxes memungkinkan Anda membuat dan mengelola kotak alat — kumpulan alat yang dapat digunakan kembali yang dapat dibagikan di seluruh agen.

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

Lihat kode sampel lengkap dalam toolboxesCrud.ts.

Pelacakan

Gerbang fitur eksperimental

Itu penting: Instrumentasi pelacakan GenAI adalah fitur pratinjau eksperimental. Rentang, atribut, dan peristiwa dapat dimodifikasi di versi mendatang. Untuk menggunakannya, Anda harus secara eksplisit ikut serta dengan meneruskan tracingOptions saat experimental: true membuat AIProjectClient, atau dengan mengatur variabel lingkungan:

AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true

Aktifkan fitur ini hanya setelah meninjau persyaratan Anda dan memahami bahwa perilaku pelacakan dapat berubah di versi mendatang.

Memulai dengan pelacakan

Anda dapat menambahkan sumber daya Application Insights Azure ke proyek Microsoft Foundry Anda. Jika salah satu diaktifkan, Anda bisa mendapatkan string koneksi Application Insights, mengonfigurasi klien Proyek AI Anda, dan mengamati pelacakan di Azure Monitor. Biasanya, Anda mungkin ingin mulai melacak sebelum membuat klien atau Agen.

Penginstalan

Untuk mengirim pelacakan ke Azure Monitor:

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

Untuk mencetak jejak ke konsol (berguna untuk pengembangan lokal):

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

Cara mengaktifkan pelacakan

Pelacakan diaktifkan dengan meneruskan tracingOptions ke AIProjectClient konstruktor. Jika tracingOptions tidak disediakan, pelacakan GenAI dinonaktifkan sepenuhnya dan tidak ada rentang atau metrik GenAI yang dipancarkan. Pengaturan ini hanya mengontrol pelacakan khusus GenAI (rentang konvensi semantik untuk panggilan model, operasi agen, penggunaan token, dll.). Konfigurasi pelacakan berlaku untuk semua operasi yang dilakukan melalui instans klien tertentu, termasuk operasi agen dan klien OpenAI apa pun yang diperoleh melalui project.getOpenAIClient(). Instans klien yang berbeda dapat memiliki konfigurasi pelacakan independen.

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

Meneruskan tracingOptions: {} (objek kosong) juga memungkinkan pelacakan — dalam hal ini, semua pengaturan individual diselesaikan dari variabel lingkungan yang sesuai.

Objek menerima tracingOptions properti berikut:

Option	Variabel Lingkungan	Default	Description
experimental	AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING	false	Akui sifat eksperimental dari fitur ini (diperlukan untuk memancarkan rentang)
contentRecording	OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	false	Menangkap konten prompt dan penyelesaian dalam pelacakan
traceContextPropagation	AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION	true	Menyuntikkan header konteks pelacakan W3C ke dalam permintaan

Setiap opsi diselesaikan menggunakan urutan prioritas berikut:

1. Nilai eksplisit di tracingOptions (prioritas tertinggi)
2. Variabel lingkungan (dicentang saat opsi dihilangkan/tidak ditentukan)
3. Nilai default (digunakan saat tidak diatur atau variabel lingkungan tidak dapat dibaca)

Catatan: Karena semua fitur pelacakan saat ini bersifat eksperimental, experimental: true juga harus diatur (baik secara eksplisit atau melalui variabel lingkungan) agar rentang apa pun akan dipancarkan.

Pelacakan Azure Monitor

Berikut adalah contoh kode yang menunjukkan cara mengaktifkan pelacakan 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,
  },
});

Anda mungkin juga ingin membuat rentang untuk skenario Anda:

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

Lihat kode sampel lengkap di agentBasicWithAzureMonitorTracing.ts.

Pelacakan konsol

Untuk pengembangan lokal, Anda dapat mencetak jejak ke konsol:

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

Lihat kode sampel lengkap di agentBasicWithConsoleTracing.ts.

Mengaktifkan perekaman konten

Perekaman konten mengontrol apakah konten pesan dan detail panggilan alat (seperti parameter dan nilai pengembalian) ditangkap dalam pelacakan. Data ini mungkin termasuk informasi pengguna yang sensitif.

Untuk mengaktifkan perekaman konten, teruskan contentRecording: truetracingOptions saat membuat klien, atau atur variabel OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT lingkungan ke true. Perekaman konten default ke false.

Mengaktifkan propagasi konteks pelacakan

Penyebaran konteks pelacakan memungkinkan rentang sisi klien dikorelasikan dengan rentang sisi server dari Azure OpenAI dan layanan Azure lainnya. Saat diaktifkan, SDK secara otomatis menyuntikkan header W3C Trace Context (traceparent dan tracestate) ke dalam permintaan HTTP yang dibuat oleh klien OpenAI yang diperoleh melalui project.getOpenAIClient().

Ini memastikan bahwa semua operasi dalam pelacakan terdistribusi berbagi ID pelacakan yang sama, memberikan visibilitas end-to-end di seluruh aplikasi Anda dan layanan Azure di backend observabilitas Anda.

Penyebaran konteks pelacakan diaktifkan secara default. Untuk menonaktifkannya, teruskan traceContextPropagation: falsetracingOptions saat membuat klien, atau atur variabel AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION lingkungan ke false.

Pertimbangan keamanan dan privasi yang penting:

• ID pelacakan: Saat propagasi konteks pelacakan diaktifkan, ID pelacakan dikirim ke Azure OpenAI dan layanan eksternal lainnya.
• Korelasi permintaan: ID pelacakan memungkinkan layanan Azure untuk menghubungkan permintaan dari sesi atau pengguna yang sama di beberapa panggilan API, yang mungkin memiliki implikasi privasi tergantung pada kasus penggunaan Anda.

Hanya aktifkan propagasi konteks pelacakan setelah meninjau persyaratan observabilitas, privasi, dan keamanan Anda dengan cermat.

Pemecahan masalah

Pengecualian

Metode klien yang melakukan panggilan layanan meningkatkan RestError untuk respons kode status HTTP yang tidak berhasil dari layanan. code pengecualian akan menyimpan kode status respons HTTP. error.message pengecualian berisi pesan terperinci yang mungkin berguna dalam mendiagnosis masalah:

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

Misalnya, saat Anda memberikan kredensial yang salah:

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

masalah Pelaporan

Untuk melaporkan masalah dengan library klien, atau meminta fitur tambahan, buka masalah GitHub di sini

Langkah berikutnya

Lihatlah folder package samples, yang berisi kode yang dapat dijalankan sepenuhnya.

Meregenerasi dari TypeSpec (pengelola)

Paket ini dibuat ulang dari spesifikasi TypeSpec di Azure/azure-rest-api-specs. Alur kerja lengkap dikodekan sebagai enam keterampilan di bawah .github/skills/ dan dapat digerakkan secara menyeluruh oleh tugas agen pengkodean GitHub Copilot.

Untuk mengirim regen sebagai tugas agen cloud, jalankan dari direktori ini:

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

Di Windows, memanggil skrip secara langsung (misalnya ./scripts/start-cloud-regen.ps1) dapat diblokir oleh kebijakan eksekusi defaultRestricted. Formulir di pwsh -NoProfile -File ... atas menghindari itu. Atau, jalankan Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned sekali untuk mengizinkan skrip lokal.

Prerequisites:

• gh CLI diinstal dan diautentikasi (gh auth login) terhadap repositori target. Subperintah dalam agent-task pratinjau dan memerlukan .gh
• Keanggotaan dalam organisasi dengan agen pengkodean GitHub Copilot diaktifkan untuk repositori target.
• Dorong akses ke repositori target (agen cloud menggunakan identitas Aplikasi GitHub sendiri untuk mendorong dan membuka draf PR).

Peringatan: prompt yang dikirim berjalan pnpm install --filter @azure/ai-projects... dan pnpm --filter @azure/ai-projects... build sebaris di awal tugas. Jika sandbox agen cloud memblokir panggilan jaringan tersebut, tugas akan gagal saat penyiapan; dalam hal ini jalankan keterampilan secara lokal, atau berkoordinasi dengan tim build SDK untuk menambahkan alur kerja yang dikelola copilot-setup-steps.yml secara terpusat di root reposito.

Berkontribusi

Proyek ini menyambut kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Saat Anda mengirimkan permintaan pull, cla-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repositori menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft . Untuk informasi selengkapnya, lihat Tanya Jawab Umum Kode Etik atau hubungi opencode@microsoft.com dengan pertanyaan atau komentar tambahan.