Azure AI Projects クライアントライブラリ for JavaScript - バージョン 2.0.0

AI Projectsクライアントライブラリ(プレビュー中)はMicrosoft Foundry SDKの一部であり、Microsoft Foundry Project内のリソースに簡単にアクセスできるよう支援します。これは次の目的で使用されます。

クライアントで Agent のプロパティを使用して。

専門ツールでエージェントを強化する:
- エージェントメモリーサーチ(プレビュー)
- エージェント間通信(A2A)(プレビュー)
- Azure AI 検索
- Bingカスタム検索(プレビュー)
- Bingグラウンドング
- ブラウザ自動化(プレビュー)
- コードインタープリター
- コンピュータ使用(プレビュー)
- ファイル検索
- ファンクションツール
- 画像生成
- Microsoft Fabric(プレビュー版)
- モデルコンテキストプロトコル (MCP)
- OpenAPI
- Microsoft SharePoint (プレビュー)
- ウェブ検索(プレビュー)

メソッドを使ってし、エージェントとレスポンス、会話、評価、ファインチューニングの操作を実行しましょう。

操作を使ってエージェントの会話のメモリストア(プレビュー)を管理します。
追加の評価ツール(プレビュー中の一部)を探索し、、、、、操作を活用して生成AIアプリケーションのパフォーマンスを評価しましょう。
操作を使って、生成AIアプリケーションに関連するリスクを特定するためにレッドチームスキャン(プレビュー)を実行しましょう。
微調整あなたのデータにAIモデルを配置します。

操作を使用して、Foundry プロジェクトにデプロイされたします。
列挙をFoundryプロジェクト内で.connections操作を使って、Azureリソース接続してください。
ドキュメントをアップロードし、操作を使用して参照するデータセットを作成します。
操作を使用してします。

クライアントライブラリは、バージョンの Microsoft Foundry データプレーン REST API を使用します。

Product documentation | Samples | Package (npm) | API reference documentation | SDK ソースコード

作業の開始
- 前提条件
- 認可
- パッケージをインストールする
主な概念
- クライアントを作成して認証する
- プレビュー運用グループとオプトイン機能フラグ
例
- OpenAIクライアントを使用したレスポンス操作の実行
- エージェント操作の実行
- エージェントツールの利用
  - 組み込みツール
  - Connection-Based ツール
- 評価作業
- デプロイ操作
- 接続操作
- データセットの操作
- ファイル操作
- インデックス操作
- ファインチューニング操作
追跡
- Installation
- トレースを有効にする方法
トラブルシューティング
- 例外
- レポートに関する問題の
次のステップ
貢献

作業の開始

前提条件

Node.js の LTS バージョン
Azureのサブスクリプション。
Microsoft Foundry のプロジェクト。
フォームのプロジェクトエンドポイントURLです。 Microsoft Foundry Projectの概要ページでご覧いただけます。以下では、環境変数がこの値を保持するように定義されていると仮定します。

認証

クライアントを認証するにはEntra IDが必要です。アプリケーションには、TokenCredential インターフェイスを実装するオブジェクトが必要です。ここでのコードサンプルはDefaultAzureCredentialを使用しています。この作業を行うには、次のものが必要です。
- 適切な役割割り当て。 Microsoft Foundryポータルのロールベースアクセス制御を参照してください。役割の割り当ては、Azureポータル内のAzure AI Projectリソースの「Access Control (IAM)」タブから行えます。
- Azure CLIがインストールされました。
- Azureアカウントにaz loginを実行してログインします。
- 複数のAzureサブスクリプションがある場合、Azure AI Projectリソースを含むサブスクリプションがデフォルトのサブスクリプションである必要があります。実行して、すべてのサブスクリプションを一覧表示し、既定のサブスクリプションを確認します。を実行して、既定のサブスクリプションを変更します。

パッケージをインストールする

npm install @azure/ai-projects dotenv

重要な概念

Entra IDでクライアントを作成・認証する

Entra IDは現在クライアントがサポートしている唯一の認証方法です。

を構築するには、からを取得できます。以下では、環境変数がこの値を保持するように定義されていると仮定します。

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

プレビュー運用グループとオプトイン機能フラグ

一部のプレビュー操作では、明示的なオプトインフラグが必要です。例えば次が挙げられます。

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

プレビュー運用グループには、、、、、、が含まれます。

例示

OpenAIクライアントを使用したレスポンス操作の実行

Microsoft Foundryプロジェクトには1つ以上のAIモデルが展開されている場合があります。これらはOpenAIモデル、Microsoftモデル、または他のプロバイダーのモデルかもしれません。以下のコードを使用して、openai パッケージから認証された OpenAI を取得し、チャット完了呼び出しを実行します。

以下のコードを実行します。ここでは、 (str) が定義されていると仮定します。これは、Foundry プロジェクトの AI モデルのデプロイ名です。 [モデル + エンドポイント] タブの [名前] 列に示されているように。

