Zelfstudie: Een agentische web-app bouwen in Azure App Service met LangGraph of Foundry Agent Service (Node.js)

De LangGraphTaskAgent wordt geïnitialiseerd in de constructor in src/agents/LangGraphTaskAgent.ts. De initialisatiecode doet het volgende:

• Hiermee configureert u de AzureChatOpenAI-client met behulp van omgevingsvariabelen.
• Hiermee maakt u de vooraf gemaakte ReAct-agent met een set CRUD-hulpprogramma's voor taakbeheer (zie LangGraph: De vooraf gemaakte ReAct-agent gebruiken).
• Hiermee stelt u geheugenbeheer in (zie LangGraph: Geheugen toevoegen aan de vooraf gemaakte ReAct-agent).

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

De geïmplementeerde sample is beschermd door App Service-authenticatie en gebruikt één door de server geselecteerde LangGraph-thread. Wanneer je gebruikersberichten verwerkt, roept de agent invoke() aan met het bericht van de gebruiker en de door de server beheerde thread-ID:

private readonly conversationThreadId = 'authenticated-conversation';

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

Het FoundryTaskAgent maakt gebruik van een luie initialisatiepatroon in src/agents/FoundryTaskAgent.ts. De initialisatiecode doet het volgende:

• Hiermee maakt u een AIProjectClient met behulp van Azure-referenties.
• Hiermee haal je een OpenAI-client op van de projectclient.
• Haalt de agent op naam op.
• Creëert één door de server beheerde conversatie voor de met App Service geauthenticeerde voorbeeldfunctionaliteit.

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

Deze initialisatiecode definieert geen functionaliteit voor de agent, omdat u doorgaans de agent zou bouwen in de Foundry-portal. Als onderdeel van het voorbeeldscenario volgt dit ook het OpenAPI-patroon dat wordt weergegeven in Een App Service-app toevoegen als een hulpprogramma in Foundry Agent Service (Node.js), en maakt de CRUD-functionaliteit beschikbaar als een OpenAPI-eindpunt. Hiermee kunt u deze later als aanroepbaar hulpprogramma toevoegen aan de agent.

De OpenAPI-code wordt gedefinieerd in src/routes/api.ts. De route 'GET /api/tasks' definieert operationId bijvoorbeeld in de JSDoc Swagger-opmerkingen, zoals vereist door het hulpprogramma OpenAPI-specificatie in Microsoft Foundry, en description helpt de agent te bepalen hoe de API moet worden aangeroepen:

/**
 * @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' });
    }
});

Bij het verwerken van gebruikersberichten wordt de agent aangeroepen door het bericht van de gebruiker toe te voegen aan het gesprek en te bellen responses.create() met de agentreferentie:

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. Maak in het Foundry-portaal een project.

2. Een model van uw keuze implementeren (zie Snelstartgids voor Microsoft Foundry: Resources maken).

3. Kopieer de naam van het model vanaf de bovenkant van de modelspeelplaats.

4. Kopieer op de startpagina het Azure OpenAI-eindpunt voor later.

1. Maak in het Foundry-portaal een project.

2. Kopieer op de startpagina het Project-eindpunt voor later gebruik.

3. Selecteer Start bouwen en volg de prompt.

4. Selecteer Tools>Toevoegen>Hulpmiddelen>Aangepaste>OpenAPI-tool>Aanmaken. Voeg in het deelvenster Setup een actie toe met het hulpprogramma OpenAPI-specificatie.

5. Plak het OpenAPI-schema dat je hebt gekopieerd uit de geauthenticeerde App Service-app.

6. Selecteer beheerde identiteit voor verificatiemethode.

7. Voor Audience plak je de Foundry OpenAPI managed identity audience waarde uit de AZD-uitvoer. Het lijkt op:

   api://<generated-client-id>
   

8. Bewaar het gereedschap en de agent.

Laat de ouder Foundry-resource de taak-API aanroepen

1. Selecteer in het Foundry-portaal Beheren in het bovenste menu.

2. Selecteer in Project details de Ouderresource van je project en selecteer vervolgens Open in Azure portal.

3. Kopieer de Object-id (principal-id) van de door het systeem toegewezen beheerde identiteit. Zoek die identiteit in de Microsoft Entra ID en kopieer de applicatie-ID. Voor gedetailleerde stappen, zie Find the parent Foundry resource identity.

4. Sla in de Codespace-terminal de applicatie-ID op in de AZD-omgeving en werk de App Service-authenticatieconfiguratie bij:

   azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
   azd provision
   

1. Selecteer in het Foundry-portaal Beheren in het bovenste menu.

2. Selecteer in Project details de Ouderresource van je project en selecteer vervolgens Open in Azure portal.

   Vanuit het Azure-portaal kun je rolgebaseerde toegang voor de resource toewijzen.

3. Voeg de volgende rol toe voor zowel de beheerde identiteit van de App Service-app als de gebruiker waarmee je werkt az login:

   Doelresource	Vereiste rol	Vereist voor
   Gieterij	Cognitive Services OpenAI-gebruiker	De voltooiingsservice voor chats in Microsoft Agent Framework.

   Zie Azure-rollen toewijzen via Azure Portal voor instructies.

1. Selecteer in het Foundry-portaal Beheren in het bovenste menu.

2. Selecteer in Project detailsOpen in Azure portal.

   Vanuit het Azure-portaal kun je rolgebaseerde toegang toewijzen voor het project.

3. Voeg de volgende rol toe voor zowel de beheerde identiteit van de App Service-app als de gebruiker waarmee je werkt az login:

   Doelresource	Vereiste rol	Vereist voor
   Foundryproject	Foundry-gebruiker	De Foundry-agent lezen en aanroepen.

   Zie Azure-rollen toewijzen via Azure Portal voor instructies.