# AgentForge
**Repository Path**: changluJava/AgentForge
## Basic Information
- **Project Name**: AgentForge
- **Description**: Java-first open-source AI Agent framework & workbench. Core framework: general-purpose ReAct agents and harness agents (sandbox, HITL approval, resumable execution). AgentForge Service: best-practice standard agent infrastructure to build, debug, publish and operate production-ready agents — streaming, ChatMemory, MCP/HTTP tools, session replay.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://agentforge-tech.github.io/AgentForge/
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-30
- **Last Updated**: 2026-11-07
## Categories & Tags
**Categories**: Uncategorized
**Tags**: agent-framework, agentforge, agentic-ai, AI, ai-agent, AI-Agents, anthropic, artificial-intelligence, Java, java-agent, llm, Machine-learning, openAI, ReAct-Agent, tool-calling, agent-workbench, MCP, mcp-client, streaming
## README
# AgentForge
> **Forge Intelligence into Action.**
[](https://agentforge-tech.github.io/AgentForge/)
[](LICENSE)
[](https://agentforge-tech.github.io/AgentForge/docs/quickstart/getting-started)
[](https://github.com/agentforge-tech/AgentForge/stargazers)
**English** | [简体中文](README.zh-CN.md)
AgentForge is an open-source Agent framework for Java developers, built **from the lowest-level LLM capabilities upward**.
Rather than starting from a highly abstracted Agent API, it first establishes a stable, unified, and extensible model abstraction, then builds Tool, Memory, Middleware, Reasoning, and Agent Runtime capabilities layer by layer.
> **LLMs provide raw intelligence. AgentForge engineers that intelligence layer by layer and forges it into Agents that can actually get things done.**
`AgentForge = Agent + Forge`: `Agent` stands for an entity that understands goals, reasons, calls tools, and completes tasks; `Forge` emphasizes shaping raw material through continuous processing, forming, and strengthening until it becomes a truly usable product.
**Documentation**:
**Roadmap**:
**Highlight**
- **Unified model protocol layer** — provider-neutral `ChatModel` / `StreamingChatModel` contracts with OpenAI-compatible and Anthropic implementations, plus a shared Function Calling / Tool executor abstraction
- **ReAct agent runtime** — one API for both sync and streaming, window ChatMemory, a pluggable Middleware chain (logging, Agent Loop trace), step limits, cancellation and retry
- **Tool ecosystem** — local Java `@Tool` methods, HTTP plugins and MCP servers converted into a unified function-call standard, with thought fields injected into every tool call
- **AgentForge Service** — a runnable single-user Agent workbench covering model config, Agent build / debug / version / publish, session history and replay on SQLite / MySQL
- **Streaming & observability** — unified SSE event protocol, dual `debug` / `elegant` rendering, session event replay, and Agent Loop Trace with flame graph and flow chart
- **Coming next** — Harness runtime (sandbox, HITL approval, resumable execution), context compression, scenario-aware retries, scheduled tasks, DingTalk / Feishu channels, and CLI / Desktop / Platform forms
---
## Architecture
AgentForge follows the two-part design from the [roadmap](https://github.com/agentforge-tech/AgentForge/issues/1):
1. **Agent framework** — reusable core components: unified model protocol, general-purpose ReAct Agent runtime, Harness Agent runtime (permissions, sandbox, HITL approval, resumable execution), plus tools, memory, middleware, tracing and token accounting.
2. **Agent Service** — `agentforge-service`, an out-of-the-box implementation of standard Agent infrastructure best practices, from model configuration to Agent build / debug / version / publish and session operations.
`agentforge-agent-core` is the heart of the framework. It takes the raw intelligence of an LLM and forges it into real action, layer by layer:
```text
LLM
↓ Message / Request / Response
↓ Context / Memory
↓ Tool / Skill / MCP
↓ Reasoning / Planning
↓ Agent Runtime
↓ Multi-Agent / Sandbox / Observability
Real Action
```
| Layer | How `agentforge-agent-core` implements it |
| --- | --- |
| LLM | Provider-neutral `ChatModel` / `StreamingChatModel`; OpenAI and Anthropic providers plug in through the model modules |
| Message / Request / Response | Unified message model, `AgentRequest` / `ChatResult`, and one consistent sync / streaming execution shape |
| Context / Memory | `ChatMemory` / `ChatMemoryStore`, window memory and `memoryId`-scoped sessions |
| Tool / Skill / MCP | `ToolService` with a shared tool specification / executor SPI: local `@Tool`, HTTP plugins and MCP servers |
| Reasoning / Planning | ReAct think → act → observe loop with step limits and interruption checks |
| Agent Runtime | `ReActAgent` for sync, `ReActTokenStream` for streaming, a middleware chain, retry and cancellation |
| Multi-Agent / Sandbox / Observability | Agent Loop Trace middleware with token accounting; Agent Team and harness sandbox are on the roadmap |
| Real Action | Real tool execution and side effects; approval and sandboxing arrive with the harness runtime |
### Project Structure
```text
AgentForge
├── agentforge-ai-parent # Centralized dependency & plugin version management
├── agentforge-ai-bom # Unified BOM coordinates
├── agentforge-model # Model layer
│ ├── agentforge-model-api # Provider-neutral model contracts & unified req/vo
│ ├── agentforge-model-core # Vendor-free default implementations & execution engine
│ ├── agentforge-model-openai # OpenAI / OpenAI-compatible provider
│ ├── agentforge-model-anthropic # Anthropic provider
│ └── agentforge-model-registry # Out-of-the-box ChatModel factory
├── agentforge-framework
│ ├── agentforge-agent-core # ReAct Agent runtime
│ └── agentforge-harness-agent # Harness runtime (design phase)
├── agentforge-service # Out-of-the-box service (Vue frontend + Spring Boot backend)
│ ├── agentforge-service-ui # Vue 2 + Vite frontend
│ └── agentforge-service-web # Spring Boot backend
├── agentforge-examples
├── pom.xml
└── README.md
```
### AgentForge Service
`agentforge-service` is a runnable single-user Agent workbench and the reference implementation of standard Agent infrastructure best practices — not a demo shell. It closes the loop from model configuration to a published Agent:
```text
Model config → Agent config → Debug → Version → Publish → Chat & session history
```
| Capability | What is implemented |
| --- | --- |
| Model management | OpenAI / Anthropic / OpenAI-compatible endpoints, API key, base URL and model name; resolved by `LlmFactory` at runtime |
| Agent configuration | Prompt, chat model, window memory and plugin references persisted in `ai_agent_config` |
| Debug & preview | Debug runs use the working config; the same event stream renders in high-density `debug` mode or user-facing `elegant` mode |
| Version history | `ai_agent_config_version` snapshots, editable version remarks, version switching and side-by-side diff |
| Publish snapshots | `ai_agent_config_published` isolates the live configuration from ongoing edits; publish / unpublish invalidates runtime caches |
| Sessions & replay | `ai_agent_session` / `ai_agent_session_message` persist titles, pinning, messages and the SSE event snapshots used for history replay |
| ChatMemory | `ai_agent_memrory` persists the model context through a pluggable `ChatMemoryStore` (in-memory by default; the service uses SQLite by default and can switch to MySQL) |
| HTTP plugins | HTTP plugin / method / parameter model, curl and JSON import, online test-run, namespaced tools (`{alias}__{method}`) |
| MCP plugins | MCP plugin / server management, one-click `mcpServers` import / export, tool discovery, multi-server aggregation with per-server failure isolation |
| Streaming UX | Unified SSE events (`session` / `think` / `resp` / `tool_call` / `resp_end` / `error`), streaming Markdown and `__thought` tool intent |
The backend is organized by business module:
```text
agentforge-service-web
└── modules
├── model # Model configuration
├── agent # Agent config, version, publish and runtime assembly
├── session # Sessions, messages and SSE replay
└── plugins # HTTP and MCP plugins
```
### Design Principles
1. **Bottom-up** — Stabilize foundational abstractions (LLM / Message / Request / Response) before building the Agent.
2. **Provider-neutral** — The upper framework is never bound to a single model vendor's protocol.
3. **Modular** — Core abstractions evolve separately from providers, framework, and Agent runtime.
4. **Lightweight** — Minimize dependencies at the bottom so it can be reused by Spring Boot, plain Java, desktop, or even embedded projects.
5. **Production-oriented** — The goal is not a demo Agent, but an Agent runtime that can genuinely reach production.
---
## Quick Start
AgentForge offers two entry points: embed the framework in your own Java application, or start the out-of-the-box service locally with one command.
### Part 1: Use the Framework
#### Dependency
Until the first Maven Central release is published, use the locally built `1.0.0-SNAPSHOT` artifacts:
```xml
cloud.changlu.agentforge
agentforge-agent-core
1.0.0-SNAPSHOT
```
Other common modules: `agentforge-model-openai`, `agentforge-model-anthropic`, or the full `agentforge-service`.
#### Requirements
> **JDK 17 recommended, JDK 8 compatible.**
- Day-to-day development and CI default to **JDK 17**; public modules compile to **Java 8 bytecode** and can be depended on and run directly under JDK 8.
- The root package name and `groupId` are both `cloud.changlu.agentforge`.
#### Call a Model
```java
ChatModel model = OpenAiChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4o-mini")
.build();
String answer = model.chat("Hello AgentForge");
```
`baseUrl` is configurable, so it also works as an OpenAI-compatible provider (DashScope / Ollama / Xinference, etc.). For streaming output, use `StreamingChatModel` with `StreamingChatResponseHandler`.
#### Build an Agent
```java
ToolService toolService = new ToolService();
toolService.tools(new WeatherTools()); // scan all @Tool methods on the object
ReActAgent agent = ReActAgent.builder()
.agentName("weather-react-agent")
.systemPrompt("You are a weather assistant.")
.chatModel(chatModel)
.streamingChatModel(streamingChatModel)
.chatMemoryProvider(ChatMemoryProvider.windowChatMemoryProvider(50))
.toolService(toolService)
.build();
ChatResult result = agent.run(AgentRequest.builder()
.memoryId("demo")
.question("What is the weather in Beijing today?")
.build());
```
For streaming, `agent.runStream(request)` returns a `TokenStream` that lets you subscribe to text / thinking deltas, tool executions, and completion events; `agent.cancel(memoryId)` cancels a task. Models, memory, tools, and middleware are all injected through the builder — see the documentation site for details.
#### Build from Source
```bash
git clone https://github.com/agentforge-tech/AgentForge.git
cd AgentForge
mvn clean install -DskipTests
```
This installs the `1.0.0-SNAPSHOT` artifacts into your local Maven repository.
### Part 2: One-Click Local Startup of AgentForge Service
`agentforge-service` is the standard Agent workbench: it closes the loop from model configuration to a published Agent. The fastest local start is the one-click installer (Docker 20.10+ and Docker Compose v2 required):
```bash
mkdir -p agentforge && cd agentforge
curl -fsSL https://raw.githubusercontent.com/agentforge-tech/AgentForge/master/agentforge-service/docker/standalone/install.sh | bash
```
It pulls the all-in-one image (backend + frontend + SQLite), initializes the database and starts the service at . Only the Compose file, environment template and upgrade script are downloaded; `conf/`, `data/`, `logs/` and `upload/` are persisted in the current directory. Re-running the installer is safe, and `./upgrade.sh [version]` upgrades an existing deployment.
The platform looks like this once started:
#### Run from Source
Requires the source build from Part 1:
```bash
# Backend (Spring Boot, default 8080)
cp agentforge-service/conf/application.yml.example agentforge-service/conf/application.yml
export AGENTFORGE_MODEL_API_KEY=your-api-key
mvn package -pl agentforge-service/agentforge-service-web -am -DskipTests
cd agentforge-service
./bin/local/upgrate-sqlite.sh
java -jar agentforge-service-web/target/agentforge-service-web-1.0.0-SNAPSHOT.jar
# Frontend (Vue 2 + Vite, default 5173, proxies /api to 8080)
cd agentforge-service/agentforge-service-ui
npm install && npm run dev
```
#### Build the All-in-One Image
```bash
cd agentforge-service/docker && ./scripts/deploy.sh
```
The service uses SQLite by default (`agentforge-service/data/agentforge.db`); set
`AGENTFORGE_DB_TYPE=mysql` to switch to MySQL. The service does not create tables at startup, so run
the SQLite migration script once before the first start.
The UI ships pages for model management (`/`), Agents (`/agents`), HTTP plugins (`/http-plugins`), MCP plugins (`/mcp`) and the published chat page (`/agent/published/{aid}`). See [agentforge-service/README.md](agentforge-service/README.md) for details.
### Testing
```bash
mvn clean test
```
Unit tests do not hit real model services by default; they verify requests and responses through a replaceable `HttpTransport` and scripted models, so CI needs no API key.
---
## Documentation
The documentation site is the best place to start. It is available in both 简体中文 and English, and covers the architecture, module-by-module design notes, and end-to-end guides.
| Resource | Link |
| --- | --- |
| Documentation | |
| Introduction | |
| Getting Started | |
| Contributing | |
| Blog | |
| Source (GitHub) | |
| Mirror (Gitee) | |
---
## Questions
If you run into any problem, please reach out via:
- GitHub Issues:
- Gitee Issues:
- Documentation:
When filing an issue, please include environment info (JDK / Maven versions), reproduction steps, and the full error log to help us locate the problem quickly.
---
## Contribution
Contributions of code, documentation, and feedback are all welcome.
1. Fork this repository and branch off from the development branch;
2. Follow the project code style (Spotless formatting runs before commit);
3. Add or update unit tests when adding or changing capabilities, and make sure `mvn clean test` passes;
4. Open a Pull Request describing the background, approach, and impact.
> Never hard-code real API keys in source code or commit them to the repository.
---
## Contributors
| Contributor | Role |
| --- | --- |
| [changlu](https://github.com/changluya) | Author / Maintainer |
Your name could be here.
---
## License
AgentForge is released under the [MIT License](LICENSE).
---
> **Models provide intelligence. AgentForge turns intelligence into action.**