Azure AI 项目客户端库

AI Projects客户端库(在预览中)是微软Foundry SDK的一部分,提供方便访问 您的微软创建项目中的资源。 用来:

• 创建和运行代理 使用 .agents 客户端上的财产.

• 用专门工具加强代理人数字 :
  • 代理内存搜索( 预览)
  • 代理对代理(A2A)(审查)
  • Azure AI 搜索
  • Bing 自定义搜索( 审查)
  • 击倒地基
  • 浏览器自动化
  • 代码口译员
  • 计算机使用(审查)
  • 文件搜索
  • 函数工具
  • 图像生成
  • 微软 Fabric (审查)
  • 示范背景协议(MCP)
  • 打开API
  • 微软SharePoint( 预览)
  • 网页搜索( 预览)
  • 工具搜索

• 获取 OpenAI 客户端 使用 .getOpenAIClient. 与您的代理商进行反应、交谈、Evals和FineTuning操作的方法.

• 管理 beta 代理会话和文件( 审查) 使用 .beta.agents 操作.
• 管理技能(审查) 可重复使用的代理能力,使用 .beta.skills 操作.
• 管理工具箱 将工具组合成可重复使用的集合,使用 .toolboxes 操作.
• 管理内存存储( 审查) 代理对话,使用 .beta.memoryStores 操作.
• 管理常规( 预览) 使用 .beta.routines 操作.
• 管理模型版本( 审查) 创建、更新和管理自定义模型版本,使用 .beta.models 操作.
• 探索其他评价工具( 有些在预览中) 评估您的基因AI应用的性能,使用 .evaluationRules, (中文(简体) ), .beta.evaluationTaxonomies, (中文(简体) ), .beta.evaluators, (中文(简体) ), .beta.insights,以及 .beta.schedules 操作.
• 运行红色团队扫描( 审查) 识别与你的基因AI应用相关的风险 .beta.redTeams 操作.
• 曲调不错 AI模型在您的数据.

• 假设 AI 模型 使用 .deployments 操作.
• 假设连接的 Azure 资源 在您的创建项目中使用 .connections 操作.
• 上传文档并创建数据集 使用 .datasets 操作.
• 创建并列出搜索索引 使用 .indexes 操作.

客户端库使用版本 v1 微软创始人 数据平面 REST APIs。 。 。 .

产品文档 | 样本 | 软件包( npm) | API 参考文件 | SDK 源代码

目录

• 开始
  • 先决条件
  • 授权
  • 安装软件包
• 关键概念
  • 创建和认证客户端
  • 预览操作组和选入特性旗
• 实例
  • 使用 OpenAI 客户端执行响应操作
  • 代理业务
  • 语音代理业务(审查)
  • 使用代理工具
    • 内建工具
    • 基于连接的工具
  • 评价业务
  • 部署行动
  • 连接操作
  • 数据集操作
  • 文件操作
  • 索引操作
  • 微调操作
  • Beta 代理会话操作( 审查)
  • 技能操作(审查)
  • 工具箱操作( 预览)
• 追踪
  • 实验特性门
  • 开始追踪
  • 安装
  • 如何进行追踪
  • 启用内容记录
  • 扶持痕量背景传播
• 解决问题
  • 例外
  • 报告问题
• 今后的步骤
• 捐款

开始

先决条件

• 节点.js的LTS版本
• [Azure订阅][azure sub].
• A 类 微软创建中的项目。 。 。 .
• 一个 应用程序 Insights 资源连接到您的创建项目 用于代理追踪.
• 窗体的项目端点 URL https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name。可以在您的微软创建项目概览页面中找到。 下面我们假设环境变数 FOUNDRY_PROJECT_ENDPOINT 定义为持有此值.

授权

