# ichliebewxy/agent_console architecture

> Architecture diagram of the GitHub repository ichliebewxy/agent_console, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ichliebewxy/agent_console
- Repository: https://github.com/ichliebewxy/agent_console

## Overview

Agent Console is a local multi-agent and RAG workspace. The main workflow streams a user chat through the FastAPI chat route to the agent, which loads session history and may answer directly, use tools, search knowledge, or delegate to a skill agent; results and traces return over SSE and are persisted. Separate product paths manage document ingestion and hybrid retrieval, durable plan-and-execute runs, and long-term memory. The README documents capabilities beyond the sampled excerpts; those branches are included at supported module paths, while uncertain internal wiring is omitted.

Main entry points: [`backend/agent.py`](https://github.com/ichliebewxy/agent_console/blob/main/backend/agent.py) (Main Agent), [`backend/routes_documents.py`](https://github.com/ichliebewxy/agent_console/blob/main/backend/routes_documents.py) (Document API), [`backend/rag_pipeline.py`](https://github.com/ichliebewxy/agent_console/blob/main/backend/rag_pipeline.py) (RAG Pipeline), [`backend/retrieval_steps.py`](https://github.com/ichliebewxy/agent_console/blob/main/backend/retrieval_steps.py) (Hybrid Retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api_ui["Console and API"]
  node_frontend["Web Console<br/>[chat.js]"]
  node_app["FastAPI App<br/>[app.py]"]
  node_chat_route["Chat Route<br/>[routes_chat.py]"]
end

subgraph group_agent_tools["Agent and Tools"]
  node_agent["Main Agent<br/>[agent.py]"]
  node_core_tools["Core Tools<br/>[core_tools.py]"]
  node_bash["Reviewed Bash<br/>[bash_tool.py]"]
  node_skill_gateway["Skill Delegation<br/>[subagents.py]"]
  node_skill_catalog["Skills Catalog<br/>[skill_service.py]"]
  node_mcp["MCP Tools<br/>[mcp_service.py]"]
end

subgraph group_knowledge["Knowledge Base"]
  node_docs_route["Document API"]
  node_loader["Document Parsing<br/>[document_loader.py]"]
  node_embedding["Chunk Embeddings<br/>[embedding.py]"]
  node_milvus[("Vector Index<br/>[milvus_client.py]")]
  node_parent_store[("Parent Chunks")]
  node_rag_tool["Knowledge Search Tool<br/>[search_tool.py]"]
  node_rag["RAG Pipeline<br/>[rag_pipeline.py]"]
  node_retrieval["Hybrid Retrieval<br/>[retrieval_steps.py]"]
  node_expanded["Expanded Retrieval<br/>[rag_expanded.py]"]
end

subgraph group_workflows["Durable Workflows"]
  node_workflow["Plan and Execute<br/>[workflow_graph.py]"]
  node_checkpoint[("Run Checkpoints")]
  node_run_routes["Run Controls<br/>[routes_runs.py]"]
end

subgraph group_state["Memory and State"]
  node_conversation[("Session History")]
  node_memory[("Long-term Memory<br/>[memory_service.py]")]
  node_extract["Memory Extraction"]
  node_artifacts["Session Artifacts"]
end

node_user(("User"))

node_user -->|"sends message"| node_frontend
node_frontend -->|"posts chat"| node_chat_route
node_chat_route -->|"invokes"| node_agent
node_agent -->|"loads and saves"| node_conversation
node_agent -->|"searches context"| node_memory
node_agent -->|"dispatches tools"| node_core_tools
node_core_tools -->|"uses guarded shell"| node_bash
node_agent -->|"delegates"| node_skill_gateway
node_skill_gateway -->|"loads skills"| node_skill_catalog
node_agent -->|"invokes discovered tools"| node_mcp
node_agent -->|"starts complex runs"| node_workflow
node_workflow -->|"checkpoints state"| node_checkpoint
node_run_routes -->|"inspects and resumes"| node_checkpoint
node_run_routes -->|"projects run state"| node_conversation
node_agent -->|"calls search tool"| node_rag_tool
node_rag_tool -->|"runs query"| node_rag
node_rag -->|"retrieves documents"| node_retrieval
node_rag -->|"retries expanded query"| node_expanded
node_retrieval -->|"hybrid searches"| node_milvus
node_retrieval -->|"loads parent context"| node_parent_store
node_docs_route -->|"parses uploads"| node_loader
node_docs_route -->|"chunks and embeds"| node_embedding
node_docs_route -->|"writes leaf vectors"| node_milvus
node_docs_route -->|"writes parent chunks"| node_parent_store
node_agent -->|"starts after reply"| node_extract
node_extract -->|"deduplicates and writes"| node_memory
node_agent -->|"lists session outputs"| node_artifacts
node_agent -->|"streams response and trace"| node_frontend

click node_frontend "https://github.com/ichliebewxy/agent_console/blob/main/frontend/js/chat.js"
click node_app "https://github.com/ichliebewxy/agent_console/blob/main/backend/app.py"
click node_chat_route "https://github.com/ichliebewxy/agent_console/blob/main/backend/routes_chat.py"
click node_agent "https://github.com/ichliebewxy/agent_console/blob/main/backend/agent.py"
click node_conversation "https://github.com/ichliebewxy/agent_console/blob/main/backend/conversation_storage.py"
click node_memory "https://github.com/ichliebewxy/agent_console/blob/main/backend/memory_service.py"
click node_extract "https://github.com/ichliebewxy/agent_console/blob/main/backend/memory_extraction.py"
click node_core_tools "https://github.com/ichliebewxy/agent_console/blob/main/backend/core_tools.py"
click node_bash "https://github.com/ichliebewxy/agent_console/blob/main/backend/bash_tool.py"
click node_skill_gateway "https://github.com/ichliebewxy/agent_console/blob/main/backend/subagents.py"
click node_skill_catalog "https://github.com/ichliebewxy/agent_console/blob/main/backend/skill_service.py"
click node_mcp "https://github.com/ichliebewxy/agent_console/blob/main/backend/mcp_service.py"
click node_workflow "https://github.com/ichliebewxy/agent_console/blob/main/backend/workflow_graph.py"
click node_checkpoint "https://github.com/ichliebewxy/agent_console/blob/main/backend/checkpoint_service.py"
click node_run_routes "https://github.com/ichliebewxy/agent_console/blob/main/backend/routes_runs.py"
click node_docs_route "https://github.com/ichliebewxy/agent_console/blob/main/backend/routes_documents.py"
click node_loader "https://github.com/ichliebewxy/agent_console/blob/main/backend/document_loader.py"
click node_embedding "https://github.com/ichliebewxy/agent_console/blob/main/backend/embedding.py"
click node_milvus "https://github.com/ichliebewxy/agent_console/blob/main/backend/milvus_client.py"
click node_parent_store "https://github.com/ichliebewxy/agent_console/blob/main/backend/parent_chunk_store.py"
click node_rag_tool "https://github.com/ichliebewxy/agent_console/blob/main/backend/search_tool.py"
click node_rag "https://github.com/ichliebewxy/agent_console/blob/main/backend/rag_pipeline.py"
click node_retrieval "https://github.com/ichliebewxy/agent_console/blob/main/backend/retrieval_steps.py"
click node_expanded "https://github.com/ichliebewxy/agent_console/blob/main/backend/rag_expanded.py"
click node_artifacts "https://github.com/ichliebewxy/agent_console/blob/main/backend/artifact_service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_app,node_chat_route,node_user toneBlue
class node_agent,node_core_tools,node_bash,node_skill_gateway,node_skill_catalog,node_mcp toneAmber
class node_docs_route,node_loader,node_embedding,node_milvus,node_parent_store,node_rag_tool,node_rag,node_retrieval,node_expanded toneMint
class node_workflow,node_checkpoint,node_run_routes toneRose
class node_conversation,node_memory,node_extract,node_artifacts toneIndigo
```

## Components

### Console and API

- [Web Console](https://github.com/ichliebewxy/agent_console/blob/main/frontend/js/chat.js): `frontend/js/chat.js`
- [FastAPI App](https://github.com/ichliebewxy/agent_console/blob/main/backend/app.py): `backend/app.py`
- [Chat Route](https://github.com/ichliebewxy/agent_console/blob/main/backend/routes_chat.py): `backend/routes_chat.py`

### Agent and Tools

- [Main Agent](https://github.com/ichliebewxy/agent_console/blob/main/backend/agent.py): `backend/agent.py`
- [Core Tools](https://github.com/ichliebewxy/agent_console/blob/main/backend/core_tools.py): `backend/core_tools.py`
- [Reviewed Bash](https://github.com/ichliebewxy/agent_console/blob/main/backend/bash_tool.py): `backend/bash_tool.py`
- [Skill Delegation](https://github.com/ichliebewxy/agent_console/blob/main/backend/subagents.py): `backend/subagents.py`
- [Skills Catalog](https://github.com/ichliebewxy/agent_console/blob/main/backend/skill_service.py): `backend/skill_service.py`
- [MCP Tools](https://github.com/ichliebewxy/agent_console/blob/main/backend/mcp_service.py): `backend/mcp_service.py`

### Knowledge Base

- [Document API](https://github.com/ichliebewxy/agent_console/blob/main/backend/routes_documents.py): `backend/routes_documents.py`
- [Document Parsing](https://github.com/ichliebewxy/agent_console/blob/main/backend/document_loader.py): `backend/document_loader.py`
- [Chunk Embeddings](https://github.com/ichliebewxy/agent_console/blob/main/backend/embedding.py): `backend/embedding.py`
- [Vector Index](https://github.com/ichliebewxy/agent_console/blob/main/backend/milvus_client.py): `backend/milvus_client.py`
- [Parent Chunks](https://github.com/ichliebewxy/agent_console/blob/main/backend/parent_chunk_store.py): `backend/parent_chunk_store.py`
- [Knowledge Search Tool](https://github.com/ichliebewxy/agent_console/blob/main/backend/search_tool.py): `backend/search_tool.py`
- [RAG Pipeline](https://github.com/ichliebewxy/agent_console/blob/main/backend/rag_pipeline.py): `backend/rag_pipeline.py`
- [Hybrid Retrieval](https://github.com/ichliebewxy/agent_console/blob/main/backend/retrieval_steps.py): `backend/retrieval_steps.py`
- [Expanded Retrieval](https://github.com/ichliebewxy/agent_console/blob/main/backend/rag_expanded.py): `backend/rag_expanded.py`

### Durable Workflows

- [Plan and Execute](https://github.com/ichliebewxy/agent_console/blob/main/backend/workflow_graph.py): `backend/workflow_graph.py`
- [Run Checkpoints](https://github.com/ichliebewxy/agent_console/blob/main/backend/checkpoint_service.py): `backend/checkpoint_service.py`
- [Run Controls](https://github.com/ichliebewxy/agent_console/blob/main/backend/routes_runs.py): `backend/routes_runs.py`

### Memory and State

- [Session History](https://github.com/ichliebewxy/agent_console/blob/main/backend/conversation_storage.py): `backend/conversation_storage.py`
- [Long-term Memory](https://github.com/ichliebewxy/agent_console/blob/main/backend/memory_service.py): `backend/memory_service.py`
- [Memory Extraction](https://github.com/ichliebewxy/agent_console/blob/main/backend/memory_extraction.py): `backend/memory_extraction.py`
- [Session Artifacts](https://github.com/ichliebewxy/agent_console/blob/main/backend/artifact_service.py): `backend/artifact_service.py`

### Other components

- **User**

## Connections

- User → Web Console: sends message
- Web Console → Chat Route: posts chat
- Chat Route → Main Agent: invokes
- Main Agent → Session History: loads and saves
- Main Agent → Long-term Memory: searches context
- Main Agent → Core Tools: dispatches tools
- Core Tools → Reviewed Bash: uses guarded shell
- Main Agent → Skill Delegation: delegates
- Skill Delegation → Skills Catalog: loads skills
- Main Agent → MCP Tools: invokes discovered tools
- Main Agent → Plan and Execute: starts complex runs
- Plan and Execute → Run Checkpoints: checkpoints state
- Run Controls → Run Checkpoints: inspects and resumes
- Run Controls → Session History: projects run state
- Main Agent → Knowledge Search Tool: calls search tool
- Knowledge Search Tool → RAG Pipeline: runs query
- RAG Pipeline → Hybrid Retrieval: retrieves documents
- RAG Pipeline → Expanded Retrieval: retries expanded query
- Hybrid Retrieval → Vector Index: hybrid searches
- Hybrid Retrieval → Parent Chunks: loads parent context
- Document API → Document Parsing: parses uploads
- Document API → Chunk Embeddings: chunks and embeds
- Document API → Vector Index: writes leaf vectors
- Document API → Parent Chunks: writes parent chunks
- Main Agent → Memory Extraction: starts after reply
- Memory Extraction → Long-term Memory: deduplicates and writes
- Main Agent → Session Artifacts: lists session outputs
- Main Agent → Web Console: streams response and trace