Bagikan melalui

Pustaka klien Azure AI Projects untuk JavaScript - versi 2.0.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)
    • Bing Grounding
    • 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 penyimpanan memori (pratinjau) untuk percakapan Agen, menggunakan .beta.memoryStores 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.
  • Sebutkan Model AI yang disebarkan ke Proyek Pengecoran Anda menggunakan .deployments operasi.
  • 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 v1REST API bidang data Microsoft Foundry.

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

Daftar isi

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 Proyek Microsoft Foundry Anda. Di bawah ini kita akan mengasumsikan variabel AZURE_AI_PROJECT_ENDPOINT lingkungan didefinisikan untuk menahan nilai ini.

Otorisasi

  • ID Entra 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)" 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

Membuat dan mengautentikasi klien dengan ID Entra

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 AZURE_AI_PROJECT_ENDPOINT lingkungan didefinisikan untuk menyimpan nilai ini:

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

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

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

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

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 Azure AI Search 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 Proyek

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 Proyek

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

Pelacakan

Nota: Fungsionalitas pelacakan dalam pratinjau awal dan dapat berubah. Rentang, atribut, dan peristiwa dapat dimodifikasi di versi mendatang.

Anda dapat menambahkan sumber daya Application Insights Azure ke proyek Microsoft Foundry Anda. Lihat tab Pelacakan di proyek Microsoft Foundry Anda. Jika salah satu diaktifkan, Anda bisa mendapatkan connection string Application Insights, mengonfigurasi klien Proyek AI Anda, dan mengamati jalur eksekusi penuh melalui Azure Monitor. Biasanya, Anda mungkin ingin mulai melacak sebelum membuat klien atau Agen.

Penginstalan

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

Cara mengaktifkan pelacakan

Berikut adalah contoh kode yang menunjukkan cara mengaktifkan pelacakan Azure Monitor:

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

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

Lihat kode sampel lengkap dalam remoteTelemetry.ts.

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.

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.

  • Last updated on