SDK · Java

平行映射自 TypeScript 权威实现。基于 Spring WebClient（响应式）+ Project Reactor。

实现状态

[TODO: ai.volo:volo-ai-sdk Maven Central 未发布。接口规格如下，依赖项 Reactor + Jackson。]

---

安装

Maven

<dependency>
  <groupId>ai.volo</groupId>
  <artifactId>volo-ai-sdk</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle

implementation 'ai.volo:volo-ai-sdk:1.0.0'

环境要求：Java ≥ 17（与 VOLO AI 后端一致）

---

初始化

import ai.volo.sdk.VoloClient;

VoloClient client = VoloClient.builder()
    .apiKey(System.getenv("VOLO_API_KEY"))
    .baseUrl("https://api.volo.ai")
    .timeout(Duration.ofSeconds(30))
    .build();

---

1 · Chat · 流式对话

响应式（推荐）

import ai.volo.sdk.chat.ChatRequest;
import ai.volo.sdk.chat.ExecutionMode;
import ai.volo.sdk.protocol.AgentEvent;
import reactor.core.publisher.Flux;

UUID sessionId = UUID.randomUUID();

Flux<AgentEvent> stream = client.chat().stream(
    ChatRequest.builder()
        .sessionId(sessionId)
        .userMessage("你好")
        .executionMode(ExecutionMode.AUTO)
        .build()
);

stream.subscribe(event -> {
    switch (event.getType()) {
        case ASSISTANT_DELTA -> System.out.print(event.getContent());
        case TOOL_START -> System.out.println("\n[工具] " + event.getToolName());
        case COMPLETE -> System.out.println("\n[完成]");
        case ERROR -> System.err.println("[错误] " + event.getMessage());
    }
});

阻塞迭代（CLI 工具用）

client.chat().streamBlocking(request).forEach(event -> {
    if (event.getType() == EventType.ASSISTANT_DELTA) {
        System.out.print(event.getContent());
    }
});

停止 / 追加 / 恢复

client.chat().stop(sessionId).block();

client.chat().append(sessionId, "顺便加夜间模式").block();

Flux<AgentEvent> resumeStream = client.chat().resume(
    pendingTurnId,
    InteractionResponse.text("选择 B 方案")
);

工具审批

client.chat().approveToolCall(
    toolCallId,
    ToolApprovalRequest.builder()
        .approved(true)
        .reason("用户已确认")
        .turnId(turnId)
        .build()
).block();

---

2 · Memory · 记忆相册

// 上传
Path file = Paths.get("/path/to/photo.jpg");
MemoryVO memory = client.memory().upload(
    UploadRequest.builder()
        .file(file)
        .userTitle("春节家宴")
        .userDescription("2026 春节...")
        .build()
).block();

// 列出
PageResult<MemoryVO> page = client.memory().list(0, 20).block();

// 语义搜索
List<MemoryVO> results = client.memory().search(
    SearchMemoryRequest.builder()
        .query("春节")
        .topK(10)
        .minScore(0.6)
        .build()
).block();

// 删除
client.memory().delete(memoryId).block();

---

3 · Skill · 技能市场

// 列出
PageResult<SkillVO> skills = client.skill().list(
    SkillListRequest.builder()
        .page(0)
        .pageSize(20)
        .category("design")
        .keyword("critique")
        .build()
).block();

// 安装 / 卸载
client.skill().install(skillId).block();
client.skill().uninstall(skillId).block();

// 我的
PageResult<SkillVO> mine = client.skill().listMine(0, 50).block();

// Package 子技能
List<ChildSkillVO> children = client.skill().getChildren(packageId).block();
client.skill().toggleChild(packageId, childSkillId, false).block();

---

4 · Auth · 鉴权

LoginResponse result = client.auth().loginByEmail(
    "user@example.com",
    "123456"
).block();

// SDK 自动管理 Token 刷新
String accessToken = client.tokens().accessToken();

client.auth().logout().block();

---

Spring Boot 集成

VoloAutoConfiguration 自动配置：

# application.yml
volo:
  ai:
    api-key: ${VOLO_API_KEY}
    base-url: https://api.volo.ai
    timeout: 30s

@RestController
public class ChatController {

    private final VoloClient voloClient;

    public ChatController(VoloClient voloClient) {
        this.voloClient = voloClient;
    }

    @PostMapping(value = "/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<ServerSentEvent<AgentEvent>> chat(@RequestBody ChatRequest req) {
        return voloClient.chat().stream(req)
            .map(event -> ServerSentEvent.builder(event)
                .event(event.getType().name())
                .build());
    }
}

---

错误处理

import ai.volo.sdk.errors.*;

stream.onErrorResume(VoloAuthError.class, e -> {
    log.error("API Key 无效");
    return Flux.empty();
}).onErrorResume(VoloRateLimitError.class, e -> {
    log.warn("被限流，retry after {}s", e.getRetryAfter());
    return Flux.empty();
}).subscribe(...);

---

类型

Java 类型	含义
AgentEvent	SSE 事件载荷
EventType enum	与后端 AgentExecutionEvent.EventType 镜像
ExecutionMode enum	FAST / MAX / AUTO
ChatRequest record	对话请求
MemoryVO / SkillVO record	业务对象
PageResult<T>	分页响应

[TODO: 完整类层级与 backend real-agent-contract 对齐——版本化时通过 codegen 保证一致性]

---

相关

• SDK · TypeScript — 权威实现参考
• API · Chat