AI Agent（智能体）这个概念火得一塌糊涂

java -version
# 需要输出 17 或更高

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-harness</artifactId>
    <version>2.0.0</version>
</dependency>

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-model-dashscope</artifactId>
    <version>2.0.0</version>
</dependency>

export DASHSCOPE_API_KEY="sk-你的API密钥"

export OPENAI_API_KEY="sk-你的API密钥"

package com.example;

import io.agentscope.core.ReActAgent;
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.formatter.openai.OpenAIChatFormatter;
import io.agentscope.core.message.UserMessage;
import io.agentscope.core.model.GenerateOptions;
import io.agentscope.core.model.OpenAIChatModel;
import io.agentscope.core.tool.Toolkit;
import io.agentscope.harness.HarnessAgent;
import java.nio.file.Path;

public class FirstAgent {
    public static void main(String[] args) {
        // 1. 创建Model（以DeepSeek为例）
        String apiKey = System.getenv("DEEPSEEK_API_KEY");
        OpenAIChatModel model = OpenAIChatModel.builder()
            .apiKey(apiKey)
            .modelName("deepseek-chat")
            .baseUrl("https://4sapi.com")
            .stream(true)                    // 启用流式输出
            .enableThinking(true)            // 启用思考模式
            .formatter(new OpenAIChatFormatter())
            .defaultOptions(GenerateOptions.builder()
                .thinkingBudget(1024)        // 思考token预算
                .build())
            .build();

        // 2. 创建Agent
        HarnessAgent agent = HarnessAgent.builder()
            .name("Assistant")
            .sysPrompt("你是一个乐于助人的AI助手，请友好简洁地回答问题。")
            .model(model)
            .workspace(Path.of("./workspace"))
            .build();

        // 3. 发送消息并获取回复
        UserMessage userMsg = new UserMessage("你好，请介绍一下自己");
        String reply = agent.call(userMsg, RuntimeContext.empty())
            .block()
            .getTextContent();
        System.out.println(reply);
    }
}

import io.agentscope.core.tool.Tool;
import io.agentscope.core.tool.ToolParam;

public class WeatherTools {
    
    @Tool(name = "get_weather", description = "获取指定城市的当前天气")
    public String getWeather(
        @ToolParam(name = "city", description = "城市名称，例如'北京'") 
        String city
    ) {
        // 这里可以调用真实的天气API
        return city + "今天晴，温度25°C";
    }
    
    @Tool(name = "calculate", description = "执行数学计算")
    public double calculate(
        @ToolParam(name = "expression", description = "数学表达式") 
        String expression
    ) {
        // 这里可以集成表达式计算引擎
        return 42.0;
    }
}

// 创建工具集
Toolkit toolkit = new Toolkit();
toolkit.registerTool(new WeatherTools());

// 将工具集传给Agent
HarnessAgent agent = HarnessAgent.builder()
    .name("Assistant")
    .sysPrompt("你是一个可以使用工具的助手。")
    .model(model)
    .toolkit(toolkit)              // 注册工具
    .workspace(Path.of("./workspace"))
    .build();

public class ToolCallingExample {
    public static void main(String[] args) {
        // 创建Model
        OpenAIChatModel model = ...;
        
        // 创建工具集
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(new WeatherTools());
        
        // 创建Agent并注册工具
        HarnessAgent agent = HarnessAgent.builder()
            .name("Assistant")
            .sysPrompt("你是一个可以使用工具的助手。当用户问天气时，调用get_weather工具。")
            .model(model)
            .toolkit(toolkit)
            .build();
        
        // 用户提问，Agent会自动决定是否调用工具
        UserMessage userMsg = new UserMessage("北京今天天气怎么样？");
        String reply = agent.call(userMsg, RuntimeContext.empty())
            .block()
            .getTextContent();
        System.out.println(reply);
        // 输出：北京今天晴，温度25°C
    }
}

id: weather
description: 查城市天气。输入：城市名 + 日期。输出：温度区间、是否下雨。
sysPrompt: |
  你是一个气象助理。用户给你一个城市和日期，你返回：
  - 温度（高/低）
  - 是否下雨
  - 是否需要带伞
  严格三行，不超过60字。

id: flight
description: 查航班信息。输入：出发城市 + 到达城市 + 日期。
sysPrompt: |
  你是一个航班查询助理。根据用户输入给出一个mock航班号和起降时间。

import io.agentscope.harness.agent.subagent.SubagentDeclaration;

