agentscope-java_skill

Overview

This skill is an expert Java developer guide for AgentScope Java, a reactive, message-driven multi-agent framework built on Project Reactor. It focuses on non-blocking agent design, LLM integration, toolkits, hooks, and production-ready patterns. Use it when building or debugging agents, pipelines, or reactive model integrations in Java 17+.

How this skill works

The skill inspects code and offers patterns that return Mono/Flux rather than blocking calls, enforces correct AgentScope imports and builder usage, and recommends safe defaults for models, tools, and hooks. It validates reactive best practices (no .block() in agent logic, no Thread.sleep/ThreadLocal), enforces environment-based secrets, and adds error handling and SLF4J logging. It also provides Maven dependency guidance and examples for tool registration, memory, and pipeline composition.

When to use it

• When implementing agents or agent pipelines using AgentScope Java.
• When integrating LLMs (OpenAI, DashScope, Gemini, Anthropic, Ollama) without blocking the Reactor chain.
• When creating or registering tools and toolkits for agents.
• When adding hooks to intercept lifecycle events or streaming reasoning chunks.
• When preparing production-ready, reactive agent applications with proper error handling.

Best practices

• Always return Mono or Flux for asynchronous operations; chain with map/flatMap/then.
• Never call .block() in agent logic or service methods (.block() allowed only in main() or tests with a comment).
• Use Reactor Context (Mono.deferContextual()) instead of ThreadLocal and Mono.delay() instead of Thread.sleep().
• Load API keys from System.getenv() and never hardcode secrets; add onErrorResume/onErrorReturn with logging.
• Use the Builder pattern for Msg, models, and messages; use correct imports from io.agentscope.core.model.*.
• Register tools via toolkit.registerTool() and follow @ToolParam(name = "x", description = "y") format exactly.

Example use cases

• Create a custom Agent by extending AgentBase that stores to InMemoryMemory and calls a DashScopeChatModel via non-blocking model.generate(...).
• Build an asynchronous tool that uses WebClient and returns Mono<String> with URL validation and onErrorResume fallback.
• Compose a pipeline that orchestrates multiple agents in sequence and streams reasoning chunks with Flux and Hook notifications.
• Implement a Hook to log PreReasoningEvent and PostActingEvent, modifying events reactively and returning Mono of the event.
• Configure a production pom.xml using agentscope:1.0.8 and optionally add mem0 or rag-dify extensions for long-term memory and RAG.