ストリーミング回答を含む追加のサンプルについては、package samplesの「responses」フォルダをご覧ください。

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

エージェント操作の実行

のプロパティを使用すると、すべてのエージェント操作にアクセスできます。エージェントは OpenAI Responses プロトコルの拡張機能を使用するため、以下の例に示すように、エージェント操作を実行するにはクライアントを取得する必要がある可能性があります。

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

エージェントツールの利用

エージェントは様々な機能に対応する専門ツールで強化可能です。ツールは接続要件ごとに整理されています:

組み込みツール

これらのツールは外部接続を必要とせず、即座に動作します。

コードインタープリター

サンドボックス環境でJavaScriptコードを書き、実行し、ファイルを処理し、多様なデータフォーマットに取り組むことができます。 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}`);

完全なサンプルコードはagentCodeInterpreter.tsでご覧ください。

ファイル検索

ベクターストアを用いて文書を処理・検索する組み込みのRAG(Retrieval-Augmented 生成)ツール。 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})`);

完全なサンプルコードはagentFileSearchStream.tsをご覧ください。

画像生成

テキストプロンプトに基づいて画像を生成し、解像度、画質、スタイルをカスタマイズ可能です:

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

に電話した後、返答したファイルをダウンロードできます:

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

ウェブ検索(プレビュー)

インターネットから最新の情報を取得するために一般的なウェブ検索を行いましょう。 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}`);

完全なサンプルコードはagentWebSearch.tsをご覧ください。

コンピュータ使用(プレビュー)

エージェントがタスク自動化やシステム操作のためにコンピュータシステムと直接やり取りできるようにすること:

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

を呼び出した後、応答をインタラクションループで処理します。出力項目処理し、タイプスクリーンショットを提供してやり取りを続けましょう。

完全なサンプルコードはagentComputerUse.tsをご覧ください。

モデルコンテキストプロトコル (MCP)

MCPサーバーを統合し、標準化されたツールやリソースでエージェントの機能を拡張します。 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" } },
  },
);

を呼び出した後、レスポンス出力に項目ががないか確認してください。承認の決定を伝えて、エージェントの作業継続を許可するを返送してください。

完全なサンプルコードはagentMcp.tsをご覧ください。

OpenAPI

追加のクライアントサイドコードなしでOpenAPI仕様で定義された外部APIを呼び出します。 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})`);

完全なサンプルコードはagentOpenApi.tsでご覧ください。

ファンクションツール

エージェントが外部API、データベース、アプリケーションロジックとやり取りできるカスタム関数を定義します。 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})`);

を呼び出した後、レスポンス出力から項目を処理し、提供された引数で関数ロジックを実行し、結果を返します。

完全なサンプルコードはagentFunctionTool.tsをご覧ください。

メモリ検索ツール(プレビュー)

メモリストアツールはエージェントにメモリを追加し、エージェントのAIモデルが現在のユーザープロンプトに関連する過去情報を検索できるようにします。

は記憶の保存や探索のためにベクトル埋め込みを作成するために使われるモデルの名前です。

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

完全なサンプルコードはagentMemorySearch.tsをご覧ください。

Connection-Based ツール

これらのツールは、AI Foundryプロジェクト内で接続を設定し、そのを活用する必要があります。

Azure AI 検索

Azure AI 検索インデックスと連携して、強力な知識検索およびセマンティック検索機能を実現しましょう:

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

完全なサンプルコードはagentAiSearch.tsをご覧ください。

Bingグラウンディング

Bingからのリアルタイムウェブ検索結果による地上エージェントの応答による、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})`);

完全なサンプルコードはagentBingGrounding.tsをご覧ください。

Bingカスタム検索(プレビュー)

ドメイン固有の検索結果やフィルター付きのウェブ検索結果には、カスタム設定のBing検索インスタンスを使用してください:

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

完全なサンプルコードはagentBingCustomSearch.tsをご覧ください。

Microsoft Fabric (プレビュー)

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

完全なサンプルコードはagentFabric.tsをご覧ください。

Microsoft SharePoint (Preview)

エンタープライズナレッジ統合のためにSharePointのドキュメント、リスト、サイトにアクセスし検索する:

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

完全なサンプルコードはagentSharepoint.tsをご覧ください。

ブラウザ自動化(プレビュー)

ウェブスクレイピング、テスト、ウェブアプリケーションとのやり取りのためのブラウザ操作の自動化:

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

完全なサンプルコードはagentBrowserAutomation.tsをご覧ください。

MCPとプロジェクト・コネクション

プロジェクト固有の接続を使ったMCP統合で、接続されたMCPサーバーへのアクセス:

