Libreria client Azure AI Projects per JavaScript - versione 2.11.0

La libreria client di AI Projects fa parte dell'SDK di Microsoft Foundry e offre un accesso semplice alle risorse presenti nel tuo Microsoft Foundry Project. Usarlo per:

  • Crea ed esegue Agenti utilizzando la .agents proprietà sul client.
  • Migliora gli agenti con strumenti specializzati:
    • Ricerca di memoria dell'agente (Anteprima)
    • Agente-ad-Agente (A2A) (Anteprima)
    • Azure AI Search
    • Ricerca personalizzata Bing (Anteprima)
    • Bing Fondamento
    • Automazione del browser
    • Interprete di codice
    • Uso del computer
    • Ricerca file
    • Strumento funzionale
    • Generazione di immagini
    • Microsoft Fabric (Anteprima)
    • Protocollo di Contesto Modello (MCP)
    • OpenAPI
    • Microsoft SharePoint (Anteprima)
    • Ricerca Web (Anteprima)
    • Ricerca Strumento
  • Ottieni un client OpenAI che utilizza il .getOpenAIClient. metodo per eseguire Risposte, Conversazioni, Valutazioni e operazioni di FineTuning con il tuo Agente.
  • Gestisci le sessioni e i file dell'agente ospitato utilizzando le .agents operazioni di una distribuzione che supporta le sessioni.
  • Gestisci le competenze (anteprima) per le funzionalità riutilizzabili dell'agente, utilizzando le .beta.skills operazioni.
  • Gestisci le cassette degli attrezzi per raggruppare gli strumenti in raccolte riutilizzabili, utilizzando le .toolboxes operazioni.
  • Gestisci gli archivi di memoria (anteprima) per le conversazioni dell'Agente, utilizzando le .beta.memoryStores operazioni.
  • Gestisci le routine (anteprima) per pianificare e distribuire flussi di lavoro automatizzati, utilizzando le .beta.routines operazioni.
  • Gestisci le versioni dei modelli (anteprima) per creare, aggiornare e gestire versioni personalizzate del modello, utilizzando le .beta.models operazioni.
  • Esplora ulteriori strumenti di valutazione (alcuni in anteprima) per valutare le prestazioni della tua applicazione di IA generativa, utilizzando , .evaluationRules.beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, e .beta.schedules operazioni.
  • Esegui scansioni del Red Team (anteprima) per identificare i rischi associati alla tua applicazione di IA generativa, utilizzando le .beta.redTeams operazioni.
  • Fine tune Modelli AI sui tuoi dati.
  • Enumera i modelli AI distribuiti al tuo Foundry Project utilizzando le .deployments operazioni.
  • Enumera le risorse Azure connesse nel tuo progetto Foundry utilizzando le .connections operazioni.
  • Carica documenti e crea Dataset per farli riferimento utilizzando le .datasets operazioni.
  • Crea ed enumera indici di ricerca utilizzando le operazioni .indexes .

La libreria client utilizza la versione delle API REST del piano dati Microsoft c1> Foundry <.

Documentazione | del prodotto Esempi | Pacchetto (npm) | Documentazione | di riferimento APICodice sorgente SDK

Sommario

Introduzione

Prerequisito

Autorizzazione

  • È necessario un Entra ID per autenticare il client. L'applicazione necessita di un oggetto che implementa l'interfaccia token . Qui esempi di codice usa DefaultAzureCredential. Per ottenere questo lavoro, è necessario:
    • Un ruolo appropriato. vedi Controllo degli accessi basato sui ruoli nel portale Microsoft Foundry. Il ruolo assegnato può essere svolto tramite la scheda "Controllo di accesso (IAM)" della tua risorsa Azure AI Project nel portale Azure.
    • interfaccia della riga di comando di Azure installata.
    • Sei connesso al tuo account Azure eseguendo az login.
    • Nota che se hai più abbonamenti Azure, l'abbonamento che contiene la tua risorsa Azure AI Project deve essere il tuo abbonamento predefinito. Eseguire az account list --output table per elencare tutte le sottoscrizioni e vedere quale è l'impostazione predefinita. Eseguire az account set --subscription "Your Subscription ID or Name" per modificare la sottoscrizione predefinita.

Installare il pacchetto

npm install @azure/ai-projects dotenv

Concetti principali

Crea e autentica il client con Entra ID

Entra ID è l'unico metodo di autenticazione supportato al momento dal client.

Per costruire un AIProjectsClient, può projectEndpoint essere recuperato da projectEndpoint. Di seguito assumeremo che la variabile FOUNDRY_PROJECT_ENDPOINT d'ambiente sia stata definita per mantenere questo valore:

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

Gruppi operativi di anteprima e flag di funzionalità opt-in

Alcune operazioni di anteprima richiedono un flag esplicito foundryFeatures di partecipazione automatica. Per esempio:

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

I gruppi di operazioni di anteprima includono .beta.voiceAgents, , .beta.skills.beta.memoryStores, .beta.routines.beta.models, .beta.evaluationTaxonomies.beta.evaluators, .beta.insights, , .beta.schedules, , e ..beta.redTeams Gli Voice Agent dispongono sia di funzionalità GA che di anteprima; vedi Operazioni dell'Agente Vocale per i requisiti di opt-in.

Usa .agentInsightMonitors per elencare i monitor che analizzano i tuoi agenti:

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

Examples

Esecuzione di operazioni di risposte utilizzando il client OpenAI

Il tuo progetto Microsoft Foundry potrebbe avere uno o più modelli di IA distribuiti. Questi potrebbero essere modelli OpenAI, modelli Microsoft o modelli di altri fornitori. Usa il codice qui sotto per ottenere un OpenAI autenticato dal pacchetto openai ed eseguire una chiamata di completamento della chat.

Esegui il codice seguente. Qui assumiamo che deploymentName (str) sia definito. È il nome di implementazione di un modello AI nel tuo Foundry Project. Come mostrato nella scheda "Modelli + endpoint", nella colonna "Nome".

Consulta la cartella "responses" nel package samples per ulteriori campioni, inclusi i streaming response.

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

Esecuzione di operazioni dell'agente

La .agents proprietà consente di accedere a tutte le operazioni dell'agente AIProjectsClient . Gli agenti utilizzano un'estensione del protocollo OpenAI Responses, quindi è probabile che sia necessario chiedere a un OpenAI client di eseguire le operazioni dell'agente, come mostrato nell'esempio seguente.

Per la configurazione, vedi Avvio rapido: Configura risorse Microsoft Foundry.

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

Operazioni dell'Agente Vocale

Usare project.agents per creare e gestire gli agenti vocali. Scegli il client di connessione che corrisponde al tuo agente:

  • project.voiceAgents.realtime per agenti vocali in tempo reale e a cascata.
  • project.beta.voiceAgents.liveper GPT Live (anteprima).

