Tutorial: Constrói uma aplicação web agente no Azure App Service com LangGraph ou Foundry Agent Service (Node.js)

O LangGraphTaskAgent é inicializado no construtor em src/agents/LangGraphTaskAgent.ts. O código de inicialização faz o seguinte:

• Configura o cliente AzureChatOpenAI usando variáveis de ambiente.
• Cria o agente ReAct pré-construído com um conjunto de ferramentas CRUD para gerenciamento de tarefas (consulte LangGraph: Como usar o agente ReAct pré-construído).
• Configura o gerenciamento de memória (consulte LangGraph: Como adicionar memória ao agente ReAct pré-construído).

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

Ao processar mensagens do utilizador, o agente é invocado usando invoke() com a mensagem do utilizador e a configuração da sessão para a continuidade da conversa.

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

Usa FoundryTaskAgent um padrão de inicialização preguiçoso em src/agents/FoundryTaskAgent.ts. O código de inicialização faz o seguinte:

• Cria um AIProjectClient usando credenciais do Azure.
• Obtém um cliente OpenAI a partir do cliente do projeto.
• Recupera o agente pelo nome.
• Cria uma nova conversa para a sessão.

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

Este código de inicialização não define qualquer funcionalidade para o agente, porque normalmente construiria o agente no portal Foundry. Como parte do cenário de exemplo, também segue o padrão OpenAPI mostrado em Adicionar uma aplicação de App Service como ferramenta no Foundry Agent Service (Node.js), e disponibiliza a sua funcionalidade CRUD como um endpoint OpenAPI. Isso permite adicioná-lo ao agente mais tarde como uma ferramenta invocável.

O código OpenAPI é definido em src/routes/api.ts. Por exemplo, a rota "GET /api/tasks" define-se operationId nos comentários do JSDoc Swagger, conforme exigido pela ferramenta de especificação OpenAPI no Microsoft Foundry, e description ajuda o agente a determinar como invocar a 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' });
    }
});

Ao processar mensagens de utilizador, o agente é invocado adicionando a mensagem do utilizador à conversa e ligando responses.create() com a referência do agente:

// 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. No portal da Foundry, certifique-se de que o botão de radio superior da New Foundry está ativado e crie um projeto.

2. Implemente um modelo à sua escolha (veja Microsoft Foundry Quickstart: Criar recursos).

3. Do topo do parque de diversões de modelos, copie o nome do modelo.

4. A forma mais fácil de obter o endpoint Azure OpenAI continua a ser através do portal clássico. Selecione o botão de opção New Foundry, depois Azure OpenAI, e depois copie o URL no Azure OpenAI endpoint para mais tarde.

   

1. No portal da Foundry, certifique-se de que o botão de radio superior da New Foundry está ativado e crie um projeto.

2. Na página inicial, copie o endpoint do Projeto para usar mais tarde.

3. Selecione Começar a construir>Criar agente e siga o prompt.

4. Na área de teste do novo agente, crie uma ferramenta personalizada OpenAPI para chamar a sua aplicação web selecionando Ferramentas>Adicionar>ferramenta personalizada OpenAPI>>Criar. No painel Configuração , adicione uma ação com a ferramenta de especificação OpenAPI. Use o esquema OpenAPI que você obtém do aplicativo Web implantado e da autenticação anônima . Para obter etapas detalhadas, consulte Como usar a ferramenta de especificação OpenAPI.

   O código da aplicação já está configurado para incluir o url e o operationId do servidor, que são necessários para o agente. Para mais informações, consulte Ligar à Especificação OpenAPI.

5. Certifica-te de selecionar Guardar.

6. Selecione Experimentar no playground e teste o seu agente Foundry com prompts como "Mostra-me todas as tarefas" e "Por favor, adiciona uma tarefa."

   Se receber uma resposta válida, o agente está a fazer solicitações para o endpoint OpenAPI na sua aplicação web implantada.

1. No menu superior do novo portal da Foundry, selecione Operar, depois selecione Administrador. Na fila do seu projeto Foundry, deve ver dois links. O elemento na coluna Nome é o recurso do projeto Foundry, e o elemento na coluna Recurso Pai é o recurso Foundry.

   

2. Selecione o recurso Foundry no recurso Pai e depois selecione Gerir este recurso no portal Azure. A partir do portal Azure, pode atribuir acesso baseado em funções para o recurso à aplicação web implementada.

3. Adicione o seguinte papel para a identidade gerida da aplicação App Service:

   Recurso de destino	Função obrigatória	Necessário para
   Fundição	Utilizador dos Serviços Cognitivos OpenAI	O serviço de conclusão de chat no Microsoft Agent Framework.

   Para obter instruções, consulte Atribuir funções do Azure utilizando o portal do Azure.

1. No menu superior do novo portal da Foundry, selecione Operar, depois selecione Administrador. Na fila do seu projeto Foundry, deve ver dois links. O elemento na coluna Nome é o recurso do projeto Foundry, e o elemento na coluna Recurso Pai é o recurso Foundry.

   

2. Selecione o recurso do projeto Foundry na coluna Nome e depois selecione Gerir este recurso no portal Azure. A partir do portal Azure, pode atribuir acesso baseado em funções para o recurso à aplicação web implementada.

3. Adicione o seguinte papel para a identidade gerida da aplicação App Service:

   Recurso de destino	Função obrigatória	Necessário para
   Projeto Foundry	Utilizador do Azure AI	A ler e a ligar para o agente da Foundry.

   Para obter instruções, consulte Atribuir funções do Azure utilizando o portal do Azure.