架构Architecture

This page covers two things: how the framework is layered and executed, and how this manual is generated statically from official sources. The first helps you find extension points; the second explains why every signature traces back to a pinned version.

1. Two editions, one conceptual model

The Python and Java editions are not line-by-line translations. They are different runtimes sharing one conceptual model:

The shared model aids migration, but concurrency differs: Python is asyncio-based, Java is Project Reactor-based. Watch return types when reading the API: a Python async def corresponds to Java Mono/Flux.

2. Python package layers

The 39 public agentscope packages fall into four groups.

Core runtime

• agentscope.agent — Agent, A2AAgent, RealtimeAgent and four config objects (ModelConfig, ContextConfig, ReActConfig, InjectionConfig);
• agentscope.message — Msg, UserMsg and all content blocks;
• agentscope.model — model base classes and vendor adapters;
• agentscope.formatter — protocol-specific message formatters;
• agentscope.tool — Toolkit, FunctionTool, built-in tools and MCP;
• agentscope.state — session state and reply/tool/task contexts;
• agentscope.middleware — middleware base and built-ins;
• agentscope.event — event types;
• agentscope.permission — permission engine and rules.

Capabilities

• agentscope.rag, agentscope.embedding — parsing, chunking, embedding, vector retrieval;
• agentscope.mcp, agentscope.skill, agentscope.sop — external tools, skills and standard operating procedures;
• agentscope.workspace — local/container/cloud isolated workspaces;
• agentscope.realtime, agentscope.asr, agentscope.tts, agentscope.classifier — realtime voice, recognition, synthesis and classification models.

Application layer

• agentscope.app and its subpackages — channels (DingTalk, Feishu, Discord, ...), message bus, storage, knowledge-base management, workspace management and access policies.

Developer experience

• agentscope.console, agentscope.tui — console rendering and terminal UI;
• agentscope.exception, agentscope.types — errors and shared types.

Dependency direction: capabilities depend on the core runtime, the application layer depends on capabilities, and the core runtime knows nothing about the application layer.

3. Java artifact taxonomy

Java splits core and optional capabilities into Maven artifacts. This manual covers 96 official source-bearing artifacts:

• core — agentscope-core: agents, messages, model SPI, tools, state, memory, RAG abstractions, permissions, hooks, tracing;
• extension — agentscope-extensions-*: model providers (OpenAI, DashScope, Anthropic, Gemini, Ollama, ...), RAG stores (Milvus, Qdrant, PgVector, Elasticsearch), A2A, AG-UI, sandboxes, channels and skill repositories;
• starter — *-spring-boot-starter: auto-configuration for models, agents or protocols in Spring Boot;
• runtime — agentscope-runtime-* and the 1.x line, kept in a separate group;
• integration — agentscope-harness, agentscope-copilotkit, agentscope-codingagent and similar.

The umbrella agentscope source jar duplicates every module, so it is not used as an ownership source. When one fully-qualified class appears in several runtime artifacts, the manual de-duplicates by "most specific artifact + best package match", resolving 126 duplicates.

4. Lifecycle of one reply

Using Java's ReActAgent.call (Python's reply has the same shape):

call(msgs, runtimeContext)
  │
  ├─ resolve/create AgentState (by userId + sessionId)
  ├─ merge system prompt, history, new input
  ├─ build tool schemas (active tool groups only)
  ├─ inject the middleware chain
  │
  ├─ loop: iter = 0..maxIters
  │    ├─ Formatter: Msg[] → vendor request
  │    ├─ Model: streaming or non-streaming call
  │    ├─ Accumulator: deltas → complete thinking/text/tool calls
  │    ├─ if tool calls exist:
  │    │    ├─ PermissionEngine check
  │    │    ├─ execute tools (parallel and streaming capable)
  │    │    ├─ produce ToolResultBlock
  │    │    └─ append to context, continue
  │    └─ else: produce final Msg, stop
  │
  ├─ context compression (when threshold is crossed)
  ├─ persist AgentState (if a store is configured)
  └─ return Msg / emit events

Key design points:

• Streaming and non-streaming share one execution path. call simply aggregates the Flux into a Mono; there are not two implementations.
• Tool calls are part of the context. Results are written back as ToolResultBlocks rather than cached on the side, so compression, persistence and replay all see the full trajectory.
• Interruption is recoverable state. Interruption saves reply_context and pending tool calls; resuming continues from the breakpoint.
• Concurrency is serialized per session. Calls sharing (userId, sessionId) are serialized while distinct sessions run concurrently. RuntimeContext is not shared mutable state.

5. Context compression

When tokens approach the model window, ContextConfig / AutoContextConfig triggers compression:

1. Keep the system prompt, the most recent turns, pending tool calls and task state;
2. Ask the model for a structured summary (task, current state, key findings, next steps, context to preserve);
3. Replace older messages with the summary and record a compression event;
4. If summarization fails, fall back to truncation or raise, depending on configuration.

This is why AgentState holds both context and summary: the former is the current window, the latter is the compressed history.

6. Extension points

Prefer implementing interfaces/base classes over modifying core classes. The runtime depends on these capabilities only through abstractions.

7. Version and source policy

This manual pins the following sources and shows file and line numbers on every page:

• Python 2.0.11: official PyPI wheel, parsed directly with ast without importing the package;
• Java 2.0.4: -sources.jar from Maven Central, parsed with the JDK Compiler Tree API using --release 21 and -proc:none, without resolving third-party classpaths;
• Preview and legacy: 2.1.0-BETA1, 2.0.0-RC4 and other previews are marked; 1.x runtime artifacts live in a legacy group;
• Excluded: examples, tests, build plugins and the umbrella jar.

Limits of static extraction:

• Only explicit source declarations are parsed; code is not executed and dependency parents are not resolved (external bases appear as text);
• Java record components come from parsing the record header; missing accessors are synthesized and marked as generated;
• Annotation defaults, generic bounds and imports come from the syntax tree;
• Documentation keeps structured Javadoc/docstring fields (summary, params, returns, throws, examples, deprecation) without recreating HTML styling.

8. The manual build pipeline

official wheel / sources.jar
        │
        ├─ extract_python.py  → inventory/python.json
        └─ extract_java.py    → inventory/java.json (96 artifacts merged and deduplicated)
                                   │
translations/*.zh.json ────────────┤
        │                          ▼
        └───────────────  sitegen (pysite / javasite / build)
                                   │
                    ┌──────────────┼──────────────┐
                    ▼              ▼              ▼
                 API pages     guides/coverage   search-index.json
                                   │
                              check_links.py

The generator needs no database or online service: inventories are JSON, translations are stable-ID JSON, and the output is pure static HTML/CSS/JS. Builds are reproducible, the site can be hosted offline, and search needs no backend.

9. Three language modes

Language mode is controlled by html[data-lang]; content blocks are emitted with .lang-zh / .lang-en markers at generation time:

• Mixed: Chinese on top, English below in a muted color;
• Chinese-only: Chinese only; missing translations fall back to English with an EN badge;
• English-only: Chinese blocks are hidden; English signatures and docs remain.

The chosen mode is stored in localStorage and applied by an inline script before first paint to avoid flashing. Signatures, code blocks, package names and type names always stay in English and are never translated.