Create ReAct Agent

AgentScope provides an out-of-the-box ReAct agent ReActAgent for developers.

It supports the following features:

• Basic Features

  • Hooks around reasoning and acting

  • Structured output

• Realtime Steering

  • User interruption

  • Custom interrupt handling

• Tools

  • Sync/async tool functions

  • Streaming tool responses

  • Parallel tool calls

  • MCP server integration

• Memory

  • Agent-controlled long-term memory

  • Static long-term memory management

Creating ReActAgent

The ReActAgent class exposes the following parameters in its constructor:

Parameter	Further Reading	Description
name (required)		Agent’s name
sysPrompt		System prompt (recommended)
model (required)	Model Integration	Model for generating responses
toolkit	Tool System	Module for registering/calling tool functions
memory	Memory Management	Short-term memory for conversation history
description		Agent description
generateOptions		LLM generation parameters (temperature, topP, maxTokens, etc.)
toolExecutionContext	Tool System	Tool execution context for dependency injection into tools
planNotebook	Planning	Plan manager
longTermMemory	Memory Management	Long-term memory
longTermMemoryMode	Memory Management	Long-term memory mode: AGENT_CONTROL, STATIC_CONTROL, or BOTH
maxIters		Max iterations for generating response (default: 10)
hooks	Hook System	Event hooks for customizing agent behavior
modelExecutionConfig		Timeout/retry config for model calls
toolExecutionConfig		Timeout/retry config for tool calls

Using DashScope API as an example, we create an agent as follows:

import io.agentscope.core.ReActAgent;
import io.agentscope.core.message.Msg;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.tool.Toolkit;
import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;

public class QuickStart {
    public static void main(String[] args) {
        // Prepare tools
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(new SimpleTools());

        // Create agent
        ReActAgent jarvis = ReActAgent.builder()
            .name("Jarvis")
            .sysPrompt("You are an assistant named Jarvis.")
            .model(DashScopeChatModel.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .modelName("qwen3-max")
                .build())
            .toolkit(toolkit)
            .build();

        // Send message
        Msg msg = Msg.builder()
            .textContent("Hello Jarvis, what time is it now?")
            .build();

        Msg response = jarvis.call(msg).block();
        System.out.println(response.getTextContent());
    }
}

// Tool class
class SimpleTools {
    @Tool(name = "get_time", description = "Get current time")
    public String getTime(
            @ToolParam(name = "zone", description = "Timezone, e.g., Beijing") String zone) {
        return java.time.LocalDateTime.now()
            .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
    }
}

Additional Configuration

Execution Control

ReActAgent agent = ReActAgent.builder()
    .name("Assistant")
    .sysPrompt("You are a helpful assistant.")
    .model(model)
    .maxIters(10)              // Max iterations (default: 10)
    .checkRunning(true)        // Prevent concurrent calls (default: true)
    .build();

Timeout and Retry

ExecutionConfig modelConfig = ExecutionConfig.builder()
    .timeout(Duration.ofMinutes(2))
    .maxAttempts(3)
    .build();

ExecutionConfig toolConfig = ExecutionConfig.builder()
    .timeout(Duration.ofSeconds(30))
    .maxAttempts(1)  // Tools typically don't retry
    .build();

ReActAgent agent = ReActAgent.builder()
    .name("Assistant")
    .model(model)
    .modelExecutionConfig(modelConfig)
    .toolExecutionConfig(toolConfig)
    .build();

Tool Execution Context

Pass business context (e.g., user info) to tools without exposing to LLM:

ToolExecutionContext context = ToolExecutionContext.builder()
    .register(new UserContext("user-123"))
    .build();

ReActAgent agent = ReActAgent.builder()
    .name("Assistant")
    .model(model)
    .toolkit(toolkit)
    .toolExecutionContext(context)
    .build();

// Auto-injected in tool
@Tool(name = "query", description = "Query data")
public String query(
    @ToolParam(name = "sql") String sql,
    UserContext ctx  // Auto-injected, no @ToolParam needed
) {
    return "Query result for user " + ctx.getUserId();
}

Plan Management

Enable PlanNotebook for complex multi-step tasks:

// Quick enable
ReActAgent agent = ReActAgent.builder()
    .name("Assistant")
    .model(model)
    .enablePlan()
    .build();

// Custom configuration
PlanNotebook planNotebook = PlanNotebook.builder()
    .maxSubtasks(15)
    .build();

ReActAgent agent = ReActAgent.builder()
    .name("Assistant")
    .model(model)
    .planNotebook(planNotebook)
    .build();

UserAgent

An agent that receives external input (e.g., command line, Web UI):

UserAgent user = UserAgent.builder()
    .name("User")
    .build();

Msg userInput = user.call(null).block();