• 认证客户端需要一个 Entra ID 。 您的应用程序需要一个可以执行 证书 接口。 这里的代码样本使用 [default AzureCreditive][default azure credititive]. 要让这个工作, 你需要:
  • 适当的角色分配。 见 微软创始门户中基于角色的访问控制。指定的角色可以通过您的 Azure AI 工程资源在 Azure 门户网站中的“ Access Control (IAM) ” 标签来完成 .
  • 阿苏尔CLI 已安装.
  • 您通过运行登录到您的 Azure 账户 az login。 。 。 .
  • 请注意, 如果您有多个 Azure 订阅, 包含您的 Azure AI 项目资源的订阅必须是您的默认订阅 。 运行 az account list --output table 以列出您的所有订阅,并查看哪个是默认的。 运行 az account set --subscription "Your Subscription ID or Name" 更改默认订阅.

安装软件包

npm install @azure/ai-projects dotenv

关键概念

用 Entra ID 创建和认证客户端

Entra ID是当前唯一由客户端支持的认证方法.

要构建一个 AIProjectsClient,则 projectEndpoint 可以从[项目终点][ai project client endpoint]中获取。 下面我们假设环境变数 FOUNDRY_PROJECT_ENDPOINT 被定义为持有此值:

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

预览操作组和选入特性旗

一些预览操作需要明确 foundryFeatures 选入旗. 例如:

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

预览操作组包括 .beta.agents, (中文(简体) ), .beta.agentInsightMonitors, (中文(简体) ), .beta.voiceAgents, (中文(简体) ), .beta.skills, (中文(简体) ), .beta.memoryStores, (中文(简体) ), .beta.routines, (中文(简体) ), .beta.models, (中文(简体) ), .beta.evaluationTaxonomies, (中文(简体) ), .beta.evaluators, (中文(简体) ), .beta.insights, (中文(简体) ), .beta.schedules,以及 .beta.redTeams。 。 。 .

使用 .beta.agentInsightMonitors 列出分析您的特工的监视器:

for await (const monitor of project.beta.agentInsightMonitors.list()) {
  console.log(`${monitor.id}: ${monitor.agent_name}`);
}

实例

使用 OpenAI 客户端执行响应操作

您的微软创建项目可能已经部署一个或多个AI模型. 这些可以是OpenAI模型,微软模型,或来自其他供应商的模型. 使用下面的代码获取认证 开放AI 从 打开 软件包,并执行聊天补全调用.

运行下面的代码。 我们假设 deploymentName (str)是定义的。 这是你创始项目中一个AI模型的部署名称. 如"Models + end points"标签所显示,"名"栏下.

补充样品,包括流化反应,见[包样][标本]中的"反应"文件夹.

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

代理业务

这个 .agents 财产 AIProjectsClient 允许你接触所有特工行动 代理人使用 OpenAI 响应协议,所以您可能需要获得 OpenAI 客户端进行代理操作,如下例所示.

关于设置,见 快速启动: 设置 Microsoft 创建资源。 。 。 .

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

语音代理业务(审查)

语音代理使用统一 project.agents 管理表面和一个双向 WebSocket 被曝光的会话 project.beta.voiceAgents.realtime。以下示例生成语音代理,发送文本,以及 串流其响应 :

const voiceAgentName = `voice-agent-${Date.now()}`;
const voiceAgent = await project.beta.agents.createFromPrompt({
  kind: "voice",
  name: voiceAgentName,
});
try {
  const connection = await project.beta.voiceAgents.realtime.connect(voiceAgent.name);
  try {
    await connection.sendText("Hello. Please introduce yourself briefly.");
    for await (const event of connection) {
      // Voice agents speak their reply, so the text form of it streams as an audio transcript
      // rather than as `response.output_text.delta`.
      if (
        event.type === "response.output_text.delta" ||
        event.type === "response.output_audio_transcript.delta"
      ) {
        process.stdout.write(event.delta);
      } else if (event.type === "unknown") {
        // event.rawEvent preserves all wire fields; validate them before using them.
        console.log(`Unrecognized server event: ${event.eventType}`);
      } else if (event.type === "response.done") {
        await connection.close();
      }
    }
  } finally {
    await connection.dispose();
  }
} finally {
  await project.agents.delete(voiceAgent.name, {
    requestOptions: { headers: { "foundry-features": "VoiceAgents=V1Preview" } },
  });
}

