# Spring AI Alibaba Quick Start Reference

Source: https://java2ai.com/docs/quick-start/
Observed page title: `快速开始 | Spring AI Alibaba`
Observed page update line: `最后由 Ken Liu 于 2026年2月2日 更新`

## Scope

This reference captures the implementation patterns shown in the Spring AI Alibaba quick-start for building a `ReactAgent`.

## Documented Prerequisites

- JDK 17+
- Maven 3.8+
- A supported model provider API key
- DashScope is the primary example provider in the page

## Dependency Examples From the Page

The page shows these artifacts:

- `com.alibaba.cloud.ai:spring-ai-alibaba-agent-framework:1.1.2.0`
- `com.alibaba.cloud.ai:spring-ai-alibaba-starter-dashscope:1.1.2.0`
- Later example: `com.alibaba.cloud.ai:spring-ai-alibaba-starter-dashscope:1.1.2.1`
- Later example: `org.springframework.ai:spring-ai-starter-model-openai:1.1.2`

Use these as documentation snapshots. Keep the chosen project on one compatible release line instead of mixing versions casually.

## Configuration Pattern

- Prefer environment variable `AI_DASHSCOPE_API_KEY`
- If using configuration files, inject from the environment:

```yaml
spring:
  ai:
    dashscope:
      api-key: ${AI_DASHSCOPE_API_KEY}
```

## Basic Agent Pattern

The simplest example in the page follows this sequence:

1. Build `DashScopeApi` from the API key
2. Build `DashScopeChatModel`
3. Define a tool with `FunctionToolCallback`
4. Build `ReactAgent`
5. Call `agent.call(...)`

## Tool Design Pattern

The page uses `BiFunction<String, ToolContext, String>` for tools and highlights two cases:

- A pure tool that only needs the user input
- A context-aware tool that reads `RunnableConfig` metadata through `ToolContext`

Important guidance taken from the page:

- Tool name, description, and parameter metadata all influence model behavior
- `@ToolParam` improves parameter descriptions
- `ToolContext` can inject runtime context into tool execution

## Production-Style Agent Assembly

The fuller example assembles a weather agent with:

- A detailed `SYSTEM_PROMPT`
- Two tools: one for weather lookup and one for user location lookup
- `DashScopeChatOptions` for temperature and token limits
- `outputType(ResponseFormat.class)` for structured output
- `MemorySaver` for conversation memory
- `RunnableConfig.builder().threadId(...).addMetadata("user_id", "1")`

## Memory Guidance

- Reuse the same `threadId` to continue a conversation
- The page uses `MemorySaver` for examples
- For production, the page recommends a persistent checkpoint implementation rather than in-memory storage

## Advanced Features Called Out By the Page

### `outputSchema`

Use this when a custom JSON response contract is easier to express as schema text than as a Java class.

### `invoke(...)`

Use this when the caller needs the full `OverAllState`, including message history and other state values.

### `ModelCallLimitHook`

Use this to set a maximum number of model calls and fail fast or exit in a controlled way if the limit is exceeded.

### Human-in-the-loop Hooks

Use hook-based approval when a tool invocation should require confirmation before execution.

## Recommended Working Heuristics

- Start from the smallest working `ReactAgent`, then add memory, output shaping, and hooks one by one
- Keep tool signatures simple and descriptions explicit
- Pass request metadata through `RunnableConfig` instead of hidden static state
- Verify version compatibility before copying dependency coordinates into a real project