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>0.1.1</version>
</dependency>

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

Basic Agent Usage Example

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

1. Create Agent

import io.agentscope.core.ReActAgent;
import io.agentscope.core.formatter.dashscope.DashScopeChatFormatter;
import io.agentscope.core.memory.InMemoryMemory;
import io.agentscope.core.tool.Toolkit;
import io.agentscope.runtime.engine.agents.agentscope.AgentScopeAgent;
import io.agentscope.runtime.engine.agents.agentscope.tools.ToolkitInit;
import io.agentscope.core.model.DashScopeChatModel;

// Create ReActAgent
ReActAgent.Builder agentBuilder = ReActAgent.builder()
    .name("Friday")
    .sysPrompt("You're a helpful assistant named Friday.")
    .memory(new InMemoryMemory())
    .model(DashScopeChatModel.builder()
        .apiKey(System.getenv("AI_DASHSCOPE_API_KEY"))
        .modelName("qwen-turbo")
        .stream(true)
        .enableThinking(true)
        .formatter(new DashScopeChatFormatter())
        .build());

// Create Runtime AgentScopeAgent
AgentScopeAgent agentScopeAgent = AgentScopeAgent.builder()
    .agent(agentBuilder)
    .build();

System.out.println("✅ AgentScope agent created successfully");

2. Configure Sandbox Manager (Optional but Recommended)

// Create Toolkit
Toolkit toolkit = new Toolkit();
toolkit.registerTool(ToolkitInit.RunPythonCodeTool());
toolkit.registerTool(ToolkitInit.RunShellCommandTool());

// Add Tools for Agent
// ...
agentBuilder.toolkit(toolkit)
// ...

// Create sandbox manager configuration (using default Docker configuration)
ManagerConfig managerConfig = ManagerConfig.builder().build();
// Create environment manager
EnvironmentManager environmentManager = new DefaultEnvironmentManager(new SandboxManager(managerConfig));

Note

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

3. Create Runner

The Runner combines the agent, context manager, and environment manager:

import io.agentscope.runtime.engine.Runner;

Runner runner = Runner.builder()
    .agent(agentScopeAgent)  // or saaAgent
    .contextManager(contextManager)
    .environmentManager(environmentManager)  // Required if using sandbox tools
    .build();

System.out.println("✅ Runner created successfully");

4. Deploy Agent

Use LocalDeployManager to deploy the agent as an A2A service:

import io.agentscope.runtime.LocalDeployManager;

// Deploy agent (default port 8080)
LocalDeployManager.builder()
    .port(8090)
    .build()
    .deploy(runner);

System.out.println("✅ Agent deployed successfully on port 8090");

Note

The usage method for Spring AI Alibaba is very similar. 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...

---

🏗️ Deployment

AgentScope Runtime Java can expose agents on a port using the standard A2A protocol or custom endpoints.

To change the port or host, deploy as follows:

LocalDeployManager.builder()
    .port(10001)
    .build()
    .deploy(runner);

---

🤝 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.

---