连接量 VoiceAgentRealtimeEvent: 一个已知 VoiceAgentServerEvent 或一个 VoiceAgentUnknownEvent 与 type: "unknown"对于未知的事件, eventType 保留 原电线歧视者和 rawEvent 保留完整的JSON有效载荷,包括: 原文 type对该有效载荷没有进行已知活动的实地验证或正常化; 在使用生地之前先验证并避免记录敏感的有效载荷。 未知事件没有 断开会话, 因此随后的事件和发送会正常进行 。 已知 event.type 分支仍然缩小到现有的生成类型。 一个只接受的处理器 VoiceAgentServerEvent 可在排除后调用 event.type === "unknown"。 。 。 .

JSON畸形、失踪或无效的歧视者,以及已知的畸形事件仍未成功 重排为 VoiceAgentProtocolError服务 error 事件仍然为 要处理的呼叫器; 此倒计时不会改变哪些外部事件 sendEvent() 支持 .

使用 project.beta.voiceAgents.conversations 检查已配置的语音代理的对话 与 store: true。通过 store 打开 connect() 以取代持续代理的设置 单会话。 如果目标代理被禁用, WebSocket 握手失败 409 Conflict 财务报告和审定财务报表 error.code = agent_disabled。见生成物剂生命周期的包样,局部 函数工具,以及 PCM 音频流.

过 query 改为 connect() 将查询参数添加到该连接的 WebSocket 升级 URL. 下列参数名称为示例;使用您服务或网关支持的名称:

const connection = await project.beta.voiceAgents.realtime.connect("my-voice-agent", {
  agentSessionId: "session-123",
  store: false,
  query: {
    custom_key: "custom value",
    custom_flag: true,
  },
});
await connection.close();

值可以是字符串,有限度的数字,也可以是布林斯并自动被URL编码. 一个值 覆盖匹配端点查询参数; undefined 删除匹配参数。 SDK这个 当 connect() 用于后期连接. 不要在查询参数中设置秘密,因为URL可以在服务器或代理日志中出现.

SDK 管理的查询名称被保留, 对大小写不敏感 : api-version, (中文(简体) ), agent_session_id, (中文(简体) ), store, (中文(简体) ), transport, (中文(简体) ), x-agent-version-override, (中文(简体) ), x-ms-client-sdk, (中文(简体) ), authorization, (中文(简体) ), api-key, (中文(简体) ), foundry_features, (中文(简体) ), foundry-features, (中文(简体) ), client-request-id, (中文(简体) ), x-ms-client-request-id, (中文(简体) ), structured_input, (中文(简体) ), structured_inputs, (中文(简体) ), x-ms-voice-structured-inputs名称开始于 h-供应 拒绝这些名称或不支持的值 connect() 与 TypeError 在认证前. 使用现有的打字选项取而代之 。 特别是,使用 structuredInputs 用于代理提示 变量;自定义查询参数不会自动成为即时输入.

使用代理工具

可通过各种能力的专门工具加强代理人。 工具按其连接要求排列:

内建工具

这些工具立即发挥作用,不需要外部连接.

代码口译员

在沙盒环境中写和运行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}`);

见完整样本代码 代理代码解释器。 。 。 .

文件搜索

内建的RAG( Retrival-Augmented Generation)工具,利用向量存储处理并搜索文档以获取知识. 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})`);

见完整样本代码 fileSearch Stream.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})`);

打电话后 responses.create(),您可以使用返回的回复下载文件 :

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

见完整样本代码 代理服务器WebSearch.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})`);

