This page introduces AgentScope Java, an agent-oriented programming framework for building production-ready LLM applications in Java 17+. It provides an overview of the framework's architecture, key features, and how to get started.
AgentScope Java is built on Project Reactor for reactive, non-blocking execution and designed for enterprise deployment. The framework enables autonomous yet controllable AI agents through the ReAct (Reasoning-Acting) paradigm, with comprehensive runtime intervention mechanisms. README.md28-41 pom.xml95-99
Key Capabilities:
| Category | Features |
|---|---|
| Smart Agents | ReAct reasoning, safe interruption, graceful cancellation, human-in-the-loop (HITL) |
| Built-in Tools | PlanNotebook (task decomposition), Structured Output (type-safe parsing), Long-term Memory, RAG |
| Integration | MCP Protocol (external tools), A2A Protocol (distributed agents), Nacos service discovery |
| Production-Ready | Reactive architecture (Project Reactor), GraalVM native image (200ms cold start), OpenTelemetry observability |
| Multi-LLM | DashScope (Qwen), OpenAI (GPT), Gemini, Anthropic (Claude), Ollama (local) |
Related Pages:
Sources: README.md1-128 README_zh.md1-128 docs/en/quickstart/installation.md1-247
AgentScope Java follows a layered architecture with clear separation between the reactive core, extension modules, and framework integrations. This diagram maps architectural concepts to concrete code entities.
Layered Architecture Overview
Core Package Structure
| Package | Key Classes | Purpose |
|---|---|---|
io.agentscope.core.agent | ReActAgent, AgentBase, UserAgent, StudioUserAgent | Agent implementations and lifecycle management |
io.agentscope.core.model | DashScopeChatModel, OpenAIChatModel, GeminiChatModel, AnthropicChatModel | LLM provider integrations |
io.agentscope.core.tool | Toolkit, AgentTool, @Tool, ToolGroup | Tool registry, execution, and grouping |
io.agentscope.core.memory | Memory, InMemoryMemory, LongTermMemory | Conversation history and long-term storage |
io.agentscope.core.hook | Hook, HookEvent, PreReasoningEvent | Lifecycle event interception |
io.agentscope.core.message | Msg, ContentBlock, TextBlock, ToolUseBlock, ToolResultBlock | Message structure and content types |
io.agentscope.core.plan | PlanNotebook, Plan, SubTask | Task planning and decomposition |
io.agentscope.core.tool.mcp | McpClientBuilder, McpClientWrapper, McpAsyncClientWrapper | Model Context Protocol client |
For a deeper dive into these components, see Architecture Overview.
Sources: pom.xml53-59 agentscope-dependencies-bom/pom.xml1-123 agentscope-distribution/agentscope-bom/pom.xml81-320
AgentScope Java uses a modular Maven structure with explicit dependency management through Bill-of-Materials (BOM) POMs. pom.xml53-59 agentscope-distribution/agentscope-bom/pom.xml1-29
Module Breakdown:
| Module | Artifact ID | Description |
|---|---|---|
| Root | agentscope-parent | Parent POM managing build plugins and versions. pom.xml23-27 |
| Core | agentscope-core | Core framework with agents, models, tools, and memory. pom.xml54 |
| Extensions | agentscope-extensions-* | Optional modules for specialized functionality like RAG and multi-agent. pom.xml55 |
| Dependencies BOM | agentscope-dependencies-bom | Manages 50+ external dependency versions. agentscope-dependencies-bom/pom.xml23-123 |
| AgentScope BOM | agentscope-bom | Manages internal AgentScope module versions. agentscope-distribution/agentscope-bom/pom.xml23-29 |
| All-in-One | agentscope | Single dependency including core + selected extensions. docs/en/quickstart/installation.md23-28 |
AgentScope Java uses a dual-BOM strategy to separate external dependencies from internal module management. agentscope-dependencies-bom/pom.xml125-161 agentscope-distribution/agentscope-bom/pom.xml81-320
Consumption Models:
| Approach | Use Case | Maven Coordinates |
|---|---|---|
| All-in-One | Quick start, most users | io.agentscope:agentscope:1.0.12-SNAPSHOT |
| Core + Extensions | Fine-grained control | io.agentscope:agentscope-core:1.0.12-SNAPSHOT + extensions |
For setup instructions, see Getting Started.
Sources: agentscope-dependencies-bom/pom.xml62-123 docs/en/quickstart/installation.md1-247 agentscope-distribution/agentscope-bom/pom.xml81-320
AgentScope provides built-in support for the Model Context Protocol (MCP), enabling agents to connect to external tool servers via StdIO, SSE, or HTTP. agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpClientBuilder.java45-78
Example Configuration:
For more on MCP and other advanced capabilities, see Key Features.
Sources: agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpClientBuilder.java1-116 agentscope-core/src/test/java/io/agentscope/core/tool/mcp/McpClientBuilderTest.java186-195
AgentScope Java includes version management and user-agent generation for LLM request tracking and statistical identification. agentscope-core/src/main/java/io/agentscope/core/Version.java18-24
Version Class:
The Version class provides the unified identification string:
This identification is automatically used by MCP clients and model providers to identify AgentScope Java clients. agentscope-core/src/main/java/io/agentscope/core/tool/mcp/McpClientBuilder.java18 agentscope-core/src/test/java/io/agentscope/core/VersionTest.java38-53
Sources: agentscope-core/src/main/java/io/agentscope/core/Version.java1-48 agentscope-core/src/test/java/io/agentscope/core/VersionTest.java1-110