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.

• Documentation
• Spring AI Alibaba

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.

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

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

• 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