This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
AgentScope Java is a reactive, agent-oriented programming framework for building LLM-powered applications. It's built on Project Reactor and follows reactive programming principles.
**Key Characteristics:** - **Reactive Architecture**: All asynchronous operations use Project Reactor's `Mono` and `Flux` - **ReAct Paradigm**: Agents autonomously reason and act using the ReAct (Reasoning-Acting) pattern - **Multi-Agent Collaboration**: Support for distributed agent communication via A2A protocol - **Production-Ready**: Includes tool sandboxing, observability with OpenTelemetry, and GraalVM native image support
## Module Structure
This is a multi-module Maven project with the following modules:
1. **agentscope-core** - Core framework containing: - Agent implementations (`ReActAgent`, `UserAgent`, etc.) - Model integrations (Anthropic, DashScope, Gemini) - Formatters and message converters - Tool system and MCP (Model Context Protocol) integration - Reactive stream handling with Project Reactor
2. **agentscope-extensions** - Optional extensions including: - RAG (Retrieval-Augmented Generation) with simple and advanced implementations - Skill repositories (MySQL, Redis session storage) - Scheduler integrations (Quartz, XXL-Job) - AGUI (Automated GUI interaction) - Nacos integration for service discovery and A2A protocol - Quarkus extensions
3. **agentscope-examples** - Example applications demonstrating: - Quickstart tutorials - Multi-agent patterns - Plan notebook system - Boba tea shop simulation - Werewolf game with human-in-the-loop
4. **agentscope-dependencies-bom** - BOM (Bill of Materials) for dependency management 5. **agentscope-distribution** - Distribution and packaging modules
## Development Commands
### Building and Testing ```bash # Build all modules mvn clean compile
# Run all tests mvn test
# Run specific test class mvn test -Dtest=YourTestClassName
# Build with tests and coverage (CI standard) mvn clean verify
# Build with Maven Daemon (faster, used in CI) mvnd -B -T1 clean verify ```
### Development Tools ```bash # Install mvnd (Maven Daemon) for faster builds curl -fsSL https://github.com/apache/maven-mvnd/releases/download/1.0.3/maven-mvnd-1.0.3-linux-amd64.tar.gz | tar xz mkdir -p ~/.mvnd mv maven-mvnd-1.0.3-linux-amd64/* ~/.mvnd/ ```
## Critical Coding Guidelines
### 🚫 ABSOLUTELY FORBIDDEN 1. **NEVER use `.block()` in library/agent code** - Only allowed in `main()` methods or test code 2. **NEVER use `Thread.sleep()`** - Use `Mono.delay()` for delays 3. **NEVER use `ThreadLocal`** - Use Reactor Context with `Mono.deferContextual()` 4. **NEVER hardcode API keys** - Always use `System.getenv()` or configuration 5. **NEVER ignore errors silently** - Always provide error handling with `.onErrorResume()` or `.onErrorReturn()`
### ✅ ALWAYS DO 1. **Use reactive patterns** - Chain operations with `.map()`, `.flatMap()`, `.then()` 2. **Use Builder pattern** for creating agents, models, and messages 3. **Add logging** with SLF4J for important operations 4. **Use correct imports**: `import io.agentscope.core.model.DashScopeChatModel;` (NOT `io.agentscope.model.*`) 5. **Follow API conventions** (see SKILL.md for detailed API mappings)
// ❌ WRONG - Blocking in agent logic (NEVER do this) String result = model.generate(messages, null, null).block();
// ✅ CORRECT - Only allowed in main() methods public static void main(String[] args) { // ⚠️ .block() is ONLY allowed here because this is a main() method Msg response = agent.call(userMsg).block(); System.out.println(response.getTextContent()); } ```
## Key Architectural Concepts
### Agents - **ReActAgent**: Primary agent implementation using Reasoning-Acting pattern - **UserAgent**: For human-in-the-loop interactions - **ObservableAgent**: Agents that can be observed via event streams - **StreamableAgent**: Support for streaming responses
### Messaging - **Msg**: Primary message class with content, metadata, and conversation history - **Content types**: Text, image, audio, tool calls, tool results - **Formatter system**: Convert between LLM provider formats and internal Msg representation
### Tools and Skills - **Tool system**: Register Java methods as tools with `@Tool` annotation - **Skill repository**: Persistent storage and retrieval of tools/skills - **MCP integration**: Connect to Model Context Protocol servers for external tool access - **Tool validation**: JSON schema validation for tool inputs
### Hooks and Observability - **StreamingHook**: Intercept and modify streaming responses - **StructuredOutputHook**: Handle structured output parsing and self-correction - **OpenTelemetry integration**: Distributed tracing across agent execution
## Configuration and Environment
### Required Environment Variables ```bash # Model API keys (examples) export DASHSCOPE_API_KEY="your-key" export ANTHROPIC_API_KEY="your-key" export GEMINI_API_KEY="your-key" ```
### Maven Dependency ```xml <dependency> <groupId>io.agentscope</groupId> <artifactId>agentscope</artifactId> <version>1.0.9</version> <!-- Check for latest version --> </dependency> ```
## Testing Strategy
- **Unit tests**: Use JUnit 5 with Project Reactor's `StepVerifier` for testing reactive streams - **Integration tests**: Mock external services with OkHttp's `MockWebServer` - **Coverage**: JaCoCo integration with `mvn verify` generating coverage reports - **Test isolation**: Each test should be independent and not rely on shared state
Examples: ```bash feat(agent): add support for Claude-3 model fix(memory): resolve memory leak in ReActAgent docs(readme): update installation instructions ```
## Resources - **Documentation**: https://java.agentscope.io/ - **GitHub Issues**: https://github.com/agentscope-ai/agentscope-java/issues - **SKILL.md**: Detailed API reference and coding guidelines in repository root - **Examples**: Comprehensive examples in `agentscope-examples/` directory
