Spring AI 2.0 Agent Skills：把团队流程从 System Prompt 拆出来

Skill = 触发条件 + 执行步骤 + 输出规范 + 可选资源

常驻：name + description，约 100 Tokens
命中：完整 SKILL.md，建议控制在 5000 Tokens 内
需要时：references / scripts / assets

扫描目录 → 暴露 name + description → 模型选择 Skill
→ 返回完整 SKILL.md → 调用业务 Tool → 最终回答

请取消订单 ORD-1001，我确认取消。请按团队流程处理。

Skill(order-cancellation)
  → queryOrder(ORD-1001)
  → cancelOrder(ORD-1001)
  → CANCELLED

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-agent-utils</artifactId>
    <version>0.12.0</version>
</dependency>

---
name: order-cancellation
description: Use when the user asks to cancel an e-commerce order or check whether an order can be cancelled.
---

# Order Cancellation

## Workflow

1. Extract the order id. Ask the user when it is missing.
2. Call `queryOrder` before any write operation. Never infer the current status.
3. Confirm that the user explicitly asked to cancel the order.
4. When the status is `PENDING_PAYMENT`, call `cancelOrder` with the same order id.
5. When the status is `PAID`, `SHIPPED`, or `COMPLETED`, do not call `cancelOrder`; explain that this demo requires the refund or after-sales workflow.
6. When the status is `CANCELLED`, report that no further action is needed.

## Output

Return the order id, original status, action result, and the next step in concise Chinese.

public final class OrderTools {

    private String status = "PENDING_PAYMENT";

    @Tool(name = "queryOrder",
            description = "Query the current status of an e-commerce order by order id")
    public OrderSnapshot queryOrder(
            @ToolParam(description = "Order id") String orderId) {
        return new OrderSnapshot(orderId, status);
    }

    @Tool(name = "cancelOrder",
            description = "Cancel an e-commerce order by order id and return the result")
    public CancellationResult cancelOrder(
            @ToolParam(description = "Order id") String orderId) {
        String previousStatus = status;
        if (!"PENDING_PAYMENT".equals(previousStatus)) {
            return new CancellationResult(
                    orderId, previousStatus, previousStatus,
                    false, "当前状态不允许直接取消");
        }

        status = "CANCELLED";
        return new CancellationResult(
                orderId, previousStatus, status,
                true, "订单取消成功");
    }

    public record OrderSnapshot(String orderId, String status) {}

    public record CancellationResult(
            String orderId, String previousStatus, String status,
            boolean success, String message) {}
}

@Bean
ChatClient chatClient(ChatClient.Builder builder) {
    ToolCallback skillTool = SkillsTool.builder()
            .addSkillsDirectory(
                    Path.of("skills").toAbsolutePath().toString())
            .build();
    OrderTools orderTools = new OrderTools();

    return builder
            .defaultTools(skillTool, orderTools)
            .build();
}

String answer = chatClient.prompt()
        .system("""
                你是电商研发助手。遇到匹配的 Skill 时，
                先加载流程，再执行流程要求的 Tool。
                """)
        .user("请取消订单 ORD-1001，我确认取消。请按团队流程处理。")
        .call()
        .content();

route[order-cancellation]=Skill({"command": "order-cancellation"})
loadedOnly[order-cancellation]=true
toolSequence[order-cancellation]=queryOrder(ORD-1001) -> cancelOrder(ORD-1001)
orderStatus[ORD-1001]=CANCELLED
answer[order-cancellation]=订单号：ORD-1001 原状态：待支付 操作结果：取消成功

name + description → Skill(command) → 完整 SKILL.md
→ 业务 Tool → 结果断言