feat: add current page context support to agent tools and API requests

Author: NoOne7135

agent/simpleAgent.ts

@@ -19,12 +19,14 @@ import {
 } from "./middleware/sequenceDebug.js";
 import type { ApiBasedTool } from "../apiBasedTools.js";
 import type { ToolCallEventSink } from "./toolCallEvents.js";
+import type { CurrentPageContext } from "./tools/getUserLocation.js";
 
 export const contextSchema = z.object({
   adminUser: z.custom<AdminUser>(),
   userTimeZone: z.string(),
   sessionId: z.string(),
   turnId: z.string(),
+  currentPage: z.custom<CurrentPageContext>().optional(),
   httpExtra: z.custom<Partial<HttpExtra>>().optional(),
   emitToolCallEvent: z.custom<ToolCallEventSink>(),
 });
@@ -231,6 +233,7 @@ export async function callAgent(params: {
   customComponentsDir: string;
   sessionId: string;
   turnId: string;
+  currentPage?: CurrentPageContext;
   httpExtra?: Partial<HttpExtra>;
   userTimeZone: string;
   emitToolCallEvent: ToolCallEventSink;
@@ -249,6 +252,7 @@ export async function callAgent(params: {
     customComponentsDir,
     sessionId,
     turnId,
+    currentPage,
     httpExtra,
     userTimeZone,
     emitToolCallEvent,
@@ -293,6 +297,7 @@ export async function callAgent(params: {
       userTimeZone,
       sessionId,
       turnId,
+      currentPage,
       httpExtra,
       emitToolCallEvent,
     },

agent/tools/getUserLocation.ts

@@ -0,0 +1,45 @@
+import { tool } from "langchain";
+import { z } from "zod";
+
+export type CurrentPageContext = {
+  path: string;
+  fullPath: string;
+  title: string;
+  url: string;
+};
+
+const getUserLocationSchema = z.object({});
+
+export function createGetUserLocationTool() {
+  return tool(
+    async (_input, runtime) => {
+      const currentPage = (runtime.context as { currentPage?: CurrentPageContext }).currentPage;
+
+      if (!currentPage) {
+        return JSON.stringify(
+          {
+            status: 404,
+            message: "Current user location is not available.",
+          },
+          null,
+          2,
+        );
+      }
+
+      return JSON.stringify(
+        {
+          status: 200,
+          location: currentPage,
+        },
+        null,
+        2,
+      );
+    },
+    {
+      name: "get_user_location",
+      description:
+        "Get the user's current location in the AdminForth UI, including current page path, full path, title, and URL. Call this tool when you do not understand what the user is referring to, especially when they say here, this page, current page, opened page, or otherwise rely on page context.",
+      schema: getUserLocationSchema,
+    },
+  );
+}

agent/tools/index.ts

@@ -3,6 +3,7 @@ import { createFetchSkillTool } from "./fetchSkill.js";
 import { createFetchToolSchemaTool } from "./fetchToolSchema.js";
 import type { ApiBasedTool } from "../../apiBasedTools.js";
 import { createApiTool } from "./apiTool.js";
+import { createGetUserLocationTool } from "./getUserLocation.js";
 
 export const ALWAYS_AVAILABLE_API_TOOL_NAMES = ["get_resource"] as const;
 
@@ -20,6 +21,7 @@ export async function createAgentTools(
 
       return createApiTool(toolName, apiBasedTool);
     }),
+    createGetUserLocationTool(),
     await createFetchSkillTool(customComponentsDir),
     await createFetchToolSchemaTool(apiBasedTools),
   ];

index.ts

@@ -35,18 +35,12 @@ import {
 } from "./agent/systemPrompt.js";
 import { ALWAYS_AVAILABLE_API_TOOL_NAMES } from "./agent/tools/index.js";
 import type { ToolCallEvent } from "./agent/toolCallEvents.js";
+import type { CurrentPageContext } from "./agent/tools/getUserLocation.js";
 
 type CurrentPageRequestBody = {
   currentPage?: CurrentPageContext;
 };
 
-type CurrentPageContext = {
-  path: string;
-  fullPath: string;
-  title: string;
-  url: string;
-};
-
 type SpeechResponseRequestBody = CurrentPageRequestBody & {
   audioBase64: string;
   filename: string;
@@ -133,18 +127,6 @@ function formatAdminUserPrompt(adminUser: AdminUser, usernameField: string) {
   ].join("\n");
 }
 
-function formatCurrentPagePrompt(currentPage: CurrentPageContext | undefined) {
-  if (!currentPage) {
-    return null;
-  }
-
-  return [
-    "Current user page context for the latest message:",
-    JSON.stringify(currentPage, null, 2),
-    "When the user says here, this page, current page, or opened page, treat it as this page.",
-  ].join("\n");
-}
-
 function assertRequiredApiTool(
   apiBasedTools: Record<string, ApiBasedTool>,
   toolName: string,
@@ -339,7 +321,6 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
     }
     assertRequiredApiTool(apiBasedTools, "update_record");
     this.apiBasedTools = apiBasedTools;
-    const currentPagePrompt = formatCurrentPagePrompt(input.currentPage);
     const stream = await callAgent({
       name: `adminforth-agent-${this.pluginInstanceId}`,
       model,
@@ -348,7 +329,6 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       checkpointer: this.getCheckpointer(),
       messages: [
         new SystemMessage(systemPrompt),
-        ...(currentPagePrompt ? [new SystemMessage(currentPagePrompt)] : []),
         new HumanMessage(input.prompt),
       ],
       adminUser: input.adminUser,
@@ -357,6 +337,7 @@ export default class AdminForthAgentPlugin extends AdminForthPlugin {
       customComponentsDir: this.adminforth.config.customization.customComponentsDir,
       sessionId: input.sessionId,
       turnId: input.turnId,
+      currentPage: input.currentPage,
       httpExtra: input.httpExtra,
       userTimeZone: input.userTimeZone,
       emitToolCallEvent: (event) => {