Tutorial: Compilación de una aplicación web agente en Azure App Service con LangGraph o Foundry Agent Service (Node.js)

LangGraphTaskAgent se inicializa en el constructor en src/agents/LangGraphTaskAgent.ts. El código de inicialización hace lo siguiente:

• Configura el cliente de AzureChatOpenAI mediante variables de entorno.
• Crea el agente ReAct pre compilado con un conjunto de herramientas CRUD para la administración de tareas (consulte LangGraph: Cómo usar el agente ReAct pre compilado).
• Configura la administración de memoria (consulte LangGraph: Adición de memoria al agente react precompilado).

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

La muestra desplegada está protegida por autenticación por App Service y utiliza un hilo LangGraph seleccionado por el servidor. Cuando procesas mensajes de usuario, el agente invoca invoke() con el mensaje del usuario y el ID del hilo gestionado por el servidor:

private readonly conversationThreadId = 'authenticated-conversation';

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

El FoundryTaskAgent utiliza un patrón de inicialización diferida en src/agents/FoundryTaskAgent.ts. El código de inicialización hace lo siguiente:

• Crea un AIProjectClient mediante credenciales de Azure.
• Obtiene un cliente de OpenAI del cliente del proyecto.
• Recupera el agente por nombre.
• Crea una conversación gestionada por el servidor para la experiencia de muestra 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;

Este código de inicialización no define ninguna funcionalidad para el agente, ya que normalmente compilaría el agente en el portal de Foundry. Como parte del escenario de ejemplo, también sigue el patrón openAPI que se muestra en Agregar una aplicación de App Service como una herramienta en Foundry Agent Service (Node.js) y hace que su funcionalidad CRUD esté disponible como punto de conexión de OpenAPI. Esto le permite agregarlo al agente más adelante como una herramienta invocable.

El código openAPI se define en src/routes/api.ts. Por ejemplo, la ruta "GET /api/tasks" define operationId en los comentarios de Swagger de JSDoc, como se requiere por la herramienta de especificación OpenAPI en Microsoft Foundry, y description ayuda al agente a determinar el modo de invocar la 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' });
    }
});

Al procesar mensajes de usuario, se invoca al agente agregando el mensaje del usuario a la conversación y llamando a responses.create() con la referencia del 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. En el portal de Foundry, crea un proyecto.

2. Implemente un modelo de su elección (consulte Inicio rápido de Microsoft Foundry: Creación de recursos).

3. En la parte superior del área de juegos de modelos, copie el nombre del modelo.

4. En la página principal, copia el punto de conexión de Azure OpenAI para usarlo más tarde.

1. En el portal de Foundry, crea un proyecto.

2. En la página principal, copia el endpoint de Project para usarlo más adelante.

3. Selecciona Empezar a construir y sigue la indicación.

4. Selecciona Herramientas>Agregar>Agregar herramientas>Personalizada>Herramienta OpenAPI>Crear. En el panel Configuración , agregue una acción con la herramienta de especificación openAPI.

5. Pega el esquema de OpenAPI que copiaste de la app App Service autenticada.

6. En Método de autenticación, seleccione Identidad administrada.

7. Para Audiencia, pega el valor de la audiencia de identidad gestionada por Foundry OpenAPI desde la salida de AZD. Se asemeja a:

   api://<generated-client-id>
   

8. Guarda la herramienta y el agente.

Permite que el recurso padre de Foundry llame a la API de tareas

1. En el portal de Foundry, selecciona Gestionar en el menú superior.

2. En Detalles del proyecto, selecciona el recurso primario para tu proyecto y después selecciona Abrir en el portal de Azure.

3. Copia el ID de objeto (principal) de la identidad asignada por el sistema. Encuentra esa identidad en Microsoft Entra ID y copia su ID de aplicación. Para pasos detallados, consulta Encontrar la identidad del recurso Foundry principal.

4. En el terminal Codespace, almacena el ID de la aplicación en el entorno AZD y actualiza la configuración de autenticación del App Service:

   azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
   azd provision
   

1. En el portal de Foundry, selecciona Gestionar en el menú superior.

2. En Detalles del proyecto, selecciona el recurso primario de tu proyecto y luego selecciona Abrir en Azure Portal.

   Desde el portal de Azure, puedes asignar acceso basado en roles para el recurso.

3. Añada el siguiente rol tanto a la identidad administrada de la aplicación de App Service como al usuario que utilice con az login:

   Recurso de destino	Rol necesario	Necesario para
   Fundición	Usuario de OpenAI de Cognitive Services	El servicio de finalización del chat en Microsoft Agent Framework.

   Para obtener instrucciones, consulte Asignación de roles de Azure mediante Azure Portal.

1. En el portal de Foundry, selecciona Gestionar en el menú superior.

2. En detalles del Project, selecciona Abrir en el portal de Azure.

   Desde el portal de Azure, puedes asignar acceso basado en roles para el proyecto.

3. Añada el siguiente rol tanto a la identidad administrada de la aplicación de App Service como al usuario que utilice con az login:

   Recurso de destino	Rol necesario	Necesario para
   Proyecto de Fábrica	Usuario de Foundry	Lectura y llamada al agente de Foundry.

   Para obtener instrucciones, consulte Asignación de roles de Azure mediante Azure Portal.