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

Ao processar mensagens de usuário, o agente é invocado usando invoke() a configuração de mensagem e sessão do usuário para continuidade da conversa:

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

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

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:

// 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 do Foundry, verifique se o botão de opção Novo Foundry no topo está definido como ativo e 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. A maneira mais fácil de obter o endpoint do Azure OpenAI ainda é a partir do portal clássico. Selecione o botão de opção Novo Foundry e, em seguida, OpenAI do Azure; depois, copie a URL no ponto de extremidade do OpenAI do Azure para uso posterior.

   

1. No portal do Foundry, verifique se o botão de opção Novo Foundry no topo está definido como ativo e crie um projeto.

2. Na página inicial, copie o ponto de extremidade do projeto para uso posterior.

3. Selecione Iniciar a criação>do agente de criação e siga o prompt.

4. No playground do novo agente, crie uma ferramenta OpenAPI para chamar seu aplicativo web selecionando Tools>Adicionar>Personalizado>Ferramenta OpenAPI>Criar. No painel Instalaçã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.

   Seu código de aplicativo já está configurado para incluir o url e operationId do servidor, que são necessários para o agente. Para obter mais informações, consulte Connect to OpenAPI Specification.

5. Certifique-se de selecionar Salvar.

6. Selecione Experimentar no playground e teste seu agente do Foundry com prompts como "Mostrar-me todas as tarefas" e "Adicione uma tarefa".

   Se você receber uma resposta válida, o agente está fazendo chamadas de ferramenta para o ponto de extremidade OpenAPI no seu aplicativo Web implantado.

1. No menu superior do novo portal do Foundry, selecione Operar e, em seguida, selecione Administrador. Na linha do projeto foundry, você deverá ver dois links. O que está na coluna Nome é o recurso do projeto Foundry, e o que está na coluna Recurso pai é o recurso Foundry.

   

2. Selecione o recurso Foundry no recurso Pai e, em seguida, selecione Gerenciar esse recurso no portal do Azure. No portal do Azure, você pode atribuir acesso baseado em função para o recurso ao aplicativo Web implantado.

3. Adicione a seguinte função para a identidade gerenciada do aplicativo do Serviço de Aplicativos:

   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 menu superior do novo portal do Foundry, selecione Operar e, em seguida, selecione Administrador. Na linha do projeto foundry, você deverá ver dois links. O que está na coluna Nome é o recurso do projeto Foundry, e o que está na coluna Recurso pai é o recurso Foundry.

   

2. Selecione o recurso do projeto Foundry na coluna Nome e, em seguida, selecione Gerenciar esse recurso no portal do Azure. No portal do Azure, você pode atribuir acesso baseado em função para o recurso ao aplicativo Web implantado.

3. Adicione a seguinte função para a identidade gerenciada do aplicativo do Serviço de Aplicativos:

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

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