// Java端补强weather子Agent
SubagentDeclaration weather = SubagentDeclaration.builder()
    .name("weather")
    .description("查城市天气；输入城市+日期，返回温度区间和是否带伞")
    .inlineAgentsBody("你是一个气象助理，会调用工具查询真实天气")
    .build();

// 在HarnessAgent中注册子Agent
HarnessAgent agent = HarnessAgent.builder()
    .name("TravelAssistant")
    .model(model)
    .subagent(weather)          // 注册子Agent
    .workspace(Path.of("./workspace"))
    .build();

travel-assistant/
├── pom.xml
└── workspace/
    ├── MEMORY.md
    ├── subagents/
    │   ├── weather.md
    │   ├── flight.md
    │   └── attraction.md
    └── state/
        └── session-*.json    # JsonFileAgentStateStore自动生成

id: weather
description: |
  查城市天气。
  输入：城市名 + 日期（YYYY-MM-DD）。
  输出：温度区间、是否下雨、是否需要带伞。
sysPrompt: |
  你是一个气象助理。
  用户给你一个城市和日期，你返回：
  - 温度（高/低，摄氏度）
  - 是否下雨
  - 是否需要带伞
  严格三行，不超过60字。

id: flight
description: |
  查航班信息（mock）。
  输入：出发城市 + 到达城市 + 日期。
  输出：航班号、起飞时间、到达时间。
sysPrompt: |
  你是一个航班查询助理。
  根据用户输入给出一个mock航班号和起降时间。
  注意：测试环境，无需真查询，给出合理mock即可。

id: attraction
description: |
  景点信息助理（mock）。
  输入：城市 + 景点名。
  输出：开放时间、是否需要预约、周边交通。
sysPrompt: |
  你是一个导游助理。
  根据用户输入给出景点的实用信息。

import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.tool.Toolkit;
import io.agentscope.harness.HarnessAgent;
import io.agentscope.harness.agent.subagent.SubagentDeclaration;
import java.nio.file.Path;

public class TravelAssistant {
    public static void main(String[] args) {
        // 1. 创建Model
        DashScopeChatModel model = DashScopeChatModel.builder()
            .apiKey(System.getenv("DASHSCOPE_API_KEY"))
            .modelName("qwen-plus")
            .build();
        
        // 2. 创建Toolkit并注册天气查询工具
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(new WeatherLookupTool());  // 真实的天气API工具
        
        // 3. Java端补强weather subagent——tools白名单过滤继承自父agent的工具
        SubagentDeclaration weather = SubagentDeclaration.builder()
            .name("weather")
            .description("查城市天气；输入城市+日期，返回温度区间和是否带伞")
            .inlineAgentsBody("你是一个气象助理，会调用工具查询真实天气")
            .build();
        
        // 4. 创建HarnessAgent，注册subagent
        HarnessAgent agent = HarnessAgent.builder()
            .name("TravelAssistant")
            .model(model)
            .toolkit(toolkit)
            .workspace(Path.of("./workspace"))
            .subagent(weather)  // Java端补强的subagent
            .build();
        
        // 5. 运行
        UserMessage userMsg = new UserMessage(
            "我明天从北京飞杭州，落地后去西湖，要带伞吗？"
        );
        String reply = agent.call(userMsg, RuntimeContext.empty())
            .block()
            .getTextContent();
        System.out.println(reply);
    }
}

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

HarnessAgent agent = HarnessAgent.builder()
    .name("GitHubAssistant")
    .model(model)
    .workspace(Path.of("./workspace"))  // 自动加载tools.json
    .build();

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    }
  }
}

{
  "mcpServers": {
    "remote-knowledge": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${env:MCP_TOKEN}"
      }
    }
  }
}

import io.agentscope.harness.agent.tools.McpServerConfig;
import io.agentscope.harness.agent.tools.ToolsConfig;

ToolsConfig cfg = new ToolsConfig();
Map<String, McpServerConfig> servers = new LinkedHashMap<>();

McpServerConfig github = new McpServerConfig();
github.setTransport("stdio");
github.setCommand("npx");
github.setArgs(List.of("-y", "@modelcontextprotocol/server-github"));
github.setEnv(Map.of("GITHUB_PERSONAL_ACCESS_TOKEN", System.getenv("GITHUB_TOKEN")));

servers.put("github", github);
cfg.setMcpServers(servers);
// 然后通过HarnessAgent的toolsConfig()方法传入