AWS SDK for Java V2 中 BedrockRuntime ConverseRequest 工具使用详解

概述

Amazon Bedrock 作为 AWS 提供的托管式生成式 AI 服务，其 Java SDK 中的 ConverseRequest 功能允许开发者实现模型与自定义工具的无缝交互。本文将深入探讨如何正确配置和使用这一功能，解决开发过程中常见的 400 Bad Request 错误问题。

核心问题分析

在实现 BedrockRuntime 的 ConverseRequest 工具功能时，开发者常遇到两个主要挑战：

1. 文档不足：官方文档对工具配置的具体实现细节描述不够详尽
2. 请求格式错误：由于对工具输入模式理解不准确，导致 400 错误

正确实现方案

1. 工具配置规范

工具配置的核心在于正确构建 ToolConfiguration 对象，特别是输入模式的 JSON Schema 定义：

private static ToolConfiguration createToolConfig() {
    return ToolConfiguration.builder()
            .tools(Tool.builder()
                    .toolSpec(ToolSpecification.builder()
                            .name("currentTemperature")
                            .description("返回城市的当前温度")
                            .inputSchema(ToolInputSchema.builder()
                                    .json(createToolSpecDocument())
                                    .build())
                            .build())
                    .build())
            .build();
}

2. 输入模式定义

输入模式必须遵循 JSON Schema 规范，包含类型定义、属性描述和必填字段：

private static Document createToolSpecDocument() {
    // 定义城市参数
    var cityParameter = Document.mapBuilder()
            .putString("type", "string")
            .putString("description", "城市名称")
            .build();

    // 组装属性
    var properties = Document.mapBuilder()
            .putDocument("city", cityParameter)
            .build();

    // 指定必填字段
    var required = Document.listBuilder()
            .addString("city")
            .build();

    return Document.mapBuilder()
            .putString("type", "object")
            .putDocument("properties", properties)
            .putDocument("required", required)
            .build();
}

3. 完整交互流程

实现工具调用的完整流程包括：

1. 发送初始请求
2. 处理工具调用响应
3. 执行工具逻辑
4. 返回工具结果
5. 获取最终响应

public static String converse() {
    var client = createClient();
    var modelId = "anthropic.claude-3-5-sonnet-20240620-v1:0";
    var toolConfig = createToolConfig();
    var messages = new ArrayList<>(List.of(createUserMessage("巴黎现在的温度是多少？")));

    try {
        var response = sendConverse(client, modelId, toolConfig, messages);
        messages.add(response.output().message());

        while (StopReason.TOOL_USE.equals(response.stopReason())) {
            handleToolUse(response, messages);
            response = sendConverse(client, modelId, toolConfig, messages);
        }

        return response.output().message().content().get(0).text();

    } catch (SdkClientException e) {
        throw new RuntimeException("调用模型失败: " + e.getMessage(), e);
    }
}

工具处理实现

当模型返回工具调用请求时，需要正确处理并返回结果：

private static void handleToolUse(ConverseResponse response, List<Message> messages) {
    var toolRequests = response.output()
            .message()
            .content()
            .stream()
            .filter(contentBlock -> Objects.nonNull(contentBlock.toolUse()))
            .toList();

    for (var toolRequest : toolRequests) {
        var tool = toolRequest.toolUse();
        ToolResultBlock toolResult = processToolRequest(tool);

        messages.add(Message.builder()
                .role(ConversationRole.USER)
                .content(ContentBlock.builder().toolResult(toolResult).build())
                .build());
    }
}

结果格式规范

工具返回结果需要遵循特定格式，包含状态和结构化数据：

private static ToolResultBlock processToolRequest(ToolUseBlock tool) {
    if ("currentTemperature".equals(tool.name())) {
        try {
            var input = tool.input();
            var inputMap = input.asMap();
            var cityName = Optional.ofNullable(inputMap.get("city"))
                    .map(Document::asString)
                    .orElse("");

            double result = getTemperatureFromAPI(cityName);

            return ToolResultBlock.builder()
                    .toolUseId(tool.toolUseId())
                    .content(ToolResultContentBlock.builder()
                            .json(createToolResultDocument(result))
                            .build())
                    .status(ToolResultStatus.SUCCESS)
                    .build();
        } catch (Exception ex) {
            return ToolResultBlock.builder()
                    .toolUseId(tool.toolUseId())
                    .content(ToolResultContentBlock.builder()
                            .text(ex.getMessage()))
                            .build())
                    .status(ToolResultStatus.ERROR)
                    .build();
        }
    }
    return null;
}

最佳实践建议

1. 输入验证：在处理工具输入时，务必进行严格的参数验证
2. 错误处理：为工具实现提供完善的错误处理机制
3. 日志记录：记录完整的交互流程，便于调试
4. 性能监控：跟踪工具调用的延迟和资源消耗
5. 结果缓存：对耗时工具考虑实现结果缓存机制

总结

通过本文介绍的正确实现方式，开发者可以充分利用 BedrockRuntime 的工具调用功能，构建强大的生成式 AI 应用。关键在于正确配置工具规范、遵循输入输出模式约定，以及实现完整的交互流程。随着 AWS 不断完善相关文档，这一功能的易用性将会进一步提高。