Assistant Agent

English | 中文

✨ Technical Features

• 🚀 Code-as-Action: Agent generates and executes code to complete tasks, rather than just calling predefined tools
• 🔒 Secure Sandbox: AI-generated code runs safely in GraalVM polyglot sandbox with resource isolation
• 📊 Multi-dimensional Evaluation: Multi-layer intent recognition through Evaluation Graph, precisely guiding Agent behavior
• 🔄 Dynamic Prompt Builder: Dynamically inject context (experiences, knowledge, etc.) into prompts based on scenarios and evaluation results
• 🧠 Experience Learning: Automatically accumulates successful experiences to continuously improve performance on subsequent tasks
• ⚡ Fast Response: For familiar scenarios, skip LLM reasoning process and respond quickly based on experience

📖 Introduction

Assistant Agent is an enterprise-grade intelligent assistant framework built on Spring AI Alibaba, adopting the Code-as-Action paradigm to orchestrate tools and complete tasks by generating and executing code. It's an intelligent assistant solution that understands, acts, and learns.

• <a href="https://java2ai.com/agents/assistantagent/quick-start" target="_blank">Documentation</a>
• <a href="https://java2ai.com/docs/overview" target="_blank">Spring AI Alibaba</a>

What Can Assistant Agent Do?

Assistant Agent is a fully-featured intelligent assistant with the following core capabilities:

• 🔍 Intelligent Q&A: Supports unified retrieval architecture across multiple data sources (extensible via SPI for knowledge base, Web, etc.), providing accurate, traceable answers
• 🛠️ Tool Invocation: Supports MCP, HTTP API (OpenAPI) and other protocols, flexibly access massive tools, combine multiple tools to implement complex business workflows
• ⏰ Proactive Service: Supports scheduled tasks, delayed execution, event callbacks, letting the assistant proactively serve you
• 📬 Multi-channel Delivery: Built-in IDE reply, extensible to DingTalk, Feishu, WeCom, Webhook and other channels via SPI

Why Choose Assistant Agent?

Use Cases

• Intelligent Customer Service: Connect to enterprise knowledge base, intelligently answer user inquiries
• Operations Assistant: Connect to monitoring and ticketing systems, automatically handle alerts, query status, execute operations
• Business Assistant: Connect to CRM, ERP and other business systems, assist employees in daily work

💡 The above are just typical scenario examples. By configuring knowledge base and integrating tools, Assistant Agent can adapt to more business scenarios. Feel free to explore.

Overall Working Principle

Below is an end-to-end flow example of how Assistant Agent processes a complete request:

Project Structure

AssistantAgent/
├── assistant-agent-common          # Common tools, enums, constants
├── assistant-agent-core            # Core engine: GraalVM executor, tool registry
├── assistant-agent-extensions      # Extension modules:
│   ├── dynamic/               #   - Dynamic tools (MCP, HTTP API)
│   ├── experience/            #   - Experience management and FastIntent configuration
│   ├── learning/              #   - Learning extraction and storage
│   ├── search/                #   - Unified search capability
│   ├── reply/                 #   - Multi-channel reply
│   ├── trigger/               #   - Trigger mechanism
│   └── evaluation/            #   - Evaluation integration
├── assistant-agent-prompt-builder  # Prompt dynamic assembly
├── assistant-agent-evaluation      # Evaluation engine
├── assistant-agent-autoconfigure   # Spring Boot auto-configuration
└── assistant-agent-start           # Startup module

🚀 Quick Start

Prerequisites

• Java 17+
• Maven 3.8+
• DashScope API Key

1. Clone and Build

git clone https://github.com/spring-ai-alibaba/AssistantAgent.git
cd AssistantAgent
mvn clean install -DskipTests

2. Configure API Key

export DASHSCOPE_API_KEY=your-api-key-here

3. Minimal Configuration

The project has built-in default configuration, just ensure the API Key is correct. For customization, edit assistant-agent-start/src/main/resources/application.yml:

spring:
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}
      chat:
        options:
          model: qwen-max

4. Start the Application

cd assistant-agent-start
mvn spring-boot:run

All extension modules are enabled by default with sensible configurations; no additional configuration is required for a quick start.

5. Configure Knowledge Base (Connect to Business Knowledge)

💡 The framework provides a Mock knowledge base implementation by default for demonstration and testing. Production environments need to connect to real knowledge sources (such as vector databases, Elasticsearch, enterprise knowledge base APIs, etc.) so that the Agent can retrieve and answer business-related questions.

Option 1: Quick Experience (Using Built-in Mock Implementation)

The default configuration has knowledge base search enabled, you can experience it directly:

spring:
  ai:
    alibaba:
      codeact:
        extension:
          search:
            enabled: true
            knowledge-search-enabled: true  # Enabled by default

Option 2: Connect to Real Knowledge Base (Recommended)

Implement the SearchProvider SPI interface to connect to your business knowledge sources:

package com.example.knowledge;

import com.alibaba.assistant.agent.extension.search.spi.SearchProvider;
import com.alibaba.assistant.agent.extension.search.model.*;
import org.springframework.stereotype.Component;
import java.util.*;

@Component  // Add this annotation, Provider will be auto-registered
public class MyKnowledgeSearchProvider implements SearchProvider {

    @Override
    public boolean supports(SearchSourceType type) {
        return SearchSourceType.KNOWLEDGE == type;
    }

    @Override
    public List<SearchResultItem> search(SearchRequest request) {
        List<SearchResultItem> results = new ArrayList<>();
        
        // 1. Query from your knowledge source (vector database, ES, API, etc.)
        // Example: List<Doc> docs = vectorStore.similaritySearch(request.getQuery());
        
        // 2. Convert to SearchResultItem
        // for (Doc doc : docs) {
        //     SearchResultItem item = new SearchResultItem();
        //     item.setId(doc.getId());
        //     item.setSourceType(SearchSourceType.KNOWLEDGE);
        //     item.setTitle(doc.getTitle());
        //     item.setSnippet(doc.getSummary());
        //     item.setContent(doc.getContent());
        //     item.setScore(doc.getScore());
        //     results.add(item);
        // }
        
        return results;
    }

    @Override
    public String getName() {
        return "MyKnowledgeSearchProvider";
    }
}

Common Knowledge Source Integration Examples

📖 For more details, refer to: Knowledge Search Module Documentation

🧩 Core Modules

For detailed documentation on each module, please visit our Documentation Site.

Core Modules

Tool Extensions

Intelligence Capabilities

Interaction Capabilities

Additional Resources

📚 Reference Documentation

• Full Configuration Reference
• Spring AI Alibaba Documentation

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

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

🙏 Acknowledgments

• Spring AI
• Spring AI Alibaba
• GraalVM