下一代企业级智能体平台API 调用指南：从入门到实战

下一代企业智能体平台特点：
会自我进化的 agent（融合了Hermes），但被装进了一个可以让整个团队、整个公司共用的平台里。用户从浏览器登录，不写代码就能搭出自己的 agent，每个人都有独立的 workspace 让 agent 在里面慢慢成长；做出好东西后，主人可以把它分享给某位同事、某个小组，或者公开给整个组织。

一、问题背景

需要通过 REST API 与 Agent（GuoAgent）进行对话。整个过程中遇到了一系列典型问题，本文将逐一分析并提供解决方案。

二、环境信息

三、问题一：NullPointerException（model 为 null）

3.1 错误现象

Cannot invoke "io.agentscope.core.model.Model.getModelName()" 
because "this.this$0.model" is null

3.2 根因分析

ReActAgent.Builder.model(String modelId) 方法内部调用 ModelRegistry.resolve(modelId)，当模型 ID 未注册或对应的 API Key 环境变量缺失时，返回 null。build() 方法未对 model 进行非空校验，导致后续 CallExecution 内部类访问 model.getModelName() 时抛出 NPE。

3.3 解决方案

设置模型 API Key 环境变量：

$env:DASHSCOPE_API_KEY = "sk-51b3ca32af504ddba2**********"

或在启动脚本中添加：

set DASHSCOPE_API_KEY=sk-51b3ca32af504ddba2********

提示：也可通过 Spring Boot 配置文件 application.yml 设置：

builder:
  dashscope:
    api-key: ${DASHSCOPE_API_KEY:}
    model-name: qwen-max
    stream: true

四、问题二：401 Unauthorized（身份认证失败）

4.1 错误现象

{
  "timestamp": "2026-06-14T10:30:44.339Z",
  "path": "/api/agents/GuoAgent/chat/send",
  "status": 401,
  "error": "Unauthorized"
}

4.2 根因分析

AgentScope Builder 启用了 Spring Security + JWT 认证。直接调用 API 缺少有效的 Authorization 请求头。

4.3 解决方案

第一步：获取 JWT Token

$loginBody = @{
    username = "admin"
    password = "admin"
} | ConvertTo-Json

$loginResponse = Invoke-RestMethod -Uri "http://localhost:8080/api/auth/login" `
    -Method Post `
    -ContentType "application/json" `
    -Body $loginBody

$token = $loginResponse.token
Write-Host "Token: $token"

第二步：在后续请求中携带 Token

$headers = @{
    "Content-Type" = "application/json"
    "Authorization" = "Bearer $token"
}

五、问题三：404 Not Found（Agent ID 错误）

5.1 错误现象

{
  "timestamp": "2026-06-14T10:30:44.339Z",
  "path": "/api/agents/GuoAgent/chat/send",
  "status": 404,
  "error": "Not Found"
}

5.2 根因分析

API 路径 /api/agents/{agentId}/chat/send 中的 {agentId} 必须使用 Agent 的唯一标识符（ID），而非显示名称。

5.3 解决方案

查询可用 Agent 列表：

Invoke-RestMethod -Uri "http://localhost:8080/api/agents" `
    -Method Get `
    -Headers $headers

返回结果：

id                 : default
name               : builder-agent
scope              : global

id                 : 22ff4fda
name               : GuoAgent
scope              : user

关键结论：GuoAgent 的显示名称是 GuoAgent，但实际 ID 是 22ff4fda。API 调用必须使用 22ff4fda。

六、问题四：500 Internal Server Error（模型连接失败）

6.1 错误现象

reactor.core.Exceptions$RetryExhaustedException: Retries exhausted: 2/2
Caused by: io.agentscope.core.model.transport.HttpTransportException: 
SSE/NDJSON stream failed: Connection reset
Caused by: java.net.SocketException: Connection reset

6.2 根因分析

虽然 Agent 已找到，但模型服务连接失败。通常是因为：

1. DASHSCOPE_API_KEY 环境变量未在 Builder 进程启动时正确加载
2. API Key 无效或过期
3. 网络代理/防火墙限制

6.3 解决方案

确保在启动 Builder 前设置环境变量：

# 在 PowerShell 中直接启动（推荐测试用）
$env:DASHSCOPE_API_KEY = "sk-51b3ca32af504ddba2*************"
$env:JAVA_HOME = "D:\WORK\workspace_java\java17"

& "$env:JAVA_HOME\bin\java.exe" -jar `
    "D:\WORK\workspace_java\agentscope-java\agentscope-examples\agents\agentscope-builder\target\agentscope-builder-2.0.0-SNAPSHOT.jar"

注意：在 .bat 文件中 set 命令只在当前会话生效。如果通过双击运行 .bat，环境变量会正确传递；如果通过其他方式启动，可能需要显式设置。

七、完整调用示例（PowerShell）

# ========== 1. 获取 Token ==========
$loginBody = @{ username = "admin"; password = "admin" } | ConvertTo-Json
$loginResponse = Invoke-RestMethod -Uri "http://localhost:8080/api/auth/login" `
    -Method Post -ContentType "application/json" -Body $loginBody
$token = $loginResponse.token

# ========== 2. 准备请求头 ==========
$headers = @{
    "Content-Type" = "application/json"
    "Authorization" = "Bearer $token"
}

# ========== 3. 查询 Agent ID ==========
# $agents = Invoke-RestMethod -Uri "http://localhost:8080/api/agents" -Headers $headers
# $agentId = $agents[1].id  # 根据实际情况选择

# ========== 4. 发送聊天请求 ==========
$body = @{
    message = "你好，请介绍一下你的功能"
    sessionKey = $null
} | ConvertTo-Json

$response = Invoke-RestMethod -Uri "http://localhost:8080/api/agents/22ff4fda/chat/send" `
    -Method Post -Headers $headers -Body $body

Write-Host "回复: $($response.reply)"
Write-Host "SessionKey: $($response.sessionKey)"

八、关键 API 端点汇总

九、经验总结