Tutorial: Constrói uma aplicação web agente no Serviço de Aplicações do Azure com LangGraph ou Foundry Agent Service (Node.js)

Este tutorial demonstra como adicionar capacidade de agente a um aplicativo CRUD Express.js orientado por dados existente. Faz isto usando duas abordagens diferentes: LangGraph e Foundry Agent Service.

Se a sua aplicação web já tem funcionalidades úteis, como compras, reservas de hotel ou gestão de dados, é relativamente simples adicionar funcionalidades de agente à sua aplicação web, envolvendo essas funcionalidades num plugin (para LangGraph) ou como endpoint OpenAPI (para Foundry Agent Service). Neste tutorial, começas com uma aplicação de lista simples to-do. No final, você poderá criar, atualizar e gerenciar tarefas com um agente em um aplicativo do Serviço de Aplicativo.

Tanto o LangGraph como o Foundry Agent Service permitem-lhe construir aplicações web agentes com capacidades baseadas em IA. LangGraph é semelhante ao Microsoft Kernel Semântico e é um SDK, mas Kernel Semântico não suporta JavaScript atualmente. A tabela a seguir mostra algumas das considerações e compensações:

Consideration LangGraph Serviço de Agente de Fundição
Performance Rápido (funciona localmente) Mais lento (gerenciado, serviço remoto)
Development Código completo, controlo máximo Baixo código, integração rápida
Testing Testes manuais/unitários em código Playground integrado para testes rápidos
Scalability App-managed Gerenciado pelo Azure, dimensionado automaticamente
Guarda-corpos de segurança Implementação personalizada necessária Segurança e moderação de conteúdos incorporadas
Identidade Implementação personalizada necessária ID de agente incorporado e autenticação
Enterprise Integração personalizada necessária Implementação integrada do Microsoft 365/Teams e chamadas de ferramentas integradas no Microsoft 365.

Na aplicação implementada, a autenticação do App Service requer o login Microsoft Entra tanto para a interface do navegador como para as APIs. O LangGraph corre dentro do App Service e chama diretamente o serviço de tarefas. O Foundry Agent Service corre remotamente e chama a API de tarefas protegidas através da sua ferramenta OpenAPI.

Neste tutorial, aprenderás como:

  • Converta a funcionalidade existente do aplicativo em um plug-in para o LangGraph.
  • Adicione o plug-in a um agente LangGraph e use-o em um aplicativo Web.
  • Converter funcionalidades existentes da aplicação num endpoint OpenAPI para o Foundry Agent Service.
  • Ligue para um agente da Foundry numa aplicação web.
  • Atribua as permissões necessárias para conectividade de identidade gerenciada.
  • Proteja uma aplicação web de Serviços de Aplicações e as suas APIs com o Microsoft Entra ID.
  • Configure uma ferramenta OpenAPI da Foundry para chamar APIs de Serviços de Aplicações protegidas com identidade gerida.

Prerequisites

Abra o exemplo com Codespaces

A maneira mais fácil de começar é usando o GitHub Codespaces, que fornece um ambiente de desenvolvimento completo com todas as ferramentas necessárias pré-instaladas.

  1. Navegue até o repositório GitHub em https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-node.

  2. Selecione o botão Código , selecione a guia Espaços de código e selecione Criar espaço de código na principal.

  3. Aguarde alguns instantes até que o Codespace seja inicializado. Quando estiver pronto, você verá um ambiente de desenvolvimento totalmente configurado em seu navegador.

  4. Execute o aplicativo localmente:

    npm install
npm run build
npm start

  5. Quando vir que a sua aplicação em execução na porta 3000 está disponível, selecione Abrir no Browser e adicione algumas tarefas.

    Os agentes não estão totalmente configurados, por isso ainda não funcionam. Você os configurará mais tarde.

Revise o código do agente

Ambas as abordagens usam o mesmo padrão de implementação, onde o agente é inicializado no início do aplicativo e responde às mensagens do usuário por solicitações POST.

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

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