打电话后 responses.create(),在交互循环中处理响应。 处理 computer_call 输出项目,并提供截图为 computer_call_output 与 computer_screenshot 键以继续交互.

见完整样本代码 计算机用户.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" } },
  },
);

打电话后 responses.create()检查 mcp_approval_request 选项。 发回去 McpApprovalResponse 您同意允许代理继续工作的决定.

见完整样本代码 代理服务器Mcp.ts。 。 。 .

打开API

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

见完整样本代码 代理服务器 OpenApi.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})`);

打电话后 responses.create(),进程 function_call 从响应输出中执行函数逻辑,并返回 FunctionCallOutput 与结果.

见完整样本代码 代理函数工具( T)。 。 。 .

• 内存搜索工具( 预览)

内存存储工具将内存添加到代理中,允许代理的AI模型搜索与当前用户提示相关的过去信息.

这个 embeddingModelDeployment 是用于创建用于存储和搜索记忆的向量嵌入的模型的名称.

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

见完整样本代码 memorySearch.ts 代理服务器。 。 。 .

基于连接的工具

这些工具需要配置您的 AI 创建项目中的连接并使用 projectConnectionId。 。 。 .

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

见完整样本代码 aiSearch.ts 代理服务器。 。 。 .

击倒地基

地面代理回应实时网络搜索结果由Bing提供最新信息:

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

见完整样本代码 代理商BingGrounding.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})`);

见完整样本代码 代理商BingCustomSearch.ts。 。 。 .

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

见完整样本代码 fabric.ts 代理服务器。 。 。 .

微软SharePoint( 预览)

企业知识集成的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})`);

见完整样本代码 代理。 。 。 .

浏览器自动化

用于网页刮取、测试和与网页应用程序交互的自动浏览器交互:

const browserAutomationProjectConnectionId =
  process.env["BROWSER_AUTOMATION_PROJECT_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",
      browser_automation: {
        connection: {
          project_connection_id: browserAutomationProjectConnectionId,
        },
      },
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

见完整样本代码 代理浏览器自动化。 。 。 .

设定 FOUNDRY_PROJECT_ENDPOINT, (中文(简体) ), FOUNDRY_MODEL_NAME,以及 BROWSER_AUTOMATION_PROJECT_CONNECTION_ID (用于 您的 Azure Playwright 资源) 在运行样本前 。 它使用GA系统 browser_automation 访问工具 https://example.com 并报告页面标题 和基于浏览器结果的可见描述. 可选设置 FOUNDRY_AGENT_NAME 以选择代理名称;默认为 MyAgent。 。 。 .

流出样本打印每个已完成的文本信息一次,包括 浏览器 live-view URL,并登录远程函数动作名,调用ID,以及 无参数 browserSessionId。将现场视图 URL 视为敏感: 不 共享或承诺用于源控。 失败或不完整的回复退出 非零地位,而不是报告成功。 样本删除代理版本 它创建在一个 finally 块,无论是响应处理成功还是失败.

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

见完整样本代码 代理服务器McpConnectionAuth.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})`);

见完整样本代码 代理代理代理。 。 。 .

