Esercitazione: Creare un'app Web agentic nel servizio app di Azure con LangGraph o il servizio agente Foundry (Node.js)

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

Il campione distribuito è protetto dall'autenticazione App Service e utilizza un thread LangGraph selezionato dal server. Quando elabori i messaggi dell'utente, l'agente invoca invoke() il messaggio dell'utente e l'ID thread gestito dal server:

private readonly conversationThreadId = 'authenticated-conversation';

const result = await this.agent.invoke(
    {
        messages: [
            { role: 'user', content: message }
        ]
    },
    {
        configurable: {
            thread_id: this.conversationThreadId
        }
    }
);

FoundryTaskAgent usa un modello di inizializzazione differita in src/agents/FoundryTaskAgent.ts. Il codice di inizializzazione esegue le operazioni seguenti:

• Crea un oggetto AIProjectClient usando le credenziali di Azure.
• Ottiene un client OpenAI dal client del progetto.
• Recupera l'agente per nome.
• Crea una conversazione gestita dal server per l'esperienza di esempio autenticata da App Service.

// Create the AI Project client
this.project = new AIProjectClient(endpoint, new DefaultAzureCredential());
this.openAIClient = await this.project.getOpenAIClient();
this.agentName = agentName;

// App Service authentication protects this app, so this sample intentionally
// keeps one server-managed authenticated conversation for the Foundry path.
const conversation = await this.openAIClient.conversations.create({
    items: [],
});
this.conversationId = conversation.id;

Questo codice di inizializzazione non definisce alcuna funzionalità per l'agente, perché in genere si compila l'agente nel portale foundry. Come parte dello scenario di esempio, segue anche il modello OpenAPI illustrato in Aggiungere un'app del servizio app come strumento nel servizio agente Foundry (Node.js), e rende disponibile la funzionalità CRUD come endpoint OpenAPI. In questo modo è possibile aggiungerlo all'agente in un secondo momento come strumento chiamabile.

Il codice OpenAPI è definito in src/routes/api.ts. Ad esempio, la route "GET /api/tasks" definisce operationId nei commenti JSDoc Swagger, come richiesto dallo strumento della specifica OpenAPI in Microsoft Foundry e description aiuta l'agente a determinare come chiamare l'API:

/**
 * @swagger
 * /api/tasks:
 *   get:
 *     summary: Get all tasks
 *     operationId: getAllTasks
 *     responses:
 *       200:
 *         description: List of tasks
 */
router.get('/tasks', async (req: Request, res: Response) => {
    try {
        const tasks = await taskService.getAllTasks();
        res.json(tasks);
    } catch (error) {
        console.error('Error getting tasks:', error);
        res.status(500).json({ error: 'Failed to get tasks' });
    }
});

Durante l'elaborazione dei messaggi utente, l'agente viene richiamato aggiungendo il messaggio dell'utente alla conversazione e chiamando responses.create() con il riferimento all'agente:

try {
    // Add the user message to the conversation
    await this.openAIClient.conversations.items.create(this.conversationId, {
        items: [{ type: 'message', role: 'user', content: message }],
    });

    // Generate response using the agent
    const response = await this.openAIClient.responses.create(
        {
            conversation: this.conversationId,
        },
        {
            body: { agent: { name: this.agentName, type: 'agent_reference' } },
        }

1. Nel portale Foundry, crea un progetto.

2. Distribuire un modello preferito (vedere Avvio rapido di Microsoft Foundry: Creare risorse).

3. Nella parte superiore del playground del modello copiare il nome del modello.

4. Nella pagina iniziale, copia l'endpoint di Azure OpenAI per usarlo in seguito.

1. Nel portale Foundry, crea un progetto.

2. Nella pagina iniziale, copia l'endpoint del progetto per usarlo in seguito.

3. Seleziona Inizia a costruire e segui il prompt.

4. Seleziona strumenti Aggiungi>>strumenti>Strumento OpenAPI personalizzato>>Crea. Nel riquadro Installazione aggiungere un'azione con lo strumento specifica OpenAPI.

5. Incolla lo schema OpenAPI che hai copiato dall'app App Service autenticata.

6. Per Metodo di autenticazione selezionare Identità gestita.

7. Per Audience, incolla il valore dell'audience dell'identità gestita di Foundry OpenAPI presente nell'output di AZD. Assomiglia a:

   api://<generated-client-id>
   

8. Salva lo strumento e l'agente.

Consentire alla risorsa Foundry madre di chiamare l'API del compito

1. Nel portale Foundry, seleziona Gestisci nel menu superiore.

2. In Project details, seleziona la risorsa Genitore per il tuo project, poi seleziona Apri in Azure portal.

3. Copia l'ID dell'oggetto (principale) dell'identità assegnata dal sistema. Individua quell'identità in Microsoft Entra ID e copia il relativo ID dell'applicazione. Per i passaggi dettagliati, vedi Trova l'identità della risorsa Foundry principale.

4. Nel terminale Codespace, memorizza l'ID dell'applicazione nell'ambiente AZD e aggiorna la configurazione di autenticazione del servizio App:

   azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
   azd provision
   

1. Nel portale Foundry, seleziona Gestisci nel menu superiore.

2. In Project details, seleziona la risorsa Genitore per il tuo project, poi seleziona Apri in Azure portal.

   Dal portale Azure puoi assegnare l'accesso basato sul ruolo per la risorsa.

3. Aggiungi il seguente ruolo sia per l'identità gestita dell'app di App Service sia per l'utente che usi con az login:

   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.

1. Nel portale Foundry, seleziona Gestisci nel menu superiore.

2. In Project details, seleziona Apri nel portale Azure.

   Dal portale Azure puoi assegnare l'accesso basato sui ruoli per il progetto.

3. Aggiungi il seguente ruolo sia per l'identità gestita dell'app di App Service sia per l'utente che usi con az login:

   Risorsa di destinazione	Ruolo obbligatorio	Necessario per
   Progetto Foundry	Utente Foundry	Lettura e chiamata dell'agente Foundry.

   Per istruzioni, vedere Assegnare ruoli di Azure usando il portale di Azure.