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.extensions.model.dashscope.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();

Quick Start

Features

Multi Agent

Harness

Creating ReActAgent

Additional Configuration

Execution Control

Timeout and Retry

Tool Execution Context

Plan Management

UserAgent

​Creating ReActAgent

​Additional Configuration

​Execution Control

​Timeout and Retry

​Tool Execution Context

​Plan Management

​UserAgent

Creating ReActAgent

Additional Configuration

Execution Control

Timeout and Retry

Tool Execution Context

Plan Management

UserAgent