Il vecchio project.beta.voiceAgents.realtime percorso è un alias di compatibilità obsoleto per lo stesso client. Usa il percorso root nel nuovo codice. Le connessioni Realtime ordinarie sono GA e non inviano di default un opt-in per l'anteprima di VoiceAgents.

Scope API o funzionalità VoiceAgents=V1Preview
GA Definizioni in tempo reale/a cascata, sottoagenti delegati e strumenti di sistema telefonico attraverso project.agents Non obbligatorio
GA project.agents.createFromPrompt (agents:generate) Non inviare
GA Tutte le 14 operazioni di conversazione in tempo reale memorizzate su project.voiceAgents.conversations; Protocollo Realtime e modelli OpenAI Realtime Non obbligatorio
GA Telefonia TPE/Twilio e call-job list/get operative su project.voiceAgents.telephony Non obbligatorio
Condizionale Connessioni in tempo reale a un agente tramite handoff inline, destinazioni di trasferimento SIP oppure post_call Passa foundryFeatures a connect()
Condizionale Collegamento telefonico/trasferimento/scrittura di chiamate e creazione/annulla/cancellazione del lavoro di chiamata su project.voiceAgents.telephony Passa foundryFeatures solo quando si utilizza SIP
Anteprima Definizioni, delega, sessioni, conversazioni memorizzate e modelli di GPT Live Richiesto; vivi nativo e project.beta.voiceAgents.liveConversations fornirlo internamente
Anteprima Configurazione/stato/eventi di handoff in linea, modelli SIP e post_call configurazioni/tipi Richiesto per questi membri di anteprima; utilizza l'opt-in dell'operazione pertinente
Anteprima Tutte e sette le operazioni di campagna su project.beta.voiceAgents.telephony Richiesto; fornito internamente

Un'operazione GA può accettare un'unione con membri solo in anteprima. Opta per l'opzione selezionando Membri Live, inline-handoff o SIP, oppure quando configuri post_call; la presenza di tali membri non rende l'intera unione o l'operazione in anteprima.

Per le scritture telefoniche, usa il fornitore di connessione, binding, chiamata o call-job per determinare l'utilizzo SIP, non solo il tipo di indirizzo: una connessione SIP può utilizzare phone_number indirizzi sorgente e di destinazione. Il modello di tracciamento REST accetta solo una connessione TPE/Twilio esistente per la sua chiamata in uscita opzionale; non mostra le chiamate SIP. Separatamente, transfer.require_handoff è un'impostazione GA transfer-summary; non abilita di per sé il handoff in anteprima inline.

Quando si migrano campioni più vecchi, sostituisci project.beta.agents.createFromPrompt con project.agents.createFromPrompt, project.beta.voiceAgents.conversationsproject.voiceAgents.conversationscon , e usi non campagna di project.beta.voiceAgents.telephony con project.voiceAgents.telephony. Sostituisci i loro tipi di risposta ritirati Beta*OptionalParams e quelli con download della conversazione con i corrispondenti tipi non beta. Mantieni le operazioni di campagna e GPT Live sotto project.beta.voiceAgents; usa il client root Realtime elencato sopra.

Questo Node.js esempio invia testo a un agente Realtime esistente e stampa la risposta. Usa un agente senza un saluto automatico così che la prima risposta sia la risposta al tuo messaggio.

// Ordinary Realtime sessions are GA and do not require a preview opt-in.
const connection = await project.voiceAgents.realtime.connect("<voice agent name>");
try {
  await connection.sendText("Hello. Please introduce yourself briefly.");
  for await (const event of connection) {
    if (
      event.type === "response.output_text.delta" ||
      event.type === "response.output_audio_transcript.delta"
    ) {
      process.stdout.write(event.delta);
    } else if (event.type === "error") {
      throw new Error(event.error.message);
    } else if (event.type === "response.done") {
      if (event.response.status !== "completed") {
        throw new Error(`Voice response ${event.response.status}.`);
      }
      break;
    }
  }
} finally {
  await connection.close();
}

Leggi gli eventi con un solo for await loop. Uscire dal loop chiude la connessione. I tipi di evento sconosciuti arrivano come type: "unknown" senza disconnettere la sessione; il loro tipo originale è in eventType. Convalida rawEvent prima di utilizzare i suoi campi. Gli eventi deformati sbilanciano VoiceAgentProtocolError. Gestisci gli eventi di servizio error come mostrato sopra.

Per mantenere le conversazioni, imposta store: true sull'agente oppure su connect(), poi usa project.voiceAgents.conversations per leggere le conversazioni in tempo reale. La connessione a un agente disabilitato fallisce con 409 Conflict un codice agent_disableddi errore .

L'esempio di passaggio in linea mostra l'opt-in esplicito per un agente Realtime che utilizza la configurazione di anteprima:

const connection = await project.voiceAgents.realtime.connect("<inline-handoff agent name>", {
  foundryFeatures: "VoiceAgents=V1Preview",
});
await connection.close();

In Node.js, questa opzione invia l'intestazione foundry-features (header). I browser e React Native inviano il parametro di query equivalente foundry_features di WebSocket. Usa l'opzione digitata, non il parametro generico query riservato. I campioni Realtime predefiniti utilizzano configurazioni di agenti GA; per un agente esistente con handoff inline, destinazioni di trasferimento SIP oppure post_call, opta come sopra.

Scegli un campione completo per l'attività che desideri:

Task Esempio Node.js
Crea e leggi una definizione di agente Configurare un agente vocale
Genera un agente a partire da un obiettivo Genera un agente vocale
Invia il discorso e salva la risposta audio Audio in tempo reale
Invia testo e gestisci una chiamata di funzione Testo e strumenti in tempo reale
Ispeziona i binding e la cronologia delle chiamate senza effettuare chiamate Telefonia
Instradare una svolta a uno specialista inline (anteprima) Passaggio in linea
Ispeziona le registrazioni in tempo reale (GA) o Live (anteprima) Registrazioni di conversazioni
Ispeziona campagne di anteprima e voci di chiamata in uscita GA Campagne di sola lettura

L'esempio di anteprima di handoff si inserisce quando si crea la definizione e si collega. Crea due specialisti in tempo reale inline, osserva gli eventi di handoff correlati e la risposta completata del bersaglio, quindi elimina il suo agente campionario. Se la creazione viene interrotta, una richiesta HTTP abortita non annulla la creazione lato server: usa il nome unico dell'agente registrato per verificare la presenza di una risorsa che termina in seguito. I campioni di tracciamento sono walkthrough separati per gli strumenti; gli esempi di generazione base, Realtime e GPT Live non richiedono la configurazione del tracciamento. Il modello di configurazione è di default GA; impostare una destinazione post-chiamata opzionale abilita l'anteprima della consegna della trascrizione e aggiunge l'opt-in per definizioni. La consegna post-chiamata supporta anche URL opzionali per la registrazione unita; il campione non richiede l'audio del chiamante.

