Compartilhar via

Azure AI Projects client library for JavaScript - versão 2.0.1

A biblioteca cliente AI Projects (em prévia) faz parte do Microsoft Foundry SDK e oferece fácil acesso aos recursos do seu Microsoft Foundry Project. Use-o para:

  • Crie e execute Agentes usando a .agents propriedade no cliente.
  • Aprimore Agentes com ferramentas especializadas:
    • Busca de Memória do Agente (Prévia)
    • Agente-para-Agente (A2A) (Prévia)
    • Pesquisa de IA do Azure 
    • Busca Personalizada do Bing (Prévia)
    • Fundamentação do Bing
    • Automação do Navegador (Prévia)
    • Interpretador de códigos
    • Uso do Computador (Prévia)
    • Pesquisa de Arquivo
    • Ferramenta de Função
    • Geração de imagem
    • Microsoft Fabric (Prévia)
    • Protocolo de Contexto de Modelo (MCP)
    • OpenAPI
    • Microsoft SharePoint (Prévia)
    • Busca na Web (Prévia)
  • Crie um cliente OpenAI usando o .getOpenAIClient. método para executar Respostas, Conversas, Avaliações e operações de FineTuning com seu Agente.
  • Gerencie os armazenamentos de memória (pré-visualização) para conversas do Agente, usando as .beta.memoryStores operações.
  • Explore ferramentas adicionais de avaliação (algumas em prévia) para avaliar o desempenho do seu aplicativo de IA generativa, usando , .evaluationRules.beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, e .beta.schedules operações.
  • Execute varreduras da Red Team (prévia) para identificar riscos associados à sua aplicação de IA generativa, usando as .beta.redTeams operações.
  • Afinar Modelos de IA nos seus dados.
  • Enumere os modelos de IA implantados em seu projeto de fundição usando as .deployments operações.
  • Enumere recursos Azure conectados no seu projeto Foundry usando as operações .connections.
  • Carregue documentos e crie conjuntos de dados para referenciá-los usando as .datasets operações.
  • Crie e enumere índices de pesquisa usando as .indexes operações.

A biblioteca de clientes usa a versão v1 das APIs REST do plano de dados do Microsoft Foundry.

Documentação do produtoSamplesPackage (npm)API documentação de referênciaSDK

Sumário

Introdução

Pré-requisito

  • Versões LTS do Node.js
  • Uma assinatura Azure.
  • Um projeto no Microsoft Foundry.
  • A URL do endpoint do projeto do formulário https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name. Ele pode ser encontrado na sua página de visão geral do Microsoft Foundry Project. Abaixo, assumiremos que a variável AZURE_AI_PROJECT_ENDPOINT ambiente foi definida para manter esse valor.

Autorização

  • Um ID Entra é necessário para autenticar o cliente. Seu aplicativo precisa de um objeto que implemente a interface TokenCredential. Exemplos de código aqui usam DefaultAzureCredential. Para que isso funcione, você precisará de:
    • Uma atribuição apropriada para o papel. veja Controle de acesso baseado em funções no portal Microsoft Foundry. A função atribuída pode ser feita via aba "Access Control (IAM)" do seu recurso Azure AI Project no portal Azure.
    • Azure CLI instalado.
    • Você está logado na sua conta Azure ao executar az login.
    • Note que, se você tem várias assinaturas do Azure, a assinatura que contém seu recurso do Azure AI Project deve ser sua assinatura padrão. Execute az account list --output table para listar toda a sua assinatura e ver qual é o padrão. Execute az account set --subscription "Your Subscription ID or Name" para alterar sua assinatura padrão.

Instalar o pacote

npm install @azure/ai-projects dotenv

Principais conceitos

Crie e autentique o cliente com o Entra ID

O Entra ID é o único método de autenticação suportado pelo cliente no momento.

Para construir um AIProjectsClient, o projectEndpoint pode ser buscado em projectEndpoint. Abaixo, vamos supor que a variável AZURE_AI_PROJECT_ENDPOINT de ambiente foi definida para manter esse 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 operações de pré-visualização e flags de recursos de opt-in

Algumas operações de pré-visualização exigem uma flag explícita foundryFeatures de opt-in. Por exemplo:

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

Grupos de operações de visualização incluem .beta.memoryStores, .beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, .beta.schedules, e .beta.redTeams.

Exemplos

Executando operações de respostas usando o cliente OpenAI

Seu projeto Microsoft Foundry pode ter um ou mais modelos de IA implantados. Esses podem ser modelos OpenAI, modelos da Microsoft ou modelos de outros provedores. Use o código abaixo para obter um OpenAI autenticado do pacote openai e execute uma chamada de conclusão de bate-papo.

Execute o código abaixo. Aqui assumimos que deploymentName (str) está definido. É o nome de implantação de um modelo de IA em seu projeto do Foundry. Conforme mostrado na guia "Modelos + endpoints", na coluna "Nome".