A amostra implementada é protegida por autenticação de App Service e utiliza um único thread LangGraph selecionado pelo servidor. Quando processa mensagens de utilizador, o agente invoca invoke() a mensagem do utilizador e o ID do thread gerido pelo servidor:

private readonly conversationThreadId = 'authenticated-conversation';

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

Implementar o exemplo de aplicação

O repositório de exemplo contém um modelo Azure Developer CLI (AZD), que cria uma aplicação de Serviços de Aplicação e implementa a sua aplicação de exemplo. O modelo permite uma identidade gerida atribuída pelo sistema para chamadas de IA Azure de saída e configura a autenticação dos Serviços de Aplicação com o Microsoft Entra ID. Para mais informações sobre a configuração de autenticação subjacente, consulte Endpoints OpenAPI Seguros para o Serviço de Agente Foundry.

  1. No terminal, inicia sessão no Azure usando o Azure Developer CLI:

    azd auth login

    Siga as instruções para concluir o processo de autenticação.

  2. Implemente a aplicação Serviço de Aplicações do Azure usando o modelo AZD:

    azd up

  3. Quando solicitado, forneça as seguintes respostas:

    Question Answer
    Insira um novo nome de ambiente: Escreva um nome exclusivo.
    Selecione uma Assinatura do Azure para usar: Selecione uma subscrição.
    Escolha um grupo de recursos para usar: Selecione Criar um novo grupo de recursos.
    Selecione um local para criar o grupo de recursos em: Selecione Suécia Central.
    Insira um nome para o novo grupo de recursos: Digite Enter.

  4. Na saída AZD, localize o URL do seu aplicativo. Copie também o valor da audiência da identidade gerida do Foundry OpenAPI para utilizar mais tarde. O resultado tem o seguinte aspeto:

     Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: <URL>

 Foundry OpenAPI managed identity audience:
 api://<generated-client-id>

  5. Abra o endpoint do App Service a partir da saída do AZD.

  6. Quando a Microsoft te pedir, inicia sessão usando uma conta no tenant de implementação e verifica se a lista de tarefas está carregada.

  7. No mesmo navegador autenticado, abra o esquema OpenAPI gerado automaticamente em https://<app-name>.azurewebsites.net/api/schema.

  8. Copie ou guarde o esquema OpenAPI gerado. Utiliza-o no pivot do Serviço de Agentes de Fundição.

    Note

    A autenticação do App Service devolve um redirecionamento HTTP 302 para pedidos de navegador não autenticados. Este exemplo contém tanto uma interface de navegador como APIs, pelo que o redirecionamento proporciona uma experiência de login utilizável. As aplicações só de API normalmente usam antes o HTTP 401.

    Agora tem uma aplicação App Service autenticada. A sua identidade gerida atribuída pelo sistema é utilizada para chamadas de saída para a Foundry. Uma identidade gerida separada atribuída pelo utilizador fornece credenciais sem segredo para a autenticação de Serviços de Aplicações.

Crie e configure o recurso Microsoft Foundry

  1. No portal da Foundry, cria 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. Na página inicial, copie o endpoint Azure OpenAI para mais tarde.

Atribuir permissões necessárias

  1. No portal do Foundry, selecione Gerir no menu superior.

  2. Em Detalhes do projeto, selecione o Recurso principal para o seu projeto e, em seguida, selecione Abrir no portal do Azure.

    A partir do portal Azure, pode atribuir acesso baseado em funções para o recurso.

  3. Adicione a seguinte função à identidade gerida da aplicação do App Service e ao utilizador que utiliza com az login:

    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.

