チュートリアル: LangGraph または Foundry Agent Service を使用して Azure App Service でエージェント Web アプリを構築する (Node.js)

LangGraphTaskAgentは、src/agents/LangGraphTaskAgent.ts のコンストラクターで初期化されます。 初期化コードでは、次の処理が行われます。

• 環境変数を使用して AzureChatOpenAI クライアントを構成します。
• タスク管理用の CRUD ツールのセットを使用して、事前構築済みの ReAct エージェントを作成します (「LangGraph: How to use the prebuilt ReAct agent」を参照)。
• メモリ管理を設定します ( 「LangGraph: 事前構築済みの ReAct エージェントにメモリを追加する方法」を参照)。

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

ユーザー メッセージを処理する場合、エージェントは、会話の継続性のために、ユーザーのメッセージとセッション構成と共に invoke() を使用して呼び出されます。

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

FoundryTaskAgentはsrc/agents/FoundryTaskAgent.tsで遅延初期化パターンを使用しています。 初期化コードでは、次の処理が行われます。

• Azure 資格情報を使用して AIProjectClient を作成します。
• プロジェクト クライアントから OpenAI クライアントを取得します。
• 名前でエージェントを取得します。
• セッションの新しい会話を作成します。

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

この初期化コードでは、通常は Foundry ポータルでエージェントをビルドするため、エージェントの機能は定義されません。 シナリオ例の一部として、「 Foundry Agent Service (Node.js) で App Service アプリをツールとして追加する(Node.js)」に示されている OpenAPI パターンに従い、その CRUD 機能を OpenAPI エンドポイントとして使用できるようにします。 これにより、後で呼び出し可能なツールとしてエージェントに追加できます。

OpenAPI コードは src/routes/api.ts で定義されています。 たとえば、"GET /api/tasks" ルートは、operationIdの要求に応じて JSDoc Swagger コメント内のを定義し、descriptionはエージェントが 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' });
    }
});

ユーザー メッセージを処理する場合、エージェントは、ユーザーのメッセージを会話に追加し、エージェント参照を使用して responses.create() を呼び出すことによって呼び出されます。

// 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. Foundry ポータルで、上部の [New Foundry] ラジオ ボタンがアクティブに設定されていることを確認し、プロジェクトを作成します。

2. 任意のモデルをデプロイします ( Microsoft Foundry クイック スタート: リソースの作成を参照)。

3. モデルプレイグラウンドの上部から、モデル名をコピーします。

4. Azure OpenAI エンドポイントを取得する最も簡単な方法は、まだクラシック ポータルから行う方法です。 New Foundry ラジオ ボタン、Azure OpenAI の順に選択し、後で使用するために Azure OpenAI エンドポイント の URL をコピーします。

   

1. Foundry ポータルで、上部の [New Foundry] ラジオ ボタンがアクティブに設定されていることを確認し、プロジェクトを作成します。

2. ホームページでProject エンドポイントをコピーして、後で使用します。

3. [ ビルドの開始]>[エージェントの作成 ]を選択し、プロンプトに従います。

4. 新しいエージェントのプレイグラウンドで、ツール>追加>Custom>OpenAPI ツール> を選択して、Web アプリを呼び出す OpenAPI ツールを作成します。 [セットアップ] ウィンドウで、OpenAPI 仕様ツールを使用してアクションを追加します。 デプロイされた Web アプリと 匿名 認証から取得した OpenAPI スキーマを使用します。 詳細な手順については、「 OpenAPI 仕様ツールの使用方法」を参照してください。

   アプリケーション コードは、エージェントが必要とするサーバーの url と operationIdを含むように既に構成されています。 詳細については、「 OpenAPI 仕様への接続」を参照してください。

5. 必ず [保存] を選択してください。

6. [ プレイグラウンドで試す ] を選択し、"すべてのタスクを表示する" や "タスクを追加してください" などのプロンプトで Foundry エージェントをテストします。

   有効な応答を受け取った場合、エージェントはデプロイされた Web アプリで OpenAPI エンドポイントに対してツール呼び出しを行います。

1. 新しい Foundry ポータルの上部メニューから [ 操作] を選択し、[ 管理者] を選択します。Foundry プロジェクトの行には、2 つのリンクが表示されます。 [名前] 列の 1 つは Foundry プロジェクト リソースで、[親リソース] 列のリソースは Foundry リソースです。

   

2. 親リソースで Foundry リソース を選択し、 Azure portal で [このリソースの管理] を選択します。 Azure portal から、デプロイされた Web アプリにリソースのロールベースのアクセス権を割り当てることができます。

3. App Service アプリのマネージド ID に次のロールを追加します。

   ターゲット リソース	必要なロール	必要な理由
   鋳造所	Cognitive Services OpenAI ユーザー	Microsoft Agent Framework のチャット完了サービス。

   手順については、「Azure portal を使用して Azure ロールを割り当てる」を参照してください。

1. 新しい Foundry ポータルの上部メニューから [ 操作] を選択し、[ 管理者] を選択します。Foundry プロジェクトの行には、2 つのリンクが表示されます。 [名前] 列の 1 つは Foundry プロジェクト リソースで、[親リソース] 列のリソースは Foundry リソースです。

   

2. [名前] 列で Foundry プロジェクト リソースを選択し、Azure portal で [このリソースの管理] を選択します。 Azure portal から、デプロイされた Web アプリにリソースのロールベースのアクセス権を割り当てることができます。

3. App Service アプリのマネージド ID に次のロールを追加します。

   ターゲット リソース	必要なロール	必要な理由
   Foundry プロジェクト	Azure AI ユーザー	Foundry エージェントの読み取りと呼び出し。

   手順については、「Azure portal を使用して Azure ロールを割り当てる」を参照してください。