Skip to content

Latest commit

 

History

History
268 lines (192 loc) · 12.8 KB

README.md

File metadata and controls

268 lines (192 loc) · 12.8 KB

Assistant Agent

English | 中文

License Java Spring Boot Spring AI GraalVM

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

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?

Value Description
Cost Reduction 24/7 intelligent customer service, significantly reducing manual support costs
Quick Integration Business platforms can integrate with simple configuration, no extensive development required
Flexible Customization Configure knowledge base, integrate enterprise tools, build your exclusive business assistant
Continuous Optimization Automatically learns and accumulates experience, the assistant gets smarter with use

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.

QA_comparison_en.png Tool_comparison_en.png

Overall Working Principle

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

workflow_en.png

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

Knowledge Source Type Integration Method
Vector Database (Alibaba Cloud AnalyticDB, Milvus, Pinecone) Call vector similarity search API in search() method
Elasticsearch Use ES client for full-text or vector search
Enterprise Knowledge Base API Call internal knowledge base REST API
Local Documents Read and index local Markdown/PDF files

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

🧩 Core Modules

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

Core Modules

Module Description Documentation
Evaluation Multi-dimensional intent recognition through Evaluation Graph with LLM and rule-based engines Quick Start ｜ Advanced
Prompt Builder Dynamic prompt assembly based on evaluation results and runtime context Quick Start ｜ Advanced

Tool Extensions

Module Description Documentation
MCP Tools Integration with Model Context Protocol servers for tool ecosystem reuse Quick Start ｜ Advanced
Dynamic HTTP Tools REST API integration through OpenAPI specification Quick Start ｜ Advanced
Custom CodeAct Tools Build custom tools using the CodeactTool interface Quick Start ｜ Advanced

Intelligence Capabilities

Module Description Documentation
Experience Accumulate and reuse historical successful execution experiences with FastIntent support Quick Start ｜ Advanced
Learning Automatically extract valuable experiences from Agent execution history Quick Start ｜ Advanced
Search Multi-source unified search engine for knowledge-based Q&A Quick Start ｜ Advanced

Interaction Capabilities

Module Description Documentation
Reply Channel Multi-channel message reply with routing support Quick Start ｜ Advanced
Trigger Scheduled tasks, delayed execution, and event callback triggers Quick Start ｜ Advanced

Additional Resources

Resource Link
Quick Start Guide AssistantAgent Quick Start
Secondary Development Guide Development Guide

📚 Reference 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