使用说明

docAgent AI - Intelligent Agent Client & Canvas UI

An agentic user interface and workflow orchestration engine built with LangGraph, FastAPI, Celery/Redis, and React (Vite + Tailwind CSS). This repository serves as the primary intelligence, agent execution, and interaction layer for the docAgent-MCPServer.

Overview

docAgentAI is much more than a frontend facade—it is an autonomous agent runtime. It constructs a stateful LangGraph workflow that plans, reasons, and executes multi-step document operations by invoking tools exposed by the Model Context Protocol (MCP) server.

Key Features

LangGraph Agent Engine: Stateful graph-based agent (Agent -> Tools -> Agent -> Facade Sanitizer -> Complete) capable of planning, iterative execution, and artifact generation.
MCP Integration: Direct connection with docAgent-MCPServer for sandboxed Python code execution, document parsing, translation, plotting, and file conversions.
Asynchronous Context & Task Offloading: Celery + Redis architecture for handling heavy background jobs (such as chat history summarization side-effects and long-running agent workflows) without blocking real-time client streaming.
Interactive Canvas UI: ChatGPT/Claude Canvas-style split screen interface supporting live chat, SSE streaming outputs, side-by-side artifact viewing (code, text, charts, images), and file uploads.
FastAPI Layer: REST and SSE endpoints managing session states, message context windows, tool execution pipelines, and background task dispatch.

