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

Wdrożona przykładowa aplikacja jest chroniona za pomocą uwierzytelniania usługi App Service i korzysta z jednego wątku LangGraph wybranego przez serwer. Podczas przetwarzania wiadomości użytkownika agent wywołuje invoke(), przekazując wiadomość użytkownika oraz identyfikator wątku zarządzanego przez serwer:

private readonly conversationThreadId = 'authenticated-conversation';

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

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 jedną rozmowę zarządzaną serwerem dla przykładowego doświadczenia uwierzytelnionego przez 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;

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:

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. W portalu Foundry stwó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. Na stronie głównej skopiuj endpoint Azure OpenAI na później.

1. W portalu Foundry stwórz projekt.

2. Na stronie głównej skopiuj punkt końcowy projektu, aby użyć go później.

3. Wybierz Start building i postępuj zgodnie z poleceniem.

4. Wybierz Narzędzia>Dodaj>Dodaj narzędzia>Niestandardowe>>Utwórz. W okienku Konfiguracja dodaj akcję za pomocą narzędzia specyfikacji interfejsu OpenAPI.

5. Wklej schemat OpenAPI, który skopiowałeś z uwierzytelnionej aplikacji App Service.

6. W polu Metoda uwierzytelniania wybierz pozycję Tożsamość zarządzana.

7. Dla odbiorców wklej wartość zarządzanej tożsamości odbiorców Foundry OpenAPI z wyjścia AZD. Wygląda to następująco:

   api://<generated-client-id>
   

8. Zachowaj narzędzie i agenta.

Zezwól nadrzędnemu zasobowi Foundry na wywoływanie interfejsu API zadań

1. W portalu Foundry wybierz Zarządzaj w górnym menu.

2. W Szczegółach projektu wybierz zasób nadrzędny dla swojego projektu, a następnie wybierz Otwórz w witrynie Azure Portal.

3. Skopiuj identyfikator obiektu (głównego) przypisanej przez system tożsamości. Znajdź tę tożsamość w Microsoft Entra ID i skopiuj jej Application ID. Szczegółowe kroki można znaleźć w artykule Znajdź tożsamość zasobu nadrzędnego Foundry.

4. W terminalu Codespace zapisz identyfikator aplikacji w środowisku AZD i zaktualizuj konfigurację uwierzytelniania App Service:

   azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
   azd provision
   

1. W portalu Foundry wybierz Zarządzaj w górnym menu.

2. W Szczegóły projektu wybierz zasób nadrzędny dla projektu, a następnie wybierz Otwórz w portalu Azure.

   Z portalu Azure możesz przypisać dostęp do zasobów opartych na rolach.

3. Dodaj następującą rolę zarówno dla zarządzanej tożsamości aplikacji App Service, jak i dla użytkownika, którego używasz az login:

   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 portalu Foundry wybierz Zarządzaj w górnym menu.

2. W szczegółach Project wybierz Otwórz w Azure portal.

   Z portalu Azure możesz przypisać do projektu dostęp oparty na rolach.

3. Dodaj następującą rolę zarówno do zarządzanej tożsamości aplikacji usługi App Service, jak i do użytkownika, którego używasz z az login:

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

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