Conversazioni e registrazioni memorizzate

Il campione delle registrazioni delle conversazioni è di sola lettura e supporta entrambe le famiglie di API persistite. Imposta FOUNDRY_AGENT_NAME e scegli FOUNDRY_VOICE_CONVERSATION_PROTOCOL=realtime oppure live. Realtime utilizza il client GA project.voiceAgents.conversations senza un'intestazione di anteprima; Live utilizza project.beta.voiceAgents.liveConversations l'intestazione di anteprima richiesta. Legge una pagina e può selezionare una conversazione o un elemento esatto utilizzando le variabili documentate in sample.env. Utilizza gli ID restituiti dalle raccolte REST, non gli ID nativi di Realtime WebSocket o quelli di risposta. Crea prima la registrazione collegandoti e store: true finalizzando la sessione prima di scaricare l'audio. Il campione non cancella mai una conversazione memorizzata né stampa le trascrizioni dei chiamanti.

Imposta FOUNDRY_VOICE_RECORDING_OUTPUT_FILE l'opzione per scaricare un file WAV. Con FOUNDRY_VOICE_AUDIO_ITEM_ID, questo scarica l'audio ascoltato da quell'elemento; altrimenti scarica la registrazione stereo unificata. Questi file WAV sono diversi dai file PCM grezzi scritti dai campioni in streaming. Mantieni privati i media dei chiamanti scaricati. Le registrazioni Breach-your-own-storage devono essere lette blob_uri con le proprie credenziali di storage; questo esempio non rileva URL di storage arbitrari.

Il tempo reale espone inoltre l'ispezione delle risposte e l'audio dei prodotti generati ma non ascoltati. Le variabili audio generati richiedono un elemento interrotto o troncato in cui il servizio ha prodotto audio oltre il segmento ascoltato; la cancellazione da sola non garantisce l'esistenza di un artefatto. Audio mancante restituisce 404. Una registrazione unita incompleta può tornare 409 recording_not_ready; seguirne Retry-After le indicazioni invece di trattare quella risposta come una registrazione vuota.

Per le sessioni live di GPT memorizzate, usa project.beta.voiceAgents.liveConversations. Connettersi con project.beta.voiceAgents.live.connect() e store: true per mantenere una sessione Live; project.voiceAgents.realtime.connect() utilizza il protocollo Realtime e non è una connessione Live. Il seguente esempio Node.js legge una conversazione Live completata, elenca gli elementi memorizzati senza stampare trascrizioni e salva la registrazione WAV unita gestita da Foundry:

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";
import { pipeline } from "node:stream/promises";
import { createWriteStream } from "node:fs";

const project = new AIProjectClient("<project endpoint>", new DefaultAzureCredential());
const agentName = "<GPT Live agent name>";
const conversationId = "<stored Live conversation ID>";
const conversations = project.beta.voiceAgents.liveConversations;
const conversation = await conversations.get(agentName, conversationId);
console.log("Conversation:", conversation.id, conversation.status);
for await (const item of conversations.listItems(agentName, conversationId)) {
  console.log("Stored item:", item.id, item.type);
}
const recording = await conversations.getAudio(agentName, conversationId);
if (recording.blob_uri) {
  throw new Error("Retrieve BYOS audio from blob_uri using your own storage credentials.");
}
const audio = await conversations.downloadAudio(agentName, conversationId);
if (!audio.readableStreamBody) {
  throw new Error("Expected a Node.js audio stream.");
}
await pipeline(audio.readableStreamBody, createWriteStream("live-conversation.wav"));

Le operazioni di campagna utilizzano il client di anteprima project.beta.voiceAgents.telephony . Usa deleteCampaign() per eliminare una campagna; deleteTelephony() è un alias di compatibilità obsoleto per quell'operazione. Le operazioni di call-job list/get utilizzano il client GA project.voiceAgents.telephony , inclusi i job creati da una campagna di anteprima. Il campione di campagna legge solo la preparazione della campagna, gli errori di validazione, i monitor operativi e i job di chiamata. Le letture della campagna richiedono un deployment con tali percorsi di anteprima abilitati. Non crea né annulla mai una chiamata: la creazione della campagna può autorizzare la chiamata prima che il sondaggio di preparazione arrivi. Una pagina di errore di validazione vuota durante la preparazione non stabilisce che la campagna sia valida o pronta.

Parametri di query personalizzati

Passa query per aggiungere parametri URL per una connessione. Usa i nomi supportati dal tuo servizio o gateway; i nomi qui sotto sono esempi:

const connection = await project.voiceAgents.realtime.connect("my-voice-agent", {
  query: {
    custom_key: "custom value",
    custom_flag: true,
    // Explicit URL transport: only use non-sensitive prompt variables.
    structured_inputs: JSON.stringify({ persona: "guide" }),
  },
});
await connection.close();

I valori possono essere stringhe, numeri finiti o booleani. L'URL SDK li codifica e li cattura quando connect() viene chiamato. Un valore sostituisce un parametro endpoint corrispondente; undefined lo rimuove. Questi valori non vengono riutilizzati per connessioni successive.

Usa opzioni digitate come store, agentVersionOverride, e quelle foundryFeatures di Realtime invece di inserire le impostazioni SDK in query. I nomi SDK/autenticazione, i nomi a input strutturati non canonici e i nomi che iniziano con h- rimangono riservati. Il tempo reale consente esplicitamente la structured_inputs chiave esatta con una stringa di oggetti JSON, come mostrato sopra; non combinarla con structuredInputs. Altri valori di query personalizzati non diventano variabili di prompt.

Realtime structuredInputs preserva il trasporto basato su header in Node.js. I browser utilizzano una query URL perché non possono inviare intestate arbitrarie per l'aggiornamento WebSocket. Se il tuo servizio richiede il modulo di query, opta esplicitamente tramite query.structured_inputs .structuredInputs Non inserire mai segreti o variabili di prompt sensibili nei parametri della query: i log di accesso server e proxy possono mantenere gli URL.

Agenti vocali GPT Live

Usa project.beta.voiceAgents.live per gli agenti GPT Live. Quando crei l'agente, imposta sub_protocol: "live", model_type: "self_deployed", e model al nome della tua distribuzione GPT Live. La creazione richiede VoiceAgents=V1Preview. Passare { foundryFeatures: "VoiceAgents=V1Preview" } a project.agents.create() o createVersion(). Le connessioni native Live inviano sempre internamente il flag di anteprima richiesto; i chiamanti non hanno bisogno di un flag su live.connect().

