Java 快速开始Java quick start

This page targets agentscope-core 2.0.4 and agentscope-extensions-model-openai 2.0.4. The Java edition is built on Project Reactor: call returns Mono<Msg> and stream returns Flux<Event>, so the examples never rely on blocking APIs.

1. Maven dependencies

<properties>
  <agentscope.version>2.0.4</agentscope.version>
</properties>

<dependencies>
  <dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-core</artifactId>
    <version>${agentscope.version}</version>
  </dependency>
  <dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-model-openai</artifactId>
    <version>${agentscope.version}</version>
  </dependency>
</dependencies>

Gradle:

dependencies {
    implementation("io.agentscope:agentscope-core:2.0.4")
    implementation("io.agentscope:agentscope-extensions-model-openai:2.0.4")
}

Coordinates for every official extension are listed in Artifacts. Model providers, RAG stores, A2A, AG-UI and sandboxes are separate artifacts; add only what you need.

2. Create a model

Vendor models are constructed with builders:

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

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

Add .baseUrl("https://your-endpoint/v1") for compatible endpoints. Other vendors use their own extensions, such as DashScopeChatModel, AnthropicChatModel, GeminiChatModel or OllamaChatModel.

3. Define a tool

A tool is a plain method with annotations. Toolkit.registerTool(Object) scans @Tool methods and @ToolParam describes parameters:

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, for example Hangzhou")
            String city) {
        // Call a real weather API in production
        return city + ": sunny, 24C";
    }
}

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

@Tool also supports readOnly, concurrencySafe, strict, externalTool and stateInjected. To enable/disable groups dynamically, use tool groups (createToolGroup, updateToolGroups).

4. Build the agent and call it

import io.agentscope.core.ReActAgent;
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.Msg;

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

RuntimeContext context = RuntimeContext.builder()
    .sessionId("demo-session")
    .userId("demo-user")
    .build();

Msg reply = agent.call("What's the weather in Hangzhou?", context).block();
System.out.println(reply.getTextContent());

agent.close();

RuntimeContext carries per-call metadata: session/user identity, an optional AgentState, tool execution context and an attribute bag. It is not persisted; state that survives between calls lives in AgentState.

5. Streaming events

import io.agentscope.core.event.TextBlockDeltaEvent;

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

Use StreamOptions.builder().eventTypes(...) to filter which events you subscribe to. The event model (thinking, tool calls, tool results, reply completion, ...) lives in io.agentscope.core.event.

6. Structured output

Pass a result class to call to get type-safe output:

public record WeatherReport(String city, double temperatureC, String condition) {}

Msg reply = agent.call(
    "Report the weather in Hangzhou as structured data.",
    WeatherReport.class,
    context
).block();

WeatherReport report = reply.getStructuredData(WeatherReport.class);

The mechanism matches Python: a structured-output tool is injected into the loop and the model must call it with schema-conforming arguments. getStructuredData uses Jackson, so the result type must be Jackson-friendly (a record, POJO or annotated class).

7. State persistence

Java persists session state through AgentStateStore. The built-in JSON-file store is convenient for local development:

import io.agentscope.core.state.JsonFileAgentStateStore;

JsonFileAgentStateStore store = new JsonFileAgentStateStore(Path.of("./agent-state"));

ReActAgent agent = ReActAgent.builder()
    .name("assistant")
    .sysPrompt("You are a helpful assistant.")
    .model(model)
    .stateStore(store)
    .defaultSessionId("demo-session")
    .build();

Production deployments can use MysqlSession, RedisSession or a custom AgentStateStore. Remember that RuntimeContext is a call argument while the real conversation state lives in AgentState; do not confuse the two.

8. Add RAG

Java RAG is composed of Reader, a vector store and Knowledge. With the in-memory store:

import io.agentscope.core.rag.knowledge.SimpleKnowledge;
import io.agentscope.core.rag.model.RetrieveConfig;
import io.agentscope.core.rag.reader.ReaderInput;
import io.agentscope.core.rag.reader.TextReader;
import io.agentscope.core.rag.store.InMemoryStore;

// embeddingModel is e.g. DashScopeTextEmbedding / OpenAITextEmbedding
SimpleKnowledge knowledge = SimpleKnowledge.builder()
    .embeddingModel(embeddingModel)
    .embeddingStore(InMemoryStore.builder().dimensions(1536).build())
    .build();

knowledge.addDocuments(
    new TextReader().read(ReaderInput.fromString(handbookText)).block()
).block();

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

Pass it via ReActAgent.builder().knowledge(knowledge), or use GenericRAGHook to control retrieval timing. Production usually replaces the in-memory store with MilvusStore, QdrantStore, PgVectorStore or ElasticsearchStore.

9. Use the Spring Boot starter

For Spring Boot projects, add:

<dependency>
  <groupId>io.agentscope</groupId>
  <artifactId>agentscope-openai-spring-boot-starter</artifactId>
  <version>2.0.4</version>
</dependency>

OpenAIAutoConfiguration creates an OpenAIChatModel bean from OpenAIProperties. Inject the model and build your ReActAgent; implement OpenAIChatModelBuilderCustomizer to customize the builder. Other starters (DashScope, Anthropic, Gemini, Ollama, A2A, AG-UI, ...) follow the same pattern.

10. Next steps

• See ReActAgent for every builder option.
• See Toolkit for tools, MCP, tool groups and meta tools.
• See AgentState and AgentStateStore for persistence.
• Browse io.agentscope.core.memory for long-term memory implementations.
• To expose an agent over HTTP, look at the A2A server and AG-UI extensions.