附录C 常见问题

附录C 常见问题

本附录收集AgentScope-Java开发中的常见问题及解决方案。

C.1 环境配置问题

C.1.1 API密钥未设置

问题描述：

java.lang.IllegalStateException: API key is not set

解决方案：

export DASHSCOPE_API_KEY="sk-your-api-key"
DashScopeChatModel.builder()
    .apiKey("sk-your-api-key")
    // ...
    .build();
agentscope:
  dashscope:
    api-key: ${DASHSCOPE_API_KEY}

C.1.2 模型不存在或无权限

问题描述：

Error: Model 'xxx' does not exist or you don't have access

解决方案：

  1. 检查模型名称是否正确
  2. 确认API密钥有权访问该模型
  3. 使用qwen-plus等通用模型测试

C.2 Agent执行问题

C.2.1 Agent陷入无限循环

问题描述： Agent不断调用工具，无法完成任务。

解决方案：

ReActAgent.builder()
    .maxIters(10)  // 限制最大迭代次数
    // ...
    .build();
  1. 检查工具返回值是否明确
  2. 优化系统提示词，明确完成条件

C.2.2 结构化输出解析失败

问题描述：

Failed to parse structured output: ...

解决方案：

public class MySchema {
    public String field1;
    public Integer field2;
    
    public MySchema() {} // 必需
}
public class MySchema {
    @JsonProperty("field_name")
    @JsonPropertyDescription("Field description")
    public String field1;
}
.structuredOutputReminder(StructuredOutputReminder.PROMPT)

C.2.3 HITL停止后无法恢复

问题描述： 调用stopAgent()后，Agent无法继续执行。

解决方案：

// 检测到待确认的工具调用
if (msg.hasContentBlocks(ToolUseBlock.class)) {
    // 用户确认后恢复
    Msg response = agent.call().block();
}
Msg cancelResult = Msg.builder()
    .role(MsgRole.TOOL)
    .content(ToolResultBlock.of(
        toolId, toolName,
        TextBlock.builder().text("Cancelled").build()))
    .build();
agent.call(cancelResult).block();

C.3 工具系统问题

C.3.1 工具未被调用

问题描述： Agent不调用任何工具，直接返回文本回答。

解决方案：

Toolkit toolkit = new Toolkit();
toolkit.registerTool(new MyTools());
// 验证注册
System.out.println(toolkit.getToolNames());

C.3.2 工具参数解析错误

问题描述：

Error: Cannot convert parameter 'xxx' to type Integer

解决方案：

@Tool(name = "my_tool", description = "...")
public String myTool(
    @ToolParam(name = "count", description = "Number of items")
    String countStr) {
    int count = Integer.parseInt(countStr);
    // ...
}

C.3.3 MCP工具注册失败

问题描述：

Failed to register MCP client: Connection refused

解决方案：

private void initializeMcpOnce() {
    if (!mcpInitialized) {
        synchronized (this) {
            if (!mcpInitialized) {
                try {
                    toolkit.registerMcpClient(mcpClient).block();
                    mcpInitialized = true;
                } catch (Exception e) {
                    logger.warn("MCP init failed, will retry");
                }
            }
        }
    }
}

C.4 记忆与会话问题

C.4.1 会话无法恢复

问题描述： 重启应用后，之前的对话记录丢失。

解决方案：

Session session = new JsonSession(Paths.get("/path/to/sessions"));
agent.saveTo(session, sessionId);
agent.loadIfExists(session, sessionId);

C.4.2 长期记忆不工作

问题描述： Mem0长期记忆没有保存或检索。

解决方案：

.longTermMemoryMode(LongTermMemoryMode.AUTO_SAVE)

C.5 多智能体协作问题

C.5.1 MsgHub消息未广播

问题描述： Agent发言后，其他Agent没有收到消息。

解决方案：

MsgHub.builder()
    .enableAutoBroadcast(true)
    // ...
    .build();
hub.broadcast(messages).block();
try (MsgHub hub = MsgHub.builder()...build()) {
    hub.enter().block();
    agent.call().block();  // 在Hub上下文中调用
}

C.5.2 A2A通信超时

问题描述：

Error: A2A request timeout

解决方案：

  1. 增加超时时间
  2. 检查网络连接
  3. 确认目标Agent服务已启动
  4. 检查防火墙设置

C.6 RAG问题

C.6.1 检索结果不相关

问题描述： RAG检索返回的文档与问题不相关。

解决方案：

.retrieveConfig(RetrieveConfig.builder()
    .scoreThreshold(0.5)  // 提高阈值
    .build())
  1. 使用重排序器
  2. 优化文档分块策略
  3. 检查嵌入模型维度配置

C.6.2 知识库添加文档失败

问题描述：

Error: Failed to add documents to knowledge base

解决方案：

  1. 检查嵌入模型配置
  2. 确认向量存储维度匹配
  3. 验证文档格式正确

C.7 性能问题

C.7.1 响应速度慢

问题描述： Agent响应时间过长。

解决方案：

  1. 使用更快的模型（如qwen-turbo）
  2. 减少工具数量
  3. 优化系统提示词长度
  4. 启用流式输出
  5. 使用AutoContextMemory控制上下文长度

C.7.2 内存占用过高

问题描述： 长时间运行后内存持续增长。

解决方案：

  1. 限制记忆消息数量
  2. 使用AutoContextMemory自动压缩
  3. 定期清理不活跃的会话
  4. 使用弱引用缓存Agent实例

C.8 调试技巧

C.8.1 启用详细日志

// 在logback.xml中配置
<logger name="io.agentscope" level="DEBUG"/>

C.8.2 使用监控Hook

.hooks(List.of(new Hook() {
    @Override
    public <T extends HookEvent> Mono<T> onEvent(T event) {
        System.out.println("Event: " + event.getClass().getSimpleName());
        return Mono.just(event);
    }
}))

C.8.3 使用Langfuse追踪

TelemetryTracer tracer = TelemetryTracer.builder()
    .endpoint(langfuseEndpoint)
    .addHeader("Authorization", authHeader)
    .build();
TracerRegistry.register(tracer);

C.9 版本兼容性

C.9.1 检查版本

确保所有AgentScope组件版本一致：

<properties>
    <agentscope.version>0.1.0</agentscope.version>
</properties>

C.9.2 JDK版本要求

AgentScope-Java需要JDK 17或更高版本。

← 返回目录