Python ↔ Java 对照Python ↔ Java mapping

Both editions share concepts but differ in naming, package layout and concurrency. This page maps them item by item so you can migrate code or read the two APIs side by side.

1. Concepts and types

2. Constructing a model

Python

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

model = OpenAIChatModel(
    credential=OpenAICredential(api_key="sk-..."),
    model="gpt-4o-mini",
    stream=True,
)

Java

import io.agentscope.extensions.model.openai.OpenAIChatModel;

OpenAIChatModel model = OpenAIChatModel.builder()
    .apiKey("sk-...")
    .modelName("gpt-4o-mini")
    .stream(true)
    .build();

Difference: Python passes a reusable credential object; most Java vendor builders take the key directly and expose httpTransport, proxy, etc.

3. Constructing messages

Python

from agentscope.message import UserMsg

msg = UserMsg("user", "What's the weather in Hangzhou?")

Or with explicit blocks:

from agentscope.message import Msg, TextBlock

msg = Msg(
    name="user",
    role="user",
    content=[TextBlock(text="What's the weather in Hangzhou?")],
)

Java

import io.agentscope.core.message.Msg;
import io.agentscope.core.message.MsgRole;

Msg msg = Msg.builder()
    .name("user")
    .role(MsgRole.USER)
    .textContent("What's the weather in Hangzhou?")
    .build();

Difference: Python roles are string literals; Java uses the MsgRole enum and also offers UserMessage, AssistantMessage, etc.

4. Registering tools

Python

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

import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;
import io.agentscope.core.tool.Toolkit;

public final class WeatherTools {
    @Tool(name = "get_weather", description = "Return the current weather for a city.")
    public String getWeather(
            @ToolParam(name = "city", description = "The city name") String city) {
        return city + ": sunny, 24C";
    }
}

Toolkit toolkit = new Toolkit();
toolkit.registerTool(new WeatherTools());

Difference: Python derives the schema from function metadata; Java declares it with annotations and can set read-only, concurrency-safe and dangerous-path policies on @Tool.

5. Building the agent

Python

from agentscope.agent import Agent, ReActConfig

agent = Agent(
    name="assistant",
    system_prompt="You are a concise assistant.",
    model=model,
    toolkit=toolkit,
    react_config=ReActConfig(max_iters=10),
)

Java

import io.agentscope.core.ReActAgent;

ReActAgent agent = ReActAgent.builder()
    .name("assistant")
    .sysPrompt("You are a concise assistant.")
    .model(model)
    .toolkit(toolkit)
    .maxIters(10)
    .build();

Difference: Python groups parameters into config objects (ReActConfig, ContextConfig, ModelConfig); Java flattens common options onto the builder and attaches complex capabilities (RAG, skills, long-term memory) with dedicated methods.

6. Calling and streaming

Python

reply = await agent.reply(msg)
print(reply.get_text_content())

async for event in agent.reply_stream(msg):
    if isinstance(event, TextBlockDeltaEvent):
        print(event.delta, end="")

Java

Msg reply = agent.call(msg).block();
System.out.println(reply.getTextContent());

agent.streamEvents("Explain ReAct.")
    .doOnNext(event -> {
        if (event instanceof TextBlockDeltaEvent delta) {
            System.out.print(delta.getDelta());
        }
    })
    .blockLast();

Difference: Python returns an async generator from reply_stream; Java returns Flux. Python returns the final message directly from reply; Java blocks or subscribes to a Mono.

7. Structured output

Python

class Report(BaseModel):
    city: str
    temperature_c: float

reply = await agent.reply(msg, structured_schema=Report)
data = reply.structured_output

Java

public record Report(String city, double temperatureC) {}

Msg reply = agent.call(msg, Report.class).block();
Report report = reply.getStructuredData(Report.class);

Difference: Python uses a Pydantic model; Java uses a class/record with Jackson. Both implement it as a tool call inside the loop.

8. State and persistence

Python

from agentscope.state import AgentState

state = AgentState(session_id="demo")
agent = Agent(..., state=state)

payload = state.model_dump_json()

Java

import io.agentscope.core.state.AgentState;
import io.agentscope.core.state.JsonFileAgentStateStore;

AgentState state = AgentState.builder()
    .sessionId("demo")
    .userId("user-1")
    .build();

var store = new JsonFileAgentStateStore(Path.of("./state"));
ReActAgent agent = ReActAgent.builder()
    .stateStore(store)
    .defaultSessionId("demo")
    .build();

Difference: Python leaves storage to the caller; Java abstracts it behind AgentStateStore with in-memory, JSON, MySQL and Redis implementations.

9. RAG

Python

from agentscope.rag import KnowledgeBase, MilvusLiteStore

kb = KnowledgeBase(
    name="handbook",
    description="Engineering handbook",
    embedding_model=embedding,
    vector_store=MilvusLiteStore(uri="./kb.db"),
    collection="handbook",
)
hits = await kb.search(["deployment"], top_k=5)

Java

import io.agentscope.core.rag.knowledge.SimpleKnowledge;
import io.agentscope.core.rag.store.InMemoryStore;

SimpleKnowledge kb = SimpleKnowledge.builder()
    .embeddingModel(embeddingModel)
    .embeddingStore(InMemoryStore.builder().dimensions(1536).build())
    .build();

var hits = kb.retrieve("deployment",
    RetrieveConfig.builder().limit(5).build()).block();

Difference: Python's KnowledgeBase takes a collection name directly; Java uses the Knowledge interface plus VDBStoreBase, where the store usually owns dimension configuration.

10. Migration notes

1. Concurrency — Python uses await, Java uses Reactor. Never block inside a Java map.
2. Errors — Python raises exceptions; Java propagates error signals through Mono/Flux (onErrorResume, ...).
3. Cancellation — Python uses asyncio.CancelledError and interruption events; Java uses Disposable, interrupt() and Reactor cancellation.
4. Config granularity — Python config objects are reusable; Java builders freeze configuration at build time.
5. Packages — Java model providers, RAG stores and protocol support live in separate Maven artifacts, so migrations must update dependencies too.