Veja a pasta "responses" na package samples para exemplos adicionais, incluindo respostas em 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));

Executando operações do Agente

A .agents propriedade no AIProjectsClient fornece acesso a todas as operações do Agente. Os agentes usam uma extensão do protocolo OpenAI Responses, portanto, você provavelmente precisará fazer com que um OpenAI cliente faça as operações do agente, conforme mostrado no exemplo abaixo.

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

Usando ferramentas de Agente

Agentes podem ser aprimorados com ferramentas especializadas para diversas capacidades. As ferramentas são organizadas de acordo com seus requisitos de conexão:

Ferramentas Embutidas

Essas ferramentas funcionam imediatamente, sem necessidade de conexões externas.

Interpretador de códigos

Escreva e execute código Javascript em um ambiente sandbox, processe arquivos e trabalhe com diversos formatos de dados. Documentação da 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}`);

Veja o código de exemplo completo em agentCodeInterpreter.ts.

Pesquisa de Arquivos

Ferramenta RAG (geraçãoRetrieval-Augmented) embutida para processar e pesquisar documentos usando armazenamento vetorial para recuperação de conhecimento. Documentação da 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})`);

Veja o código de exemplo completo em agentFileSearchStream.ts.

Geração de Imagem

Gerar imagens baseadas em prompts de texto com configurações personalizáveis de resolução, qualidade e 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})`);

Após ligar responses.create()para , você pode baixar o arquivo usando a resposta retornada:

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

Busca na Web (Prévia)

Realize buscas gerais na internet para recuperar informações atuais da internet. Documentação da 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}`);

Veja o código de exemplo completo em agentWebSearch.ts.

Uso do Computador (Prévia)

Permitir que agentes interajam diretamente com sistemas de computador para automação de tarefas e operações do 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})`);

Após chamar responses.create(), processe a resposta em um ciclo de interação. Gerencie computer_call itens de saída e forneça capturas de tela conforme computer_call_output o computer_screenshot tipo para continuar a interação.

Veja o código de exemplo completo em agentComputerUse.ts.

Protocolo de Contexto de Modelo (MCP)

Integre servidores MCP para ampliar as capacidades dos agentes com ferramentas e recursos padronizados. Documentação da 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" } },
  },
);

Após chamar responses.create(), verifique os mcp_approval_request itens na saída da resposta. Envie de volta McpApprovalResponse com sua aprovação a decisão para permitir que o corretor continue seu trabalho.

Veja o código de exemplo completo em agentMcp.ts.

OpenAPI

Chame APIs externas definidas pelas especificações do OpenAPI sem código adicional do lado do cliente. Documentação da 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})`);

Veja o código de exemplo completo em agentOpenApi.ts.

Ferramenta de Função

Defina funções personalizadas que permitam que agentes interajam com APIs externas, bancos de dados ou lógica de aplicação. Documentação da 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})`);

Após chamar responses.create(), processar function_call itens da saída da resposta, execute sua lógica funcional com os argumentos fornecidos e envie de volta FunctionCallOutput com os resultados.

Veja o código de exemplo completo em agentFunctionTool.ts.

  • Ferramenta de Busca de Memória (Prévia)

A Ferramenta de Armazenamento de Memória adiciona Memória a um Agente, permitindo que o modelo de IA do Agente pesquise informações passadas relacionadas ao prompt do usuário atual.

O embeddingModelDeployment é o nome do modelo usado para criar embeddings vetoriais para armazenar e pesquisar memórias.

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

Veja o código de exemplo completo em agentMemorySearch.ts.

Connection-Based Ferramentas

Essas ferramentas requerem configurar conexões no seu projeto de AI Foundry e usar projectConnectionId.

Azure AI Search

Integre com os índices do Azure AI Search para poderosas capacidades de recuperação de conhecimento e busca 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})`);

Veja o código de exemplo completo em agentAiSearch.ts.

Aterramento do Bing

Respostas de agentes terrestres com resultados de busca web em tempo real do Bing para fornecer informações up-todatas:

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

Veja o código completo de exemplo em agentBingGrounding.ts.

Busca Personalizada do Bing (Prévia)

Use instâncias de busca Bing configuradas sob medida para resultados de busca web específicos de domínio ou 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})`);

Veja o código de exemplo completo em agentBingCustomSearch.ts.

Microsoft Fabric (Prévia)

Conecte-se e consulte a 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})`);

Veja o código de exemplo completo em agentFabric.ts.

Microsoft SharePoint (Prévia)

Acesse e pesquise documentos, listas e sites do SharePoint para integração de conhecimento 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})`);

Veja o código de exemplo completo em agentSharepoint.ts.

Automação do Navegador (Prévia)

Automatize interações com navegadores para web scraping, testes e interação com aplicações 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})`);

Veja o código de exemplo completo em agentBrowserAutomation.ts.

