チュートリアル: 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);
        }
    }

展開されたサンプルはApp Service認証で保護されており、サーバーが選択した1つのLangGraphスレッドを使用します。 ユーザーメッセージを処理する際、エージェントはユーザーのメッセージとサーバー管理スレッドIDで invoke() を呼び出します。

private readonly conversationThreadId = 'authenticated-conversation';

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

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

• Azure 資格情報を使用して AIProjectClient を作成します。
• プロジェクト クライアントから OpenAI クライアントを取得します。
• 名前でエージェントを取得します。
• App Service認証済みサンプル体験のために、サーバー管理の会話を1つ作成します。

// 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;

この初期化コードでは、通常は 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() を呼び出すことによって呼び出されます。

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. Foundryポータルでプロジェクトを作成します。

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

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

4. ホームページでAzure OpenAIエンドポイントをコピーしておきましょう。

1. Foundryポータルでプロジェクトを作成します。

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

3. 「 開始建設 」を選び、プロンプトに従ってください。

4. Tools>Add>Add tools>Custom>OpenAPI tool>Create を選択します。 [セットアップ] ウィンドウで、OpenAPI 仕様ツールを使用してアクションを追加します。

5. 認証済みのApp ServiceアプリからコピーしたOpenAPIスキーマを貼り付けます。

6. [認証方法] で、[マネージド ID] を選択します。

7. Audienceについては、AZD出力からFoundry OpenAPI管理型アイデンティティのオーディエンス値を貼り付けます。 その外観は以下の通りです:

   api://<generated-client-id>
   

8. ツールとエージェントは節約しましょう。

親FoundryリソースがタスクAPIを呼び出すことを許可します

1. Foundryポータルの上部メニューで 「管理 」を選択してください。

2. Projectの詳細で、projectの親リソースを選択し、「Open in Azure portal」を選択します。

3. システムに割り当てられたアイデンティティの オブジェクト(プリンシパル)IDをコピーします。 そのIDをMicrosoft Entra IDで見つけ、そのApplication IDをコピーします。 詳細な手順については、「 親Foundryリソース識別子を探す」をご覧ください。

4. Codespace端末でアプリケーションIDをAZD環境に保存し、App Service認証設定を更新します:

   azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
   azd provision
   

1. Foundryポータルの上部メニューで 「管理 」を選択してください。

2. Projectの詳細で、projectの親リソースを選択し、「Open in Azure portal」を選択します。

   Azureポータルからは、リソースにロールベースのアクセスを割り当てることができます。

3. App Serviceアプリのマネージデンティティと az loginで使用するユーザーの両方に、以下の役割を追加します。

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

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

1. Foundryポータルの上部メニューで 「管理 」を選択してください。

2. Projectの詳細で「Azureポータルで開く」を選択します。

   Azureポータルから、プロジェクトにロールベースのアクセスを割り当てることができます。

3. App Serviceアプリのマネージデンティティと az loginで使用するユーザーの両方に、以下の役割を追加します。

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

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