Compartir a través de

Azure AI Projects biblioteca cliente para JavaScript - versión 2.0.0

La biblioteca cliente de AI Projects (en vista previa) forma parte del SDK de Microsoft Foundry y proporciona un acceso fácil a los recursos de tu Microsoft Foundry Project. Utilícelo para:

  • Cree y ejecute agentes mediante la .agents propiedad en el cliente.
  • Mejora a los agentes con herramientas especializadas:
    • Búsqueda de memoria de agentes (Vista previa)
    • Agente a agente (A2A) (Vista previa)
    • Azure AI Search
    • Búsqueda personalizada de Bing (Vista previa)
    • Fundamentos de Bing
    • Automatización del navegador (Vista previa)
    • Intérprete de código
    • Uso del ordenador (Vista previa)
    • Búsqueda de archivos
    • Herramienta de función
    • Generación de imágenes
    • Microsoft Fabric (Vista previa)
    • Protocolo de contexto de modelo (MCP)
    • OpenAPI
    • Microsoft SharePoint (Vista previa)
    • Búsqueda web (Vista previa)
  • Consigue un cliente OpenAI que utilice el .getOpenAIClient. método para ejecutar Respuestas, Conversaciones, Evaluaciones y operaciones de Ajuste Fino con tu Agente.
  • Gestionar almacenes de memoria (vista previa) para las conversaciones del Agente, utilizando las .beta.memoryStores operaciones.
  • Explora herramientas adicionales de evaluación (algunas en vista previa) para evaluar el rendimiento de tu aplicación de IA generativa, utilizando las .evaluationRulesoperaciones, .beta.evaluationTaxonomies, .beta.evaluators.beta.insightsy .beta.schedules operaciones.
  • Realiza escaneos del Red Team (vista previa) para identificar los riesgos asociados a tu aplicación de IA generativa, utilizando las .beta.redTeams operaciones.
  • Afinar Modelos de IA en tus datos.
  • Enumere los modelos de IA implementados en su proyecto de Foundry mediante las .deployments operaciones.
  • Enumera recursos de Azure conectados en tu proyecto Foundry usando las operaciones .connections.
  • Cargue documentos y cree conjuntos de datos para hacer referencia a ellos mediante las .datasets operaciones.
  • Cree y enumere índices de búsqueda mediante las .indexes operaciones.

La biblioteca cliente usa la versión v1 de las API de REST del plano de datos de Microsoft Foundry.

Documentación del productoSamplesPackage (npm)API documentación de referenciaSDK

Tabla de contenido

Empezar

Requisito previo

  • Versiones de LTS de Node.js
  • Una suscripción Azure.
  • Un proyecto en Microsoft Foundry.
  • La URL del endpoint del proyecto del formulario https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name. Se puede encontrar en tu página de resumen de Microsoft Foundry Project. A continuación asumiremos que la variable AZURE_AI_PROJECT_ENDPOINT de entorno fue definida para mantener este valor.

Autorización

  • Se necesita un ID de Entra para autenticar al cliente. La aplicación necesita un objeto que implemente la interfaz TokenCredential. Aquí se utilizan ejemplos de código DefaultAzureCredential. Para que funcione, necesitará lo siguiente:
    • Una asignación de rol adecuada. véase Control de acceso basado en roles en el portal Microsoft Foundry. El rol asignado puede realizarse a través de la pestaña "Access Control (IAM)" de tu recurso Azure AI Project en el portal de Azure.
    • Azure CLI instalado.
    • Estás conectado a tu cuenta de Azure ejecutando az login.
    • Ten en cuenta que si tienes varias suscripciones a Azure, la suscripción que contiene tu recurso de Azure AI Project debe ser tu suscripción predeterminada. Ejecute az account list --output table para enumerar toda la suscripción y ver cuál es el valor predeterminado. Ejecute az account set --subscription "Your Subscription ID or Name" para cambiar la suscripción predeterminada.

Instalar el paquete