Questo breve esempio richiede un agente esistente configurato per audio mono PCM16LE a 24 kHz. Live avanza su un orologio audio anche aggiungendo istruzioni testuali, quindi l'esempio invia silenzio fino a quando non arriva la conferma correlata, quindi chiude la sessione. Usa gli esempi completi qui sotto per inviare testo o voce e leggere la risposta.

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

const project = new AIProjectClient("<project endpoint>", new DefaultAzureCredential());
const connection = await project.beta.voiceAgents.live.connect("<GPT Live agent name>", {
  store: false,
});
const eventId = "brief-instructions";
// Requires an agent configured for mono PCM16LE at 24 kHz.
const silence = new Uint8Array(4800); // 100 ms of audio.
let correlatedAck = false;
let serviceError: Error | undefined;
const onAppended = (event: LiveServerEventLiveInstructionsAppended): void => {
  if (event.client_event_id === eventId) correlatedAck = true;
};
const onError = (event: LiveServerEventLiveErrorEvent): void => {
  serviceError = new Error(event.error.message);
};
connection.on("session.instructions.appended", onAppended);
connection.on("error", onError);
try {
  await connection.appendInstructions("Keep your answers brief.", { eventId });
  const deadline = Date.now() + 10000;
  while (!correlatedAck) {
    if (serviceError) throw serviceError;
    if (connection.state !== "connected") {
      throw new Error(`Live connection became ${connection.state} before the instructions ACK.`);
    }
    if (Date.now() >= deadline) {
      throw new Error("Timed out waiting for the correlated instructions ACK.");
    }
    await connection.sendAudio(silence);
    await new Promise((resolve) => setTimeout(resolve, 100));
  }
  if (serviceError) throw serviceError;
} finally {
  connection.off("session.instructions.appended", onAppended);
  connection.off("error", onError);
  await connection.close();
}

Esegui un campione GPT Live

Set FOUNDRY_PROJECT_ENDPOINT e FOUNDRY_LIVE_MODEL in .env. Usa un nome di distribuzione, non un ID del catalogo modello. Il campione di funzione necessita FOUNDRY_LIVE_BACKEND_MODELanch'esso di . Vedi sample.env per queste impostazioni e i percorsi opzionali dei file audio.

Task Esempio Node.js
Invia un saluto e stampa la risposta parlata come testo GPT Live text
Invia un file vocale e salva la risposta audio GPT Live audio
Esegui una funzione locale e lascia che l'agente parli del risultato Chiamata della funzione GPT Live

Da un checkout SDK compilato, esegui un esempio con Node.js 22.18 o successiva:

node samples-dev/agents/agentVoiceLiveText.ts

Ogni esempio crea ed elimina il proprio agente. Stampa sottotitoli ma non riproduce il suono dagli altoparlanti. Il campione audio utilizza un file registrato, non un microfono, e legge e salva PCM16LE mono grezzi a 24 kHz, senza WAV o altro header file.

Premi Invio dopo la risposta, oppure Ctrl+C, per fermare. L'utilizzo è fatturabile fino alla chiusura della sessione. Il live necessita di input audio continuo, anche per testi e strumenti, quindi i campioni lasciano silenzio mentre sono inattivi. Live non ha un evento con voce completata; una risposta backend completata non significa che l'agente abbia finito di parlare.

Il testo di esempio aggiunge istruzioni della sessione e attende il loro riconoscimento correlato prima di aggiungere il commento. Tale conferma conferma l'accettazione, non il discorso completato; mantieni aperta la sessione fino all'arrivo della risposta attesa.

Controlli di sessione ed eventi

connect()aspetta .session.started Leggi le impostazioni correnti da connection.session, inclusi l'agente gestito selezionato e la versione quando applicabile. Leggi gli eventi con un solo for await loop oppure usa on, off, e once ascoltatori per gli eventi successivi. Per il consumo solo dell'ascoltatore, fornire onEvent durante la connessione per ricevere eventi di avvio e audio iniziale senza attendere il connect() ritorno. L'evento di avvio originale, incluso l'ID della conversazione persistente quando fornito dal servizio, rimane disponibile tramite connection.sessionStarted. Un iteratore avviato dopo la configurazione di un onEvent callback riceve eventi successivi, non eventi passati.

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

const project = new AIProjectClient("<project endpoint>", new DefaultAzureCredential());
const connection = await project.beta.voiceAgents.live.connect("<GPT Live agent name>", {
  store: true,
  onEvent: (event) => {
    if (event.type === "session.started") {
      console.log("Conversation:", event.conversation_id);
    } else if (event.type === "session.output_audio.delta") {
      console.log("Received an audio chunk.");
    }
  },
});
try {
  console.log("Session:", connection.sessionStarted.session.id);
} finally {
  await connection.close();
}
Task API o evento
Invia audio grezzo sendAudio(); Live rileva i confini vocali, quindi non è necessario alcun commit del buffer audio
Leggere le trascrizioni session.input_transcript.delta, session.output_transcript.delta
Ricevi audio session.output_audio.delta; decodifica i dati base64 prima di salvarli o riprodurli
Aggiungi contesto testuale, anziché un messaggio utente appendInstructions(), appendThinking(), appendCommentary()
Pausa o riprendi l'elaborazione audio muteInputAudio(), unmuteInputAudio()
Aggiorna le impostazioni del backend e i trigger delle trascrizioni configureSession(); il modello iniziale, il formato audio e il proprietario della delega non possono cambiare
Chiudi sessione close(); aspetta session.closed e rifiuta se la finalizzazione non è confermata

close() e dispose() anche rifiutare un spegnimento non confermato quando la presa è già scollegata. Ispezionare connection.closed l'evento di finalizzazione del servizio e eventuali errori di connessione.

Con la delegazione delle Risposte, gli eventi backend arrivano all'interno response.eventdi . Usa sendResponseItem() per aggiungere un messaggio utente e requestResponse() chiedere una risposta. Per una chiamata di funzione, attendi che la risposta backend che chiama termini, quindi usa sendToolOutput() per restituire il risultato e richiedere la continuazione. Questi metodi richiedono la delega delle Risposte. Per la delega gestita dal client, usa appendThinking() oppure appendCommentary() e passa l'ID di delega come delegationId.

Gli elementi di contesto decisionale supportano messaggi utente, chiamate e risultati di funzione, chiamate e risultati di strumenti personalizzati. Inviali con decision.item.creategli eventi ricevuti decision.item.created ; mantengono i campi dell'elemento corrispondenti e l'ID memorizzato. I comandi decisionali richiedono supporto da parte della distribuzione del servizio.

