# AgentForge

**Repository Path**: North_Fan/AgentForge

## Basic Information

- **Project Name**: AgentForge
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentForge

**An orchestrable multi-layer agent platform** built on LangChain / LangGraph, delivering the core loop of *MultiAgent orchestration → autonomous execution → service publishing*.

[中文文档](#agentforge---可编排多层智能体平台)

## Overview

AgentForge is an orchestrable multi-layer agent platform for **building, operating and observing complex AI agent systems in production**.

Instead of a single chatbot, you get:

- **Multi‑tenant workspaces** – isolate data, agents and services per tenant with shared infrastructure.
- **SubAgent‑based orchestration** – visually compose coordinator + executor agents with layered SubAgent hierarchies.
- **Pluggable skills** – register reusable atomic skills once, bind them to agents and services many‑to‑many.
- **Memory layer** – long‑term agent memory plus shared memory with vector retrieval.
- **Multiple I/O surfaces** – chat UI, HTTP API, workflows/triggers, scheduled tasks and IM channels.
- **Service publishing** – turn agent graphs into versioned services with API keys and OpenAPI specs.
- **Knowledge base service** – document‑centric retrieval and timelines via a dedicated microservice.

### Feature Highlights

- **Deep observability**
  - Invocation timeline with per‑step status, tool calls, tokens and durations.
  - Per‑agent debug panel showing routed messages, tool inputs/outputs and LLM request payloads.
  - Static execution graph + per‑invocation highlighting of the exact path taken.

- **Sandboxed execution**
  - Dedicated Sandbox daemon for running skills and workflows in an isolated environment.
  - Full capture of stdin/stdout, logs and artifacts for each run.
  - Designed for slow / side‑effect‑heavy tools without blocking the main agent loop.

- **Workflow engine & triggers**
  - Flow‑based orchestration with support for **cron**, **event** and **manual** triggers.
  - Triggers can start workflows, call services, or poke existing conversations.
  - First‑class integration with observability so every run is traceable.

- **IM & channel integrations**
  - IM channels (e.g. Feishu/Lark) mapped to conversations and services.
  - Webhook entrypoints so external systems can talk to your agents.

- **Extensible skills**
  - System‑level skills for platform capabilities (ontology, services, observability, etc.).
  - Business skills loaded from the `skills/` directory with a unified execution contract.
  - Workflow / knowledge‑base / observability features are all exposed as first‑class skills.

### Screenshots

- **Product overview – one place to manage agents, skills and services.**  
  ![AgentForge Overview](./docs/public/assets/Overview.png)

- **Agent workspace – browse, search and configure individual agents.**  
  ![Agent List](./docs/public/assets/Agent.png)

- **Skill catalog – register, organize and reuse atomic skills across teams.**  
  ![Skill Catalog](./docs/public/assets/Skill.png)

- **Multi-agent orchestration flows – design and inspect how coordinator and executors collaborate step by step.**  
  ![MultiAgent Flows](./docs/public/assets/Flows.png)

- **Sub-agent topology – understand layered flows and execution hierarchy at a glance.**  
  ![SubAgent Topology](./docs/public/assets/SubAgent.png)

- **Sandbox runs – execute skills and workflows safely with full input/output visibility.**  
  ![Sandbox Runs](./docs/public/assets/Sandbox.png)

- **Triggers – connect agents to schedules, events and external systems.**  
  ![Triggers](./docs/public/assets/Triggers.png)

- **End-to-end observability – inspect each invocation, timeline and tool call in a unified debug panel.**  
  ![Observability Panel](./docs/public/assets/Observability.png)

- **Per-agent debug info – drill into a single agent’s decisions, tool calls and messages.**  
  ![Agent Debug Info](./docs/public/assets/Agent%20Debug%20Info.png)

- **IM channels – plug agents into Slack/IM-style channels for multi-user collaboration.**  
  ![IM Channel](./docs/public/assets/IM%20Channel.png)

## Tech Stack

| Layer | Technologies |
|-------|-------------|
| **Backend** | FastAPI, LangChain / LangGraph, PostgreSQL / SQLite, Redis, ChromaDB / FAISS |
| **Infra & Docs** | Docker Compose, Prometheus, VitePress (docs site) |

## Project Structure

```
AgentForge/
├── backend/                  # Backend API service
├── knowledge-base-service-py/# Knowledge-base microservice (memvid)
├── sandbox_daemon/           # Sandbox WebSocket daemon
├── skills/                   # Skill script library
├── docker/                   # Docker orchestration
├── docs/                     # Documentation (internal + public)
├── docs-site/                # VitePress documentation site
└── scripts/                  # Utility scripts
```

See [docs/public/README.md](./docs/public/README.md) for a high-level documentation index.

## Using This Repo With an AI Assistant

This project is designed to be friendly to AI coding assistants. If you feed this `README.md` (plus the referenced files) to an AI agent, it should be able to:

1. **Start the full stack with Docker**
   - Follow the steps in [docker/.env.example](./docker/.env.example) to create and adjust `docker/.env`.
   - Use `./docker/start.sh` or `docker-compose`/`make` targets as described in this README and in `docker/README.md`.
2. **Run backend and frontend locally (without Docker)**
   - Backend entrypoint: `backend/app/main.py` via `uvicorn app.main:app --reload` (see `backend/README.md`).
   - Frontend entrypoint: `frontend/src/main.js` via `npm install && npm run dev` in `frontend/`.
3. **Understand core configuration and secrets**
   - Runtime settings come from environment variables, primarily configured via `docker/.env` and parsed in `backend/app/core/config.py` (`Settings` class).
   - Production **must** override `JWT_SECRET` and `DEFAULT_ADMIN_PASSWORD`; see validation logic in `Settings._require_secrets_in_production`.
4. **Work with the knowledge base and sandbox daemon**
   - Knowledge-base microservice: `knowledge-base-service-py/` (HTTP service used by backend when enabled).
   - Sandbox daemon: `sandbox_daemon/daemon.py` (connects back to backend via `--platform-url` and `--token`).
5. **Navigate skills and agent logic**
   - Skill scripts live in `skills/` and are mounted via configuration in `backend/app/` (see `SKILLS_DIR` in `config.py`).
   - Multi-agent orchestration and execution logic is in `backend/app/agents/` and related modules.
6. **Find public docs**
   - Public, open-source–friendly docs live under `docs/public/`, including:
     - `docs/public/docker/QUICKSTART.md` – Docker quickstart.
     - `docs/public/topics/auth/README.md` – auth and 2FA overview.
     - `docs/public/topics/architecture/gateway-pattern.md` – selected architecture notes.

When instructing an AI assistant to modify or extend the project, prefer giving it:

- This `README.md`
- `docker/.env.example`
- `backend/app/core/config.py`
- The specific backend/Frontend files you want to change
- Any relevant docs under `docs/public/`

## Quick Start

### Prerequisites

- Docker & Docker Compose
- Python 3.10+ (local development)
- Node.js 18+ (for running the docs site locally)

### Docker (Recommended)

```bash
git clone <repository-url>
cd AgentForge

# Configure environment
cd docker
cp .env.example .env
# Edit .env as needed (API keys, etc.)

# Start all services
./start.sh
# or: docker-compose up -d --build
# or: make up-build
```

**Access:**

| Service | URL |
|---------|-----|
| Backend API | http://localhost:8000 |
| API Docs (Swagger) | http://localhost:8000/docs |
| Health Check | http://localhost:8000/health |

**Default admin credentials:** `admin` / `admin123` (change `DEFAULT_ADMIN_PASSWORD` in production).

See [docs/public/topics/auth/README.md](./docs/public/topics/auth/README.md) for 2FA setup.

### Local Development

**Backend:**

```bash
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload
```

**Docs site (optional):**

```bash
cd docs-site
npm install
npm run dev
```

## Core Features

1. **Multi‑tenant workspaces**
   - Isolated agents, applications and data per tenant.
   - Shared infrastructure layer (DB, vector stores, observability) to reduce operational cost.

2. **SubAgent hierarchy**
   - Nested SubAgent topology to express multi‑layer task decomposition.
   - Visual configuration of coordinator + executor agents and their responsibilities.

3. **Skill plugin & system skill framework**
   - Skills are first‑class plug‑ins with a standard `skill_execute(**kwargs)` contract.
   - Both business skills and platform/system skills share the same registration + execution path.

4. **Execution, Sandbox & observability**
   - Task decomposition view + live execution timeline, including tool calls and LLM calls.
   - Sandbox daemon for isolated tool execution with full logs and artifacts.
   - Static execution graph with per‑invocation highlighting and Prometheus metrics.

5. **Service publishing & workflows**
   - Publish agent graphs as standalone API services with API keys and version management.
   - Workflow engine with cron/event/manual triggers, all tied back to conversations and observability.

6. **Knowledge base & IM channels**
   - Document‑based knowledge base via a dedicated microservice (memvid).
   - IM channels (e.g. Feishu/Lark) mapped into conversations for multi‑user collaboration.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for development workflow and guidelines.

## License

[Apache License 2.0](./LICENSE)

## Security

Please report vulnerabilities via GitHub Security Advisories. See [SECURITY.md](./SECURITY.md).

---

# AgentForge - 多智能体操作系统

基于 LangChain / LangGraph 构建的多智能体操作系统，聚焦「多租户、多智能体编排、Skill 插件体系、Workflow / Trigger、Sandbox 执行、可观测性、IM 通道与知识库」的完整闭环。

## 项目概述

相较于单一 Chatbot，AgentForge 更像一套「多智能体操作系统」，提供：

- **多租户工作区**：不同租户/环境共享基础设施，又相互隔离应用、服务与数据。
- **SubAgent 分层编排**：以 SubAgent 拓扑描述协调 Agent 与执行 Agent 的分工与多层任务拆解路径。
- **Skill 插件体系**：业务 Skill 与系统 Skill 统一注册/发现/执行，复用原子能力，减少重复接入。
- **记忆层**：同时支持 Agent 个人长期记忆与共享记忆，基于向量检索。
- **多种入口**：Chat UI、HTTP API、工作流触发器（定时、事件、手动）、IM Channel 等。
- **服务化发布**：将编排好的智能体能力一键发布为带版本与 API Key 管理的服务，支持 OpenAPI 导出。

## 能力亮点

- **可观测性优先**
  - 会话维度记录每一次调用（同步/流式），构建执行时间线。
  - 每个 Agent / Skill / 工具调用都有独立调试面板：请求体、响应体、Token & 耗时、调用链等一目了然。
  - 静态执行拓扑 +「按次高亮」，支持从调用记录一键高亮本次经过的节点与边。

- **Sandbox 执行环境**
  - 独立 Sandbox Daemon，通过 WebSocket 与平台通信。
  - 适合 I/O 密集或有强副作用的 Skill，执行过程与日志、产出物完整可追踪。

- **工作流与触发器**
  - 基于 Flow 的任务编排，支持 Cron / 事件 / 手动三类 Trigger。
  - 每次触发都对应完整的执行记录和可观测数据，方便排障与审计。

- **知识库与 IM 通道**
  - 通过独立微服务提供文档知识库（上传、切分、向量检索、时间线等）。
  - 支持飞书/IM Channel 集成，将 Agent 接入到现有沟通工具中。

## 技术栈

| 层次 | 技术 |
|------|------|
| **后端** | FastAPI、LangChain / LangGraph、PostgreSQL / SQLite、Redis、ChromaDB / FAISS |
| **基础设施与文档** | Docker Compose、Prometheus、VitePress（文档站） |

## 快速开始

### 前置要求

- Docker & Docker Compose
- Python 3.10+（本地开发）
- Node.js 18+（用于本地运行文档站，可选）

### 使用 Docker 启动（推荐）

```bash
git clone <repository-url>
cd AgentForge

# 配置环境变量
cd docker
cp .env.example .env
# 编辑 .env 文件，配置 API Key 等参数

# 启动所有服务
./start.sh
# 或: docker-compose up -d --build
# 或: make up-build
```

Compose 项目名已固定为 `agentforge`，用于避免与其他项目发生服务覆盖。

**访问服务：**

| 服务 | 地址 |
|------|------|
| 后端 API | http://localhost:8000 |
| API 文档（Swagger） | http://localhost:8000/docs |
| 健康检查 | http://localhost:8000/health |

**默认管理员：** 用户名 `admin`，密码 `admin123`（生产环境请修改 `DEFAULT_ADMIN_PASSWORD`）。

首次登录后可启用两步验证（2FA），详见 [docs/topics/auth/README.md](./docs/topics/auth/README.md)。

### 本地开发

**后端：**

```bash
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload
```

**文档站（可选）：**

```bash
cd docs-site
npm install
npm run dev
```

## 核心功能

1. **多租户工作区**
   - 支持按租户/环境隔离应用、服务与数据。
   - 共享底层数据库、向量库与可观测基础设施，降低运维成本。

2. **SubAgent 分层编排**
   - 通过 SubAgent 拓扑表达协调 Agent 与执行 Agent 的职责边界与多层任务拆解路径。

3. **Skill 插件与系统 Skill 框架**
   - Skill 以统一的 `skill_execute(**kwargs)` 协议实现，支持动态加载与注册。
   - 业务 Skill 与系统级 Skill（服务、可观测、知识库等）走同一套执行路径。

4. **执行引擎、Sandbox 与可观测性**
   - 任务拆解视图 + 实时执行时间线（含工具调用与 LLM 调用）。
   - 独立 Sandbox Daemon 支持有副作用/长耗时的 Skill 隔离执行，完整保留日志与产出物。
   - 静态执行拓扑 + 按次高亮，并输出 Prometheus 指标。

5. **服务发布与工作流**
   - 将编排好的 Agent Graph 发布为带版本与 API Key 管理的独立 API 服务。
   - 工作流引擎支持 Cron / 事件 / 手动触发，并与会话与可观测体系打通。

6. **知识库与 IM 通道**
   - 通过独立微服务提供文档知识库能力（上传、切分、向量检索、时间线等）。
   - 支持飞书 / IM Channel 等接入方式，将 Agent 带入实际沟通场景。

## 开发指南

请参考公开文档入口（`docs/public/` 目录）和 [CONTRIBUTING.md](./CONTRIBUTING.md)。

## 数据存储

- **关系型数据库**：Docker 下为 PostgreSQL；本地默认 SQLite（`backend/data/agentforge.db`）
- **向量数据库**：`backend/data/chroma/`
- **Skill 脚本**：`skills/` 目录
- **日志文件**：`backend/logs/`

## 贡献指南

见 [CONTRIBUTING.md](./CONTRIBUTING.md)。

## 许可证

[Apache License 2.0](./LICENSE)

## 联系方式

通过 GitHub Issues 提问；安全问题请见 [SECURITY.md](./SECURITY.md)。