# Assistant Agent runs generated code in a GraalVM sandbox

> spring-ai-alibaba/AssistantAgent is a Java framework built on Spring AI Alibaba that follows a Code-as-Action paradigm, where the agent writes and executes code to finish a task rather than only calling fixed tools, with the generated code confined to a GraalVM polyglot sandbox. It is a large Spring Boot application with eleven modules and a knowledge base that ships as a mock.

**spring-ai-alibaba/AssistantAgent** — Framework for building enterprise-level assistant agents.

- Repository: https://github.com/spring-ai-alibaba/AssistantAgent
- Stars: 519 · Forks: 150
- Language: Java
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/spring-ai-alibaba-assistantagent

## Code-as-Action, and why it changes the risk profile

The defining choice in Assistant Agent is the first item on the technical features list: Code-as-Action, where the agent generates and executes code to complete tasks rather than just calling predefined tools.

The distinction matters. A tool-calling agent can only do what the tool schema allows, which makes it predictable and auditable, and makes every action a named operation you approved. A code-generating agent can compose arbitrary logic, which makes it far more capable for the long tail of tasks nobody wrote a tool for, and makes its behaviour a function of a model output rather than of a contract.

The framework's answer to that risk is the second feature, a secure sandbox where AI-generated code runs in a GraalVM polyglot sandbox with resource isolation. The project structure makes the placement visible: `assistant-agent-core` is described as the core engine holding the GraalVM executor and the tool registry.

The rest of the feature list is about control rather than capability. Multi-dimensional evaluation guides the agent through an Evaluation Graph, with multi-layer intent recognition used to guide behaviour. The dynamic prompt builder injects runtime context, prefetched experience candidates and stable guidance into prompts depending on the scenario and the evaluation result. A unified experience system manages COMMON, REACT and TOOL experiences in one model, supports conversion to and from the Skills model, and improves efficiency through progressive disclosure. A management console module handles experience search, CRUD, statistics, and skill preview, import and export.

And there is a fast path. For familiar scenarios, the agent skips LLM reasoning entirely and responds from stored experience, which is the one feature on the list that reduces cost rather than adding capability.

## Eleven modules, and what each one owns

The project structure in the README is a map of the design, and it is worth reading as a list of responsibilities rather than as a directory tree.

`assistant-agent-common` holds common tools, enums and constants. `assistant-agent-core` is the core engine with the GraalVM executor and the tool registry. `assistant-agent-extensions` is where the pluggable pieces live, and its subdirectories name the extension points precisely: `dynamic/` for dynamic tools over MCP and HTTP API, `experience/` for the unified experience runtime, disclosure and FastIntent configuration, `learning/` for learning extraction and storage, `search/` for unified search, `reply/` for multi-channel reply, `trigger/` for the trigger mechanism, and `evaluation/` for evaluation integration.

Then there are four standalone modules. `assistant-agent-prompt-builder` handles prompt dynamic assembly. `assistant-agent-evaluation` is the evaluation engine itself. `assistant-agent-management` provides the experience management and skill conversion APIs. `assistant-agent-autoconfigure` holds the Spring Boot auto-configuration, and `assistant-agent-start` is the startup module you actually run.

Two structural observations. First, the extension package is where the framework is designed to be extended, and the split of search, reply and trigger as separate extensions means a deployment can replace the knowledge source or the delivery channel without touching the core. Second, the split between the `experience/` extension and the `assistant-agent-management` module is deliberate: one is runtime behaviour, the other is the API surface for administering stored experience and converting it to and from skill packages.

The module boundaries also explain the build shape, since a Maven multi-module project like this builds parent first, which is why the quick start uses a full install rather than a single module build.

## Building and running it: Maven, one environment variable, one model name

The prerequisites are Java 17 or newer, Maven 3.8 or newer, and a DashScope API key. The badges also pin the stack: Spring Boot 3.4, Spring AI 1.1.0, GraalVM polyglot support, and the Apache 2.0 licence.

The build is a plain clone and install:

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

The key is supplied through the environment:

```bash
export DASHSCOPE_API_KEY=your-api-key-here
```

Configuration defaults are built in, so the only thing you must get right is the key. When you do want to change something, the file is `assistant-agent-start/src/main/resources/application.yml`, and the minimal shape the README shows is:

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

The model default is `qwen-max`, which tells you the framework is wired to DashScope and to the Qwen family out of the box. That is a reasonable default for a project from the Spring AI Alibaba organisation, and it is also the first thing to change if you want a different provider.

Starting is one command from the startup module:

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

All extension modules are enabled by default with what the README calls sensible configurations, so nothing else needs enabling for a first run. That is convenient, and it also means the default running system has every extension active, including the mock knowledge base.

## The mock knowledge base is a demo, and the README says so twice

The fifth step of the quick start is where a careful reader should stop. The framework provides a mock knowledge base implementation by default for demonstration and testing, and the README states in bold that production environments need to connect to real knowledge sources, naming vector databases, Elasticsearch and enterprise knowledge base APIs as examples.

This is the framework's most likely failure in a real deployment, and it fails quietly. An assistant that answers confidently from a mock store looks identical to one that answers correctly until someone asks a question the mock does not cover. There is no error, no timeout and no log line that says the retrieval layer is still a stand-in.

The retrieval architecture behind it is described as unified across multiple data sources, extensible via SPI for the knowledge base, the Web and other sources, with the aim of accurate and traceable answers. The `search/` extension module in the project structure is where that lives, and the extension point means the knowledge source is meant to be replaced rather than configured around.