带有工程连接的 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})`);

见完整样本代码 代理服务器 OpenApiConnection Auth.ts。 。 。 .

关于所有工具的完整工作实例,见 样本- dev 目录。 。 。 .

评价

Azure AI项目客户端库的评价提供定量、AI协助的质量和安全衡量标准,用于评估业绩和评价LLM模型、GenAI应用和代理。 计量被定义为评价者. 内设评价员或定制评价员可提供全面的评价见解.

以下代码显示一些评价业务. 完整的样本清单可以在[包样 [样本]中的"评价"文件夹下找到

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

见完整样本代码 评价.ts。 。 。 .

部署行动

下面的代码显示了一些部署操作,这使得您可以列举部署在您微软创始项目上的AI模型. 这些模型可以在你的微软创始项目"Models + end points"标签中看到. 完整的样本可以在[包装样本][样本]中的"部署"文件夹下找到.

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

连接操作

下面的代码显示了一些连接操作,这些操作允许您列举与您微软创建项目相连的Azure资源. 这些连接可见于您微软创建项目中的"管理中心","连接资源"标签. 完整的样本可以在[包装样本][样本]中的"连接"文件夹下找到.

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

数据集操作

以下代码显示一些Dataset操作. 完整的样本可以在"数据集"下找到 文件夹在 [包样 [样本] 中.

本地文件系统上传( N)project.datasets.uploadFile, (中文(简体) ), project.datasets.uploadFolder,以及 project.beta.models.create)只在Node.js中支持. 浏览器应用程序 能够导入 AIProjectClient 财务报告和审定财务报表 VoiceAgentRealtimeClient 从 @azure/ai-projects 并使用 数据集和模型 REST 操作没有节点.js 文件系统多填充.

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模型操作的文件很有用. 完整的样本可以在[包装样本][样本]中的"文件"文件夹下找到.

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

索引操作

以下代码显示一些索引操作. 完整的样本可以在"索引"下找到 文件夹在 [包样 [样本] 中.

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客户端创建微调工作. 这些行动支持各种微调技术,如监督精通(SFT)、强化精通(RFT)和直接性能优化(DPO)。 完整的样本可以在[包装样本][样本]中的"fineturn"文件夹下找到.

import { JobCreateParams } from "openai/resources/fine-tuning/jobs";

const trainingFilePath = "training_data_path.jsonl";
const validationFilePath = "validation_data_path.jsonl";
const openAIClient = project.getOpenAIClient();
// 1) Create the training and validation files
const trainingFile = await openAIClient.files.create({
  file: fs.createReadStream(trainingFilePath),
  purpose: "fine-tune",
});
console.log(`Uploaded file with ID: ${trainingFile.id}`);
const validationFile = await openAIClient.files.create({
  file: fs.createReadStream(validationFilePath),
  purpose: "fine-tune",
});
console.log(`Uploaded file with ID: ${validationFile.id}`);
// 2) Wait for the files to be processed
await openAIClient.files.waitForProcessing(trainingFile.id);
await openAIClient.files.waitForProcessing(validationFile.id);
console.log("Files processed.");
// 3) Create a supervised fine-tuning job
const fineTuningJob = await openAIClient.fineTuning.jobs.create({} as JobCreateParams, {
  body: {
    trainingType: "Standard",
    training_file: trainingFile.id,
    validation_file: validationFile.id,
    model: deploymentName,
    method: {
      type: "supervised",
      supervised: {
        hyperparameters: {
          n_epochs: 3,
          batch_size: 1,
          learning_rate_multiplier: 1.0,
        },
      },
    },
  },
});
console.log("Created fine-tuning job:\n", JSON.stringify(fineTuningJob));

Beta 代理会话操作( 审查)

这个 .beta.agents 操作允许您为主机代理管理代理会话和会话文件。 会话为剂相互作用提供了孤立的沙盒环境.

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

见完整样本代码 β 剂.ts。 。 。 .

技能操作(审查)

这个 .beta.skills 操作允许您创建和管理定义代理能力的可重复使用的技能.

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

见完整样本代码 基本技术。 。 。 .

工具箱操作( 预览)

这个 .toolboxes 操作允许您创建和管理工具箱——可以重复使用的工具库,这些工具可以跨代理共享.

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

见完整样本代码 工具箱Crud.ts。 。 。 .

追踪

实验特性门

重要内容: GenAI追踪仪表是一种实验性的预览功能. Spans,属性,事件可能在未来的版本中被修改. 要使用它,必须经过明确选择 tracingOptions 与 experimental: true 当建造 AIProjectClient,或者设置环境变量:

AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true

只有在审查您的要求和理解追踪行为在未来版本中可能发生改变后,才能启用此功能.

开始追踪

您可以将应用程序 Insights Azure 资源添加到您的微软创建项目中. 如果启用了, 您可以获取应用程序 Insights 连接字符串, 配置您的 AI 工程客户端, 在 Azure 监视器中观测到痕迹 。 通常,你可能想要在创建客户端或代理之前开始追踪.

安装

要向 Azure 监视器发送痕迹 :

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

将痕迹打印到控制台( 用于本地发展 ):

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

如何进行追踪

追踪是通过路过实现的 tracingOptions 页:1 AIProjectClient 建筑师。 若为 tracingOptions 没有提供GenAI跟踪,GenAI跟踪被完全禁用,也没有发射GenAI的跨度或度量. 此设置只控制 GenAI 特定追踪( 模式调用、 代理操作、 信使使用等的语义规范) 。 追踪配置适用于通过该特定客户实例进行的所有操作,包括代理操作和通过OpenAI获取的任何客户端 project.getOpenAIClient()。不同的客户端可以有独立的追踪配置.

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

通过 tracingOptions: {} (空的物体)也能够进行追踪——在这种情况下,所有单个设置都通过相应的环境变量解决.

这个 tracingOptions 对象接受以下属性:

使用下列优先顺序解决每个选项:

1. 明确价值 内 tracingOptions (最高优先级)
2. 环境变量 (当选项被省略/未定义时选中)
3. 默认值 (既未设定又无法读取环境变量时使用)

说明: 因为目前所有追踪特征都是实验性的, experimental: true 还必须确定(明确或通过环境变量)排放的任何跨度.

语音代理追踪

在配置了以下显示的 OpenTelemetry 提供者/导出器后, 现有的 tracingOptions: { experimental: true } 设定还跟踪语音代理生成, 电话突变,对话删除,以及实时连接/响应. 不需要单独的特征旗. 不呼叫语音代理 API 的用户 没有额外的语音代理 跨度.

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

const project = new AIProjectClient("<project endpoint>", new DefaultAzureCredential(), {
  tracingOptions: {
    experimental: true,
    contentRecording: false,
  },
});
const connection = await project.beta.voiceAgents.realtime.connect("<voice agent name>");
try {
  await connection.sendText("Hello.");
  for await (const event of connection) {
    if (event.type === "response.done") break;
  }
} finally {
  await connection.close();
}

实时创建会话跨度、短连接子和 invoke_agent 每个观测到的孩子 response.created编号 :response.done 双人 它记录状态, 服务ID、符号使用、汇总音频字节和接收到的第一自动休息时间 (从) response.created,而不是用户的语音或播放). 它不会产生跨度 每个音频块。 服务标识只显示在痕迹上,而非度量. 资源 project.beta.voiceAgents.realtime 使用相同的现有项目级别 tracingOptions;不需要额外选项或实时覆盖. 独立建造 VoiceAgentRealtimeClient 保留其现有的 API 并且没有获得项目的追踪配置.

届会的输入信息摘要代表最近观察到的输入,而不是 整个对话的历史。 新的音频用音频替换更古老的记录 正在等待其项目ID时的元数据。 完成的笔录取代 仅当其项目ID与当前输入相关时的元数据.

信件摘要默认省略了内容 。 明确 contentRecording: true 允许 限定文本/语句和工具参数/结果;可能暴露敏感的用户 资料。 原始介质、证书、查询值、电话号码、SDP和原始 错误/ 关闭信件从未被此仪器故意记录 . 读取/列表呼叫继续使用现有的HTTP管道跟踪.

见 实时跟踪样本 财务报告和审定财务报表 REST 追踪样本。 。 。 .

Azure 监视器跟踪

以下是显示如何启用 Azure 监视器追踪的代码样本 :

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

您还可能想要为您的情景设定一个跨度 :

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,