Request Lifecycle & Execution Flow

  ┌──────────────────────────────────────────────────────────────┐
  │                       React Canvas UI                        │
  │        (Chat Interface, File Uploads, Artifact Canvas)       │
  └──────────────────────────────┬───────────────────────────────┘
                                 │ REST / SSE Stream
                                 ▼
  ┌──────────────────────────────────────────────────────────────┐
  │                 FastAPI Layer (controller.py)               │
  │                                                              │
  │  1. Fetch Session Context from Redis                        │
  │  2. Check Redis History List Size                            │
  │     └─► If > Threshold: Trigger Celery Summarization Task    │
  │  3. Pass Prompt & Context to LangGraph Workflow              │
  │  4. Update Redis State with New Messages & Artifacts          │
  └──────────────────────────────┬───────────────────────────────┘
                                 │
                 ┌───────────────┴───────────────┐
                 │                               │
                 ▼                               ▼
  ┌─────────────────────────────┐ ┌─────────────────────────────┐
  │     LangGraph Agent Graph   │ │     Celery Worker Queue     │
  │   (workflow_agent.py)       │ │     (tasks.py)              │
  │                             │ │                             │
  │  - Planner / LLM Node       │ │  - Asynchronous background  │
  │  - MCP Tool Node            │ │    chat history truncation  │
  │  - Facade Sanitizer Node    │ │    & summarization          │
  └──────────────┬──────────────┘ └─────────────────────────────┘
                 │
                 ▼ MCP (Model Context Protocol)
  ┌──────────────────────────────────────────────────────────────┐
  │                     docAgent-MCPServer                       │
  │    (https://github.com/assignment-sets/docAgent-MCPServer)   │
  └──────────────────────────────────────────────────────────────┘

Detailed Request Step-by-Step (`api/controller.py`)

Context Retrieval: On receiving a user prompt or file upload, the FastAPI controller queries Redis to retrieve stored session history and active conversation state.
Context Window Check: The controller evaluates the size of the Redis message list. If history exceeds configured limits, an asynchronous Celery background task (summarize_chat_history_task) is dispatched as a side-effect to compress older turns into a condensed summary, preventing LLM token overflow without adding latency to the current response.
LangGraph Execution: The prompt, context, and file references are dispatched to the workflow_agent LangGraph graph.
State Persistence: Once the agent finishes processing and formatting artifacts, the newly generated messages, tool outputs, and visual canvas artifacts are written back to Redis.
Streaming / Client Response: The response is streamed back to the React UI via SSE (Server-Sent Events) or REST response.

Agent Architecture (`agent/workflow_agent.py`)

The heart of docAgentAI is a directed graph built using LangGraph. The workflow state (AgentState) maintains conversation history, active file references, tool execution logs, generated artifacts, and plan states.

  [ START ] ──► ( Agent / Planner Node )
                       │
             ┌─────────┴─────────┐
             │ Requires Tool?    │
             ▼                   ▼
      [ YES: Tool Node ]     [ NO: Facade Node ]
             │                   │
             └──────► Agent ─────┤
                                 ▼
                            [   END   ]

Core Nodes & Components

agent (Planner & Execution Node): Uses the primary LLM initialized with tools fetched directly from docAgent-MCPServer. It evaluates incoming context, determines necessary steps, and decides whether to invoke an MCP tool or finalize output.
tools (MCP Execution Node): Connects to docAgent-MCPServer via the MCP Client bridge (get_mcp_client) to execute sandboxed Python code, document extraction, translations, OCR, image plotting, or archiving.
facade_sanitizer (Response Formatting Node): Passes raw tool outputs through a secondary LLM wrapper (get_facade_llm) to sanitize data, extract Canvas-compatible artifacts (code snippets, HTML, Markdown, charts), and format clean Markdown text for the UI.

Project Structure

.
├── agent/
│   ├── __init__.py
│   └── workflow_agent.py          # LangGraph state graph, nodes & routing logic
├── api/
│   ├── __init__.py
│   └── controller.py              # FastAPI endpoints, Redis context handling & Celery trigger
├── celery_worker/
│   ├── __init__.py
│   ├── celery_app.py              # Celery instance setup
│   └── tasks.py                   # Async background tasks (chat history summarization)
├── core/
│   ├── __init__.py
│   └── logging_config.py          # Structured application logger
├── services/
│   ├── __init__.py
│   ├── facade_sanitizer.py        # Output sanitizer & canvas response formatter
│   ├── get_auth.py                # Auth verification & user session helpers
│   ├── get_facade_llm.py          # Secondary LLM wrapper for formatting
│   ├── get_llm.py                 # Primary LLM provider initializer (OpenAI, etc.)
│   ├── get_mcp_client.py          # MCP Client bridge connecting to docAgent-MCPServer
│   ├── get_prompts.py             # System prompts & agent persona definitions
│   └── get_redis.py               # Redis connection factory
├── ui/                            # React Frontend (Vite + Tailwind CSS)
│   ├── public/
│   ├── src/
│   │   ├── components/            # Chat, Artifact, Canvas, Upload, Navigation
│   │   ├── context/               # ChatAPIContext state provider
│   │   ├── pages/                 # HomePage, LandingPage, CallbackPage, ProtectedRoute
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── package.json
│   └── vite.config.js
├── utils/
│   ├── __init__.py
│   ├── op_parser.py               # Tool execution & output parser
│   ├── summarizer.py              # Text summarization utilities
│   └── upload_file.py             # Local file handling & storage
├── .env.example                   # Reference environment configuration template
├── main.py                        # Backend application entry point
├── pyproject.toml                 # Project metadata & dependencies
├── run_app.sh                     # Unified application launch script
└── uv.lock                        # Lockfile

Prerequisites

Python: 3.12+
Package Manager: uv (recommended) or pip
Node.js: 18+ & npm
Redis Server: Required for session state caching and Celery task execution
MCP Server: Target instance of docAgent-MCPServer
API Keys: OpenAI / Anthropic / Supported LLM API Key

Environment Setup

Copy .env.example to create your local .env configuration file:

cp .env.example .env

Refer to .env.example for all configurable environment variables, including LLM provider credentials, Redis connection settings, MCP server launch parameters, and API server host settings.

Installation & Running

1. Install Backend Dependencies

Using uv:

uv sync

2. Install Frontend Dependencies

cd ui
npm install
cd ..

3. Start Redis Server

Ensure Redis is running locally or via Docker:

docker run -d -p 6379:6379 redis:alpine

4. Launch Application

You can launch the FastAPI server, Celery worker, and Vite dev server simultaneously using the startup script:

chmod +x run_app.sh
./run_app.sh

Or run each service individually:

FastAPI Server:

uv run python main.py

Celery Worker:

uv run celery -A celery_worker.celery_app worker --loglevel=info

Vite Frontend:

cd ui
npm run dev

Related Repositories

🛠️ MCP Server: docAgent-MCPServer - Exposes document processing, containerized Python execution, file format conversion, OCR, and plotting tools via Model Context Protocol.

License

This project is licensed under the MIT License.