pro-agent

<div align="center"> # Pro-Agent **A production-ready multi-agent application platform · Go control plane + Python(LangGraph) cognition plane** <!-- <p align="center"> <a href="https://github.com/yrris/pro-agent/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/yrris/pro-agent?style=flat&logo=github"></a> <a href="https://github.com/yrris/pro-agent/forks"><img alt="Forks" src="https://img.shields.io/github/forks/yrris/pro-agent?style=flat&logo=github"></a> <a href="https://github.com/yrris/pro-agent/commits/main"><img alt="Last Commit" src="https://img.shields.io/github/last-commit/yrris/pro-agent?style=flat&logo=github"></a> <a href="https://github.com/yrris/pro-agent/issues"><img alt="Issues" src="https://img.shields.io/github/issues/yrris/pro-agent?style=flat&logo=github"></a> </p> --> <p align="center"> <img alt="Go" src="https://img.shields.io/badge/Go-control-00ADD8?logo=go"> <img alt="Python" src="https://img.shields.io/badge/Python-cognition-3776AB?logo=python"> <img alt="LangGraph" src="https://img.shields.io/badge/LangGraph-agent--orchestration-1C3C3C?logo=langgraph"> <img alt="React" src="https://img.shields.io/badge/React-frontend-61DAFB?logo=react"> <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-web-3178C6?logo=typescript"> <img alt="Docker" src="https://img.shields.io/badge/Docker-compose-2496ED?logo=docker"> <img alt="Prometheus" src="https://img.shields.io/badge/Prometheus-metrics-E6522C?logo=prometheus"> <img alt="OpenTelemetry" src="https://img.shields.io/badge/OpenTelemetry-tracing-000000?logo=opentelemetry&logoColor=white"> </p> [](https://zread.ai/yrris/pro-agent) Upgrade "passive Q&A AI applications" to "a complex task execution system that is programmable, observable, replayable, and proactive". </div> > Placeholder for screenshot: `docs/assets/hero.png` — Homepage dialogue flow + plan view + product workspace overall look. > > <!--  --> --- ## Table of Contents - [What problems does it solve](#what-problems-does-it-solve) - [Core highlights](#core-highlights) - [Dual-plane architecture](#dual-plane-architecture) - [Two core data flows](#two-core-data-flows) - [Single Agent internal and multi-Agent collaboration](#single-agent-internal-and-multi-agent-collaboration) - [Capability panorama](#capability-panorama) - [Observability](#observability) - [Tech stack](#tech-stack) - [Quick start](#quick-start) - [Directory structure](#directory-structure) - [Roadmap](#roadmap) --- ## What problems does it solve Ordinary "large model shell" applications stay at Q&A: model answers and forgets, multi-step tasks rely on users to manually disassemble, tool capabilities are hard-coded, problems occur without review, and can only wait for users to ask. This platform systematically designs solutions for these pain points: | Pain points | Solutions | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | Complex tasks require users to disassemble steps | **ReAct + Plan-Execute dual orchestration**: model plans and executes sub-tasks in parallel, dynamically replans based on results | | Model answers and forgets, changes sessions lose memory | **LangGraph checkpoint memory** + server-side session ledger, multi-round continuation, cross-device consistency, can fork out parallel timelines | | Adding new capabilities requires code changes and redeployment | **Unified tool ecosystem**: local tools / MCP three-transmission / Skill progressive disclosure, add capabilities = add configuration/add files | | Knowledge Q&A recall difference, can only pure text | **Agentic RAG**: dense + sparse mixed retrieval + multi-round reflection + rerank; attachment automatic storage (including image/scanned PDF vision OCR, table/multi-column restoration) | | High concurrency is prone to collapse | **Go control plane bears concurrency and back pressure**: goroutine + semaphore + context cancellation + gateway current limiting, "elegant busy" replaces collapse | | Problems occur without review, experience cannot be restored | **Execution fact ledger + replay isomorphic**: every step falls into the library, historical replay and real-time streaming are frame-by-frame consistent | | Can only passively wait for user questions | **Proactive connector**: external events (GitHub, etc.) automatically trigger agents, high-risk actions go through human approval gate | | Production environment invisible, unmanageable | **Prometheus metrics + OTel link tracking + Grafana dashboard + multi-user RBAC + management backend** | --- ## Core highlights - **Dual orchestration hybrid**: quickly ReAct (think⇄act ring) / deep thinking Plan-Execute (planning → parallel sub-executors → summary → replan) / in-depth research (multi-round retrieval-verification-reference) three-gear one-key switching. - **Controllable parallel sub-agents**: based on LangGraph `Send` fan-out, self-developed parallel width, budget, timeout, state merging (exchangeable and combinable reducer), failure isolation - put long-chain task time-consuming pressure down and ensure product and ledger attribution consistency. - **Execution is an asset**: unified event schema + event ledger, real-time and replay isomorphic (not relying on re-running, but event replay); supports problem location and experience recovery. - **Human in the loop (HITL)**: "approval = run boundary", high-risk tool execution suspended before approval, cross-refresh/restart/overnight approval, decision-making into ledger, replay visible complete decision chain. - **Production-ready**: model layered routing (strong model planning, cost-effective model execution) + Docker one-click full suite dependency + full-link observability + multi-tenant authentication, reserved plug-in boundary for scalability. > Placeholder for screenshot: `docs/assets/orchestration.png` (plan view + parallel sub-task cards), `docs/assets/hitl.png` (human approval card). --- ## Dual-plane architecture **Two planes each responsible for its own role**: Go holds "everything facing the world", Python holds "everything thinking", and the two communicate with each other using gRPC streaming, with Go as the only external entry. ```mermaid flowchart TB subgraph client["Frontend (React + TypeScript)"] UI["Dialogue / Plan View / Product Workspace<br/>Image Generation Workspace / Knowledge Base / Management Backend"] end ext["External Event Source<br/>(GitHub polling ...)"] subgraph go["Go Control Plane (control-plane) — Only External"] API["API Gateway<br/>Authentication (RBAC) · Session Attribution · Current Limiting/Back Pressure"] DISP["Dispatcher<br/>Concurrent Semaphore · Run Lifecycle Single Receipt"] HUB["Streaming Hub<br/>Event Storage + SSE/WS Push"] SCH["Scheduler / Poller<br/>Timing Trigger · Event Polling"] OBS["Observability<br/>Prometheus Metrics · OTel Trace · Health Aggregation"] end subgraph py["Python Cognition Plane (cognition) — Internal Cognition Service"] GRAPH["LangGraph Orchestration Engine"] REACT["ReAct Graph (think⇄act)"] PLAN["Plan-Execute Graph<br/>(plan→Send parallel executor→summary)"] RAG["Agentic RAG Subgraph<br/>(Mixed Retrieval · Reflection · rerank)"] TOOLS["Tool Registry<br/>Local / MCP / Skill"] MEM["Checkpointer(Recoverable) · Memory · Model Routing"] end subgraph infra["Infrastructure (Docker)"] PG[("PostgreSQL<br/>Business · Event Ledger · checkpoint")] QD[("Qdrant<br/>Vector Database")] MINIO[("MinIO<br/>Product/Attachment")] REDIS[("Redis")] NATS[("NATS")] end UI -->|HTTP/SSE| API ext -->|polling| SCH API --> DISP -->|gRPC streaming| GRAPH SCH --> DISP GRAPH --> REACT & PLAN & RAG GRAPH --> TOOLS & MEM GRAPH -->|astream_events| HUB HUB -->|SSE/WS| UI HUB --> PG MEM --> PG RAG --> QD TOOLS --> MINIO OBS -.-> API ``` **Go Control Plane**: API / Streaming (SSE/WS), concurrency and scheduling (goroutine + semaphore + context cancellation), back pressure/load shedding, execution fact recording and historical replay distribution, connector/event-driven, health and observability, key and multi-tenancy. **Python Cognition Plane**: use LangGraph to express ReAct / Plan-Execute / Agentic RAG as **graphs**, bearing tools (local / MCP / Skill), skills and SOP, memory, model routing. --- ## Two core data flows ### Flow A: User-initiated requests (synchronous, streaming) ```mermaid sequenceDiagram participant U as Frontend participant G as Go Control Plane participant P as Python Cognition Plane participant DB as Event Ledger(PG) U->>G: POST /runs (query, sessionId) G->>G: Authentication + session attribution + apply concurrent quota<br/>(semaphore full 429 elegant busy) G->>P: gRPC streaming Run(RunRequest) P->>P: assemble State → select graph (ReAct/Plan) → execution<br/>each step checkpoint (interruptible/recoverable/forked) loop astream_events event by event P-->>G: thought / tool_calls / plan / result / token G->>DB: first storage (fact ledger) G-->>U: then push via SSE end Note over G,U: replay GET /runs/{id}/events and real-time frame-by-frame consistent ``` ### Flow B: External events proactively trigger (Proactive) ```mermaid sequenceDiagram participant EXT as GitHub participant POLL as Poller(Go) participant G as Dispatcher participant P as Cognition Plane participant U as User POLL->>EXT: polling (PAT, incremental cursor) EXT-->>POLL: new event (issue/@…) POLL->>POLL: normalize → match trigger rules → render query POLL->>G: dispatch.Run (same entry as timing trigger) G->>P: start an agent run(draft reply/action) P->>P: hit high-risk action → HITL suspended Note over U: user approval → resume run complete action ``` --- ## Single Agent internal and multi-Agent collaboration ### Single Agent: ReAct loop One Agent internally is a "think → act → observe" loop graph: model thinks and decides which tool to call, tool results are used as observations and fed back, looping until a conclusion is reached. Typed State (equivalent to AgentContext) carries messages, tools, and artifacts; each step falls into checkpoint, naturally interruptible, recoverable. ```mermaid flowchart LR START([User Question]) --> THINK{think<br/>model reasoning} THINK -->|needs tool| ACT[act<br/>call tool] ACT -->|observation result| THINK THINK -->|already answered| DONE([Conclusion]) ACT -.artifact.-> ART[(artifact)] ``` ### Multi-Agent: Plan-Execute + Send Fan-out Complex tasks are broken down into multiple sub-tasks by the planner, which are then **parallelized and sent out** to multiple executor subgraphs via LangGraph's `Send` feature, allowing for **independent execution** (isolated, with timeouts, and failure degradation). The results are then **merged back** to the main state via a reducer, based on which the planner decides to continue, replan, or conclude. This is a typical example of "framework handling fan-out, with user control over width/budget/merging/ownership". ```mermaid flowchart TB Q([Complex Task]) --> PLANNER[planner<br/>break down sub-tasks + decide to continue/replan] PLANNER -->|Send fan-out| E1[executor subgraph #1] PLANNER -->|Send fan-out| E2[executor subgraph #2] PLANNER -->|Send fan-out| E3[executor subgraph #3] E1 --> REDUCER[State reducer<br/>exchangeable and combinable merging] E2 --> REDUCER E3 --> REDUCER REDUCER --> PLANNER PLANNER -->|conclude| SUMMARY[summary] --> FIN([final product]) ``` **Three-level concurrency**: request-level (Go goroutine + semaphore), task-level (LangGraph `Send` parallel sub-tasks), and tool-level (tool invocation within subgraphs) — each level has backpressure and ownership control. ## Capability Panorama ### Orchestration and Execution - **Three modes of reasoning**: quick (ReAct) / in-depth thinking (Plan-Execute + parallel sub-tasks) / in-depth research (multi-round retrieval-verification-citation). - **Dynamic replanning**: the planner decides to continue, replan, or conclude based on sub-task results. - **Recoverable execution**: each step has a checkpoint, and long tasks can be interrupted and continued. ### Tools and Artifacts - **Unified tool ecosystem**: local tools / MCP (stdio·sse·streamable_http three transmissions, with preheating+caching+serialization) / Skill (SKILL.md progressive disclosure + sandbox script runner). - **Artifact registration and reuse**: tool artifacts are stored in object storage, attributed to run/tool_calls, and can be reused across tools; cross-session artifact gallery (cursor pagination). - **Production skills**: data analysis (DuckDB) / charting / PPT / web design / image style library / GitHub in-depth research. ### Knowledge and Memory - **Agentic RAG**: Qdrant dense+sparse hybrid retrieval (RRF fusion) + multi-round reflection + rerank + citation generation. - **User knowledge base closed loop**: attachment upload → automatic入库 → citation answering → panel management (deletion only affects subsequent retrieval). - **Enhanced document parsing**: text/docx/xlsx/PDF; **image and scanned PDF page-by-page vision OCR**; **PDF table → markdown, multi-column reading order restoration, formula whole-page coverage**. - **Session memory and continuation**: LangGraph thread checkpoint multi-round memory + server-side session ledger + cross-device consistency. - **Session fork / time travel**: from any historical round, fork out a parallel session, inheriting previous memory, evolving independently. ### Multimodality and Generation - **Multimodal input**: image (vision gated), table file citation. - **Image generation workspace**: text-to-image / image-to-image / **inpaint local re-painting (canvas mask + `/images/edits` mask)** / generated image inline into webpage. ### Active and Collaborative - **HITL human approval**: approval=run boundary, pause-recovery cross-dual plane consistency, decision entry ledger. - **Scheduled triggering**: cron-style schedules, automatic headless run at designated time. - **Proactive connector**: GitHub PAT polling → trigger rules → automatic agent activation → high-risk actions subject to approval. ### Engineering - **Multi-user + RBAC**: password login + two roles + management backend (user / all runs / system statistics). - **Observability**: Prometheus metrics (concurrency/backpressure/duration/tokens/scheduling) + OTel cross-plane link tracing + Grafana dashboard + cost panel. - **Health and backpressure**: `/healthz` aggregated probe; under concurrency limit, "elegant busy" (429) instead of avalanche. - **One-click deployment**: `make stack-up` single-port complete platform; E2E Playwright browser testing. > Placeholder screenshots (to be supplemented): `docs/assets/generate-workspace.png` (image generation workspace + mask editor), `docs/assets/gallery.png` (artifact gallery), `docs/assets/kb.png` (knowledge base management), `docs/assets/admin.png` (management backend), `docs/assets/grafana.png` (Grafana dashboard), `docs/assets/fork.png` (session fork divider). ## Observability ```mermaid flowchart LR subgraph app["pro-agent"] M["/metrics<br/>myagent_ metrics"] T["OTel trace<br/>one run one span cross-plane"] end M -->|scrape| PROM[(Prometheus)] T -->|OTLP| TEMPO[(Tempo)] PROM --> GRAF[Grafana dashboard] TEMPO --> GRAF ``` - **Metrics** (Prometheus, enabled by default): run concurrency level / terminal count / duration quantile / 429 rejection / tokens / SSE frames / scheduling / connection pool — quantify "elegant busy" and throughput. - **Link tracing** (OTel, config-gated default off): one run = one trace, cross Go↔Python one chain, trace_id associates two-plane structured logs. - **Dashboard**: `deploy/observability/` provides Grafana datasource + dashboard JSON (provisioning reproducible). ## Tech Stack | Layer | Technology | | --- | --- | | **Control Plane (Go)** | chi (HTTP routing) · pgx (PostgreSQL driver) · gRPC (cross-plane streaming) · x/sync semaphore (concurrency admission) · prometheus/client_golang (metrics) · OpenTelemetry (link tracing) · AES-GCM + bcrypt (credential encryption/password hashing) · minio-go (object storage client) | | **Cognitive Plane (Python)** | LangGraph (graph orchestration / checkpoint / `Send` fan-out / interrupt) · LangChain (tool and message abstraction) · grpcio (gRPC service) · pydantic-settings (configuration) · MCP SDK (three transmissions tool) · pdfplumber / pypdf / pypdfium2 / Pillow (document and image parsing) · fastembed (local embedding) · DuckDB (data analysis skill) · qdrant-client | | **Model** | LLM: **Claude** + **DeepSeek** (layered routing, strong model planning / cost-effective model execution) · Image generation: **gpt-image** (provider abstraction, switchable) · Vision OCR (image / scanned PDF transcription) | | **Data and Storage** | **PostgreSQL** (business + event ledger + LangGraph checkpoint) · **Qdrant** (dense+sparse hybrid retrieval, RRF fusion) · **MinIO** (artifact / attachment object storage) · **Redis** (cache) · **NATS** (event bus) | | **Observability** | **Prometheus** (metrics) · **OpenTelemetry** + **Tempo** (link tracing) · **Grafana** (dashboard) | | **Frontend** | **React 19** · **TypeScript** · **Vite** · **Tailwind CSS v4** · **shadcn/ui** · SSE streaming (native fetch handwriting parsing) | | **Testing** | Go `testing` (including `-race`) · pytest (offline contract + fake model) · vitest (pure logic) · **Playwright** (browser E2E) | | **Deployment** | **Docker Compose** (one-click complete dependency + business service single-port hosting) | ## Quick Start ```bash # 1. Start dependencies (PostgreSQL / Qdrant / Redis / MinIO / NATS) make infra-up # 2. Configure: cp -n deploy/.env.example deploy/.env, fill in LLM/image generation API Key # 3a. Development mode (three terminals) make cognition # cognitive plane gRPC :50051 make control # control plane HTTP/SSE :8080 make web # frontend Vite :5173 # 3b. Or one-click complete platform (Go single-port hosting frontend) make stack-up # → http://localhost:8080 # No Key smoke test: COGNITION_FAKE_MODEL=1 make stack-up # Full testing: make check Browser E2E: make e2e ``` ## Directory Structure ``` pro-agent/ ├── control-plane/ # Go control plane (API/scheduling/concurrency/streaming/ledger/connector/observability/authentication) ├── cognition/ # Python cognitive plane (LangGraph graph/tool/skill/RAG/memory/routing) ├── web/ # frontend (React + TS + shadcn/ui) ├── deploy/ # docker-compose + observability provisioning └── proto/ # Go↔Python gRPC contract (event flow schema) ``` ## Roadmap Delivered: dual orchestration · tool ecosystem (local/MCP/Skill) · Agentic RAG · memory and replay · session continuation and fork · multimodal and knowledge base · three modes and production skills · image generation workspace (including inpaint) · HITL approval · scheduled/event triggering · cost panel · Prometheus + OTel + Grafana observability · multi-user RBAC and management backend · Playwright E2E. Planned: data analysis NL2SQL / TableRAG · Gmail/Feishu connector (OAuth) · complete Eval system · true sandbox (gVisor/microVM) · MinerU-grade layout analysis · long-term memory+user portrait self-evolution · more comprehensive intelligent agent strategy collaboration, tool combination, model routing, observability, and management platform, etc.