npm install @azure/ai-projects dotenv

Conceptos clave

Crea y autentica al cliente con Entra ID

Entra ID es el único método de autenticación que soporta actualmente el cliente.

Para construir un AIProjectsClient, se projectEndpoint puede recuperar de projectEndpoint. A continuación, asumiremos que la variable AZURE_AI_PROJECT_ENDPOINT de entorno se definió para mantener este valor:

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

Grupos de operaciones de vista previa y banderas de funciones de opt-in

Algunas operaciones de vista previa requieren una bandera explícita foundryFeatures de opt-in. Por ejemplo:

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

Los grupos de operaciones de vista previa incluyen .beta.memoryStores, .beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, .beta.schedules, y .beta.redTeams.

Ejemplos

Realización de operaciones de respuestas mediante el cliente OpenAI

Tu proyecto Microsoft Foundry puede tener uno o más modelos de IA desplegados. Estos pueden ser modelos OpenAI, modelos de Microsoft o modelos de otros proveedores. Utilice el siguiente código para obtener un OpenAI autenticado del paquete openai y ejecute una llamada de finalización de chat.

Ejecute el código a continuación. Aquí suponemos que deploymentName (str) está definido. Es el nombre de implementación de un modelo de IA en su proyecto de Foundry. Como se muestra en la pestaña "Modelos + puntos finales", en la columna "Nombre".

Consulta la carpeta "responses" en el package samples para más ejemplos, incluyendo respuestas en 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));

Realización de operaciones de agente

La .agents propiedad de la propiedad le da acceso a todas las operaciones del AIProjectsClient agente. Los agentes utilizan una extensión del protocolo OpenAI Responses, por lo que es probable que necesite que un OpenAI cliente realice operaciones de agente, como se muestra en el siguiente ejemplo.

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

Uso de herramientas de Agent

Los agentes pueden mejorarse con herramientas especializadas para diversas capacidades. Las herramientas se organizan según sus necesidades de conexión:

Herramientas integradas

Estas herramientas funcionan de inmediato sin necesidad de conexiones externas.

Intérprete de código

Escribe y ejecuta código Javascript en un entorno sandbox, procesa archivos y trabaja con diversos formatos de datos. Documentación 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}`);

Consulta el código de muestra completo en agentCodeInterpreter.ts.

Búsqueda de archivos

Herramienta incorporada de RAG (generación deRetrieval-Augmented) para procesar y buscar documentos utilizando almacenes vectoriales para la recuperación de conocimiento. Documentación 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})`);

Consulta el código de muestra completo en agentFileSearchStream.ts.

Generación de imágenes

Genera imágenes basadas en indicaciones de texto con ajustes personalizables de resolución, calidad y estilo:

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

Después de llamar responses.create()a , puedes descargar el archivo usando la respuesta devuelta:

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

Búsqueda web (Vista previa)

Realiza búsquedas generales en la web para recuperar información actual de internet. Documentación 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}`);

Consulta el código de muestra completo en agentWebSearch.ts.

Uso del ordenador (Vista previa)

Permitir que los agentes interactúen directamente con sistemas informáticos para la automatización de tareas y operaciones del sistema:

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

Después de llamar responses.create()a , procesa la respuesta en un bucle de interacción. Maneja computer_call los elementos de salida y proporciona capturas de pantalla según computer_call_output el computer_screenshot tipo para continuar la interacción.

Consulta el código de muestra completo en agentComputerUse.ts.

Protocolo de contexto de modelo (MCP)

Integrar servidores MCP para ampliar las capacidades de los agentes con herramientas y recursos estandarizados. Documentación 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" } },
  },
);

Después de llamar responses.create(), comprueba los mcp_approval_request elementos en la salida de respuesta. Envía tu McpApprovalResponse aprobación para que el agente continúe con su trabajo.

Consulta el código de muestra completo en agentMcp.ts.

OpenAPI

Llama a APIs externas definidas por las especificaciones OpenAPI sin código adicional del lado del cliente. Documentación 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})`);

