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/

Highlights

• Provider-neutral model abstraction with OpenAI-compatible and Anthropic implementations
• ReAct agent runtime with streaming, ChatMemory, local / HTTP / MCP tools, middleware, retry and cancellation
• Out-of-the-box AgentForge Service: model config, Agent build / debug / version / publish, session history and plugin management
• Unified SSE event protocol with MySQL-backed ChatMemory, replayable session events and dual debug / elegant rendering
• Harness runtime and advanced observability are on the roadmap

---

Architecture

AgentForge is built bottom-up: stabilize the lowest-level model abstraction first, then forge Agent capabilities layer by layer.

LLM
 ↓  Message / Request / Response
 ↓  Context / Memory
 ↓  Tool / Skill / MCP
 ↓  Reasoning / Planning
 ↓  Agent Runtime
 ↓  Multi-Agent / Sandbox / Observability
Real Action

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

Module Capabilities

Module	Capabilities
agentforge-model-api	Unified ChatModel / StreamingChatModel contracts, Message / Request / Response, tool contracts, and HTTP Transport SPI
agentforge-model-core	Zero-dependency HTTP Transport, built-in JSON, @Tool reflective execution, and the inference-tool loop engine
agentforge-model-openai	OpenAI Chat Completions sync / streaming, Function Calling, OpenAI-compatible endpoints
agentforge-model-anthropic	Anthropic Messages API sync / streaming, Tool Use
agentforge-model-registry	LlmFactory builds ChatModel / StreamingChatModel per provider
agentforge-agent-core	ReAct main loop (sync / streaming), pluggable ChatMemory / ChatMemoryStore, window memory, local / HTTP / MCP tools, tool-calling rounds, Middleware chain, retry & cancellation
agentforge-harness-agent	Harness runtime on top of the core Agent (design phase): permission, tool approval, human-in-the-loop, sandbox, trace, resumable execution
agentforge-service	Runnable Agent workbench: model config, Agent config / debug / version / publish, sessions & replay, MySQL ChatMemory, HTTP / MCP plugins, unified SSE (Vue frontend + Spring Boot backend)

AgentForge Service

agentforge-service is a runnable single-user Agent workbench, 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, MySQL in the service)
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.

Roadmap

The roadmap is maintained and discussed in Issue #1.

---

Quick Start

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.

Run AgentForge Service

# 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
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

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.