Live non supporta il response.cancelfile di Realtime . Un segnale di aborto annulla una connessione SDK o un'operazione di invio, non la voce già generata. Per memorizzare le conversazioni live, abilitare store e utilizzare project.beta.voiceAgents.liveConversations; il deployment del servizio deve supportare la persistenza. Imposta liveOptionsAIProjectClient su Modifica connessione, inizio sessione e timeout chiusi. Usa il sample di conversazione memorizzata per FOUNDRY_VOICE_CONVERSATION_PROTOCOL=live ispezionare gli elementi persistiti o scaricare il loro audio WAV.

Autenticazione del browser

Usa un'identificazione del browser come InteractiveBrowserCredential. L'SDK utilizza sottoprotocolli nativi WebSocket con live e sottoprotocolli bearer-token di breve durata, inclusi i Web Workers. Node.js usa invece un header portante. Non fornire realtime come sottoprotocollo Live, non inserire token negli URL né incorporare chiavi API, segreti client o token di lunga durata nel codice del browser. Se l'autenticazione diretta del browser non è disponibile, fornisci un relay backend autenticato tramite webSocketFactory.

Le connessioni in tempo reale restano structuredInputs nell'intestazione x-ms-voice-structured-inputs in Node.js e utilizzano la structured_inputs query URL nei browser e nei Worker. Il Realtime query.structured_inputs esplicito opta per il trasporto URL su qualsiasi host. GPT Live continua a utilizzare la query URL su tutti gli host e non ha un'alternativa basata su header. I log di accesso proxy e server possono conservare URL: non inserire credenziali, dati personali o altre informazioni sensibili negli input portati dagli URL.

Utilizzo degli strumenti Agent

Gli agenti possono essere potenziati con strumenti specializzati per varie capacità. Gli strumenti sono organizzati in base ai requisiti di connessione:

Strumenti integrati

Questi strumenti funzionano immediatamente senza necessità di connessioni esterne.

Interprete di codice

Scrivi ed esegui codice Javascript in un ambiente sandbox, elabora file e lavora con diversi formati dati. Documentazione 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}`);

Vedi il codice campione completo in agentCodeInterpreter.ts.

Ricerca file

Strumento RAG integrato (Retrieval-Augmented Generation) per elaborare e cercare documenti utilizzando vettoriali store per il recupero della conoscenza. Documentazione 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})`);

Vedi il codice campione completo in agentFileSearchStream.ts.

Generazione di immagini

Genera immagini basate su prompt di testo con impostazioni personalizzabili di risoluzione, qualità e stile:

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

Dopo aver chiamato responses.create(), puoi scaricare il file usando la risposta restituita:

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

Ricerca Web (Anteprima)

Effettua ricerche generali sul web per recuperare informazioni aggiornate da internet. Documentazione 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}`);

Vedi il codice campione completo in agentWebSearch.ts.

Uso del computer

Consentire agli agenti di interagire direttamente con i sistemi informatici per l'automazione delle attività e le operazioni di sistema (richiede un modello di distribuzione che supporti lo computer strumento, ad esempio gpt-5.4; per computer-use-preview le distribuzioni, utilizzare computer_use_preview):

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",
    },
  ],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

Dopo aver chiamato responses.create(), elabora la risposta in un ciclo di interazione. Gestisci computer_call gli elementi in uscita e fornisci screenshot come computer_call_output il computer_screenshot tipo per continuare l'interazione.

Vedi il codice campione completo in agentComputerUse.ts.

Model Context Protocol (MCP)

Integrare i server MCP per estendere le capacità degli agenti con strumenti e risorse standardizzate. Documentazione 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" } },
  },
);

Dopo aver chiamato responses.create(), controlla gli mcp_approval_request elementi nell'output della risposta. Invia McpApprovalResponse indietro con la tua approvazione la decisione per permettere all'agente di continuare a lavorare.

Vedi il codice campione completo in agentMcp.ts.

OpenAPI

Chiama API esterne definite dalle specifiche OpenAPI senza codice lato client aggiuntivo. Documentazione 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})`);

Vedi il codice campione completo in agentOpenApi.ts.

Strumento funzionale