Consulta el código de muestra completo en agentOpenApi.ts.

Herramienta de función

Define funciones personalizadas que permitan a los agentes interactuar con APIs externas, bases de datos o lógica de aplicaciones. Documentación 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})`);

Después de llamar responses.create(), procesa function_call los elementos de la salida de respuesta, ejecuta la lógica de tu función con los argumentos proporcionados y envía de vuelta FunctionCallOutput con los resultados.

Consulta el código de muestra completo en agentFunctionTool.ts.

  • Herramienta de búsqueda de memoria (Vista previa)

La herramienta de almacenamiento de memoria añade memoria a un agente, permitiendo que el modelo de IA del agente busque información pasada relacionada con el prompt actual del usuario.

El embeddingModelDeployment es el nombre del modelo utilizado para crear incrustaciones vectoriales para almacenar y buscar memorias.

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

Consulta el código de muestra completo en agentMemorySearch.ts.

Connection-Based Herramientas

Estas herramientas requieren configurar conexiones en tu proyecto de AI Foundry y usar projectConnectionId.

Azure AI Search

Integra con los índices de Azure AI Search para potentes capacidades de recuperación de conocimiento y búsqueda semántica:

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

Consulta el código de muestra completo en agentAiSearch.ts.

Conexión a tierra Bing

Respuestas de agentes terrestres con resultados de búsqueda web en tiempo real de Bing para proporcionar información up-tofecha:

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

Consulta el código de muestra completo en agentBingGrounding.ts.

Búsqueda personalizada de Bing (Vista previa)

Utiliza instancias de búsqueda Bing configuradas a medida para resultados web específicos de dominio o filtrados:

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

Consulta el código de muestra completo en agentBingCustomSearch.ts.

Microsoft Fabric (Vista previa)

Conéctate y consulta 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})`);

Consulta el código de muestra completo en agentFabric.ts.

Microsoft SharePoint (Vista previa)

Accede y busca documentos, listas y sitios de SharePoint para la integración del conocimiento empresarial:

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

Consulta el código de muestra completo en agentSharepoint.ts.

Automatización del navegador (Vista previa)

Automatiza las interacciones del navegador para el web scraping, pruebas e interacción con aplicaciones 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})`);

Consulta el código de ejemplo completo en agentBrowserAutomation.ts.

MCP con Project Connection

Integración MCP utilizando conexiones específicas de proyecto para acceder a servidores MCP conectados:

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

Consulta el código de ejemplo completo en agentMcpConnectionAuth.ts.

Agente a agente (A2A) (Vista previa)

Permitir la colaboración multiagente donde los agentes puedan comunicarse y delegar tareas a otros agentes especializados:

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

Consulta el código de muestra completo en agentAgentToAgent.ts.

OpenAPI con Conexión al Proyecto

Llama a APIs externas definidas por las especificaciones de OpenAPI usando autenticación de conexión de proyecto:

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

Consulta el código de muestra completo en agentOpenApiConnectionAuth.ts.

Para ejemplos completos de todas las herramientas, consulta el directorio samples-dev.

Evaluation

La evaluación en la biblioteca de clientes de Azure AI Project proporciona métricas cuantitativas de calidad y seguridad asistidas por IA para evaluar el rendimiento y evaluar modelos LLM, aplicaciones GenAI y agentes. Las métricas se definen como evaluadores. Los evaluadores integrados o personalizados pueden proporcionar información exhaustiva sobre la evaluación.

El código siguiente muestra algunas operaciones de evaluación. La lista completa de muestras se puede encontrar en la carpeta "evaluaciones" en la sección paquetes c0

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

Consulta el código de muestra completo en agentEvaluation.ts.

Operaciones de despliegues

En el código siguiente se muestran algunas operaciones de implementaciones, que le permiten enumerar los modelos de IA implementados en los proyectos de Microsoft Foundry. Estos modelos se pueden ver en la pestaña "Modelos + puntos finales" en su proyecto de Microsoft Foundry. Las muestras completas pueden encontrarse en la carpeta "deployment" en el paquete 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)}`);
}

