AgentScope Runtime for Java

Cookbook

AgentScope Runtime Java

This is the Java implementation of AgentScope Runtime.

---

✨ Key Features

• Deployment Infrastructure: Built-in services for session management, memory, and sandbox environment control
• Sandboxed Tool Execution: Isolated sandboxes ensure safe tool execution without system compromise
• Developer Friendly: Simple deployment with powerful customization options
• Framework Agnostic: Not tied to any specific framework. Works seamlessly with popular open-source agent frameworks and custom implementations
• 🚧 Observability: Trace and visualize agent operations comprehensively

---

💬 Community

Join our community on DingTalk:

DingTalk

---

📋 Table of Contents

• Quick Start
• Agent Framework Integration
• Deployment
• Contributing
• License

---

🚀 Quick Start

Prerequisites

• Java 17 or higher
• Maven 3.6+

Add Dependency

Add the following dependency to your pom.xml:

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>spring-boot-starter-runtime-a2a</artifactId>
    <version>1.0.0-BETA1</version>
</dependency>

<!-- Add AgentScope Agent adapter dependency -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-runtime-agentscope</artifactId>
    <version>1.0.0-BETA1</version>
</dependency>

Basic Agent Usage Example

The following example demonstrates how to delegate a AgentScope ReactAgent using AgentScope Runtime. The complete source code can be found in the examples directory.

1. Create Agent Handler

Create a custom agent handler by extending AgentScopeAgentHandler:

public class MyAgentScopeAgentHandler extends AgentScopeAgentHandler {
    
    @Override
    public Flux<io.agentscope.core.agent.Event> streamQuery(AgentRequest request, Object messages) {
        // Create Toolkit and register tools
        Toolkit toolkit = new Toolkit();
        if (sandboxService != null) {
            Sandbox sandbox = sandboxService.connect(
                request.getUserId(), 
                request.getSessionId(), 
                BaseSandbox.class
            );
            toolkit.registerTool(ToolkitInit.RunPythonCodeTool(sandbox));
        }
        
        // Create ReActAgent with tools
        ReActAgent agent = ReActAgent.builder()
            .name("Friday")
            .toolkit(toolkit)
            .model(DashScopeChatModel.builder()
                .apiKey(System.getenv("AI_DASHSCOPE_API_KEY"))
                .modelName("qwen-max")
                .stream(true)
                .formatter(new DashScopeChatFormatter())
                .build())
            .build();
        
        // Convert messages and stream agent responses
        // See examples/README.md for complete implementation
        return agent.stream(queryMessage, streamOptions);
    }
}

2. Initialize Services and Deploy

Configure the agent handler with required services and deploy using AgentApp:

// Create and configure the agent handler
MyAgentScopeAgentHandler agentHandler = new MyAgentScopeAgentHandler();
agentHandler.setStateService(new InMemoryStateService());
agentHandler.setSessionHistoryService(new InMemorySessionHistoryService());
agentHandler.setMemoryService(new InMemoryMemoryService());
agentHandler.setSandboxService(new SandboxService(
    new SandboxManager(ManagerConfig.builder().build())
));

// Deploy using AgentApp
AgentApp agentApp = new AgentApp(agentHandler);
agentApp.run(8090); // Server will listen on port 8090

Note

You can also use Kubernetes or Alibaba FC platform AgentRun to execute sandbox tools. Please refer to the examples directory for more details.

---

🔌 Agent Framework Integration

AgentScope Runtime Java implementation can be easily integrated with any agent frameworks developed in Java. Currently supported frameworks include:

• AgentScope Java
• Spring AI Alibaba, Langchain4j and more coming soon...

---

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

🐛 Bug Reports

• Use GitHub Issues to report bugs
• Include detailed reproduction steps
• Provide system information and relevant logs

💡 Feature Requests

• Discuss new ideas in GitHub Discussions
• Follow the feature request template
• Consider implementation feasibility

🔧 Code Contributions

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For detailed contributing guidelines, please see CONTRIBUTING.md.

---

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

---