MCP com Conexão de Projeto

Integração MCP usando conexões específicas de projeto para acessar 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})`);

Veja o código de exemplo completo em agentMcpConnectionAuth.ts.

Agente-para-Agente (A2A) (Prévia)

Permitir a colaboração entre múltiplos agentes, onde os agentes podem se comunicar e delegar tarefas para outros 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})`);

Veja o código de exemplo completo em agentAgentToAgent.ts.

OpenAPI com Conexão de Projeto

Chame APIs externas definidas pelas especificações OpenAPI usando autenticação de conexão de projeto:

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

Veja o código de exemplo completo em agentOpenApiConnectionAuth.ts.

Para exemplos completos funcionais de todas as ferramentas, veja o diretório samples-dev.

Evaluation

A avaliação na biblioteca de clientes do Azure AI Project fornece métricas quantitativas de qualidade e segurança assistidas por IA para avaliar desempenho e avaliar modelos LLM, aplicações GenAI e agentes. Métricas são definidas como avaliadores. Avaliadores integrados ou personalizados podem fornecer insights abrangentes sobre avaliações.

O código abaixo mostra algumas operações de avaliação. A lista completa de exemplos pode ser encontrada na pasta "avaliações" na seção 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})`);

Veja o código de exemplo completo em agentEvaluation.ts.

Operações de implantações

O código a seguir mostra algumas operações de Implantações, que permitem enumerar os modelos de IA implantados em seus Projetos do Microsoft Foundry. Esses modelos podem ser vistos na guia "Modelos + pontos de extremidade" em seu projeto do Microsoft Foundry. Exemplos completos podem ser encontrados na pasta "deployment" na seção pacotes c0.

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

Operações de conexões

O código abaixo mostra algumas operações de Conexão, que permitem enumerar os Recursos do Azure conectados aos seus Projetos Microsoft Foundry. Essas conexões podem ser vistas no "Centro de Gerenciamento", na guia "Recursos conectados" em seu Projeto do Microsoft Foundry. Samples completos podem ser encontrados na pasta "connections" na seção 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)}`);

Operações de conjunto de dados

O código abaixo mostra algumas operações do conjunto de dados. Samples completos podem ser encontrados na pasta "datasets" na seção 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.");

Operações de arquivos

O código abaixo mostra algumas operações do Files usando o cliente OpenAI, que permitem fazer upload, recuperar, listar e excluir arquivos. Essas operações são úteis para trabalhar com arquivos que podem ser usados para ajuste fino e outras operações de modelo de IA. Samples completos podem ser encontrados na pasta "files" na seção 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)}`,
);

Operações de índices

O código abaixo mostra algumas operações de índices. Samples completos podem ser encontrados na pasta "indexes" na seção 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);

Operações de ajuste fino

O código abaixo mostra como criar trabalhos de ajuste fino usando o cliente OpenAI. Essas operações suportam várias técnicas de ajuste fino como Fine-Tuning supervisionada (SFT), Fine-Tuning de reforço (RFT) e Otimização Direta de Desempenho (DPO). Samples completos podem ser encontrados na pasta "finetuning" na seção c0.

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

Rastreamento

Nota: A funcionalidade de rastreamento está em visualização preliminar e está sujeita a alterações. Intervalos, atributos e eventos podem ser modificados em versões futuras.

Você pode adicionar um recurso do Application Insights Azure ao seu projeto Microsoft Foundry. Consulte a guia Rastreamento em seu projeto do Microsoft Foundry. Se uma estivesse ativada, você pode acessar a connection string do Application Insights, configurar seu cliente AI Projects e observar o caminho completo de execução pelo Azure Monitor. Normalmente, talvez você queira iniciar o rastreamento antes de criar um cliente ou agente.

Instalação

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

Como ativar o rastreamento

Aqui está um exemplo de código que mostra como ativar o rastreamento do 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);

Veja o código de exemplo completo em remoteTelemetry.ts.

Solução de problemas

Exceções

Os métodos de cliente que fazem chamadas de serviço geram uma restError para uma resposta de código de status HTTP sem êxito do serviço. O code da exceção conterá o código de status de resposta HTTP. O error.message da exceção contém uma mensagem detalhada que pode ser útil para diagnosticar o 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 exemplo, quando você fornece credenciais erradas:

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

problemas de relatório

Para reportar problemas com a biblioteca cliente ou solicitar recursos adicionais, por favor, abra uma edição GitHub aqui

Próximas Etapas 

Dê uma olhada na pasta package samples, que contém código totalmente executável.

contribuindo com

Este projeto recebe contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença de Colaborador) declarando que você tem o direito de, e realmente fazer, conceder-nos os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Ao enviar uma solicitação de pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar a PR adequadamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, consulte as perguntas frequentes sobre o Código de Conduta ou entre em contato com opencode@microsoft.com com perguntas ou comentários adicionais.

  • Last updated on