Operaciones de conexión

El código siguiente muestra algunas operaciones de Conexión, que te permiten enumerar los Recursos de Azure conectados a tus Proyectos Microsoft Foundry. Estas conexiones se pueden ver en el "Centro de gestión", en la pestaña "Recursos conectados" en su proyecto de Microsoft Foundry. Las muestras completas se pueden encontrar en la carpeta "connections" en la sección 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)}`);

Operaciones de conjuntos de datos

En el código siguiente se muestran algunas operaciones del conjunto de datos. Las muestras completas pueden encontrarse en la carpeta "datasets" en la sección 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.");

Operaciones de archivos

El siguiente código muestra algunas operaciones de archivos utilizando el cliente OpenAI, que le permiten cargar, recuperar, enumerar y eliminar archivos. Estas operaciones son útiles para trabajar con archivos que se pueden usar para ajustar y otras operaciones de modelos de IA. Las muestras completas se pueden encontrar en la carpeta "archivos" en la sección 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)}`,
);

Operaciones de índices

En el código siguiente se muestran algunas operaciones de índices. Las muestras completas se pueden encontrar en la carpeta "indexes" en la sección 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);

Operaciones de ajuste

El código siguiente muestra cómo crear trabajos de ajuste fino usando el cliente OpenAI. Estas operaciones soportan diversas técnicas de ajuste fino como el Fine-Tuning supervisado (SFT), el Fine-Tuning de refuerzo (RFT) y la Optimización Directa del Rendimiento (DPO). Las muestras completas se pueden encontrar en la carpeta "finetuning" en la sección 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));

Seguimiento

Nota: La funcionalidad de seguimiento se encuentra en versión preliminar preliminar y está sujeta a cambios. Los intervalos, atributos y eventos pueden modificarse en versiones futuras.

Puedes añadir un recurso de Application Insights Azure a tu proyecto de Microsoft Foundry. Consulte la pestaña Seguimiento en el proyecto de Microsoft Foundry. Si uno estuviera habilitado, puedes acceder a la connection string de Application Insights, configurar tu cliente de AI Projects y observar la ruta completa de ejecución a través de Azure Monitor. Normalmente, es posible que desee comenzar el seguimiento antes de crear un cliente o agente.

Instalación

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

Cómo habilitar el trazado

Aquí tienes un ejemplo de código que muestra cómo habilitar el trazado de 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);

Consulta el código de muestra completo en remoteTelemetry.ts.

Solución de problemas

Excepciones

Los métodos cliente que realizan llamadas de servicio generan un restError para una respuesta de código de estado HTTP no correcta del servicio. El code de la excepción contendrá el código de estado de respuesta HTTP. El error.message de la excepción contiene un mensaje detallado que puede resultar útil para diagnosticar el problema:

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

Por ejemplo, cuando se proporcionan credenciales incorrectas:

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

problemas de informes

Para informar de problemas con la biblioteca del cliente o solicitar funciones adicionales, por favor abra un GitHub aquí

Pasos siguientes

Echa un vistazo a la carpeta package samples, que contiene código completamente ejecutable.

de contribución

Este proyecto da la bienvenida a las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia de colaborador (CLA) declarando que tiene derecho a, y en realidad, concedanos los derechos para usar su contribución. Para obtener más información, visite https://cla.microsoft.com.

Al enviar una solicitud de incorporación de cambios, un bot CLA determinará automáticamente si necesita proporcionar un CLA y decorar la solicitud de incorporación de cambios de forma adecuada (por ejemplo, etiqueta, comentario). Solo tiene que seguir las instrucciones proporcionadas por el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestro CLA.

Este proyecto ha adoptado el código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes sobre el código de conducta o póngase en contacto con opencode@microsoft.com con preguntas o comentarios adicionales.

  • Last updated on