AgentForge

Forge Intelligence into Action.

English | 简体中文

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: https://agentforge-tech.github.io/AgentForge/

Roadmap: #1

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:

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:

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

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:

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:

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:

<dependency>
    <groupId>cloud.changlu.agentforge</groupId>
    <artifactId>agentforge-agent-core</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

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

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

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

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):

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 http://127.0.0.1:17080. 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:

# 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

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 for details.

Testing

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	https://agentforge-tech.github.io/AgentForge/
Introduction	https://agentforge-tech.github.io/AgentForge/docs/about/introduction
Getting Started	https://agentforge-tech.github.io/AgentForge/docs/quickstart/getting-started
Contributing	https://agentforge-tech.github.io/AgentForge/docs/quickstart/contributing
Blog	https://agentforge-tech.github.io/AgentForge/blog
Source (GitHub)	https://github.com/agentforge-tech/AgentForge
Mirror (Gitee)	https://gitee.com/changluJava/agent-forge

---

Questions

If you run into any problem, please reach out via:

• GitHub Issues: https://github.com/agentforge-tech/AgentForge/issues
• Gitee Issues: https://gitee.com/changluJava/agent-forge/issues
• Documentation: https://agentforge-tech.github.io/AgentForge/

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	Author / Maintainer

Your name could be here.

---

License

AgentForge is released under the MIT License.

---

Models provide intelligence. AgentForge turns intelligence into action.