Configurar variáveis de conexão em seu aplicativo de exemplo

  1. Abra .env. Usando os valores que copiou anteriormente do portal Foundry, configure as seguintes variáveis:

    Variable Description
    AZURE_OPENAI_ENDPOINT Azure OpenAI endpoint (copiado da página inicial do portal Foundry).
    AZURE_OPENAI_DEPLOYMENT_NAME Nome do modelo na implementação (copiado da área de testes do modelo no novo portal da Foundry).

    Note

    Para manter o tutorial simples, você usará essas variáveis em .env em vez de substituí-las pelas configurações do aplicativo no Serviço de Aplicativo.

    Note

    Para manter o tutorial simples, você usará essas variáveis em .env em vez de substituí-las pelas configurações do aplicativo no Serviço de Aplicativo.

    Os valores em .env configuram a ligação de saída da aplicação para o Foundry. AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID configura a ligação OpenAPI de entrada separada entre o Foundry e o App Service e é armazenada no ambiente AZD.

A autenticação de Serviços de Aplicações corre no Azure, não no processo local Express, pelo que o fluxo de trabalho local de testes mantém-se inalterado.

  1. Entre no Azure com a CLI do Azure:

    az login

    Isso permite que a biblioteca de cliente do Azure Identity no código de exemplo receba um token de autenticação para o usuário conectado. Lembre-se de que você adicionou a função necessária para esse usuário anteriormente.

  2. Execute o aplicativo localmente:

    npm run build
npm start

  3. Quando você vir Seu aplicativo em execução na porta 3000 está disponível, selecione Abrir no navegador.

  4. Valide ambos os pivôs separadamente:

    • LangGraph:Selecione LangGraph Agent e peça ao agente para criar uma tarefa. O LangGraph chama a ferramenta de tarefas em processo.
    • Serviço Foundry Agent: Selecione Foundry Agent e peça ao agente para criar uma tarefa. O agente Foundry remoto invoca o endpoint /api/tasks implementado e protegido, utilizando a identidade gerida.

    A tarefa que o agente Foundry cria aparece na instância do Serviço de Aplicação implementado, e não na base de dados local em memória. A ferramenta Foundry OpenAPI utiliza sempre a URL do servidor embutida no esquema OpenAPI.

  5. De volta ao espaço de código do GitHub, implante as alterações do seu aplicativo.

    azd up

  6. Navegue até à aplicação implementada, inicie sessão e teste ambos os pivôs. Crie e liste tarefas com o Agente LangGraph, e depois crie e liste tarefas com o Agente Foundry. Verifica se ambos os pivôs atualizam a lista de tarefas.

Perguntas mais frequentes

Como posso adicionar geração aumentada de recuperação (RAG) ao agente da Foundry?

Esta orientação aplica-se ao caminho Foundry Agent Service neste tutorial. Não altera as implementações do LangGraph, Kernel Semântico ou Microsoft Agent Framework mostradas no outro separador.

Crie ou selecione uma base de conhecimento Foundry IQ e depois ligue essa base ao agente do Serviço de Agentes da Foundry. A conexão é apresentada ao agente como uma ferramenta de conhecimento MCP gerida.

O código do App Service continua a invocar o mesmo agente pelo respetivo nome através do cliente Foundry existente e agent_reference. A aplicação web não precisa de uma integração direta com Pesquisa de IA do Azure nem de um cliente MCP próprio. Se a interface mostrar as fontes, processe as anotações de citação devolvidas pelo agente.

Que identidade gerida é que cada ligação utiliza?

Direção Identidade
O App Service chama a Foundry Identidade atribuída ao sistema do App Service
Chamadas de ferramenta da Foundry OpenAPI /api/tasks Identidade atribuída ao sistema de recursos da Fundição Pai

O endpoint do projeto seleciona o projeto e o agente. Não determina a identidade que a ferramenta OpenAPI alojada utiliza.

Limpeza de recursos

Quando terminar de usar o aplicativo, você poderá excluir os recursos do Serviço de Aplicativo para evitar incorrer em custos adicionais:

azd down --purge

Depois, apaga o recurso Foundry se o criaste separadamente.

Mais recursos

  • Last updated on