Union AI - 通用 Agent 开发框架

一个工业级的 AI Agent 开发框架，基于 Google ADK 和 CopilotKit 构建。

项目概述

本项目包含两个主要部分：

1. 通用 Agent 模板 (agent/) - 工业级、模块化的 Agent 开发框架
2. 示例应用 (examples/proverbs-agent/) - 完整的 CopilotKit + ADK 集成示例

核心特性

• 多模型支持: OpenAI, Anthropic, Google, LiteLLM
• 工具系统: 内置网络搜索、计算器等工具，支持自定义工具
• 状态管理: 支持内存、SQLite、Redis 等多种存储后端
• 会话持久化: 自动保存对话历史，支持会话恢复
• 中间件支持: 可扩展的中间件系统
• 工业级架构: 模块化设计，易于扩展和维护

项目结构

union-ai/
├── agent/                    # 通用 Agent 框架
│   ├── universal_agent.py    # 通用 Agent 入口
│   ├── core/                 # 核心模块
│   ├── tools/                # 工具系统
│   ├── state/                # 状态管理
│   ├── middleware/           # 中间件系统
│   └── README.md             # Agent 文档
├── examples/                 # 示例应用
│   └── proverbs-agent/       # Proverbs Agent 示例
├── src/                      # 前端应用
│   ├── app/                  # Next.js App Router
│   └── components/           # React 组件
├── docs/                     # 文档
│   └── ARCHITECTURE.md       # 架构设计文档
└── scripts/                  # 脚本工具

快速开始

使用通用 Agent 模板

1. 进入 agent 目录并安装依赖：

cd agent
uv sync

2. 配置环境变量（创建 .env 文件）：

API_KEY=your-api-key-here
MODEL_NAME=gpt-4
ENABLE_WEB_SEARCH=true

3. 启动 Agent：

uv run universal_agent.py

运行示例应用

1. 安装依赖：

npm install
npm run install:agent

2. 设置 API Key：

export GOOGLE_API_KEY="your-google-api-key-here"

3. 启动开发服务器：

npm run dev

文档

• 架构设计文档 - 了解工业级架构设计
• Agent 框架文档 - 通用 Agent 模板使用指南
• 示例应用文档 - Proverbs Agent 示例

📚 外部资源

• ADK Documentation - Google ADK 官方文档
• CopilotKit Documentation - CopilotKit 官方文档
• Next.js Documentation - Next.js 官方文档

Prerequisites

• Node.js 18+
• Python 3.12+
• API Key (OpenAI/Google/其他 LLM 提供商)
• uv (推荐) 或 pip

可用脚本

npm 脚本

• npm run dev - 同时启动 UI 和 Agent 服务器
• npm run dev:ui - 仅启动 Next.js UI 服务器
• npm run dev:agent - 仅启动 ADK Agent 服务器
• npm run build - 构建生产版本
• npm run install:agent - 安装 Python Agent 依赖

下一步

基于这个通用 Agent 模板，你可以：

1. 自定义工具 - 在 agent/custom_tools/ 中添加业务特定的工具
2. ChatBI - 添加数据库查询和数据可视化工具
3. 数据分析 Agent - 集成数据分析库和可视化组件
4. 自动化 Agent - 添加任务调度和自动化执行功能

Contributing

Feel free to submit issues and enhancement requests! This starter is designed to be easily extensible.

License

This project is licensed under the MIT License - see the LICENSE file for details.

故障排除

Agent 连接问题

如果看到 "I'm having trouble connecting to my tools"，请确保：

1. Agent 服务器正在运行在端口 8000
2. API Key 已正确设置
3. 服务器成功启动

Python 依赖问题

如果遇到 Python 导入错误：

cd agent
uv sync

端口冲突

如果端口 3000 或 8000 被占用：

• 修改 agent/.env 中的 PORT 变量
• 修改 Next.js 配置中的端口号

License

MIT License