aegis-psych-agent

<h1 align="center">Aegis Psych Agent</h1> <p align="center"> Multi-Agent Risk Identification and Intervention Collaboration Platform for Campus Psychological Support </p> <p align="center"> <a href="https://github.com/m4rklee/aegis-psych-agent"><img alt="GitHub repo" src="https://img.shields.io/badge/GitHub-aegis--psych--agent-181717?logo=github"></a> <img alt="Python" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white"> <img alt="FastAPI" src="https://img.shields.io/badge/FastAPI-Backend-009688?logo=fastapi&logoColor=white"> <img alt="MCP" src="https://img.shields.io/badge/FastMCP-Tools-4B5563"> <img alt="Tests" src="https://img.shields.io/badge/Pytest-43%20passed-0A7C42"> <img alt="RAG Eval" src="https://img.shields.io/badge/RAG%20Eval-66%20cases-2563EB"> </p> ## Project Overview `Aegis Psych Agent` is a multi-agent platform for campus psychological support, focusing on student complaints, psychological knowledge retrieval, risk identification, counselor workstations, and high-risk tool execution. The project is not just a simple chatbot but a comprehensive system that separates "student-side instant support" and "management-side auditable intervention" into two independent information architectures, unified by the backend Agent Runtime Harness. During the design process, three main issues were addressed: - Ordinary chat should not be overly retrieved or overly toolized to avoid invalid recall affecting response quality. - High-risk expressions must enter an auditable process, and tool execution requires human review, desensitization, retry, and dead letter mechanisms. - Multi-agent collaboration cannot only stay in sequential calls, requiring shared state, task claiming, artifact acceptance, and runtime trace. > Safety Statement: This project is used for psychological support and engineering demonstrations, not providing medical diagnosis or replacing professional psychological counseling or crisis intervention services. In high-risk scenarios, the system only performs risk identification, auxiliary summarization, and referral suggestions, and final intervention should be completed by qualified personnel. ## Core Highlights | Module | Problem Solved | Implementation | | --- | --- | --- | | Dual-end Independent Interface | Student complaint experience and administrator disposal process have different focuses, making product boundaries confusing if mixed | `/student` provides student dialogue and session memory, `/admin` provides report, case, trace, knowledge base, tool queue, and assessment workstation | | Agent Runtime Harness | Agent calls, context injection, risk reporting, and tool planning are scattered in business code, making auditing difficult | `AegisAgentHarness` uniformly encapsulates input desensitization, runtime calls, trace saving, message persistence, report generation, and tool planning | | Autonomous Multi-Agent Collaboration | Single Lead Agent serial dispatch easily becomes "pseudo-collaboration," and complex scenarios lack intermediate artifacts | Based on append-only blackboard, implements task publishing, agent claiming, artifact output, risk override, and final acceptance, not relying on LangGraph | | MemoryAgent | Psychological support needs continuity, and single-turn replies cannot reflect understanding of user state | Independent `MemoryAgent` maintains session summary and recent context, injecting memory as agent collaboration input | | Agentic RAG | Retrieving knowledge base for all messages increases noise, especially ordinary companion conversations easily deviating due to knowledge documents | Through CHAT / CONSULT / RISK intent routing, decides whether to retrieve, combining BM25 + vector retrieval, and supports metadata filtering and rerank | | Tool Governance and MCP | High-risk alerts, Excel records, email notifications cannot be directly executed by models without permission | Tool calls first generate `ToolJob`, which, after role, risk level, approval, desensitization, and auditing, enters the queue; supports internal and FastMCP backends | | Background Tool Queue | External tools slow, failed, or rate-limited should not block student-side streaming replies | Independent worker supports dependency scheduling, retry delay, email rate limiting, dead letter, ExcelRecord, and AlertRecord persistence | | Engineering Harness | Agent projects only seeing demos easily overestimates completion; needs repeatable verification | Provides pytest, RAG eval, comprehensive eval, and harness runner, covering routing, risk, safety, RAG, API, tool queue, and other links | ## Architecture Overview ```mermaid flowchart LR Student["Student End /student"] --> API["FastAPI API Layer"] Admin["Admin End /admin"] --> API API --> Harness["AegisAgentHarness"] Harness --> Runtime["Autonomous Blackboard Runtime"] Runtime --> Memory["MemoryAgent"] Runtime --> Lead["Lead / Supervisor Agent"] Runtime --> Risk["RiskGuardianAgent"] Runtime --> Knowledge["KnowledgeAgent"] Runtime --> Counselor["CounselorAgent"] Runtime --> Companion["CompanionAgent"] Knowledge --> RAG["Hybrid RAG<br/>BM25 + Vector + Rerank"] Harness --> Store["SQLite / PostgreSQL<br/>messages, memory, reports, traces"] Harness --> ToolPlan["Governed ToolJob"] ToolPlan --> Queue["Tool Queue Worker"] Queue --> MCP["FastMCP / internal tools"] MCP --> Outputs["Excel, Alert, Email, Handoff, Audit"] Admin --> Eval["Eval & Harness Reports"] Eval --> Store ``` ## Function List ### Student End - Login, logout, session creation, session renaming, and session deletion. - SSE streaming psychological support replies, compatible with non-streaming `/api/chat`. - Low-risk companionship, psychological counseling suggestions, and high-risk safety responses. - Session-level memory summary, supporting multi-turn context continuity. - High-risk content not exposing internal report fields to students to avoid secondary harm or information leakage. ### Admin End - Risk report list, status transition, and report trace viewing. - Case creation, counselor confirmation, remark addition, and status update. - Knowledge base retrieval, file upload, index rebuilding, and vector index rebuilding and backup. - Independent viewing of ToolJob, ToolAudit, ExcelRecord, AlertRecord, and DeadLetter. - Agent model configuration status, agent private memory, and runtime state viewing. - One-click triggering of comprehensive assessment and harness verification. ### Agent Collaboration - `MemoryAgent`: loads and updates session memory. - `LeadAgent / SupervisorAgent`: identifies intent and decides collaboration path. - `RiskGuardianAgent`: risk grading, safety override, and high-risk report generation. - `KnowledgeAgent`: retrieves knowledge base according to intent and risk level, injecting standard Skill. - `CounselorAgent`: generates counseling support plans and trackable replies. - `CompanionAgent`: handles low-risk companionship and emotional support conversations. ### Tools and Governance - FastMCP server: exposes case create, case ack, case note add, alert, ledger, email, handoff, and resource lookup tools. - MCP client: supports switching from platform to MCP backend execution. - Tool contract: restricts role, risk level, approval requirements, desensitization fields, and maximum retries. - Background worker: supports batch claiming, dependency scheduling, failure retry, rate limiting, and dead letter. - Real output: Excel writing, Alert independent record, email sending or log delivery, handoff Markdown file. ## Technical Stack | Layer | Technology | | --- | --- | | Backend API | Python, FastAPI, Pydantic, SQLAlchemy | | Agent Runtime | Self-developed blackboard runtime, agent claim loop, artifact acceptance, runtime trace | | RAG | BM25, vector retrieval, Chroma optional backend, metadata filter, rerank | | Tool Protocol | FastMCP, governed ToolJob, background worker | | Storage | SQLite local mode, optional PostgreSQL, optional Redis lock | | Frontend | Native HTML/CSS/JavaScript, student/admin dual-end pages | | Engineering Verification | pytest, custom eval runner, RAG eval runner, harness runner | | Deployment | Dockerfile, docker-compose | ## Quick Start ### Local Running ```bash git clone https://github.com/m4rklee/aegis-psych-agent.git cd aegis-psych-agent python -m venv .venv source .venv/bin/activate pip install -r requirements.txt cp .env.example .env python -m app.init_db uvicorn app.main:app --host 127.0.0.1 --port 8091 ``` Open browser to: - Homepage: [http://127.0.0.1:8091](http://127.0.0.1:8091) - Student End: [http://127.0.0.1:8091/student](http://127.0.0.1:8091/student) - Admin End: [http://127.0.0.1:8091/admin](http://127.0.0.1:8091/admin) Default demo accounts: | Role | Username | Password | | --- | --- | --- | | Student | `student` | `student123!` | | Admin | `admin` | `admin123!` | ### Docker Compose ```bash docker compose up --build ``` Compose will start the application, PostgreSQL, Redis, and Chroma. The default local mode uses SQLite; if you want to switch to a database or vector backend, adjust `DATABASE_URL`, `VECTOR_ENABLED`, `VECTOR_BACKEND`, etc., in `.env`. ## Common Commands ```bash # Initialize database python -m app.init_db # Backend testing python -m pytest -q # Frontend script syntax check node --check static/app.js static/student.js static/admin.js # Comprehensive evaluation python -m eval.run_eval # RAG independent evaluation python -m app.rag_eval.runner # Engineering harness verification python -m app.harness.runner --suite all --output data/harness/latest.json # View MCP capabilities python -m app.mcp_tools.server --list ``` ## Evaluation Results The current repository contains a set of repeatable engineering verification scripts, not relying on human clicks on demos to judge effectiveness. | Verification Item | Covered Content | Recent Verification Result | | --- | --- | --- | | Unit and Interface Test | API, authentication, risk identification, agent runtime, MCP tools, evaluation runner | `43 passed` | | RAG Independent Evaluation | 66 multi-theme psychological support retrieval samples, including expected source and expected terms | `HitRate 1.0000`, `MRR 0.9924`, `NDCG@K 0.9722` | | Comprehensive Evaluation | Routing, risk, safety, skill, multi-turn, RAG summary, scaled benchmark | `all_passed=true`, `scaled_benchmark_total=150` | | Harness Verification | Risk Safety, Agent Routing, Standard Skills, RAG, API, Tool Queue, etc. | `7/7 passed` | > Evaluation data is used for engineering regression and capability demonstration, not equivalent to clinical effectiveness evaluation. ## Directory Structure ```text . ├── app/ │ ├── agent_harness.py # Runtime Harness entry │ ├── autonomous_runtime.py # blackboard Agent collaboration runtime │ ├── autonomous_agents.py # Memory / Lead / Risk / Knowledge / Counselor / Companion │ ├── mcp_tools/server.py # FastMCP tool service │ ├── rag_eval/ # RAG independent evaluation data and runner │ ├── services/ # report/case, tool executor, queue, audit records │ └── knowledge/ # Built-in psychological support knowledge base ├── eval/ # Routing, risk, safety, multi-turn, retrieval evaluation ├── skills/ # Standardized psychological support Skill specification ├── static/ # Student end and admin end pages ├── tests/ # pytest testing ├── docs/ # Architecture, safety, and demonstration documents ├── Dockerfile └── docker-compose.yml ``` ## API Summary | Type | Interface | | --- | --- | | Authentication | `POST /api/auth/login`, `POST /api/auth/logout`, `GET /api/auth/me` | | Student Session | `GET /api/sessions`, `POST /api/sessions`, `GET /api/sessions/{id}`, `PATCH /api/sessions/{id}` | | Chat | `POST /api/chat`, `POST /api/chat/stream` | | Admin Report | `GET /api/admin/reports`, `PATCH /api/admin/reports/{report_id}` | | Case | `GET /api/admin/cases`, `POST /api/admin/cases/{case_id}/notes`, `PATCH /api/admin/cases/{case_id}` | | Tool Queue | `GET /api/admin/tool-jobs`, `POST /api/admin/tool-jobs/run`, `GET /api/admin/tool-worker/status` | | Tool Audit | `GET /api/admin/tool-audits`, `GET /api/admin/excel-records`, `GET /api/admin/alert-records`, `GET /api/admin/dead-letters` | | Knowledge Base | `GET /api/admin/knowledge/search`, `POST /api/admin/knowledge`, `POST /api/admin/knowledge/rebuild-vector` | | Evaluation | `GET /api/admin/eval-results`, `POST /api/admin/eval-results/run` | ## Environment Variables | Variable | Description | | --- | --- | | `AI_PROVIDER` | `mock`, `openai`, or `ollama`. Default supports local demonstration without API key | | `DATABASE_URL` | Default `sqlite:///data/aegis.sqlite`, can switch to PostgreSQL | | `VECTOR_ENABLED` | Whether to enable vector retrieval | | `VECTOR_BACKEND` | Vector backend, supports local or Chroma configuration | | `TOOL_BACKEND` | `internal` or `mcp` | | `MCP_ENABLED` | Whether to enable MCP tool path | | `TOOL_QUEUE_*` | Background tool worker polling, batch, thread, and retry configuration | | `SMTP_*` | Email alert sending configuration | | `ALERT_EMAIL_*` | High-risk alert email delivery configuration | | `AUTH_DEFAULT_*` | Default student and admin accounts | ## Design Trade-offs - Not using LangGraph: To clearly demonstrate the agent collaboration mechanism, this project adopts a self-developed blackboard runtime. Each agent participates in collaboration through claim and artifact, and the trace can be stored and replayed. - Not directly connecting tools to the student end: High-risk tool execution all goes through ToolJob to avoid models directly triggering external actions in streaming replies. - Not performing RAG on all inputs: First, do intent routing, and only consult and risk scenarios trigger knowledge retrieval; ordinary companionship conversations emphasize listening and emotional support. - Default local running: Without external API keys, it can complete end-to-end demonstration; after accessing OpenAI, Ollama, Chroma, Redis, SMTP, you can switch to a more production-like configuration. ## Documents - [Architecture Description](docs/architecture.md) - [Safety Design](docs/safety-design.md) - [Demonstration Script](docs/demo-script.md) ## License The current repository does not declare an open-source license. Without the author's permission, please do not use the code for commercial distribution or production psychological counseling services.