Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Questa esercitazione illustra come aggiungere funzionalità agentiche a un'applicazione CRUD basata sui dati esistente Express.js. A tale scopo, si usano due approcci diversi: LangGraph e Foundry Agent Service.
Se l'applicazione Web ha già funzionalità utili, ad esempio acquisti, prenotazioni di hotel o gestione dei dati, è relativamente semplice aggiungere funzionalità dell'agente all'applicazione Web eseguendo il wrapping di tali funzionalità in un plug-in (per LangGraph) o come endpoint OpenAPI (per il servizio agente Foundry). In questo tutorial inizi con una semplice app lista di cose da fare. Al termine, sarai in grado di creare, aggiornare e gestire attività con un agente in un'app di Servizio App.
Sia LangGraph che il servizio agente Foundry consentono di creare applicazioni Web agentic con funzionalità basate su intelligenza artificiale. LangGraph è simile a Microsoft Semantic Kernel ed è un SDK, ma il kernel semantico attualmente non supporta JavaScript. La tabella seguente illustra alcune considerazioni e compromessi:
| Consideration | LangGraph | Servizio Agente Fonderia |
|---|---|---|
| Performance | Veloce (funziona localmente) | Più lento (gestito, servizio remoto) |
| Development | Codice completo, controllo massimo | Basso codice, integrazione rapida |
| Testing | Test manuali/unit test nel codice | Playground predefinito per i test rapidi |
| Scalability | Gestito dall'app | Gestito da Azure, con scalabilità automatica |
| Protezioni di sicurezza | Implementazione personalizzata richiesta | Sicurezza e moderazione dei contenuti predefiniti |
| Identità | Implementazione personalizzata richiesta | ID e autenticazione predefiniti dell'agente |
| Enterprise | Integrazione personalizzata richiesta | Distribuzione predefinita di Microsoft 365/Teams e chiamate agli strumenti integrati di Microsoft 365. |
In questa esercitazione si apprenderà come:
- Convertire le funzionalità dell'app esistenti in un plug-in per LangGraph.
- Aggiungere il plug-in a un agente LangGraph e usarlo in un'app Web.
- Convertire le funzionalità dell'app esistenti in un endpoint OpenAPI per il servizio agente Foundry.
- Chiamare un agente Foundry in un'applicazione web.
- Assegnare le autorizzazioni necessarie per la connettività dell'identità gestita.
Prerequisites
- Un account Azure con una sottoscrizione attiva: creare gratuitamente un account.
- Account GitHub per usare GitHub Codespaces - Scopri di più su GitHub Codespaces.
Aprire l'esempio con Codespaces
Il modo più semplice per iniziare consiste nell'usare GitHub Codespaces, che offre un ambiente di sviluppo completo con tutti gli strumenti necessari preinstallati.
Passare al repository GitHub all'indirizzo https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-node.
Selezionare il pulsante Codice , selezionare la scheda Codespaces e selezionare Crea spazio di codice nel main.
Attendere alcuni istanti per inizializzare Codespace. Quando si è pronti, nel browser verrà visualizzato un ambiente di sviluppo completamente configurato.
Eseguire l'applicazione in locale:
npm install npm run build npm startQuando viene visualizzato L'applicazione in esecuzione sulla porta 3000 è disponibile, selezionare Apri nel browser e aggiungere alcune attività.
Gli agenti non sono completamente configurati per cui non funzionano ancora. Verranno configurati in un secondo momento.
Esaminare il codice dell'agente
Entrambi gli approcci usano lo stesso modello di implementazione, in cui l'agente viene inizializzato all'avvio dell'applicazione e risponde ai messaggi utente da richieste POST.
LangGraphTaskAgent viene inizializzato nel costruttore in src/agents/LangGraphTaskAgent.ts. Il codice di inizializzazione esegue le operazioni seguenti:
- Configura il client AzureChatOpenAI usando le variabili di ambiente.
- Crea l'agente ReAct predefinito con un insieme di strumenti CRUD per la gestione delle attività (vedere LangGraph: Come usare l'agente ReAct predefinito).
- Configura la gestione della memoria (vedere LangGraph: Come aggiungere memoria all'agente ReAct predefinito).
constructor(taskService: TaskService) {
this.taskService = taskService;
this.memory = new MemorySaver();
try {
const endpoint = process.env.AZURE_OPENAI_ENDPOINT;
const deploymentName = process.env.AZURE_OPENAI_DEPLOYMENT_NAME;
if (!endpoint || !deploymentName) {
console.warn('Azure OpenAI configuration missing for LangGraph agent');
return;
}
// Initialize Azure OpenAI client
const credential = new DefaultAzureCredential();
const azureADTokenProvider = getBearerTokenProvider(credential, "https://cognitiveservices.azure.com/.default");
this.llm = new AzureChatOpenAI({
azureOpenAIEndpoint: endpoint,
azureOpenAIApiDeploymentName: deploymentName,
azureADTokenProvider: azureADTokenProvider,
azureOpenAIApiVersion: "2024-10-21"
});
// Define tools directly in the array
const tools = [
tool(
async ({ title, isComplete = false }) => {
const task = await this.taskService.addTask(title, isComplete);
return `Task created successfully: "${task.title}" (ID: ${task.id})`;
},
{
name: 'createTask',
description: 'Create a new task',
schema: z.object({
title: z.string(),
isComplete: z.boolean().optional()
}) as any
}
),
tool(
async () => {
const tasks = await this.taskService.getAllTasks();
if (tasks.length === 0) {
return 'No tasks found.';
}
return `Found ${tasks.length} tasks:\n` +
tasks.map(t => `- ${t.id}: ${t.title} (${t.isComplete ? 'Complete' : 'Incomplete'})`).join('\n');
},
{
name: 'getTasks',
description: 'Get all tasks',
schema: z.object({}) as any
}
),
tool(
async ({ id }) => {
const task = await this.taskService.getTaskById(id);
if (!task) {
return `Task with ID ${id} not found.`;
}
return `Task ${task.id}: "${task.title}" - Status: ${task.isComplete ? 'Complete' : 'Incomplete'}`;
},
{
name: 'getTask',
description: 'Get a specific task by ID',
schema: z.object({
id: z.number()
}) as any
}
),
tool(
async ({ id, title, isComplete }) => {
const updated = await this.taskService.updateTask(id, title, isComplete);
if (!updated) {
return `Task with ID ${id} not found.`;
}
return `Task ${id} updated successfully.`;
},
{
name: 'updateTask',
description: 'Update an existing task',
schema: z.object({
id: z.number(),
title: z.string().optional(),
isComplete: z.boolean().optional()
}) as any
}
),
tool(
async ({ id }) => {
const deleted = await this.taskService.deleteTask(id);
if (!deleted) {
return `Task with ID ${id} not found.`;
}
return `Task ${id} deleted successfully.`;
},
{
name: 'deleteTask',
description: 'Delete a task',
schema: z.object({
id: z.number()
}) as any
}
)
];
// Create the ReAct agent with memory
this.agent = createReactAgent({
llm: this.llm,
tools,
checkpointSaver: this.memory,
stateModifier: `You are an AI assistant that manages tasks using CRUD operations.
You have access to tools for creating, reading, updating, and deleting tasks.
Always use the appropriate tool for any task management request.
Be helpful and provide clear responses about the actions you take.
If you need more information to complete a request, ask the user for it.`
});
} catch (error) {
console.error('Error initializing LangGraph agent:', error);
}
}
Durante l'elaborazione dei messaggi utente, l'agente viene richiamato usando invoke() con la configurazione del messaggio e della sessione dell'utente per la continuità della conversazione:
const result = await this.agent.invoke(
{
messages: [
{ role: 'user', content: message }
]
},
{
configurable: {
thread_id: currentSessionId
}
}
);
Distribuire l'applicazione di esempio
Il repository di esempio contiene un modello per la CLI per sviluppatori Azure (AZD), che crea un'App Service app con identità gestita e distribuisce l'applicazione di esempio.
Nel terminale accedere ad Azure usando l'interfaccia della riga di comando per sviluppatori di Azure:
azd auth loginSeguire le istruzioni per completare il processo di autenticazione.
Distribuire l'app del servizio app di Azure con il modello AZD:
azd upQuando richiesto, fornire le risposte seguenti:
Question Answer Immettere un nuovo nome di ambiente: Digitare un nome univoco. Selezionare una sottoscrizione di Azure da usare: Selezionare la sottoscrizione. Selezionare un gruppo di risorse da usare: Selezionare Crea un nuovo gruppo di risorse. Selezionare un percorso in cui creare il gruppo di risorse: Selezionare Svezia centrale. Immettere un nome per il nuovo gruppo di risorse: Immettere Invio. Nell'output AZD, individua l'URL della tua app e accedi a esso tramite il browser. L'URL è simile al seguente nell'output AZD:
Deploying services (azd deploy) (✓) Done: Deploying service web - Endpoint: <URL>
Aprire lo schema OpenAPI generato automaticamente nel
https://....azurewebsites.net/api/schemapercorso. Questo schema sarà necessario in un secondo momento.Adesso hai un'app di App Service con un'identità gestita assegnata dal sistema.
Creare e configurare la risorsa Microsoft Foundry
Nel portale di Foundry verificare che il pulsante di opzione New Foundry in alto sia impostato su attivo e creare un progetto.
Distribuire un modello preferito (vedere Avvio rapido di Microsoft Foundry: Creare risorse).
Nella parte superiore del playground del modello copiare il nome del modello.
Il modo più semplice per ottenere l'endpoint OpenAI di Azure è ancora dal portale classico. Selezionare il pulsante di opzione New Foundry, quindi Azure OpenAI, e quindi copiare l'URL nell'Azure OpenAI endpoint per un secondo momento.
Assegnare le autorizzazioni necessarie
Nel menu in alto del nuovo portale Foundry, selezionare Opera, quindi Amministrazione. Nella riga del progetto Foundry, dovrebbero essere visualizzati due collegamenti. Quello nella colonna Nome è la risorsa del progetto Foundry e quella nella colonna Risorsa padre è la risorsa Foundry.
Selezionare la risorsa Foundry nella risorsa padre e quindi selezionare Gestisci questa risorsa nel portale di Azure. Dal portale di Azure è possibile assegnare l'accesso in base al ruolo per la risorsa all'app Web distribuita.
Aggiungi il ruolo seguente per l'identità gestita dell'app di App Service:
Risorsa di destinazione Ruolo obbligatorio Necessario per Fonderia Utente di Servizi Cognitivi OpenAI Servizio di completamento della chat in Microsoft Agent Framework. Per istruzioni, vedere Assegnare ruoli di Azure usando il portale di Azure.
Configurare le variabili di connessione nell'applicazione di esempio
Aprire il file con estensione env. Usando i valori copiati in precedenza dal portale foundry, configurare le variabili seguenti:
Variable Description AZURE_OPENAI_ENDPOINTEndpoint OpenAI di Azure (copiato dal portale di Foundry classico). AZURE_OPENAI_DEPLOYMENT_NAMENome del modello nella distribuzione (copiato dall'area di sperimentazione del modello nel nuovo portale Foundry). Note
Per semplificare l'esercitazione, queste variabili verranno usate in .env invece di sovrascriverle con le impostazioni dell'app nel servizio app.
Note
Per semplificare l'esercitazione, queste variabili verranno usate in .env invece di sovrascriverle con le impostazioni dell'app nel servizio app.
Accedere ad Azure con l'interfaccia della riga di comando di Azure:
az loginCiò consente alla libreria client di Identità di Azure nel codice di esempio di ricevere un token di autenticazione per l'utente connesso. Tenere presente che è stato aggiunto il ruolo necessario per questo utente in precedenza.
Eseguire l'applicazione in locale:
npm run build npm startQuando viene visualizzato L'applicazione in esecuzione sulla porta 3000 è disponibile, selezionare Apri nel browser.
Selezionare il collegamento LangGraph Agent e il collegamento Foundry Agent per provare l'interfaccia di chat. Se si riceve una risposta, l'applicazione si connette correttamente alla risorsa Microsoft Foundry.
Tornare nello spazio di codice GitHub, distribuire le modifiche dell'app.
azd upPassare di nuovo all'applicazione distribuita e testare gli agenti di chat.
Pulire le risorse
Al termine dell'applicazione, è possibile eliminare le risorse del servizio app per evitare di sostenere ulteriori costi:
azd down --purge
Poiché il modello AZD non include le risorse di Microsoft Foundry, è necessario eliminarle manualmente, se necessario.