AgentScope-Java API指南：构建智能体与消息处理

1. AgentScope-Java API参考指南概述

作为AgentScope-Java框架的核心组成部分，API参考文档是开发者日常开发中不可或缺的实用工具。这份快速指南专为已经掌握基础概念的开发者设计，帮助快速定位和查阅关键API的使用方法。

在AgentScope-Java 2.0版本中，API设计遵循了几个核心原则：

• 类型安全：全面采用Java 17的特性如Records和Sealed Classes
• 响应式编程：基于Project Reactor实现非阻塞式调用
• 模块化设计：通过清晰的包结构划分功能边界

提示：本指南假设读者已经完成AgentScope-Java的基础安装并熟悉核心概念。如需入门指导，请先参阅《快速开始》章节。

2. 核心API分类解析

2.1 智能体构建API

构建智能体的核心类HarnessAgent.Builder提供链式调用的配置方法：

java复制HarnessAgent agent = HarnessAgent.builder()
    .name("customer_service")  // 智能体名称
    .model("dashscope:qwen-max")  // 模型配置
    .workspace(Paths.get("/workspace"))  // 工作目录
    .memory(new RedisMemoryStore())  // 记忆存储
    .addTool(KnowledgeSearchTool.class)  // 添加工具
    .build();

关键参数说明：

• model：支持格式为provider:model-name，如openai:gpt-4
• workspace：建议使用绝对路径，确保跨会话持久化
• memory：内置实现包括内存、Redis和文件存储

2.2 消息处理API

消息系统采用类型化的Message体系：

java复制// 创建文本消息
TextMessage textMsg = MessageFactory.text("Hello World");

// 创建复合消息
CompositeMessage compositeMsg = MessageFactory.composite()
    .add(textMsg)
    .add(MessageFactory.image("https://example.com/img.png"));

// 消息发送
agent.call(compositeMsg, RuntimeContext.of("session123"));

消息类型包括：

• TextMessage：基础文本内容
• ImageMessage：支持URL和Base64两种格式
• ToolMessage：工具调用和返回结果
• SystemMessage：系统级通知

2.3 工具系统API

工具注册和使用示例：

java复制@ToolDef(name = "search", desc = "知识检索")
public class KnowledgeSearchTool {
    @ToolAction
    public String search(
        @ToolParam("query") String query,
        @ToolParam("top_k") int topK) {
        // 实现检索逻辑
        return results;
    }
}

// 工具调用示例
ToolMessage toolCall = MessageFactory.toolCall("search")
    .param("query", "AgentScope架构")
    .param("top_k", 3);

工具系统特性：

• 自动参数校验和类型转换
• 支持同步/异步执行模式
• 内置超时和重试机制

3. 高级功能API详解

3.1 记忆管理API

记忆操作接口示例：

java复制// 写入记忆
agent.memory().put("user_preference", "theme=dark");

// 读取记忆
Optional<String> pref = agent.memory().get("user_preference");

// 记忆片段管理
MemoryFragment fragment = agent.memory()
    .fragment("conversation_history")
    .maxSize(1000)  // 最多保留1000条
    .ttl(Duration.ofHours(1))  // 1小时有效期
    .build();

记忆系统特点：

• 支持分级存储策略
• 自动清理过期内容
• 提供上下文压缩功能

3.2 多智能体协作API

多智能体场景下的典型用法：

java复制// 子智能体声明
SubAgentConfig assistant = SubAgentConfig.builder()
    .name("assistant")
    .model("anthropic:claude-3")
    .build();

// 主智能体配置
HarnessAgent mainAgent = HarnessAgent.builder()
    .name("coordinator")
    .subAgent(assistant)
    .build();

// 消息路由
mainAgent.route("assistant", userMessage);

协作机制包括：

• 直接消息传递
• 发布/订阅模式
• 竞争消费模式

4. 常见问题排查指南

4.1 认证问题

典型错误场景：

java复制// 错误：未配置API密钥
ModelException: Missing API key for provider 'dashscope'

// 解决方案：
// 1. 设置环境变量
export DASHSCOPE_API_KEY=your_key

// 2. 或代码中指定
ModelRegistry.register("dashscope", new ApiKeyCredential("your_key"));

4.2 上下文超限

处理大上下文的推荐方式：

java复制// 启用自动压缩
HarnessAgent agent = HarnessAgent.builder()
    .contextPolicy(ContextPolicy.builder()
        .maxTokens(8000)
        .compactionStrategy(new KeyInfoCompactionStrategy())
        .build())
    .build();

// 手动控制上下文
agent.currentContext()
    .keepImportant()  // 保留关键消息
    .compressOthers();  // 压缩其他内容

4.3 工具执行超时

工具调用的超时配置：

java复制@ToolDef(name = "slow_op", timeout = 30)  // 单位：秒
public class SlowOperationTool {
    @ToolAction
    public String execute() {
        // 长时间运行的操作
    }
}

// 调用时覆盖默认值
ToolMessage msg = MessageFactory.toolCall("slow_op")
    .timeout(60);  // 延长至60秒

5. 最佳实践建议

5.1 性能优化技巧

1. 连接池配置：

java复制// 优化HTTP连接池
HttpClientOptions options = HttpClientOptions.builder()
    .maxConnections(100)
    .connectTimeout(Duration.ofSeconds(5))
    .build();
ModelRegistry.setHttpOptions(options);

2. 缓存策略：

java复制// 启用模型响应缓存
CachedModel cachedModel = new CachedModel(
    new DashScopeModel("qwen-max"),
    new RedisCacheStore()
);
agent.model(cachedModel);

5.2 调试技巧

1. 事件追踪：

java复制agent.eventStream()
    .filter(e -> e.getType() == EventType.MODEL_CALL)
    .subscribe(e -> {
        System.out.println("Model input: " + e.getPayload());
    });

2. 状态检查：

java复制// 获取运行时指标
AgentMetrics metrics = agent.getMetrics();
System.out.println("平均响应时间: " + metrics.avgResponseTime());

注意：生产环境建议通过Studio组件进行可视化监控，而非直接输出日志

6. API版本兼容性说明

AgentScope-Java 2.0保持对1.x版本的核心兼容，主要变更点包括：

对于废弃API，框架会输出警告日志并自动转换到新API。建议在开发环境开启严格模式检测兼容问题：

java复制System.setProperty("agentscope.strict_mode", "true");