Add procurement agent ui

Author: declan-scale

agentex-ui/README.md

@@ -47,6 +47,163 @@ A modern web interface for building, testing, and monitoring intelligent agents.
 - **Error Handling** - User-friendly error messages with toast notifications
 - **Dark Mode** - WCAG-compliant dark mode with proper contrast ratios
 
+## Extended Features
+
+This UI includes several enhancements beyond the standard Agentex capabilities:
+
+### Artifact Panel
+
+An interactive side panel for viewing rich content generated by agents:
+
+- **PDF Viewer** - In-app PDF document viewing with navigation controls
+- **Map Viewer** - Interactive Google Maps integration for location-based data
+- **Data Tables** - Native database query results displayed in sortable tables
+- **Split View** - Resizable panel that allows simultaneous viewing of artifacts and chat
+
+The artifact panel automatically detects and displays procurement events, documents, and location data from agent responses.
+
+### Task Creation Without Messages
+
+Start agent tasks using structured parameters instead of requiring an initial message:
+
+- **Project Form Interface** - Create construction project tasks with dedicated input fields
+- **Direct Parameter Passing** - Pass structured data directly to agent initialization
+- **No Chat Required** - Begin tasks without sending an initial message
+- **Flexible Params** - Support for any agent-specific parameters via the params object
+
+### Human-in-the-Loop Support
+
+Interactive agent workflows that pause for human input, decisions, or approvals:
+
+- **wait_for_human Tool Detection** - Automatically detects when agents request human input
+- **Inline Response Forms** - Displays contextual forms directly in the message stream
+- **Recommended Actions** - Shows agent's suggested actions or questions to guide responses
+- **Optimistic UI** - Instant feedback when submitting responses
+- **Keyboard Shortcuts** - Submit responses with Cmd/Ctrl + Enter
+- **Response State Tracking** - Clearly indicates when responses have been received
+
+When an agent calls the `wait_for_human` tool with a `recommended_action` parameter, the UI automatically renders an interactive form allowing the user to provide input. Once submitted, the response is sent back to the agent to continue execution.
+
+### Native Data API
+
+A Next.js API route for querying external databases directly from the UI:
+
+- **SQLite Integration** - Query SQLite databases via `app/api/data/[taskId]/route.ts`
+- **Custom Tables** - Access agent-specific data tables (schedules, procurement items, etc.)
+- **Type-Safe** - Fully typed responses with TypeScript interfaces
+- **Performance** - Direct database access without backend roundtrips
+
+This enables agents to maintain their own data stores that the UI can query independently of the main Agentex API.
+
+## Demo: Procurement Agent
+
+To see these features in action, try the procurement agent demo from the Scale Agentex Python SDK:
+
+ <img src="./docs/images/procurement-agent.gif" alt="Procurement Agent" width="1280"/>
+
+### Setup Instructions
+
+1. **Clone the SDK repository:**
+
+   ```bash
+   git clone https://github.com/scaleapi/scale-agentex-python.git
+   cd scale-agentex-python
+   ```
+
+2. **Navigate to the procurement agent:**
+
+   ```bash
+   cd examples/demos/procurement_agent
+   ```
+
+3. **Run the agent:**
+
+   ```bash
+   # Install dependencies
+   uv sync
+
+   # Run the agent
+   export ENVIRONMENT=development && uv run agentex agents run --manifest manifest.yaml
+   ```
+
+4. **Configure the UI:**
+
+   In your `agentex-ui/.env.development`:
+
+   ```bash
+   NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your_google_maps_api_key
+   NEXT_PUBLIC_SQLITE_DB_PATH=/path/to/procurement_agent/construction_project.db
+   ```
+
+5. **Start a project:**
+
+   Open the UI, select the procurement agent, and create a new construction project. The agent will:
+   - Track procurement items and their status
+   - Display interactive maps of delivery locations
+   - Show project schedules in data tables
+   - Render submitted documents in the PDF viewer
+
+6. **Copy the task id**
+
+   Copy the task id in the top left of the UI
+
+   <img src="./docs/images/task-id.png" alt="Task Id" width="1280"/>
+
+7. **Send Test Events**
+
+   From this directory (`scale-agentex-python/examples/demos/procurement_agent`):
+
+   ```bash
+   # Navigate to the scripts directory
+   cd project/scripts
+
+   # Send events (you'll be prompted for the task ID)
+   uv run send_test_events.py
+   ```
+
+**Learn More:** [Agentex Procurement Agent](https://github.com/scaleapi/scale-agentex-python/tree/main/examples/demos/procurement_agent)
+
+### Using Human-in-the-Loop in Your Agents
+
+To request human input in your agent code, use the `wait_for_human` tool:
+
+```python
+# In your agent's tool definitions
+from agentex import tool
+
+@tool
+def wait_for_human(recommended_action: str) -> str:
+    """
+    Pause execution and wait for human input.
+
+    Args:
+        recommended_action: A message or question to display to the user
+
+    Returns:
+        The user's response text
+    """
+    pass  # Implementation handled by Agentex framework
+
+# Example usage in agent logic
+response = wait_for_human(
+    recommended_action="Should we proceed with ordering 500 units of steel beams at $50,000?"
+)
+
+if "yes" in response.lower() or "approve" in response.lower():
+    # Continue with the order
+    place_order(item="steel beams", quantity=500)
+else:
+    # Cancel or adjust the order
+    cancel_order()
+```
+
+The UI will automatically:
+
+1. Detect the `wait_for_human` tool call
+2. Render an interactive form with the `recommended_action` message
+3. Wait for the user to submit their response
+4. Send the response back to the agent to continue execution
+
 ## Stack
 
 - **Framework**: Next.js 15 (App Router), React 19, TypeScript
@@ -85,10 +242,24 @@ cp example.env.development .env.development
 Edit `.env.development` with your configuration:
 
 ```bash
-# Backend API endpoint
+# Required: Backend API endpoint
 NEXT_PUBLIC_AGENTEX_API_BASE_URL=http://localhost:5003
+
+# Optional: Google Maps API key for map visualization features
+NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
+
+# Optional: SQLite database path for native data API (used by procurement agent)
+NEXT_PUBLIC_SQLITE_DB_PATH=/path/to/your/database.db
 ```
 
+**Environment Variable Details:**
+
+| Variable                           | Required | Description                                                                |
+| ---------------------------------- | -------- | -------------------------------------------------------------------------- |
+| `NEXT_PUBLIC_AGENTEX_API_BASE_URL` | Yes      | Base URL for the Agentex backend API (default: `http://localhost:5003`)    |
+| `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY`  | No       | Google Maps API key for rendering map visualizations in the artifact panel |
+| `NEXT_PUBLIC_SQLITE_DB_PATH`       | No       | Path to SQLite database for native data queries (used by procurement demo) |
+
 ### 3. Install Dependencies
 
 ```bash

agentex-ui/app/api/data/[taskId]/route.ts

@@ -0,0 +1,59 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import Database from 'better-sqlite3';
+
+import { ScheduleData, ProcurementItem, TaskDataTables } from '@/lib/types';
+
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: Promise<{ taskId: string }> }
+): Promise<NextResponse<TaskDataTables | { error: string }>> {
+  try {
+    const { taskId } = await params;
+
+    const dbPath = process.env.NEXT_PUBLIC_SQLITE_DB_PATH;
+
+    if (!dbPath) {
+      return NextResponse.json(
+        { error: 'NEXT_PUBLIC_SQLITE_DB_PATH environment variable not set' },
+        { status: 500 }
+      );
+    }
+
+    const db = new Database(dbPath, { readonly: true });
+
+    try {
+      const scheduleQuery = db.prepare(`
+        SELECT workflow_id, project_name, project_start_date, project_end_date,
+               schedule_json, created_at, updated_at
+        FROM master_construction_schedule
+        WHERE workflow_id = ?
+      `);
+      const schedule = scheduleQuery.get(taskId) as ScheduleData | undefined;
+
+      const procurementQuery = db.prepare(`
+        SELECT workflow_id, item, status, eta, date_arrived,
+               purchase_order_id, created_at, updated_at
+        FROM procurement_items
+        WHERE workflow_id = ?
+        ORDER BY created_at DESC
+      `);
+      const procurementItems = procurementQuery.all(
+        taskId
+      ) as ProcurementItem[];
+
+      return NextResponse.json({
+        schedule: schedule || null,
+        procurement_items: procurementItems,
+      });
+    } finally {
+      db.close();
+    }
+  } catch (error) {
+    console.error('Error querying SQLite database:', error);
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Unknown error' },
+      { status: 500 }
+    );
+  }
+}

agentex-ui/app/globals.css

@@ -52,6 +52,16 @@
   --ring: #19202f;
   --secondary-foreground: #ffffff;
   --secondary: #45464f;
+  --toastify-icon-color-success: var(--color-green-700);
+  --toastify-color-progress-success: var(--color-green-700);
+  --toastify-icon-color-error: var(--color-red-700);
+  --toastify-color-progress-error: var(--color-red-700);
+  --toastify-icon-color-warning: var(--color-yellow-700);
+  --toastify-color-progress-warning: var(--color-yellow-700);
+  --toastify-icon-color-info: var(--color-blue-700);
+  --toastify-color-progress-info: var(--color-blue-700);
+  --toastify-icon-color-default: var(--color-gray-700);
+  --toastify-color-progress-default: var(--color-gray-700);
 }
 
 .dark {

agentex-ui/app/layout.tsx

@@ -1,6 +1,7 @@
 import { Geist, Geist_Mono } from 'next/font/google';
 
 import { QueryProvider, ThemeProvider } from '@/components/providers';
+import { ArtifactPanelProvider } from '@/contexts/artifact-panel-context';
 
 import type { Metadata } from 'next';
 import '@/app/globals.css';
@@ -37,7 +38,7 @@ export default function RootLayout({
             enableSystem={false}
             disableTransitionOnChange
           >
-            {children}
+            <ArtifactPanelProvider>{children}</ArtifactPanelProvider>
           </ThemeProvider>
         </QueryProvider>
       </body>

agentex-ui/components/agentex-ui-root.tsx

@@ -4,10 +4,12 @@ import { useCallback, useEffect, useState } from 'react';
 
 import { ToastContainer } from 'react-toastify';
 
+import { ArtifactPanel } from '@/components/artifacts/artifact-panel';
 import { PrimaryContent } from '@/components/primary-content/primary-content';
 import { useAgentexClient } from '@/components/providers';
 import { TaskSidebar } from '@/components/task-sidebar/task-sidebar';
 import { TracesSidebar } from '@/components/traces-sidebar/traces-sidebar';
+import { useArtifactPanel } from '@/contexts/artifact-panel-context';
 import { useAgents } from '@/hooks/use-agents';
 import { useLocalStorageState } from '@/hooks/use-local-storage-state';
 import {
@@ -20,6 +22,7 @@ export function AgentexUIRoot() {
   const [isTracesSidebarOpen, setIsTracesSidebarOpen] = useState(false);
   const { agentexClient } = useAgentexClient();
   const { data: agents = [], isLoading } = useAgents(agentexClient);
+  const { isOpen: isArtifactPanelOpen, closeArtifact } = useArtifactPanel();
   const [localAgentName, setLocalAgentName] = useLocalStorageState<
     string | undefined
   >('lastSelectedAgent', undefined);
@@ -41,6 +44,21 @@ export function AgentexUIRoot() {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [isLoading]);
 
+  // Close artifact when task or agent changes
+  useEffect(() => {
+    if (isArtifactPanelOpen) {
+      closeArtifact();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [taskID, agentName]);
+
+  // Close traces sidebar when artifact opens
+  useEffect(() => {
+    if (isArtifactPanelOpen && isTracesSidebarOpen) {
+      setIsTracesSidebarOpen(false);
+    }
+  }, [isArtifactPanelOpen, isTracesSidebarOpen]);
+
   const handleSelectTask = useCallback(
     (taskId: string | null) => {
       updateParams({
@@ -82,8 +100,10 @@ export function AgentexUIRoot() {
           toggleTracesSidebar={() =>
             setIsTracesSidebarOpen(!isTracesSidebarOpen)
           }
+          isArtifactPanelOpen={isArtifactPanelOpen}
         />
         <TracesSidebar isOpen={isTracesSidebarOpen} />
+        <ArtifactPanel />
       </div>
       <ToastContainer />
     </>