# ai-agent-demo

**Repository Path**: HotJavaEn/ai-agent-demo

## Basic Information

- **Project Name**: ai-agent-demo
- **Description**: 一个展示AI代理开发的示例项目，涵盖自动化、数据分析等功能，适用于学习和研究智能代理技术。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-24
- **Last Updated**: 2025-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI, Agent, MCP, tools

## README

# AI Agent Demo - Java版本

这是一个基于Java + Spring Boot + LangChain4j的AI Agent演示项目，展示了如何实现AI、Agent、Tools、MCP之间的协作关系。

## 🎯 项目概述

### 核心概念验证

- **🧠 AI** = 智能核心（推理/决策/生成） → `ChatLanguageModel`
- **🤖 Agent** = AI + 记忆 + 工具调用 + 规划能力 → `WeatherAgent`  
- **🛠️ Tools** = Agent的"手和脚"，扩展能力边界 → `WeatherTool`
- **🔗 MCP** = 标准化通信协议 → `McpToolAdapter`

### 解决的问题

正如网上讨论的，Agent"看不见摸不着"的问题。本项目通过以下方式让Agent"具象化"：

1. **详细日志** - 记录Agent的每一步思考和行动
2. **HTTP接口** - 让Agent变成可调用的Web服务
3. **对话历史** - 展示Agent的记忆能力
4. **工具调用追踪** - 观察Agent如何使用外部能力

## 🏗️ 项目结构

```
src/main/java/com/example/aiagent/
├── AgentApplication.java          # 主启动类
├── agent/
│   └── WeatherAgent.java          # Agent核心实现
├── tool/
│   ├── WeatherTool.java           # 天气查询工具
│   └── McpToolAdapter.java        # MCP协议适配器
├── controller/
│   └── AgentController.java       # REST API控制器
├── dto/
│   ├── AgentQueryRequest.java     # 请求DTO
│   └── AgentQueryResponse.java    # 响应DTO
└── config/
    └── (配置类，可选)

src/main/resources/
└── application.yml                # 应用配置
```

## 🚀 快速开始

### 1. 环境要求

- Java 17+
- Maven 3.6+
- 可选：OpenAI API Key 或 本地Ollama模型

### 2. 配置模型

编辑 `src/main/resources/application.yml`：

```yaml
langchain4j:
  open-ai:
    chat-model:
      api-key: your-openai-api-key-here
      model-name: gpt-3.5-turbo
```

或使用本地模型（Ollama）：
```yaml
langchain4j:
  ollama:
    chat-model:
      base-url: http://localhost:11434
      model-name: llama2
```

### 3. 运行项目

```bash
# 编译项目
mvn clean compile

# 启动应用
mvn spring-boot:run
```

### 4. 访问接口

启动成功后，访问：

- **Swagger UI**: http://localhost:8080/swagger-ui.html
- **健康检查**: http://localhost:8080/api/agent/health
- **能力说明**: http://localhost:8080/api/agent/capabilities

## 📱 API 使用示例

### 基础对话

```bash
curl -X GET "http://localhost:8080/api/agent/ask?query=北京今天天气怎么样？"
```

### 完整对话（包含历史）

```bash
curl -X POST "http://localhost:8080/api/agent/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "对比一下北京和上海的天气",
    "clearHistory": false
  }'
```

### 查看对话历史

```bash
curl -X GET "http://localhost:8080/api/agent/history"
```

## 🧠 Agent工作流程演示

当你问"北京今天天气怎么样？"时，在日志中可以看到：

```
[👤 用户输入] 北京今天天气怎么样？
[🧠 Agent开始思考...]
[🛠️ 工具调用] WeatherTool.getCurrentWeather(北京)
[✅ 工具结果] 【北京】天气实况（09-18 14:30更新） | 🌤️ 天气：晴 | 🌡️ 温度：25°C | 💡 建议：适合户外运动
[🤖 Agent回答] 根据最新的天气信息，北京今天天气晴朗，温度25°C，非常适合户外运动！建议您可以出门散步或进行其他户外活动。 (耗时: 1250ms)
```

这样，Agent的行为就"可视化"了！

## 🛠️ 工具扩展

### 添加新工具

1. 创建新的工具类：

```java
@Component
public class CalculatorTool {
    
    @Tool("执行数学计算")
    public String calculate(String expression) {
        // 实现计算逻辑
        return "计算结果：" + result;
    }
}
```

2. 在Agent中注入并注册：

```java
@Autowired
private CalculatorTool calculatorTool;

// 在initializeAssistant方法中添加
.tools(weatherTool, calculatorTool)
```

### MCP协议集成

项目已包含MCP适配器示例，可以：

1. 连接外部MCP服务器
2. 标准化工具调用
3. 跨平台工具共享

## 🔧 配置说明

### 模型配置

支持多种LLM提供商：

- **OpenAI**: GPT-3.5/GPT-4
- **通义千问**: qwen-turbo/qwen-plus  
- **本地模型**: Ollama + Llama2/Mistral

### 日志配置

可调整日志级别查看不同详细程度的Agent行为：

```yaml
logging:
  level:
    com.example.aiagent: DEBUG  # Agent详细日志
    dev.langchain4j: INFO       # LangChain4j框架日志
```

## 🎯 核心特性展示

### 1. Agent"不再抽象"

通过详细的日志记录，你可以清楚看到：
- Agent的思考过程
- 工具调用的时机和参数
- 每个步骤的执行时间
- 决策的依据和结果

### 2. 记忆系统

Agent具有对话记忆，可以：
- 记住之前的对话内容
- 理解上下文关联
- 进行多轮复杂对话

### 3. 工具生态

演示了完整的工具系统：
- 本地工具（WeatherTool）
- 远程工具（MCP）
- 工具自动发现和调用

### 4. 企业级特性

- Spring Boot生产级框架
- RESTful API设计
- 完整的错误处理
- 监控和健康检查
- 可扩展架构

## 🚧 扩展方向

### 短期扩展

1. **更多工具**：邮件发送、数据库查询、文件操作
2. **更强记忆**：向量数据库、长期记忆
3. **多模态**：图像理解、语音交互

### 长期扩展

1. **多Agent协作**：Agent之间的任务分配和协调
2. **工作流引擎**：复杂业务流程自动化
3. **插件市场**：第三方工具生态

## 💡 学习要点

这个项目证明了：

1. **Agent不是魔法** - 它是可理解、可观察的程序逻辑
2. **Java也能玩转AI** - 企业级AI应用的优选技术栈  
3. **工具是Agent的核心** - 没有工具的Agent只是聊天机器人
4. **标准化很重要** - MCP这样的协议是未来趋势

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📄 许可证

MIT License

---

**让Agent从"看不见摸不着"变成"看得见摸得着"的Java同事！** 🚀