DOCSEARCHbyAlgolia
Submit Docs

AgentScope Runtime for Java

repository·main·Indexed 41 days ago

https://github.com/agentscope-ai/agentscope-runtime-java

A framework-agnostic deployment infrastructure for AI agents in Java. It provides session management, memory, and a sandboxed tool execution system supporting Python, Shell, and browser navigation. The runtime features a decoupled architecture with an Infrastructure Layer (supporting Docker, Kubernetes, and Cloud Functions) and an Application Layer for custom sandbox behaviors, and includes support for the Agent-to-Agent (A2A) protocol and DashScope (Qwen) LLM integration.

Tokens
50.2K
Snippets
111
Records
177
Agent score
51%

What's inside AgentScope Runtime for Java

  1. AgentScope Runtime Java Features

    main

    The AgentScope Runtime Java provides several capabilities for building intelligent agents:

    • Agent Construction: Build agents using the ReActAgent class.
    • LLM Integration: Support for DashScope (Qwen) large language models.
    • Tool Execution: Integrated sandboxed tools including Python execution, Shell command execution, and browser navigation.
    • Deployment: Local deployment as an A2A (Agent-to-Agent) application.
    • Streaming: Support for streaming responses and visualizing the agent's thinking process.
    • Packaging: One-click Docker image packaging support.

  2. Key Features of AgentScope Runtime Java V1.0

    main

    AgentScope Runtime Java V1.0 introduces several production-ready capabilities:

    • Unified Development/Production Paradigm: Consistent agent functionality across environments.
    • Native Multi-Agent Support: Full compatibility with AgentScope Java's multi-agent paradigm.
    • Protocol Integration: Supports OpenAI Responses API SDK and Google A2A protocol.
    • Visual Web UI: Includes an out-of-the-box web chat interface.
    • Extended Sandbox Types: Supports GUI, browser, and file system sandboxes (often visualizable via VNC).
    • Flexible Deployment: Supports local thread/process, Docker, Kubernetes, or managed cloud.

  3. Core features of AgentScope Runtime

    main

    AgentScope Runtime for Java provides several key capabilities for building agentic applications:

    • Deployment Infrastructure: Built-in services for session management, memory, and sandbox environment control.
    • Sandboxed Tool Execution: Isolated environments to ensure tool execution is secure and does not compromise the host system.
    • Framework Agnostic: Does not bind to a specific framework; it can work with any Java-based agent framework (e.g., AgentScope Java, Spring AI Alibaba, Langchain4j).
    • Observability (In Development): Comprehensive tracking and visualization of Agent operations.

  4. What is AgentScope Runtime Java?

    main

    AgentScope Runtime Java is a framework designed for efficient agent deployment and secure sandbox execution. It provides foundational services including:

    • Memory Services: Both long-term and short-term memory.
    • State Management: Agent state persistence.
    • Sandbox Infrastructure: Secure environments for tool execution.
    • Observability: Full tracking and monitoring of runtime operations.

    In version 1.0, the framework uses a white-box adapter pattern. Instead of replacing your existing agent modules (black-box), you embed runtime capabilities (like session recording or tool registration) into your application lifecycle. This allows you to preserve your original agent framework's interfaces and behavior while gaining access to AgentScope's production-grade services.

  5. What is the AgentScope Runtime Sandbox

    main

    The AgentScope Runtime Java Sandbox provides a secure and isolated environment designed for various agent tasks, including:

    • Tool execution
    • Browser automation
    • File system operations
    • Training and evaluation

    By default, the sandbox uses Docker for isolation. However, it also supports remote service backends via extension modules, such as Kubernetes (K8s) and Alibaba Cloud Function Compute (AgentRun and FC).

  6. What is the Training Sandbox in AgentScope Runtime Java

    main

    The Training Sandbox is a specialized environment designed for training and evaluating AI agents. It provides data based on public datasets (such as APPWorld, Webshop, and BFCL) to facilitate agent training, tool call simulation, and real-time reward validation.

    Key characteristics include:

    • High Concurrency: It implements high-concurrency data calls using Ray.
    • Lifecycle: Once a sandbox is created, external Agents can create, execute, and evaluate instances for different samples concurrently.
    • Dataset Support: It integrates environments like APPWorld (for complex multi-step tasks) and BFCL (for evaluating LLM function calling capabilities).

  7. What is the Agent State Service and how does it differ from Session History?

    main

    The Agent State Service is a core component designed for storing and managing an agent's serializable state. This allows agents to maintain internal context (like variable values, execution progress, or intermediate tool results) across multiple conversation rounds or different sessions.

    Key distinction:

    • Session History Service: Primarily stores text-based message histories.
    • Agent State Service: Focuses on structured, serializable data (e.g., the output of an agent's state_dict() method) that can be reloaded into an agent via load_state_dict().

  8. What is an AgentApp and how is it used

    main

    The AgentApp is the application entry point in AgentScope Runtime. It is used to deploy Agents as API applications that can be consumed externally.

    Key responsibilities of AgentApp include:

    • Initializing and binding an Agent and an AgentScopeAgentHandler.
    • Automatically building the Runner.
    • Providing standardized HTTP API interfaces (including health checks).
    • Supporting Server-Sent Events (SSE) and standard JSON responses.
    • Registering middleware, task queues (e.g., Celery), and custom routes.
    • Managing the application lifecycle via before_start and after_finish hooks.
    • Deploying agent applications as services.

  9. What is the Session History Service?

    main

    The Session History Service manages user conversation sessions, providing agents with a structured way to handle conversation history and message storage in multi-turn conversations. Each session is identified by a unique session_id and contains a list of Message objects representing the conversation from its start to the current point.

    Key capabilities include:

    • Create Session: Initiating a new conversation.
    • Read Session: Retrieving history to maintain context continuity.
    • Append Messages: Adding new messages from users or agents to the session.
    • List Sessions: Viewing all sessions associated with a user.
    • Delete Session: Cleaning up session data.

    Best Practice: Do not call underlying service classes (like InMemorySessionHistoryService) directly in your business logic. Instead, use an adapter to decouple your code from the specific storage implementation.

  10. What is the Memory Service and how does it differ from Session History?

    main

    The Memory Service manages an agent's long-term memory. It is designed to store, retrieve, and manage information that persists across multiple interactions, such as user preferences, long-term task plans, and knowledge bases.

    Key Differences:

    • Session History Service: Primarily saves short-term context (e.g., the most recent few rounds of a conversation).
    • Memory Service: Saves long-term, cross-session information for knowledge reference, personalization, or task tracking.

    Core Functions of the Memory Service interface:

    • Add Memory: Stores a batch of messages or information.
    • Search Memory: Filters relevant information based on current queries or context.
    • List Memory: Provides paginated traversal of all memory content for a user.
    • Delete Memory: Cleans up memory for a specific session or user.

  11. How the Sandbox Service works

    main

    The Sandbox Service provides isolated tool execution environments (sandboxes) for agents to use tools like browsers or code executors securely. It manages the lifecycle of these environments, including:

    • Creating Execution Environments: Generating new instances (e.g., a browser sandbox) for a specific user or session.
    • Connecting to Existing Environments: Allowing agents to reconnect to previous sandboxes during multi-turn conversations.
    • Tool Invocation: Providing callable methods (like navigate or takeScreenshot) that can be registered as tools.
    • Releasing Environments: Cleaning up resources when sessions end.

    Best Practice: Do not write underlying management logic for SandboxService or SandboxManager directly in your business code. Instead, use the encapsulated sandbox methods provided by ToolkitInit and register them in the Agent's Toolkit. This shields your business logic from changes in runtime modes or sandbox types.

    import io.agentscope.core.tool.Toolkit;
import io.agentscope.runtime.engine.agents.agentscope.tools.ToolkitInit;
import io.agentscope.runtime.sandbox.box.BrowserSandbox;
import io.agentscope.runtime.sandbox.box.Sandbox;
import io.agentscope.runtime.sandbox.manager.ManagerConfig;
import io.agentscope.runtime.sandbox.manager.SandboxService;

// ... setup sandboxService ...

Toolkit toolkit = new Toolkit();
// Use ToolkitInit to wrap sandbox methods into tools
toolkit.registerTool(ToolkitInit.BrowserNavigateTool(sandbox));
toolkit.registerTool(ToolkitInit.BrowserTakeScreenshotTool(sandbox));

  12. How Services and Adapters work together

    main

    In AgentScope Runtime Java, Services (Service) provide core capabilities like session history, memory, sandboxing, and state management. However, end-users should rarely interact with services directly. Instead, they should use Adapters.

    Adapters serve as the bridge between the Runtime services and the agent framework. They provide several key benefits:

    1. Decoupling: The agent framework remains agnostic of the underlying service implementation (e.g., switching from in-memory to database storage).
    2. Cross-framework Reuse: The same services can be plugged into different agent frameworks via different adapters.
    3. Unified Lifecycle: Adapters ensure that service lifecycles (starting and stopping) are synchronized with the Runner or Engine.
    4. Seamless Integration: They inject Runtime service objects into compatible framework modules, allowing agents to call functionality like session memory or tool sandboxes easily.