AgentScope

application -> prompt -> model -> response

user goal
   |
   v
model reasons -> chooses a tool -> application executes it
      ^                                  |
      +----------- tool result <---------+
   |
   v
final answer, interruption, or next action

pip install agentscope

import asyncio
import os

from agentscope.agent import Agent
from agentscope.credential import DashScopeCredential
from agentscope.message import UserMsg
from agentscope.model import DashScopeChatModel


async def main() -> None:
    agent = Agent(
        name="assistant",
        system_prompt="You are a concise technical assistant.",
        model=DashScopeChatModel(
            credential=DashScopeCredential(
                api_key=os.environ["DASHSCOPE_API_KEY"],
            ),
            model="qwen3.6-plus",
        ),
    )

    async for event in agent.reply_stream(
        UserMsg("alice", "Explain optimistic locking."),
    ):
        print(event)


asyncio.run(main())

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.agentscope</groupId>
      <artifactId>agentscope-bom</artifactId>
      <version>2.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-core</artifactId>
  </dependency>
  <dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-model-dashscope</artifactId>
  </dependency>
</dependencies>

import io.agentscope.core.ReActAgent;
import io.agentscope.core.message.Msg;
import io.agentscope.core.message.UserMessage;
import io.agentscope.extensions.model.dashscope.DashScopeChatModel;

public class FirstAgent {

    public static void main(String[] args) {
        var model = DashScopeChatModel.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .modelName("qwen-plus")
                .stream(true)
                .build();

        var agent = ReActAgent.builder()
                .name("technical-assistant")
                .sysPrompt("""
                        You are a technical assistant.
                        Distinguish facts from assumptions.
                        Ask before performing a destructive operation.
                        """)
                .model(model)
                .build();

        Msg result = agent.call(
                new UserMessage("Explain write skew in two paragraphs.")
        ).block();

        System.out.println(result.getTextContent());
    }
}

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

public final class OrderTools {

    private final OrderService orders;

    public OrderTools(OrderService orders) {
        this.orders = orders;
    }

    @Tool(
            name = "get_order",
            description = "Get the current state of an order visible to the caller",
            readOnly = true)
    public OrderView getOrder(
            @ToolParam(
                    name = "order_id",
                    description = "Numeric order ID")
            long orderId,
            RequestIdentity identity) {
        return orders.get(identity.tenantId(), identity.userId(), orderId);
    }

    @Tool(
            name = "cancel_order",
            description = """
                    Cancel an order that has not shipped. This changes business
                    state and must be approved by the user before execution.
                    """)
    public OrderView cancelOrder(
            @ToolParam(
                    name = "order_id",
                    description = "Numeric order ID")
            long orderId,
            @ToolParam(
                    name = "reason",
                    description = "Business reason for cancellation")
            String reason,
            RequestIdentity identity) {
        return orders.cancel(
                identity.tenantId(),
                identity.userId(),
                orderId,
                reason);
    }
}

Toolkit toolkit = new Toolkit();
toolkit.registerTool(new OrderTools(orderService));

ReActAgent agent = ReActAgent.builder()
        .name("order-assistant")
        .sysPrompt("""
                Help users inspect their orders.
                Never cancel an order without explicit approval.
                """)
        .model(model)
        .toolkit(toolkit)
        .build();

REST or WebSocket controller
        |
        v
AgentScope agent factory
        |
        +----> model provider
        +----> application tools ----> existing Spring services
        +----> shared state store

import io.agentscope.core.ReActAgent;
import io.agentscope.core.state.AgentStateStore;
import io.agentscope.core.state.JsonFileAgentStateStore;
import io.agentscope.core.tool.Toolkit;
import io.agentscope.extensions.model.dashscope.DashScopeChatModel;
import java.nio.file.Path;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@ConfigurationProperties(prefix = "app.agent")
record AgentProperties(String apiKey, String model) {
}

@Configuration
@EnableConfigurationProperties(AgentProperties.class)
class AgentConfiguration {

    @Bean
    DashScopeChatModel agentModel(AgentProperties properties) {
        return DashScopeChatModel.builder()
                .apiKey(properties.apiKey())
                .modelName(properties.model())
                .stream(true)
                .build();
    }

    @Bean
    AgentStateStore agentStateStore() {
        return new JsonFileAgentStateStore(
                Path.of(".agentscope", "sessions"));
    }

    @Bean
    Toolkit orderToolkit(OrderService orders) {
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(new OrderTools(orders));
        return toolkit;
    }

    @Bean
    OrderAgentFactory orderAgentFactory(
            DashScopeChatModel model,
            AgentStateStore stateStore,
            Toolkit orderToolkit) {
        return new OrderAgentFactory(model, stateStore, orderToolkit);
    }
}

app:
  agent:
    model: qwen-plus
    api-key: ${DASHSCOPE_API_KEY}

public record OrderAgentFactory(
        DashScopeChatModel model,
        AgentStateStore stateStore,
        Toolkit toolkit) {

    ReActAgent create() {
        return ReActAgent.builder()
                .name("order-assistant")
                .sysPrompt("""
                        Help the authenticated user inspect orders.
                        Use tools for current order data.
                        Never claim that a mutation succeeded unless its tool
                        returned a successful result.
                        """)
                .model(model)
                .stateStore(stateStore)
                .toolkit(toolkit)
                .build();
    }
}

import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.event.TextBlockDeltaEvent;
import io.agentscope.core.message.UserMessage;
import java.security.Principal;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

record ChatRequest(String sessionId, String message) {
}

record RequestIdentity(String tenantId, String userId) {
}

@RestController
@RequestMapping("/api/assistant")
class AgentController {

    private final OrderAgentFactory agents;
    private final TenantResolver tenants;

    AgentController(OrderAgentFactory agents, TenantResolver tenants) {
        this.agents = agents;
        this.tenants = tenants;
    }

    @PostMapping(
            path = "/messages",
            produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    Flux<String> chat(
            @RequestBody ChatRequest request,
            Principal principal) {
        String userId = principal.getName();
        String tenantId = tenants.currentTenant();

        RuntimeContext context = RuntimeContext.builder()
                .userId(userId)
                .sessionId(request.sessionId())
                .put(
                        RequestIdentity.class,
                        new RequestIdentity(tenantId, userId))
                .build();

        return agents.create()
                .streamEvents(
                        new UserMessage(request.message()),
                        context)
                .filter(TextBlockDeltaEvent.class::isInstance)
                .cast(TextBlockDeltaEvent.class)
                .map(TextBlockDeltaEvent::getDelta);
    }
}

permission rule:
  Is this category of tool allowed in this agent flow?

OrderService authorization:
  May this authenticated user cancel this specific order?

Spring Boot service
    -> authenticated HTTP, A2A, or messaging contract
    -> Python AgentScope service
    -> model and tools