The rest of the capability list is broader than the mock issue. Tool invocation supports MCP, HTTP API over OpenAPI and other protocols, and the README distinguishes two modes: invoking tools directly inside the React loop, or orchestrating several tools inside generated code for more complex workflows. Proactive service covers scheduled tasks, delayed execution and event callbacks. Multi-channel delivery ships with an IDE reply built in and extends to DingTalk, Feishu, WeCom and Webhook through the same SPI mechanism.

Those channel integrations are worth noting for a Chinese enterprise deployment, and they are also the clearest signal of where this framework expects to be used.

## The experience system, and the difference between a memory and a workflow

The experience system is the part of the design that has no obvious equivalent in a plain tool-calling agent, so it deserves a close look.

Experiences are stored in one unified model with three kinds: COMMON, REACT and TOOL. The README says this supports conversion to and from the Skills model, and that progressive disclosure improves experience efficiency and quality. Progressive disclosure is the mechanism that makes a large experience store usable: rather than injecting everything into the prompt, the agent is told what exists and fetches detail when it becomes relevant.

The fast path is the payoff. For a familiar scenario the agent skips LLM reasoning and responds from experience directly, which is both the latency and the cost argument for keeping a store at all. The `learning/` extension handles extraction and storage, and the `experience/` extension handles the runtime, disclosure and what the README calls FastIntent configuration.

The management module is where the operations story sits. It provides experience management and skill conversion APIs, tenant-aware retrieval, and a console for search, CRUD, statistics, and skill preview, import and export. Tenant awareness is the detail that tells you this was designed for a multi-tenant deployment rather than a single internal assistant.

What the README does not explain is how an experience is validated before it enters the store, or what prevents a bad experience from being served for a long time. Automatic learning and a statistics console imply a review workflow, but the mechanism is not documented here, and that is the first question to ask before letting the store grow unattended.

## Licence, release cadence and what the repository does not tell you

The licence is Apache-2.0, which is the most permissive common choice for a Spring-ecosystem framework and removes the copyleft obligations that would otherwise complicate embedding it in a commercial product. The project is not archived, but the last push was on 2026-06-02, and there are no GitHub releases, so the version you get is whatever the main branch holds.

That gap between an active-looking framework and a four-month-old last push is worth naming rather than glossing over. The repository does contain a `CHANGELOG.md`, a `ROADMAP.md` and a `CONTRIBUTING.md`, so the project intends to be developed in the open, but the absence of tagged releases means there is no upgrade path you can pin to, and no way to tell from the outside whether a given commit is one you would want in production.

The documentation is hosted off-repository, on java2ai.com, with a quick start page for the project and a broader Spring AI Alibaba overview. There is also a Chinese README, which is a reasonable signal about the primary audience.

What the README does not tell you is just as important as what it does. There is no mention of authentication, of how the management console is secured, of how the DashScope key is protected in a deployment, or of how the GraalVM sandbox is configured for resource limits. There are no test instructions, and the build in the quick start explicitly skips tests with `-DskipTests`. The listed use cases, intelligent customer service, an operations assistant and a business assistant connecting to CRM and ERP systems, are described as typical scenario examples rather than as shipped integrations.

For an enterprise framework, those are the details to obtain from the documentation and from the people running it, not from the README.

## Conclusion

Adopt Assistant Agent if you are a Spring Boot team in Java that wants an agent framework with retrieval, MCP and HTTP tools, an experience store that accumulates reusable behaviour, and multi-channel delivery, and you accept that the agent writes code rather than only calling tools. Do not adopt it if you cannot run a GraalVM polyglot sandbox, if a hard requirement forbids model-generated code execution, or if the Apache-2.0 dependency set and the Spring AI Alibaba 1.1.0 line are not acceptable. Before you deploy, replace the mock knowledge base with a real source as the README insists, pin the model in `application.yml` because the default is `qwen-max`, and confirm the repository has moved since the last push on 2026-06-02.

## FAQ

### What is the Code-as-Action approach in Assistant Agent?

It means the agent generates and executes code to complete a task rather than only invoking predefined tools. The framework describes tool invocation as either direct calls in the React loop or orchestration of multiple tools inside generated code for more complex workflows.

### How is AI-generated code kept safe in Assistant Agent?

The generated code runs in a GraalVM polyglot sandbox with resource isolation, and the core module holds the GraalVM executor. The framework also lists multi-dimensional evaluation through an Evaluation Graph as a way of guiding agent behaviour.

### What do I need to build and run Assistant Agent?

Java 17 or newer, Maven 3.8 or newer and a DashScope API key. You clone the repository, run `mvn clean install -DskipTests`, export `DASHSCOPE_API_KEY`, then run `mvn spring-boot:run` from the assistant-agent-start module. The stack is Spring Boot 3.4 with Spring AI 1.1.0.

### Do I need to configure a knowledge base before using Assistant Agent?

For a demo, no. The framework ships a mock knowledge base for demonstration and testing, and all extension modules are enabled by default. For production the README is explicit that you must connect real knowledge sources such as a vector database, Elasticsearch or an enterprise knowledge base API.

### Which tools and channels can Assistant Agent use?

Tools can be invoked over MCP, HTTP API with OpenAPI and other protocols, and the delivery side has a built-in IDE reply with extensions to DingTalk, Feishu, WeCom and Webhook through SPI. Tool, knowledge and channel access are all pluggable extensions.

## Sources

- [Issues](https://github.com/spring-ai-alibaba/AssistantAgent/issues)
- [License: Apache-2.0](https://github.com/spring-ai-alibaba/AssistantAgent/blob/main/LICENSE)
- [README](https://github.com/spring-ai-alibaba/AssistantAgent/blob/main/README.md)
- [spring-ai-alibaba/AssistantAgent on GitHub](https://github.com/spring-ai-alibaba/AssistantAgent)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/spring-ai-alibaba-assistantagent