Definire funzioni personalizzate che permettano agli agenti di interagire con API esterne, database o logica applicativa. Documentazione 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})`);

Dopo aver chiamato responses.create(), processa function_call gli elementi dall'output della risposta, esegui la logica della tua funzione con gli argomenti forniti e invia indietro FunctionCallOutput con i risultati.

Consulta il codice campione completo in agentFunctionTool.ts.

  • Strumento di ricerca di memoria (Anteprima)

Lo strumento di memorizzazione aggiunge memoria a un Agente, permettendo al modello AI dell'Agente di cercare informazioni passate relative al prompt utente corrente.

Il embeddingModelDeployment è il nome del modello utilizzato per creare embedding vettoriali per memorizzare e cercare memorie.

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

Vedi il codice campione completo in agentMemorySearch.ts.

Connection-Based Strumenti

Questi strumenti richiedono di configurare le connessioni nel tuo progetto AI Foundry e di utilizzare projectConnectionId.

Azure AI Search

Integra con gli indici di Azure AI Search per potenti capacità di recupero della conoscenza e ricerca semantica:

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

Vedi il codice campione completo in agentAiSearch.ts.

Grounding di Bing

Risposte degli agenti di terra con risultati di ricerca web in tempo reale da Bing per fornire informazioni up-todata:

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

Vedi il codice campione completo in agentBingGrounding.ts.

Ricerca personalizzata Bing (Anteprima)

Usa istanze di ricerca Bing configurate su misura per risultati di ricerca web specifici per dominio o filtrati:

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 il codice campione completo in agentBingCustomSearch.ts.

Microsoft Fabric (Anteprima)

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

Vedi il codice campione completo in agentFabric.ts.

Microsoft SharePoint (Anteprima)

Accedi e cerca documenti, liste e siti SharePoint per l'integrazione della conoscenza aziendale:

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

Vedi il codice campione completo in agentSharepoint.ts.

Automazione del browser

Automatizza le interazioni con i browser per web scraping, test e interazione con applicazioni web:

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

Vedi il codice campione completo in agentBrowserAutomation.ts.

Imposta FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_NAME, e BROWSER_AUTOMATION_PROJECT_CONNECTION_ID (l'ID della risorsa di connessione del progetto per la tua risorsa Azure Playwright) prima di eseguire il campione. Utilizza lo strumento GA browser_automation per visitare https://example.com e segnalare il titolo della pagina e la descrizione visibile in base ai risultati del browser. Opzionalmente impostato FOUNDRY_AGENT_NAME per scegliere il nome dell'agente; di default si imposta su MyAgent.

Il campione di streaming stampa ogni messaggio di testo completato una volta, incluso l'URL della visualizzazione live del browser, e registra nomi di azioni di funzioni remote, ID chiamate e argomenti senza browserSessionId. Considera l'URL della visualizzazione in diretta come sensibile: non condividerlo né sottoscriverlo al controllo del fonte. Le risposte fallite o incomplete escono con uno stato non zero invece di segnalare il successo. Il campione elimina la versione dell'agente che ha creato in un finally blocco, indipendentemente dal fatto che l'elaborazione delle risposte abbia successo o meno.

MCP con Project Connection

Integrazione MCP utilizzando connessioni specifiche per progetto per accedere ai server MCP connessi:

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

Vedi il codice campione completo in agentMcpConnectionAuth.ts.

Agent-to-Agent (A2A) (Anteprima)

Consentire la collaborazione multi-agente in cui gli agenti possono comunicare e delegare compiti ad altri agenti specializzati:

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 il codice campione completo in agentAgentToAgent.ts.

OpenAPI con Project Connection

Chiama API esterne definite dalle specifiche OpenAPI utilizzando l'autenticazione della connessione di progetto:

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

Vedi il codice campione completo in agentOpenApiConnectionAuth.ts.

Per esempi completi di tutti gli strumenti, consulta la directory samples-dev.

Evaluation

La valutazione nella libreria client Azure AI Project fornisce metriche quantitative di qualità e sicurezza assistite dall'IA per valutare le prestazioni e valutare modelli LLM, applicazioni GenAI e agenti. Le metriche sono definite come valutatori. Valutatori integrati o personalizzati possono fornire approfondimenti completi sulle valutazioni.

Il codice qui sotto mostra alcune operazioni di valutazione. L'elenco completo dei campioni si trova nella cartella "valutazioni" nella sezione package samples

const openAIClient = project.getOpenAIClient();
const dataSourceConfig = {
  type: "custom" as const,
  item_schema: {
    type: "object",
    properties: { query: { type: "string" } },
    required: ["query"],
  },
  include_sample_schema: true,
};
const evalObject = await openAIClient.evals.create({
  name: "Agent Evaluation",
  data_source_config: dataSourceConfig,
  testing_criteria: [
    {
      type: "azure_ai_evaluator",
      name: "violence_detection",
      evaluator_name: "builtin.violence",
      data_mapping: { query: "{{item.query}}", response: "{{item.response}}" },
    } as any,
  ],
});
console.log(`Evaluation created (id: ${evalObject.id}, name: ${evalObject.name})`);

Vedi il codice campione completo in agentEvaluation.ts.

Operazioni di distribuzione

Il codice qui sotto mostra alcune operazioni di Deployment, che ti permettono di enumerare i modelli di IA distribuiti nei tuoi progetti Microsoft Foundry. Questi modelli possono essere visti nella scheda "Modelli + endpoint" nel tuo Microsoft Foundry Project. Campioni completi si trovano nella cartella "deployment" nel package samples.

import { ModelDeployment } from "@azure/ai-projects";

const modelPublisher = process.env["MODEL_PUBLISHER"] || "<model publisher>";
console.log("List all deployments:");
const deployments: ModelDeployment[] = [];
const properties: Array<Record<string, string>> = [];

for await (const deployment of project.deployments.list()) {
  // Check if this is a ModelDeployment (has the required properties)
  if (
    deployment.type === "ModelDeployment" &&
    "modelName" in deployment &&
    "modelPublisher" in deployment &&
    "modelVersion" in deployment
  ) {
    deployments.push(deployment);
    properties.push({
      name: deployment.name,
      modelPublisher: deployment.modelPublisher,
      modelName: deployment.modelName,
    });
  }
}
console.log(`Retrieved deployments: ${JSON.stringify(properties, null, 2)}`);

// List all deployments by a specific model publisher (assuming we have one from the list)
console.log(`List all deployments by the model publisher '${modelPublisher}':`);
const filteredDeployments: ModelDeployment[] = [];
for await (const deployment of project.deployments.list({
  modelPublisher,
})) {
  // Check if this is a ModelDeployment
  if (
    deployment.type === "ModelDeployment" &&
    "modelName" in deployment &&
    "modelPublisher" in deployment &&
    "modelVersion" in deployment
  ) {
    filteredDeployments.push(deployment);
  }
}
console.log(
  `Retrieved ${filteredDeployments.length} deployments from model publisher '${modelPublisher}'`,
);

// Get a single deployment by name
if (deployments.length > 0) {
  const deploymentName = deployments[0].name;
  console.log(`Get a single deployment named '${deploymentName}':`);
  const singleDeployment = await project.deployments.get(deploymentName);
  console.log(`Retrieved deployment: ${JSON.stringify(singleDeployment, null, 2)}`);
}

Operazioni di connessione

Il codice qui sotto mostra alcune operazioni di Connessione, che ti permettono di enumerare le Risorse Azure collegate ai tuoi progetti Microsoft Foundry. Queste connessioni sono visibili nel "Centro di Gestione", nella scheda "Risorse connesse" nel tuo Microsoft Foundry Project. I campioni completi si trovano nella cartella "connection" nel 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)}`);

Operazioni sui set di dati

Il codice seguente mostra alcune operazioni del set di dati. I campioni completi si trovano nella cartella "datasets" nel package samples.

I caricamenti locali del file system (project.datasets.uploadFile, project.datasets.uploadFolder, e project.beta.models.create) sono supportati solo in Node.js. Le applicazioni browser possono importare AIProjectClient , VoiceAgentRealtimeClient partire @azure/ai-projects e utilizzare il dataset e modellare operazioni REST senza Node.js polifill del file system.

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

Operazioni sui file

Il codice seguente mostra alcune operazioni sui file utilizzando il client OpenAI, che consentono di caricare, recuperare, elencare ed eliminare file. Queste operazioni sono utili per l'uso di file che possono essere utilizzati per l'ottimizzazione e altre operazioni del modello di intelligenza artificiale. Campioni completi si trovano nella cartella "files" nella sezione 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)}`,
);

Operazioni sugli indici

Il codice seguente mostra alcune operazioni sugli indici. I campioni completi si trovano nella cartella "indexes" nella sezione 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);

Operazioni di ottimizzazione

Il codice qui sotto mostra come creare lavori di fine-tuning utilizzando il client OpenAI. Queste operazioni supportano varie tecniche di fine-tuning come il Supervised Fine-Tuning (SFT), il Reinforcement Fine-Tuning (RFT) e l'Ottimizzazione Diretta delle Prestazioni (DPO). I campioni completi si trovano nella cartella "finetuning" nel 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));

Operazioni di sessione dell'agente

Usa project.agents per gestire sessioni e file di sessione per agenti ospiti. Le sessioni forniscono ambienti sandbox isolati per le interazioni con gli agenti. Questo esempio richiede una distribuzione di un agente ospitato che supporti le operazioni di sessione.

import { VersionRefIndicator } from "@azure/ai-projects";

const agentName = "MySessionAgent";
// Create a session for the agent
const versionIndicator: VersionRefIndicator = {
  type: "version_ref",
  agent_version: "1.0",
};
const session = await project.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 agent sessions sample!");
const uploadResult = await project.agents.uploadSessionFile(
  agentName,
  session.agent_session_id,
  filePath,
  fileContent,
);
console.log(`Uploaded file: ${uploadResult.path} (${uploadResult.bytes_written} bytes)`);

Vedi il codice di esempio completo in agentSessions.ts e nel blocco apposito.

Operazioni sulle competenze (anteprima)

Le .beta.skills operazioni ti permettono di creare e gestire competenze riutilizzabili che definiscono le capacità degli agenti.

const skillName = "sample-skill";
// Create a new skill
const created = await project.beta.skills.create(skillName, {
  inlineContent: {
    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.id})`);

