Tutorial: Criar um aplicativo Web agente no Serviço de Aplicativo do Azure com o LangGraph ou o Serviço do Foundry Agent (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 predefinido com um conjunto de ferramentas CRUD para gerenciamento de tarefas (consulte LangGraph: Como usar o agente ReAct predefinido).
• Configura o gerenciamento de memória (consulte LangGraph: Como adicionar memória ao agente ReAct predefinido).

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

O exemplo implantado é protegido por autenticação de App Service e utiliza um único thread LangGraph selecionado pelo servidor. Quando você processa mensagens de usuário, o agente invoca invoke() a mensagem do usuário e o ID da thread gerenciada pelo servidor:

private readonly conversationThreadId = 'authenticated-conversation';

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

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

• Cria um AIProjectClient com credenciais do Azure.
• Obtém um cliente OpenAI do cliente do projeto.
• Recupera o agente pelo nome.
• Cria uma conversa gerenciada pelo servidor para a experiência de amostra autenticada por 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;

Esse código de inicialização não define nenhuma funcionalidade para o agente, pois você normalmente compilaria o agente no portal do Foundry. Como parte do cenário de exemplo, ele também segue o padrão OpenAPI mostrado em Adicionar um aplicativo do Serviço de Aplicativo como uma ferramenta no Serviço do Foundry Agent (Node.js) e disponibiliza sua funcionalidade CRUD como um endpoint OpenAPI. Isso permite adicioná-lo ao agente posteriormente como uma ferramenta invocável.

O código OpenAPI é definido em src/routes/api.ts. Por exemplo, a rota "GET /api/tasks" define operationId dentro dos comentários JSDoc Swagger, conforme exigido pela ferramenta de especificação OpenAPI no Microsoft Foundry, e description ajuda o agente a determinar como chamar 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 usuário, o agente é invocado adicionando a mensagem do usuário à conversa e chamando responses.create() com a referência do agente:

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. No portal da Foundry, crie um projeto.

2. Implante um modelo de sua escolha (consulte o Início Rápido do Microsoft Foundry: Criar recursos).

3. Na parte superior da área de testes do modelo, copie o nome dele.

4. Na página inicial, copie o endpoint do Azure OpenAI para depois.

1. No portal da Foundry, crie um projeto.

2. Na página inicial, copie o endpoint do Project para uso posterior.

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

4. Selecione ferramentas Adicionar>>ferramentas>Ferramenta OpenAPI personalizada>>Criar. No painel Instalação , adicione uma ação com a ferramenta de especificação OpenAPI.

5. Cole o esquema OpenAPI que você copiou do aplicativo App Service autenticado.

6. Para o método autenticação, selecione Identidade gerenciada.

7. Para Público-alvo, cole o valor de Público-alvo da identidade gerenciada da OpenAPI do Foundry da saída do AZD. Ele se assemelha a:

   api://<generated-client-id>
   

8. Salve a ferramenta e o agente.

Permita que o recurso pai do Foundry chame a API da tarefa

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

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

3. Copie o ID do objeto (principal) da identidade atribuída pelo sistema. Encontre essa identidade no Microsoft Entra ID e copie o ID da Aplicação dele. Para obter instruções detalhadas, consulte Encontrar a identidade do recurso pai do Foundry.

4. No terminal Codespace, armazene o ID da aplicação no ambiente AZD e atualize a configuração de autenticação do App Service:

   azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
   azd provision
   

1. No portal Foundry, selecione Gerenciar no menu superior.

2. Em Detalhes do projeto, selecione o recurso pai do seu projeto e selecione Abrir no portal do Azure.

   Pelo portal Azure, você pode atribuir acesso baseado em função para o recurso.

3. Adicione a seguinte função tanto para a identidade gerenciada do aplicativo do App Service quanto para o usuário que você usa com az login:

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

   Para obter instruções, confira Atribuir funções do Azure usando o portal do Azure.

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

2. Nos detalhes do Project, selecione Abrir no portal do Azure.

   Pelo portal do Azure, você pode atribuir acesso baseado em funções para o projeto.

3. Adicione a seguinte função tanto à identidade gerenciada do aplicativo do App Service quanto ao usuário que você usa com az login:

   Recurso de destino	Função necessária	Necessário para
   Projeto de fundimento	Usuário do Foundry	Lendo e chamando o agente do Foundry.

   Para obter instruções, confira Atribuir funções do Azure usando o portal do Azure.