Enterprise agent platform for building, deploying, and operating AI teammates.
xagent Frontend
A modern React-based frontend for the xagent Agent system, built with Next.js, TypeScript, and Tailwind CSS.
Features
- Three-Column Layout: User interaction, DAG visualization, and step details
- Real-time Communication: WebSocket integration for live updates
- DAG Visualization: Interactive graph execution display using React Flow
- Modern UI: Built with shadcn/ui components and Tailwind CSS
- TypeScript: Full type safety throughout the application
- Responsive Design: Works on desktop and mobile devices
Tech Stack
- Framework: Next.js 15 with App Router
- Language: TypeScript
- Styling: Tailwind CSS
- UI Components: shadcn/ui
- State Management: React Context + useReducer
- Real-time: Socket.io Client
- Visualization: @xyflow/react (React Flow)
- Markdown: Marked.js + Highlight.js
- Icons: Lucide React
Getting Started
Prerequisites
- Node.js 20.19+ within the 20.x line, or 22.12+ (required by the Vite 7 test toolchain)
- npm or yarn
Installation
- Navigate to the frontend directory:
cd frontend
- Install dependencies:
npm install
- Configure environment variables:
cp .env.local.example .env.local
- Start the development server:
npm run dev
- Open http://localhost:3000 in your browser.
Project Structure
src/
├── app/ # Next.js app router
│ ├── globals.css # Global styles
│ ├── layout.tsx # Root layout
│ └── page.tsx # Main application page
├── components/ # React components
│ ├── layout/ # Layout components
│ │ ├── three-column-layout.tsx
│ │ ├── left-panel.tsx
│ │ ├── center-panel.tsx
│ │ └── right-panel.tsx
│ └── ui/ # shadcn/ui components
├── contexts/ # React contexts
│ └── app-context.tsx # Global app state
├── hooks/ # Custom React hooks
│ └── use-websocket.ts # WebSocket hook
└── lib/ # Utility functions
├── utils.ts # General utilities
└── markdown.ts # Markdown rendering
Key Components
ThreeColumnLayout
Main layout component that arranges the three panels.
LeftPanel
Handles user input and displays conversation history.
CenterPanel
Interactive DAG visualization using React Flow.
RightPanel
Shows step execution details and trace events.
WebSocket Integration
Real-time communication with the FastAPI backend for live updates.
Configuration
Environment Variables
NEXT_PUBLIC_WS_URL: WebSocket server URLNEXT_PUBLIC_API_URL: HTTP API server URLNEXT_PUBLIC_XAGENT_HTML_PREVIEW_ORIGIN: Optional isolated HTML preview origin. Set an HTTPS origin (HTTP is allowed only on localhost/127.0.0.1/[::1] for development) to load its/renderrunner; any configured path/query/fragment is discarded. Useautofor the XAgent SaaS mapping (cloud.xagent.cotopreview.xagent.co, stage/dev topreview-stage.xagent.co/preview-dev.xagent.co). Unset/invalid settings or an 8-second ready timeout use the scripts-only opaquesrcDocfallback. The serving CSP must permit the runner inframe-src: Next includes the build setting; packaged/static serving needs the same variable at backend runtime (and custom proxies must match). Docker accepts a build argument. Nightly builds use the repository variable of the same name, defaulting to disabled; the official PyPI wheel is built with the runner disabled and needs a custom frontend build to enable it. Setting a runtime variable on an already-built frontend does not enable it. The separate runner is not shipped or deployed by this repository. It must implement the/renderready/render v1 protocol described in HTML preview security. Embedded widget/share pages retainsrcDoc, because the managed runner's exactframe-ancestorspolicy cannot authorize an arbitrary outer customer site. Static quotedsrc/hrefassets are rewritten; other relative URL syntaxes and runtime-constructed URLs must be absolute or inlined.
Backend Integration
The frontend connects to the FastAPI backend running on port 8000 by default. Make sure the backend is running before starting the frontend.
Development
Available Scripts
npm run dev- Start development servernpm run build- Build for productionnpm run start- Start production servernpm run lint- Run ESLintnpm run type-check- Run TypeScript type checking
Adding New Components
- Use shadcn/ui for consistent design:
npx shadcn@latest add [component-name]
- Follow the established patterns in the existing components.
Styling
- Use Tailwind CSS classes for styling
- Follow the shadcn/ui design system
- Use the
cn()utility for conditional class merging
WebSocket Events
The frontend handles the following WebSocket events:
trace_event- Execution trace eventstask_completed- Task completion notificationsdag_execution- DAG execution state updatesdag_step_info- Individual step informationtask_paused/task_resumed- Task state changesagent_error- Error notifications
Browser Support
- Chrome 90+
- Firefox 96+
- Safari 15.4+
- Edge 90+
Browser sign-in also requires local storage, the Web Locks API, and a secure
context. Use HTTPS outside local development; loopback hosts such as
localhost, 127.0.0.1, and ::1 are suitable for local development.
Contributing
- Follow the existing code style
- Add TypeScript types for new features
- Test thoroughly
- Update documentation as needed
License
This project is part of xagent and follows the same license terms.