Руководство по созданию агентного веб-приложения в Службе приложений Azure с помощью LangGraph или Службы агента Foundry (Node.js)

LangGraphTaskAgent инициализируется в конструкторе в src/agents/LangGraphTaskAgent.ts. Код инициализации выполняет следующие действия:

• Настраивает клиент AzureChatOpenAI с помощью переменных среды.
• Создает предварительно созданный агент ReAct с набором средств CRUD для управления задачами (см. статью LangGraph: использование предварительно созданного агента ReAct).
• Настройка управления памятью (см. LangGraph: добавление памяти в предварительно созданный агент 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);
        }
    }

При обработке сообщений пользователей агент вызывается с помощью invoke() вместе с пользовательским сообщением и конфигурацией сеанса для обеспечения непрерывности беседы.

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

Компонент FoundryTaskAgent использует шаблон отложенной инициализации в src/agents/FoundryTaskAgent.ts. Код инициализации выполняет следующие действия:

• Создает AIProjectClient, используя учетные данные Azure.
• Возвращает клиент OpenAI от клиента проекта.
• Извлекает агент по имени.
• Создает новую беседу для сеанса.

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

Этот код инициализации не определяет какие-либо функциональные возможности агента, так как обычно создается агент на портале Foundry. В рамках примера сценария он также следует шаблону OpenAPI, показанному в разделе "Добавление приложения службы приложений в качестве инструмента" в Службе агента Foundry (Node.js), и делает его функциональные возможности CRUD доступными в качестве конечной точки OpenAPI. Это позволяет добавить его в агент позже в качестве вызываемой функции.

Код OpenAPI определяется в src/routes/api.ts. Например, маршрут 'GET /api/tasks' определяется operationId в комментариях JSDoc Swagger, как требуется инструменту спецификации OpenAPI в Microsoft Foundry, и помогает агенту определить, как вызывать 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' });
    }
});

При обработке сообщений пользователей агент вызывается путем добавления сообщения пользователя в беседу и вызова responses.create() со ссылкой на агент:

// 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. На портале Foundry убедитесь, что верхняя кнопка-переключатель New Foundry активирована, и создайте проект.

2. Разверните модель выбранного варианта (см. краткое руководство по Microsoft Foundry: создание ресурсов).

3. В верхней части игровой площадки модели скопируйте имя модели.

4. Самый простой способ получить конечную точку Azure OpenAI по-прежнему с классического портала. Нажмите переключатель New Foundry, затем выберите Azure OpenAI, а потом скопируйте URL-адрес в Azure OpenAI endpoint на будущее.

   

1. На портале Foundry убедитесь, что верхняя кнопка-переключатель New Foundry активирована, и создайте проект.

2. На домашней странице скопируйте конечную точку проекта для последующего использования.

3. Нажмите кнопку "Начать создание> и следуйте запросу.

4. На игровой площадке нового агента создайте средство OpenAPI для вызова вашего веб-приложения, выбрав Инструменты>Добавить>Пользовательское>Средство OpenAPI>Создать. В области установки добавьте действие с помощью средства спецификации OpenAPI. Используйте схему OpenAPI, полученную из развернутого веб-приложения и анонимной проверки подлинности. Подробные инструкции см. в разделе "Использование средства спецификации OpenAPI".

   Ваш код приложения уже настроен, чтобы включать url и operationId сервера, которые необходимы агенту. Дополнительные сведения см. в разделе "Подключение к спецификации OpenAPI".

5. Не забудьте нажать кнопку "Сохранить".

6. Выберите "Попробовать на игровой площадке" и протестируйте агент Foundry с помощью запросов, таких как "Показать мне все задачи" и "Добавьте задачу".

   Если вы получаете допустимый ответ, агент совершает вызовы инструментов к конечной точке OpenAPI в вашем развернутом веб-приложении.

1. В верхнем меню нового портала Foundry выберите "Работа", а затем выберите "Администратор". В строке проекта Foundry вы увидите две ссылки. Один из столбцов Name — ресурс проекта Foundry, а в столбце "Родительский ресурс" — ресурс Foundry.

   

2. Выберите ресурс Foundry в родительском ресурсе и выберите "Управление этим ресурсом" на портале Azure. На портале Azure можно назначить доступ на основе ролей для ресурса развернутого веб-приложения.

3. Добавьте следующую роль для управляемой идентификации приложения службы приложений.

   Целевой ресурс	Требуемая роль	Требуется для
   Литейный завод	Пользователь когнитивных сервисов OpenAI	Служба завершения чата в Microsoft Agent Framework.

   Инструкции см. в разделе Назначение ролей Azure с помощью портала Azure.

1. В верхнем меню нового портала Foundry выберите "Работа", а затем выберите "Администратор". В строке проекта Foundry вы увидите две ссылки. Один из столбцов Name — ресурс проекта Foundry, а в столбце "Родительский ресурс" — ресурс Foundry.

   

2. Выберите ресурс проекта Foundry в столбце "Имя" , а затем выберите "Управление этим ресурсом" на портале Azure. На портале Azure можно назначить доступ на основе ролей для ресурса развернутого веб-приложения.

3. Добавьте следующую роль для управляемой идентификации приложения службы приложений.

   Целевой ресурс	Требуемая роль	Требуется для
   Проект Foundry	Пользователь Foundry	Чтение и вызов агента Foundry.

   Инструкции см. в разделе Назначение ролей Azure с помощью портала Azure.