Vedi il codice campione completo in skillBasic.ts.

Operazioni Toolboxes (anteprima)

Le .toolboxes operazioni ti permettono di creare e gestire cassette degli attrezzi — collezioni riutilizzabili di strumenti che possono essere condivise tra agenti.

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

Consulta il codice campione completo in toolboxesCrud.ts.

tracciamento

Porta sperimentale delle caratteristiche

Importante: La strumentazione di tracciamento GenAI è una funzione di anteprima sperimentale. Gli intervalli, gli attributi e gli eventi possono essere modificati nelle versioni future. Per utilizzarlo, devi optare esplicitamente passando tracingOptions con experimental: true quando costruisci il AIProjectClient, oppure impostando la variabile di ambiente:

AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true

Abilita questa funzione solo dopo aver esaminato i requisiti e aver capito che il comportamento di tracciamento potrebbe cambiare nelle versioni future.

Iniziare con il tracciamento

Puoi aggiungere una risorsa Application Insights Azure al tuo progetto Microsoft Foundry. Se una era abilitata, puoi ottenere la stringa di connessione di Application Insights, configurare il client AI Projects e osservare tracce in Monitoraggio di Azure. In genere, potrebbe essere necessario iniziare la traccia prima di creare un client o un agente.

Installazione

Per inviare tracce ad Monitoraggio di Azure:

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

Per stampare tracce sulla console (utile per lo sviluppo locale):

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

Come abilitare il tracciamento

Il tracciamento è abilitato passando tracingOptions al AIProjectClient costruttore. Se tracingOptions non viene fornito, il tracciamento GenAI viene completamente disabilitato e non vengono emessi spettacoli o metriche GenAI. Questa impostazione controlla solo il tracciamento specifico di GenAI (convenzione semantica per chiamate a modelli, operazioni agent, utilizzo dei token, ecc.). La configurazione di tracciamento si applica a tutte le operazioni eseguite tramite quella specifica istanza client, incluse le operazioni degli agenti e qualsiasi client OpenAI ottenuto tramite project.getOpenAIClient(). Istanze client diverse possono avere configurazioni di tracciamento indipendenti.

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

Il passaggio tracingOptions: {} (un oggetto vuoto) consente anche il tracciamento — in tal caso, tutte le singole impostazioni vengono risolte dalle rispettive variabili ambientali.

L'oggetto tracingOptions accetta le seguenti proprietà:

Option Variabile di ambiente Default Description
experimental AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING false Riconosciamo la natura sperimentale di questa caratteristica (necessaria per emettere le campate)
contentRecording OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT false Cattura contenuti di prompt e completamento nelle tracce
traceContextPropagation AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION true Inietta le intestazioni contestuali dei trace W3C nelle richieste

Ogni opzione viene risolta utilizzando il seguente ordine di precedenza:

  1. Valore esplicito in tracingOptions (priorità più alta)
  2. Variabile di ambiente (selezionata quando l'opzione viene omessa/non definita)
  3. Valore predefinito (usato quando nessuno dei due è impostato o la variabile di ambiente non può essere letta)

Nota: Poiché tutte le caratteristiche di tracciamento sono attualmente sperimentali, experimental: true devono essere impostate (esplicitamente o tramite la variabile ambientale) per eventuali intervalli da emettere.

Tracciamento degli agenti vocali

Registra un provider e un esportatore OpenTelemetry, quindi imposta tracingOptions: { experimental: true } su AIProjectClient. Questo traccia la generazione degli agenti vocali, le modifiche telefoniche, la cancellazione delle conversazioni e le sessioni e risposte in tempo reale. Non è necessario un flag di tracciamento separato per Voice Agent.

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.voiceAgents.realtime.connect("<voice agent name>");
try {
  await connection.sendText("Hello.");
  for await (const event of connection) {
    if (event.type === "error") {
      throw new Error(event.error.message);
    }
    if (event.type === "response.done") {
      if (event.response.status !== "completed") {
        throw new Error(`Voice response ${event.response.status}.`);
      }
      break;
    }
  }
} finally {
  await connection.close();
}

Registra in tempo reale un'intervalla di sessione, una durata di connessione e una invoke_agent portata per risposta, non per blocco audio. Questi includono status, utilizzo dei token e conteggio di byte audio. La latenza del primo audio viene misurata dalla creazione della risposta alla ricezione, non dal linguaggio dell'utente o dalla riproduzione degli altoparlanti. Gli ID di servizio appaiono nelle tracce, non nelle dimensioni metriche.

REST e project.voiceAgents.realtime condividi le impostazioni di tracciamento del progetto. Un costruito VoiceAgentRealtimeClient separatamente non li eredita. I riassunti degli input descrivono gli input più recenti, non l'intera cronologia della conversazione.

La registrazione dei contenuti è disattivata di default. Abilita contentRecording: true solo se intendi registrare testo, trascrizioni e strumenti, argomentazioni/risultati, che possono contenere dati sensibili. I supporti grezzi, le credenziali, i valori delle query, i numeri di telefono, SDP e i messaggi grezzi di errore/chiusura non vengono registrati. Le operazioni di lettura/lista utilizzano il tracciamento HTTP della pipeline esistente.

Vedi campione di tracciamento in tempo reale e campione di tracciamento REST.

Monitoraggio di Azure tracing

Ecco un esempio di codice che mostra come abilitare il tracciamento Monitoraggio di 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,
  },
});

Potresti anche voler creare una campata per il tuo scenario:

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, async () => {
  // Your agent operations here
});
span.end();

Vedi il codice campione completo in agentBasicWithAzureMonitorTracing.ts.

Tracciamento delle console

Per lo sviluppo locale, puoi stampare tracce sulla console:

import {
  NodeTracerProvider,
  SimpleSpanProcessor,
  ConsoleSpanExporter,
} from "@opentelemetry/sdk-trace-node";
import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

// Set up OpenTelemetry with a console exporter (must be done before creating the client)
const provider = new NodeTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
});
provider.register();
// Create client with tracing enabled (experimental)
const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential(), {
  tracingOptions: {
    experimental: true,
    contentRecording: false,
    traceContextPropagation: true,
  },
});

Vedi il codice campione completo in agentBasicWithConsoleTracing.ts.

Abilitazione della registrazione dei contenuti

La registrazione dei contenuti controlla se i contenuti dei messaggi e i dettagli delle chiamate allo strumento (come parametri e valori di ritorno) vengano catturati nelle tracce. Questi dati possono includere informazioni sensibili degli utenti.

Per abilitare la registrazione dei contenuti, passare contentRecording: true in tracingOptions quando si costruisce il client, oppure impostare la variabile OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT di ambiente su true. La registrazione dei contenuti è predefinita su false.

Abilitazione della propagazione del contesto delle tracce

La propagazione del contesto delle tracce consente di correlare span lato client con span lato server di Azure, OpenAI e altri servizi Azure. Quando abilitato, l'SDK inietta automaticamente le intestazioni W3C Trace Context (traceparent e tracestate) nelle richieste HTTP effettuate dai client OpenAI ottenute tramite project.getOpenAIClient().

Questo garantisce che tutte le operazioni all'interno di una traccia distribuita condividano lo stesso ID di traccia, fornendo visibilità end-to-end della tua applicazione e dei servizi Azure nel backend di osservabilità.

La propagazione del contesto delle tracce è abilitata di default. Per disabilitarla, passa traceContextPropagation: false nel tracingOptions momento della costruzione del client, oppure imposta la variabile AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION ambiente su false.

Considerazioni importanti sulla sicurezza e sulla privacy:

  • ID di traccia: Quando la propagazione del contesto di traccia è abilitata, gli ID di traccia vengono inviati ad Azure OpenAI e ad altri servizi esterni.
  • Correlazione delle richieste: Gli ID di tracciamento consentono ai servizi Azure di correlare le richieste provenienti dalla stessa sessione o utente attraverso più chiamate API, il che può avere implicazioni sulla privacy a seconda del tuo caso d'uso.

Abilita la propagazione del contesto delle tracce solo dopo aver esaminato attentamente i requisiti di osservabilità, privacy e sicurezza.

Risoluzione dei problemi

Eccezioni

I metodi client che effettuano chiamate al servizio generano un RestError per una risposta di codice di stato HTTP non riuscita dal servizio. Il code dell'eccezione conterrà il codice di stato della risposta HTTP. L'error.message dell'eccezione contiene un messaggio dettagliato che può essere utile per diagnosticare il 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);
  }
}

Ad esempio, quando si specificano credenziali errate:

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

La segnalazione dei problemi

Per segnalare problemi con la libreria client o richiedere funzionalità aggiuntive, si prega di aprire un GitHub issue qui

Passaggi successivi

Dai un'occhiata alla cartella package samples, che contiene codice completamente eseguibile.

Rigenerazione da TypeSpec (manutentori)

Questo pacchetto è rigenerato dalla specifica TypeSpec in Azure/azure-rest-api-specs. Le sei fasi di rigenerazione e il loro orchestratore assegnato a issue sono codificati come abilità sotto .github/skills/ e possono essere guidati end-to-end da un compito di GitHub Copilot coding-agent.

L'agente personalizzato a livello ai-projects-regen di repository è solo un punto di ingresso di discovery su GitHub. Il flusso di lavoro assegnato al problema è di proprietà della skill locale-packagerun-issue-regeneration.

Per iniziare il flusso di lavoro da un problema, includere esattamente un valore per ciascuna etichetta richiesta nella descrizione del problema:

TypeSpec commit: <40-character-lowercase-SHA>
Base branch: <branch>

Assegna il problema a Copilot, seleziona l'agente ai-projects-regen personalizzato e seleziona lo stesso ramo iniziale indicato nella descrizione. L'agente si ferma prima di apportare modifiche quando uno dei valori manca o è invalido.

Per inviare una rigenerazione come task cloud agent, esegui da questa directory:

pwsh -NoProfile -File ./scripts/start-cloud-regen.ps1                     # latest commit on feature/foundry-release
pwsh -NoProfile -File ./scripts/start-cloud-regen.ps1 -TspCommit <sha>    # pin a specific commit
pwsh -NoProfile -File ./scripts/start-cloud-regen.ps1 -DryRun             # render the prompt locally, do not dispatch
pwsh -NoProfile -File ./scripts/start-cloud-regen.ps1 -Repo myuser/azure-sdk-for-js -Follow   # smoke-test on a fork

A Windows, l'invocazione diretta dello script (ad esempio ./scripts/start-cloud-regen.ps1) può essere bloccata dalla politica di esecuzione predefinita Restricted. La pwsh -NoProfile -File ... forma sopra evita questo. In alternativa, esegui Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned una volta per permettere script locali.

Prerequisiti:

  • gh CLI installata e autenticata (gh auth login) sul repository target. Il agent-task sottocomando è in anteprima e richiede un file recente gh.
  • Appartenenza a un'organizzazione con l'agente di codifica GitHub Copilot abilitato per il repository target.
  • Pusha l'accesso al repository target (l'agente cloud usa la propria identità di GitHub App per spingere e aprire la bozza PR).

Avvertenza: il prompt inviato viene eseguito pnpm install --filter "@azure/ai-projects..." e pnpm turbo build --filter="@azure/ai-projects..." --token 1 in linea all'inizio del compito. Se il sandbox dell'agente cloud blocca quelle chiamate di rete, il compito fallirà all'installazione; in tal caso, esegui le competenze localmente, oppure coordina con il team di build SDK per aggiungere un flusso di lavoro gestito copilot-setup-steps.yml centralmente alla radice del repository.

contributi

Questo progetto accoglie contributi e suggerimenti. La maggior parte dei contributi richiede l'accettazione di un Contratto di licenza collaboratore (CLA) che dichiara di avere il diritto e, in realtà, concedere a Microsoft i diritti per l'uso del contributo. Per informazioni dettagliate, visitare https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determinerà automaticamente se è necessario fornire un cla e decorare la richiesta pull in modo appropriato (ad esempio, etichetta, commento). Seguire semplicemente le istruzioni fornite dal bot. Dovrai eseguire questa operazione una sola volta in tutti i repository usando la nostra cla.

Questo progetto ha adottato il Microsoft Open Source Code of Conduct. Per altre informazioni, vedere domande frequenti sul codice di condotta o contattare opencode@microsoft.com con eventuali domande o commenti aggiuntivi.