核心精讲Core deep dives

Agent is the core agent implementation in AgentScope 2.x. It owns the reasoning-acting loop, tool execution, context compression and event stream, assembling a model, tools, memory and middleware into a persistable session runtime.

ReActConfig describes the policy of the reasoning-acting loop: how many iterations to allow, how much grace to give structured output, and how to end when a tool call is rejected or the reply is interrupted.

Msg is the unified carrier exchanged between agents. Its content is a list of blocks such as TextBlock, ThinkingBlock, ToolCallBlock and ToolResultBlock, covering plain text, multimodal data and tool interactions.

Toolkit is the unified registry for tools, skills and MCP clients. It turns Python functions or MCP tools into model-readable schemas and handles permission checks, concurrency and result wrapping at call time.

ChatModelBase is the abstraction shared by all chat models. It unifies streaming and non-streaming calls, token counting, retries and structured output so upper layers can switch providers without code changes.

OpenAIChatModel speaks the OpenAI Chat Completions protocol to OpenAI and compatible endpoints, with streaming, tool calls, structured output and a customizable formatter.

FormatterBase converts a list of Msg objects into provider requests and parses provider responses back into ChatResponse. It isolates differences in tool, multimodal and role encoding across models.

AgentState stores all mutable state of a session: message context, reply context, permissions, tool and task context. It lets agents resume after a restart and supports concurrency control for the same session.

MiddlewareBase exposes hooks for reply, reasoning, acting, model calls, permission checks, context compression and system prompts. Middleware wraps the next handler, adding logging, auditing, caching or policy without modifying agent source.

KnowledgeBase binds an embedding model, a vector store and a collection name, providing document ingestion, vector search and document/chunk management. It can be exposed as a tool or used by RAGMiddleware to inject retrieved context.

MCPClient manages a connection to an MCP server over STDIO or HTTP. It discovers remote tools as ToolBase objects, registers them into a Toolkit in one step, and owns lifecycle and timeout handling.

FunctionTool derives a tool schema from a Python function's signature, type hints and docstring, and wraps results into ToolResponse. It is the most common way to add custom tools.

ReActAgent is the core agent in Java. Its builder assembles the model, tools, permissions, state store and middleware; call returns Mono and streamEvents returns a stream of AgentEvent.

AgentBase implements the lifecycle shared by all agents: run mutual exclusion, hooks, state restoration, structured output dispatch and cooperative interruption. Custom agents typically extend it and implement doCall.

RuntimeContext carries per-call session/user identity, AgentState, tool execution configuration and custom attributes. It is not persisted; cross-call state belongs in AgentState.

Msg is the unified message object in Java, composed of a MsgRole and a list of ContentBlock. The builder constructs messages, while getTextContent and getStructuredData provide common accessors.

Toolkit scans @Tool-annotated methods, converts Java methods into model tool schemas, and handles lookup, grouping, MCP registration and permission metadata.

ChatModelBase defines the Java model contract: stream returns Flux and subclasses implement doStream. It also exposes capability flags such as context window and native structured output.

OpenAIChatModel lives in the official openai extension. Its builder configures API key, model name, endpoint, formatter and context window while implementing the ChatModelBase streaming protocol.

Formatter converts Msg lists and GenerateOptions into provider requests and parses responses into ChatResponse. applyTools and applyOptions map tools and sampling parameters onto the provider protocol.

AgentState stores the Java agent's context, summary, reply progress, permissions, tool and task state. The builder constructs it, and AgentStateStore persists it across processes.

MiddlewareBase wraps agent execution as a Flux chain, exposing hooks such as onAgent, onReasoning, onActing, onModelCall and onSystemPrompt. order controls how multiple middlewares nest.

SimpleKnowledge is a ready-made implementation of the Knowledge interface, combining an EmbeddingModel with a vector store to provide document ingestion and similarity search. It can be passed to ReActAgent.builder().knowledge(...).

McpClientBuilder creates MCP clients over STDIO, SSE or Streamable HTTP, with common headers, query parameters and timeouts. The resulting client registers directly into a Toolkit.