const mcpProjectConnectionId = process.env["MCP_PROJECT_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("agent-mcp-connection-auth", {
  kind: "prompt",
  model: deploymentName,
  instructions: "Use MCP tools as needed",
  tools: [
    {
      type: "mcp",
      server_label: "api-specs",
      server_url: "https://api.githubcopilot.com/mcp",
      require_approval: "always",
      project_connection_id: mcpProjectConnectionId,
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

完全なサンプルコードはagentMcpConnectionAuth.tsでご覧ください。

エージェント間通信(A2A)(プレビュー)

エージェント同士がコミュニケーションを取り、タスクを他の専門エージェントに委任できるマルチエージェント協働を可能にする:

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

完全なサンプルコードはagentAgentToAgent.tsをご覧ください。

プロジェクト接続付きOpenAPI

プロジェクト接続認証を用いてOpenAPI仕様で定義された外部APIを呼び出します:

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

完全なサンプルコードはagentOpenApiConnectionAuth.tsでご覧ください。

すべてのツールの完全な動作例については、samples-devディレクトリをご覧ください。

Evaluation

Azure AIプロジェクトの評価クライアントライブラリは、定量的かつAI支援による品質・安全性指標を提供し、パフォーマンス評価やLLMモデル、生成AIアプリケーション、エージェントの評価を行います。指標は評価者として定義されます。組み込みまたはカスタム評価ツールは包括的な評価洞察を提供します。

以下のコードは評価操作のいくつかを示しています。サンプルの全リストは、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})`);

完全なサンプルコードはagentEvaluation.tsをご覧ください。

デプロイ操作

次のコードは、Microsoft Foundry プロジェクトにデプロイされた AI モデルを列挙できるいくつかのデプロイ操作を示しています。これらのモデルは、Microsoft Foundry プロジェクトの [モデル + エンドポイント] タブで確認できます。完全なサンプルはpackage samplesの「deployment」フォルダ内で見つけることができます。

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

接続操作

以下のコードは、Microsoft Foundry Projectsに接続されたAzureリソースを列挙できるConnection操作を示しています。これらの接続は、Microsoft Foundry Projectの「Management Center」の「接続されたリソース」タブで確認できます。完全なサンプルはpackage samplesの「connections」フォルダで見つけることができます。

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

データセットの操作

次のコードは、一部のデータセット操作を示しています。完全なサンプルはpackage samplesの「datasets」フォルダで見つけることができます。

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

ファイル操作

以下のコードは、OpenAI クライアントを使用したいくつかのファイル操作を示しており、ファイルのアップロード、取得、一覧表示、削除が可能です。これらの操作は、微調整やその他の AI モデル操作に使用できるファイルを操作する場合に役立ちます。フルサンプルはpackage samplesの「files」フォルダ内で見つけることができます。

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

インデックス操作

次のコードは、一部の Indexes 操作を示しています。完全なサンプルはpackage samplesの「indexes」フォルダ内で見つけることができます。

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

微調整操作

以下のコードはOpenAIクライアントを使ってファインチューニングジョブを作成する方法を示しています。これらの運用は、監督付き Fine-Tuning(SFT)、強化 Fine-Tuning(RFT)、直接パフォーマンス最適化(DPO)などの様々なファインチューニング技術をサポートしています。フルサンプルはpackage samplesの「finetuning」フォルダで見つけることができます。

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

追跡

手記：トレース機能は予備プレビュー段階であり、変更される可能性があります。スパン、属性、およびイベントは、将来のバージョンで変更される可能性があります。

Microsoft FoundryプロジェクトにApplication Insights Azureリソースを追加できます。 Microsoft Foundry プロジェクトの [トレース] タブを参照してください。もし有効にしていれば、Application Insightsの接続文字列を取得し、AI Projectsクライアントを設定し、Azure Monitorを通じて実行経路全体を観察できます。通常、クライアントまたはエージェントを作成する前にトレースを開始することをお勧めします。

インストール作業

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

トレースを有効にする方法

こちらは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);

完全なサンプルコードはremoteTelemetry.tsをご覧ください。

トラブルシューティング

例外

サービス呼び出しを行うクライアントメソッドは、サービスからの成功しない HTTP 状態コード応答に対して、RestError を発生させます。例外のは、HTTP 応答状態コードを保持します。例外のには、問題の診断に役立つ詳細なメッセージが含まれています。

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

たとえば、間違った資格情報を指定した場合は、次のようになります。

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

問題の報告

クライアントライブラリの問題を報告したり、追加機能をリクエストする場合は、GitHub号hereを開いてください。

次のステップ

完全に実行可能なコードが入っているpackage samplesフォルダを見てみてください。

投稿

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの投稿では、お客様が投稿を使用する権利を当社に付与する権利を有し、実際に行うことを宣言する共同作成者ライセンス契約 (CLA) に同意する必要があります。詳細については、を参照してください。

プル要求を送信すると、CLA ボットは、CLA を提供し、PR を適切に装飾する必要があるかどうかを自動的に判断します (ラベル、コメントなど)。ボットによって提供される手順にそのまま従ってください。これは、CLA を使用するすべてのリポジトリで 1 回だけ行う必要があります。

このプロジェクトは、「Microsoft のオープンソースの倫理規定」を採用しています。詳細については、行動規範に関する FAQ を参照するか、その他の質問やコメントをにお問い合わせください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-09