Samouczek: Budowanie agentowej aplikacji internetowej w usłudze Azure App Service przy użyciu LangGraph lub Foundry Agent Service (Node.js)

Element LangGraphTaskAgent jest inicjowany w konstruktorze w pliku src/agents/LangGraphTaskAgent.ts. Kod inicjowania wykonuje następujące czynności:

• Konfiguruje klienta AzureChatOpenAI przy użyciu zmiennych środowiskowych.
• Tworzy wstępnie utworzonego agenta ReAct z zestawem narzędzi CRUD do zarządzania zadaniami (zobacz LangGraph: Jak używać wstępnie utworzonego agenta ReAct).
• Konfiguruje zarządzanie pamięcią (zobacz LangGraph: Jak dodać pamięć do wstępnie utworzonego agenta ReAct).

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

Podczas przetwarzania komunikatów użytkownika agent jest wywoływany przy użyciu invoke() komunikatu użytkownika i konfiguracji sesji na potrzeby ciągłości konwersacji:

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

Funkcja FoundryTaskAgent używa leniwego wzorca inicjowania w pliku src/agents/FoundryTaskAgent.ts. Kod inicjowania wykonuje następujące czynności:

• Tworzy AIProjectClient używając poświadczeń platformy Azure.
• Pobiera klienta OpenAI z klienta projektu.
• Pobiera agenta na podstawie nazwy.
• Tworzy nową konwersację dla sesji.

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

// Create a conversation for this session
const conversation = await this.openAIClient.conversations.create({
    items: [],
});
this.conversationId = conversation.id;

console.log(`Foundry agent initialized with name: ${this.agentName}, Conversation: ${this.conversationId}`);

Ten kod inicjowania nie definiuje żadnych funkcji agenta, ponieważ zwykle kompilujesz agenta w portalu Foundry. W ramach przykładowego scenariusza jest również zgodny ze wzorcem OpenAPI pokazanym w Dodawanie aplikacji usługi App Service jako narzędzia w usłudze agenta usługi Foundry (Node.js) i udostępnia funkcje CRUD jako punkt końcowy OpenAPI. Dzięki temu można dodać go do agenta później jako narzędzie do wywołania.

Kod OpenAPI jest zdefiniowany w pliku src/routes/api.ts. Na przykład trasa "GET /api/tasks" definiuje operationId się w komentarzach struktury Swagger JSDoc zgodnie z wymaganiami narzędzia specyfikacji OpenAPI w usłudze Microsoft Foundry i description pomaga agentowi określić sposób wywoływania interfejsu 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' });
    }
});

Podczas przetwarzania komunikatów użytkownika agent jest wywoływany przez dodanie komunikatu użytkownika do konwersacji i wywołanie responses.create() z odwołaniem agenta:

// 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. W portalu Foundry upewnij się, że górny przycisk radiowy New Foundry jest ustawiony na aktywny i utwórz projekt.

2. Wdróż wybrany model (zobacz Przewodnik Szybki start firmy Microsoft Foundry: tworzenie zasobów).

3. W górnej części placu zabaw modelu skopiuj nazwę modelu.

4. Najprostszym sposobem na uzyskanie punktu końcowego Azure OpenAI nadal jest korzystanie z portalu klasycznego. Wybierz przycisk radiowy New Foundry , a następnie pozycję Azure OpenAI, a następnie skopiuj adres URL w punkcie końcowym usługi Azure OpenAI na później.

   

1. W portalu Foundry upewnij się, że górny przycisk radiowy New Foundry jest ustawiony na aktywny i utwórz projekt.

2. Na stronie głównej skopiuj punkt końcowy projektu do późniejszego użycia.

3. Wybierz pozycję Rozpocznij tworzenie>agenta i postępuj zgodnie z monitem.

4. Na platformie nowego agenta, utwórz narzędzie OpenAPI do wywoływania swojej aplikacji webowej, wybierając Narzędzia>Dodaj>niestandardowe>narzędzie OpenAPI>Utwórz. W okienku Konfiguracja dodaj akcję za pomocą narzędzia specyfikacji interfejsu OpenAPI. Użyj schematu OpenAPI pobranego z wdrożonej aplikacji internetowej i uwierzytelniania anonimowego . Aby uzyskać szczegółowe instrukcje, zobacz How to use the OpenAPI spec tool (Jak używać narzędzia specyfikacji Interfejsu OpenAPI).

   Kod aplikacji jest już skonfigurowany do uwzględnienia serwerów url i operationId, które są wymagane przez agenta. Aby uzyskać więcej informacji, zobacz Nawiązywanie połączenia ze specyfikacją interfejsu OpenAPI.

5. Pamiętaj, aby wybrać pozycję Zapisz.

6. Wybierz Wypróbuj w środowisku testowym i przetestuj agenta Foundry z poleceniami, takimi jak "Pokaż mi wszystkie zadania" i "Dodaj zadanie".

   Jeśli otrzymasz prawidłową odpowiedź, agent wykonuje wywołania narzędzi do punktu końcowego interfejsu OpenAPI w wdrożonej aplikacji internetowej.

1. W górnym menu nowego portalu Foundry wybierz pozycję Obsługa, a następnie wybierz pozycję Administrator. W wierszu projektu Foundry powinny zostać wyświetlone dwa linki. Element w kolumnie Name to zasób projektu Foundry, a element w kolumnie Zasób nadrzędny to zasób Foundry.

   

2. Wybierz zasób Foundry w zasobie nadrzędnym , a następnie wybierz pozycję Zarządzaj tym zasobem w witrynie Azure Portal. W witrynie Azure Portal możesz przypisać dostęp oparty na rolach dla zasobu do wdrożonej aplikacji internetowej.

3. Dodaj następującą rolę dla zarządzanej tożsamości aplikacji App Service:

   Zasób docelowy	Wymagana rola	Wymagane do
   Odlewnia	Użytkownik Usług Cognitive Services OpenAI	Usługa uzupełniania czatu w programie Microsoft Agent Framework.

   Aby uzyskać instrukcje, zobacz temat Przypisywanie ról platformy Azure za pomocą witryny Azure Portal.

1. W górnym menu nowego portalu Foundry wybierz pozycję Obsługa, a następnie wybierz pozycję Administrator. W wierszu projektu Foundry powinny zostać wyświetlone dwa linki. Element w kolumnie Name to zasób projektu Foundry, a element w kolumnie Zasób nadrzędny to zasób Foundry.

   

2. Wybierz zasób projektu Foundry w kolumnie Nazwa , a następnie wybierz pozycję Zarządzaj tym zasobem w witrynie Azure Portal. W witrynie Azure Portal możesz przypisać dostęp oparty na rolach dla zasobu do wdrożonej aplikacji internetowej.

3. Dodaj następującą rolę dla zarządzanej tożsamości aplikacji App Service:

   Zasób docelowy	Wymagana rola	Wymagane do
   Projekt odlewniczy	Użytkownik sztucznej inteligencji platformy Azure	Odczytywanie i wywoływanie agenta usługi Foundry.

   Aby uzyskać instrukcje, zobacz temat Przypisywanie ról platformy Azure za pomocą witryny Azure Portal.