Content
align="center">
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=30&duration=2800&pause=900&color=6366F1¢er=true&vCenter=true&width=760&lines=EverLoop;Agent+Runtime+%2B+MCP+%2B+Skills;Loop-first+Autonomous+Agent+Framework" alt="EverLoop" />
<br/>
**A loop-first autonomous agent runtime framework, integrating MCP, Skill, function calling validation, memory system, and streaming runtime tracing.**
<br/>
](https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white://python.org)
[](https://fastapi.t.com)
[](https://react.dev)
[](https://typescriptlang.orgChain](https://.io/badge/LangChain1C3C3C?style=for-the-badge&logoColorhttps://www.langchain.com/)
<br/>
**Agent Loop | MCP Runtime | Skill System | Function Calling | SSE Trace**
</div>
---
## Project Overview
EverLoop is an engineering runtime framework for autonomous agents. It's not just a simple chat shell, but a stable `AgentLoop`-centric architecture that integrates context management, tool execution, MCP access, skill orchestration, memory systems, and frontend runtime tracing.
It focuses on core issues: how agents maintain stability, controllability, and observability during multi-turn reasoning, tool calls, parameter correction, and result integration.
## Core Capabilities
| Area | Description |
|---|---|
| Agent Loop | With `AgentLoop.arun()` as the core, it integrates reasoning, validation, tool execution, and observation write-back into a single loop. |
| Function Calling | `tools_schema` for LLM, `tools_map` for runtime execution, avoiding mixing "what the model sees" and "what the system executes". |
| Tool Validation | Local linter validation of tool names, parameter types, required fields, and suspicious content before actual tool execution. |
| MCP Runtime | MCP Server can be encapsulated as a runtime skill callable by the main agent. |
| Skill System | Skills can encapsulate descriptions, files, templates, scripts, and domain workflows. |
| Streaming Trace | SSE pushes thinking, tool calls, observations, usage, and runtime status to the frontend in real-time. |
---
## Interface Display
### Workspace
The main workspace integrates the conversation entrance, model selection, runtime status panel, and main agent interaction area, serving as the core interface for users to initiate tasks and observe the agent's runtime process.
<div align="center">
<img src="./img/1.png" alt="EverLoop workspace" width="100%" />
</div>
### MCP Center
The MCP management center is used for registering and managing MCP Servers, viewing exposed tool schemas, and integrating external tool capabilities into the EverLoop runtime.
<div align="center">
<img src="./img/2.png" alt="EverLoop MCP center" width="100%" />
</div>
### Skill Workbench
The skill workbench manages local capability packages and MCP-backed skills. For the main agent, skills are callable capability entrances; internally, they can load files, scripts, templates, or call MCP sub-agents.
<div align="center">
<img src="./img/3.png" alt="EverLoop skill workbench" width="100%" />
</div>
### Runtime Trace
The trace view displays the real-time status of the agent loop, including SSE events, tool calls, observations, tool results, and runtime stages, facilitating debugging of complex tasks.
<div align="center">
<img src="./img/4.png" alt="EverLoop runtime trace" width="100%" />
</div>
---
## Quick Start
EverLoop is recommended to be started with a one-click script that launches both the backend and frontend:
```bash
sh start.sh
```
Default addresses:
```text
Frontend: http://localhost:5173
Backend: http://127.0.0.1:8001
API docs: http://127.0.0.1:8001/docs
```
### Environment Requirements
- Conda
- Python 3.10+
- Node.js 18+
- OpenAI-compatible LLM endpoint
By default, `start.sh` uses a conda environment named `agent`.
To create an environment:
```bash
conda create -n agent python=3.11
```
To use another conda environment:
```bash
EVERLOOP_CONDA_ENV=my-env sh start.sh
```
To skip LLM health checks at startup:
```bash
EVERLOOP_CHECK_LLM=0 sh start.sh
```
---
## Configuration
EverLoop reads model, authentication, and database configurations from `.env`.
```env
DEFAULT_MODEL=qwen3-32b
LLM_ENDPOINT__qwen3-32b=https://your-openai-compatible-endpoint/v1/chat/completions
LLM_API_KEY__qwen3-32b=your_api_key
JWT_SECRET_KEY=change-this-secret
DATABASE_URL=sqlite+aiosqlite:///./everloop.db
```
Model names are dynamic. Each model requires a set of endpoint and API key configurations:
```text
LLM_ENDPOINT__<model_name>
LLM_API_KEY__<model_name>
```
Then set the default model:
```text
DEFAULT_MODEL=<model_name>
```
Common startup variables:
| Variable | Default | Description |
|---|---:|---|
| `EVERLOOP_CONDA_ENV` | `agent` | Conda environment used by the startup script. |
| `EVERLOOP_BACKEND_HOST` | `127.0.0.1` | Backend listening address. |
| `EVERLOOP_BACKEND_PORT` | `8001` | Default backend port. |
| `EVERLOOP_BACKEND_WAIT_SECONDS` | `120` | Maximum time to wait for the backend to be ready. |
| `EVERLOOP_CHECK_LLM` | `1` | Set to `0` to skip LLM health checks. |
| `EVERLOOP_STARTUP_CLEANUP` | `1` | Set to `0` to skip startup cleanup. |
---
## Architecture
```mermaid
flowchart TD
U[User Request] --> API["POST /api/chat/stream"]
API --> AGENT["create_agent_for_request()"]
AGENT --> TOOLS["Builtin Tools + Package Skills + Runtime MCP Skills"]
TOOLS --> LOOP["AgentLoop.arun()"]
LOOP --> CTX["ContextPipeline.prepare()"]
CTX --> MEM["STM / LTM / Compression / Env State"]
MEM --> LLM["LLM with tools_schema"]
LLM --> DECIDE{"Tool calls?"}
DECIDE -- No --> ANSWER["Final Answer"]
DECIDE -- Yes --> LINT["Function-call Linter"]
LINT -->|valid| EXEC["Execute via tools_map"]
LINT -->|invalid| RETRY["Validation feedback"]
EXEC --> OBS["ToolMessage / Observation"]
RETRY --> LOOP
OBS --> LOOP
LOOP --> SSE["Typed SSE Stream"]
SSE --> UI["React Frontend"]
```
---
## Agent Loop
EverLoop explicitly breaks down the agent's core lifecycle: context preparation, model inference, tool validation, tool execution, result write-back, and next-round inference are all clearly happening in the loop.
```mermaid
flowchart TD
A["Load STM / LTM / env state"] --> B["Prepare compressed context"]
B --> C["LLM inference with tools_schema"]
C --> D{"Tool calls?"}
D -- No --> E["Return final response"]
D -- Yes --> F["Validate arguments"]
F --> G{"Valid?"}
G -- No --> H["Write validation feedback"]
G -- Yes --> I["Execute via tools_map"]
I --> J["Write observation"]
H --> B
J --> B
```
This design makes tool selection, parameter validation, execution results, and error recovery all visible and rather than hidden in a model response.
---
## Function Calling
EverLoop separates "tool definitions seen by the model" and "functions actually executed at runtime".
| Component | Description |
|---|---|
| `tools_schema` | Tool schema passed to LLM, including name, description, and parameter structure. |
| `tools_map` | Runtime tool mapping, responsible for mapping tool actual Python functions or. |
| `fc_validator.py` | Local before tool execution. |
_validator.py` checks if tools exist, parameters are JSON objects, required fields are not missing, types match, there are no extra parameters, and if content is present. If, errors are written back as feedback to the next round of the agent loop, allowing the model to correct calls.
---
## Skill System
Skills are capability packages that can expose descriptions, files, scripts, templates, and domain-specific workflow contexts to agents.
```mermaid
flowchart TD
A[User Request] --> B["Match skill description"]
B --> C["Read SKILL.md"]
C --> D["Load references / assets / scripts"]
D --> E["Run local tools if needed"]
E --> F["Return result to agent loop"]
```
EverLoop supports two types of skills:
| Skill Type | Description |
|---|---|
| Package Skill | Local capability packages, suitable for encapsulating fixed workflows, document templates, and scripts. |
| Runtime MCP Skill | Dynamic skills based on MCP Servers, appearing as callable tools to the main agent. |
---
## MCP Runtime
EverLoop uses MCP as a client-server protocol for external tools. The main agent calls MCP skills, and MCP sub-agents select actual tools exposed by MCP Servers based on specific tasks.
```mermaid
flowchart TD
A[User Request] --> B["Main Agent"]
B --> C["Call skill_xxx"]
C --> D["runtime_mcp_skills._invoke_skill()"]
D --> E["MCPAgent.ainvoke()"]
E --> F["Parse MCP tool schema"]
F --> G["Child LLM selects MCP tool"]
G --> H["Validate tool args"]
H --> I["mcp_client.call_tool()"]
I --> J["Observation returns to main Agent"]
```
Prefer standard JSON-RPC MCP:
- `initialize`
- `notifications/initialized`
- `tools/list`
- `tools/call`
Also compatible with old REST-style interfaces:
- `GET /tools/list`
- `POST /tools/call`
---
## Streaming Observability
The backend pushes runtime events to the frontend through typed SSE packets, allowing users to see agents thinking, calling tools, receiving observations, or entering certain loop stages.
| Packet Type | Description |
|---|---|
| `think` | Thinking content stream. |
| `think_end` | End of thinking stage. |
| `text` | Final answer text stream. |
| `text_replace` | Cleaned and replaced text that has been streamingly output. |
| `loop_status` | Current runtime stage. |
| `tool_calls_start` | Tool call start. |
| `tool_calls_done` | Tool call completion. |
| `observation` | Standardized tool return results. |
| `usage_update` | Token and cost estimation updates. |
| `control` | Streaming lifecycle events. |
---
## Project Structure
```text
EverLoop/
|-- api/ FastAPI routes: chat, auth, MCP, skill
|-- core/ Agent loop, context pipeline, streaming handler
|-- database/ SQLAlchemy models, CRUD, persistence
|-- function_calling/ Tool registry and function-call validation
|-- harness_framework/ Runtime plugins, guards, cleanup daemons
|-- init/ Agent assembly and runtime initialization
|-- llm/ Model factory and provider configuration
|-- mcp_ecosystem MCP client, server manager-agent pipeline
|-- memory/ Short-term and long-term memory layers
|-- skill_system/ Package skills and runtime MCP skills
|-- frontend/ React + TypeScript UI
|-- scripts/ Startup and health-check helpers
`-- main.py FastAPI application entrypoint
```
---
## Tech Stack
| Layer | Stack |
|---|---|
| Backend | Python, FastAPI, LangChain, SQLAlchemy |
| Frontend | React, TypeScript, Vite, Zustand |
| Agent Runtime | Custom AgentLoop, function-call validator, MCP child agent |
| Memory | STM, LTM, vector-store-ready retrieval |
| Streaming | Server-Sent Events with typed packets |
---
<div align="center">
<sub>Built for agent systems that need to keep thinking, calling tools, and recovering in the same loop.</sub>
</div>
Connection Info
You Might Also Like
No recommendations available