核心概念Core concepts

AgentScope is not a thin prompt wrapper. It is a runtime organized around messages, models, agents, tools and state. Understanding how these layers relate matters more than memorizing constructor parameters; each concept below points to its Python and Java API entry points.

1. Layers

From bottom to top:

Dependencies always point downward. Agents depend on models and tools, models depend on formatters, and no layer depends back on agents. That constraint keeps models, tools and stores independently replaceable.

2. Messages

A message has a role, a sender name and a list of content blocks. Content blocks are the central abstraction: text, thinking, tool calls, tool results, images, audio and files are all just block types.

• Python's Msg is a Pydantic model with content: list[ContentBlock]. Build user messages with UserMsg (or Msg(role="user", content=[TextBlock(...)])); it wraps a plain string into a TextBlock automatically.
• Java's Msg is built with Msg.builder(). UserMessage, AssistantMessage, SystemMessage and ToolResultMessage are role subclasses. Msg.builder().textContent("...") is the shorthand for a single text segment.

Separating content blocks buys two things:

1. Multimodality needs no special API. Images, audio and files travel through the same message channel as DataBlock/ImageBlock.
2. Streaming deltas are structured. Thinking, text and tool-call arguments arrive as typed block events, so a UI can render by block type instead of parsing strings.

Messages also carry usage, finished_reason, structured_output and error. These do not enter the model context; they support billing, observability and recovery.

3. Models and formatters

A model adapter calls the vendor API and normalizes the response. A formatter translates AgentScope messages into that vendor's request shape. Keeping them separate lets the same agent logic move between OpenAI, DashScope, Anthropic, Gemini, Ollama and others without changing business code.

Python's ChatModelBase defines __call__, count_tokens and generate_structured_output. For example, OpenAIChatModel:

from agentscope.credential import OpenAICredential
from agentscope.model import OpenAIChatModel

model = OpenAIChatModel(
    credential=OpenAICredential(api_key="sk-...", base_url=None),
    model="gpt-4o-mini",
    stream=True,
    context_size=128_000,
)

On the Java side, Model is the common interface and vendor implementations live in agentscope-extensions-model-* artifacts. For example: OpenAIChatModel.builder().apiKey(...).modelName(...).build().

Three semantics are easy to miss:

• Streaming is the default. With stream=True the model yields incremental responses; the agent's reply_stream/stream wraps those into events.
• Retry belongs to the model layer. max_retries and retry_delay operate inside the adapter. Agent-level ModelConfig.max_retries counts failovers to a fallback model. Do not conflate them.
• The context window is a model property. context_size (Python) or contextWindowSize (Java) feeds context-compression thresholds.

4. The ReAct agent

ReAct = Reasoning + Acting. A reply is not a single model call but a loop:

1. Assemble system prompt, history, current input, tool schemas and structured-output constraints.
2. Call the model and stream thinking/text/tool calls.
3. If there is no tool call, finish with the final message.
4. If there are tool calls, execute them under the permission policy and append ToolResultBlocks to the context.
5. Repeat 2–4 until a final answer, the iteration limit, an interruption or an error.

Python's Agent is the default implementation. Its constructor separates concerns:

from agentscope.agent import Agent, ContextConfig, ReActConfig
from agentscope.tool import Toolkit

agent = Agent(
    name="assistant",
    system_prompt="You are a careful engineer.",
    model=model,
    toolkit=Toolkit(),
    react_config=ReActConfig(max_iters=12),          # loop limits and interruption
    context_config=ContextConfig(trigger_ratio=0.8), # context compression
)

It exposes three entry points:

• await agent.reply(msg) returns the final Msg;
• agent.reply_stream(msg) yields an async event stream for incremental UIs;
• await agent.observe(msg) writes a message into the context without calling the model, typically used to sync peers in multi-agent collaboration.

Java's ReActAgent configures the same concerns through a builder: name, sysPrompt, model, toolkit, maxIters, middlewares, stateStore, permissionContext and more. Execution is reactive:

Msg reply = agent.call("Summarize this repository.").block();

call returns Mono<Msg> and stream returns Flux<Event>. Event types (thinking deltas, tool calls, tool results, reply completion, etc.) live in io.agentscope.core.event.

Interruption and human confirmation

Tool execution can require human confirmation. Python expresses this through ToolCallBlock state and confirmation requests in the event stream; Java uses RequireUserConfirmEvent, ConfirmResult and the permission engine. Both follow the same rule: confirmation is a first-class state in the loop, not a temporary boolean in a callback. After an interruption, the agent resumes from saved state rather than replaying the whole conversation.

Structured output

reply(..., structured_schema=Model) / call(..., ResultType.class) constrain the output to a schema. This is not naive JSON parsing: the loop injects a structured-output tool that the model must call with schema-conforming arguments. Even if the model emits prose first, the final structured value remains usable.

5. Tools

Tools are the only channel through which an agent touches the outside world. Python's Toolkit manages three kinds of capability:

• Function tools: FunctionTool wraps a plain function; its signature and Google-style docstring become a JSON Schema.
• MCP tools: MCPClient connects to external MCP servers.
• Skills: Skill/SkillLoaderBase provide instructions and resources loaded on demand.

from agentscope.tool import FunctionTool, Toolkit

def get_weather(city: str) -> str:
    """Return the current weather for a city.

    Args:
        city: The city name.
    """
    return f"{city}: sunny, 24C"

toolkit = Toolkit(tools=[FunctionTool(get_weather)])

Java declares tools with annotations: Toolkit.registerTool(Object) scans @Tool methods and @ToolParam describes parameters. MCP clients register through McpClientBuilder; skills are managed by SkillBox and AgentSkillRepository.

The tool system also handles:

• Groups and activation — only active tool schemas are sent to the model, saving tokens;
• Concurrency and read-only flags — is_concurrency_safe / readOnly decide whether tools may run in parallel;
• Permission checks — every call passes through PermissionEngine, which can allow, deny or ask;
• Streaming tool results — long-running tools can emit ToolChunks while executing.

6. State, memory and sessions

AgentScope separates temporary variables of one reply from session state that must persist:

• Python's AgentState holds session_id, context, reply_context, tool_context, tasks_context, middle_context and more. It is serializable; your storage layer owns persistence.
• Java's AgentState has a similar shape and ships with the AgentStateStore abstraction plus in-memory, JSON-file, MySQL and Redis implementations.

Two concepts are easy to confuse:

• Context is the message list sent to the model; it grows with the conversation and must be compressed.
• Memory is information kept across sessions. Python wires it through AgenticMemoryMiddleware, Mem0Middleware and ReMeMiddleware; Java has dedicated Memory and LongTermMemory abstractions plus AgentStateMemoryView.

Context compression is controlled by ContextConfig (Python) or AutoContextConfig (Java). Once the threshold is crossed, the framework replaces older messages with a structured summary while preserving tool calls and task state. Compression is itself a model call and therefore appears in the event stream.

7. Middleware and hooks

Both are extension points, with different roles:

• Middleware wraps stages such as model call, reasoning and acting. It can modify inputs/outputs, short-circuit execution and inject context. Python's MiddlewareBase and Java's MiddlewareBase live here.
• Hooks observe loop events for tracing and intervention. Java's Hook system (PreReasoningEvent, PostActingEvent, ...) is the primary implementation; Python's event stream plays a similar role.

Rule of thumb: use middleware to change behavior, hooks/events to observe or record. Neither should hold mutable global state across requests, because one agent may serve several sessions concurrently.

8. Multi-agent systems and workflows

Python ships TeamPipeline and GoalPipeline: the former splits work across team members, the latter drives multiple rounds toward a goal. Agents synchronize through observe and coordinate state through a shared AgentState or external storage.

Java leans toward "agent as tool": SubAgentTool exposes one agent as a tool of another; the A2A extension connects remote agents as A2aAgent; the AG-UI extension adapts agent event streams to frontend protocols.

9. RAG and knowledge bases

RAG is split into four replaceable stages:

1. Parse — PDF, Word, PPT, Excel, images, plain text → documents;
2. Chunk — by token, paragraph or section;
3. Embed — EmbeddingModelBase / EmbeddingModel;
4. Retrieve — vector stores (Milvus, Qdrant, Elasticsearch, MongoDB, in-memory, ...).

Python's KnowledgeBase binds an embedding model to a vector collection and offers insert_document, search, delete_document. Java's counterpart is SimpleKnowledge with Reader and VDBStoreBase. On the agent side, RAGMiddleware (Python) or GenericRAGHook (Java) injects retrieved context.

10. Skills, MCP, permissions and workspaces

• Skills are instruction/resource bundles loaded on demand, so domain knowledge does not have to live in the system prompt. Python uses LocalSkillLoader; Java offers FileSystemSkillRepository, ClasspathSkillRepository and GitSkillRepository.
• MCP is the Model Context Protocol client. Python's MCPClient supports stdio and HTTP; Java's McpClientBuilder provides sync and async clients.
• Permissions: PermissionEngine decides allow/deny/ask based on tool, path and mode. Both editions support working-directory allowlists and dangerous-path checks.
• Workspaces provide isolated execution environments. Python has LocalWorkspace, DockerWorkspace, E2BWorkspace and more; Java exposes equivalent sandbox extensions.

11. Observability and deployment

• Python: TracingMiddleware, the event stream and the agentscope.tui console renderer.
• Java: OtelTracingMiddleware, JsonlTraceExporter and Reactor's Flux<Event>.
• Deployment: Python's agentscope.app provides web services, channels, storage and knowledge-base management; Java provides Spring Boot starters, an A2A server and an AG-UI runtime.

With these eleven blocks in mind, API pages stop feeling like a maze: every class belongs to a layer and every method is part of that layer's contract. Continue with the Python quick start or the Java quick start.