智能体API服务 (cus-ai-agent)

基于 LangGraph 构建的智能体系统，通过 FastAPI 暴露 OpenAPI 接口，实现智能体编排功能。

功能特性

✅ 基于LangGraph的智能体编排
✅ FastAPI提供RESTful API接口
✅ OpenAI 兼容 API - 使用标准 OpenAI SDK 即可访问
✅ 多模型支持 - 通过 model 参数选择不同的智能体配置
✅ 支持工具调用（计算器、文本处理、API调用等）
✅ 支持RAG知识库（Milvus向量数据库）
✅ 支持独立的 Embedding API 配置 - 对话和 RAG 可使用不同的 API
✅ 支持 MCP 工具 - 可配置多个 MCP 服务器，单独启用/禁用
✅ 支持流式输出（SSE）
✅ OpenAPI文档自动生成
✅ 结构化日志记录
✅ 配置化管理
✅ LangSmith 集成 - 完整的可观测性和调试能力
✅ LangGraph Studio 支持 - 可视化调试和监控

技术栈

Python 3.10+
LangGraph: 智能体编排框架
LangGraph Studio: 可视化调试工具
LangChain 0.3+: LLM应用开发框架 (Pydantic v2 兼容)
LangSmith: 可观测性和调试平台
FastAPI: Web框架
Uvicorn: ASGI服务器
Milvus: 向量数据库
OpenAI: 大模型API

项目结构

cus-ai-agent/
├── docs/                    # 文档目录
│   ├── PRD.md              # 产品需求文档
│   └── architecture.md     # 架构设计文档
├── scripts/                 # 脚本目录
│   ├── start.sh            # 启动脚本
│   └── test_api.sh         # API测试脚本
├── src/                     # 源代码目录
│   ├── agent/              # 智能体核心
│   │   ├── graph.py        # LangGraph图定义
│   │   ├── nodes.py        # 节点定义
│   │   └── state.py        # 状态定义
│   ├── tools/              # 工具集
│   │   ├── api_caller.py   # API调用工具
│   │   └── custom_tools.py # 自定义工具
│   ├── api/                # API接口
│   │   ├── main.py         # FastAPI主入口
│   │   ├── routes.py       # 路由定义
│   │   └── models.py       # 数据模型
│   ├── config/             # 配置
│   │   └── settings.py     # 配置文件
│   └── utils/              # 工具类
│       └── logger.py       # 日志工具
├── logs/                    # 日志目录
├── requirements.txt         # Python依赖
├── .env.example            # 环境变量示例
└── README.md               # 项目说明

快速开始

1. 环境准备

确保已安装Python 3.10或更高版本：

python3 --version

2. 克隆项目

git clone <repository-url>
cd cus-ai-agent

3. 配置环境变量

复制环境变量示例文件并编辑：

cp .env.example .env

编辑.env文件，配置必要的环境变量：

方式 1: 使用配置向导（推荐）

bash scripts/setup_rag_config.sh

方式 2: 手动配置

# 必需配置
OPENAI_API_KEY=your_openai_api_key_here

# LangSmith 配置（可观测性和调试）
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langsmith_api_key_here
LANGCHAIN_PROJECT=cus-ai-agent

# RAG 知识库配置（可选）
ENABLE_RAG_TOOL=true

# 独立的 Embedding API 配置（推荐：对话用 DeepSeek，Embedding 用 OpenAI）
# 如果不设置，将使用上面的 OPENAI_API_KEY
RAG_OPENAI_API_KEY=your_openai_api_key_for_embedding
RAG_OPENAI_API_BASE=https://api.openai.com/v1

# 可选配置
MODEL_NAME=gpt-4-turbo-preview
TEMPERATURE=0.7
API_PORT=8000

💡 成本优化建议：

对话使用 DeepSeek（$0.14/1M tokens）
Embedding 使用 OpenAI（$0.02/1M tokens）
总成本节省约 99%

详细配置说明请查看：

获取 LangSmith API Key:

访问 LangSmith
注册/登录账号
进入 Settings → API Keys
创建新的 API Key

MCP 工具配置（可选）

如果需要使用 MCP (Model Context Protocol) 工具：

# 复制配置示例
cp config/mcp_tools.example.yaml config/mcp_tools.yaml

# 编辑配置文件
vim config/mcp_tools.yaml

配置示例：

global:
  enabled: true  # 启用 MCP 工具

servers:
  - name: filesystem
    enabled: true
    url: http://localhost:3000
    tool_prefix: fs_

详细配置说明请查看：MCP 工具集成方案

4. 安装依赖

方式一：使用安装脚本（推荐）

chmod +x scripts/install.sh
./scripts/install.sh

方式二：手动安装

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 升级pip
pip install --upgrade pip

# 安装依赖
pip install -r requirements.txt

遇到依赖冲突?

如果安装过程中遇到依赖冲突错误,可以使用修复脚本:

chmod +x scripts/fix_dependencies.sh
./scripts/fix_dependencies.sh

详细说明请查看: 依赖冲突解决方案

5. 启动服务

方式一：使用Python启动脚本（推荐）

# 确保已安装依赖
python run.py

方式二：使用Shell脚本

chmod +x scripts/start.sh
./scripts/start.sh

方式三：直接运行

# 如果使用虚拟环境，先激活
source venv/bin/activate

# 启动服务
python -m uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload

6. 访问服务

API文档: http://localhost:8000/docs
ReDoc文档: http://localhost:8000/redoc
OpenAPI规范: http://localhost:8000/openapi.json

API接口说明

OpenAI 兼容 API（推荐）

使用标准的 OpenAI SDK 访问智能体服务：

from openai import OpenAI

# 创建客户端
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="any-value"  # API key 不验证
)

# 发送消息
response = client.chat.completions.create(
    model="multi-agent-default",
    messages=[
        {"role": "user", "content": "你好"}
    ]
)

print(response.choices[0].message.content)

可用模型：

multi-agent-default - 默认的多智能体配置
multi-agent-supervisor - Supervisor 模式
multi-agent-with-memory - 启用记忆的配置

详细文档：OpenAI 兼容 API 使用指南

原有 API（向后兼容）

1. 健康检查

GET /api/v1/health

2. 普通对话

POST /api/v1/chat
Content-Type: application/json

{
  "message": "帮我计算 123 + 456",
  "session_id": "user-123",
  "config": {
    "temperature": 0.7
  }
}

3. 流式对话

POST /api/v1/chat/stream
Content-Type: application/json

{
  "message": "你好",
  "session_id": "user-123"
}

使用示例

Python示例

import requests

# 普通对话
response = requests.post(
    "http://localhost:8000/api/v1/chat",
    json={
        "message": "帮我计算 123 + 456",
        "session_id": "test-session"
    }
)
print(response.json())

cURL示例

# 普通对话
curl -X POST "http://localhost:8000/api/v1/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "帮我计算 123 + 456",
    "session_id": "test-session"
  }'

# 健康检查
curl -X GET "http://localhost:8000/api/v1/health"

测试脚本

chmod +x scripts/test_api.sh
./scripts/test_api.sh

可用工具

1. 计算器工具（calculator）

执行数学计算：

用户: 帮我计算 123 + 456
智能体: 使用计算器工具计算结果为 579

2. 文本处理工具（text_process）

处理文本（大小写转换、反转、长度等）：

用户: 请把 hello world 转换为大写
智能体: 使用文本处理工具，结果为 HELLO WORLD

3. API调用工具（api_call）

调用外部HTTP API：

用户: 调用 https://api.example.com/data 获取数据
智能体: 使用API调用工具获取数据...

配置说明

环境变量

变量名	说明	默认值
OPENAI_API_KEY	OpenAI API密钥	必需
MODEL_NAME	模型名称	gpt-4-turbo-preview
TEMPERATURE	温度参数	0.7
MAX_TOKENS	最大令牌数	2000
API_HOST	API主机	0.0.0.0
API_PORT	API端口	8000
LOG_LEVEL	日志级别	INFO

工具开关

变量名	说明	默认值
ENABLE_API_TOOL	启用API调用工具	true
ENABLE_SEARCH_TOOL	启用搜索工具	false

开发指南

添加自定义工具

在src/tools/custom_tools.py中创建新工具类：

from langchain.tools import BaseTool

class MyCustomTool(BaseTool):
    name: str = "my_tool"
    description: str = "工具描述"
    
    def _run(self, query: str) -> str:
        # 实现工具逻辑
        return "结果"

在src/tools/__init__.py中注册工具：

from .custom_tools import MyCustomTool

def get_available_tools():
    tools = []
    tools.append(MyCustomTool())
    return tools

修改智能体流程

编辑src/agent/graph.py和src/agent/nodes.py来自定义智能体的执行流程。

部署

Docker部署（待实现）

docker build -t cus-ai-agent .
docker run -p 8000:8000 --env-file .env cus-ai-agent

生产环境部署

使用Gunicorn + Uvicorn：

gunicorn src.api.main:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000

常见问题

1. 如何更换大模型？

修改.env文件中的MODEL_NAME和相关API配置。

3. 如何启用流式输出？

使用/api/v1/chat/stream接口，返回Server-Sent Events流。

4. Pydantic v2 兼容性问题？

如果遇到 Pydantic 相关错误,运行升级脚本:

python scripts/upgrade_langchain.py

详见故障排查指南

LangSmith 集成

功能特性

✅ 自动追踪: 自动追踪所有 LLM 调用和工具执行
✅ 实时监控: 实时查看性能指标和错误
✅ 调用链路: 完整的调用链路可视化
✅ 性能分析: Token 使用量、响应时间统计
✅ 错误调试: 详细的错误堆栈和上下文

快速开始

配置环境变量

# 在 .env 文件中
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langsmith_api_key_here
LANGCHAIN_PROJECT=cus-ai-agent

启动服务

python run.py

查看追踪数据

访问 LangSmith Dashboard 查看实时追踪数据

追踪内容

LLM 调用 (ChatOpenAI)
工具执行 (Calculator, TextProcess, API Call, RAG)
智能体决策 (LangGraph 节点)
错误和异常
性能指标 (响应时间、Token 使用量)

LangGraph Studio 集成

功能特性

✅ 可视化 Graph: 直观查看智能体执行流程
✅ 交互式调试: 实时测试和调试智能体
✅ 状态检查: 查看每个节点的状态变化
✅ 性能监控: 执行时间和 Token 使用统计
✅ 状态回溯: 检查历史执行状态

快速开始

安装依赖

pip install -r requirements.txt

启动 Studio

# 使用启动脚本 (推荐)
chmod +x scripts/start_studio.sh
./scripts/start_studio.sh

# 或直接使用 CLI
langgraph dev

遇到端口冲突? 使用自动修复脚本:

./scripts/fix_port_conflict.sh

访问 Studio UI

浏览器自动打开或手动访问: http://localhost:8123

Studio 功能

Graph 可视化: 查看节点和边的关系
交互测试: 输入消息并查看执行过程
状态追踪: 查看每个节点的输入输出
调试工具: 断点、单步执行、状态回溯

📄 许可证

本项目采用 MIT License 开源许可证。

🤝 贡献

我们欢迎所有形式的贡献！

🐛 报告 Bug
💡 提出新功能
📖 改进文档
🔧 提交代码

请阅读贡献指南了解详情。

📞 联系方式

GitHub Issues: 问题反馈
文档: 完整文档

⭐ Star History

如果这个项目对你有帮助，请给我们一个 Star！

🙏 致谢

感谢以下开源项目：

LangGraph - 智能体编排框架
LangChain - LLM 应用开发框架
FastAPI - 现代 Web 框架
Milvus - 向量数据库

Made with ❤️ by the cus-ai-agent team

⬆ 回到顶部

Name		Name	Last commit message	Last commit date
Latest commit History 41 Commits
.github		.github
config		config
docs		docs
scripts		scripts
src		src
tests		tests
tiktoken_cache		tiktoken_cache
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
langgraph.json		langgraph.json
requirements.txt		requirements.txt
run.py		run.py

Folders and files

Latest commit

History

Repository files navigation

智能体API服务 (cus-ai-agent)

功能特性

技术栈

项目结构

快速开始

1. 环境准备

2. 克隆项目

3. 配置环境变量

方式 1: 使用配置向导（推荐）

方式 2: 手动配置

MCP 工具配置（可选）

4. 安装依赖

方式一：使用安装脚本（推荐）

方式二：手动安装

遇到依赖冲突?

5. 启动服务

方式一：使用Python启动脚本（推荐）

方式二：使用Shell脚本

方式三：直接运行

6. 访问服务

API接口说明

OpenAI 兼容 API（推荐）

原有 API（向后兼容）

1. 健康检查

2. 普通对话

3. 流式对话

使用示例

Python示例

cURL示例

测试脚本

可用工具

1. 计算器工具（calculator）

2. 文本处理工具（text_process）

3. API调用工具（api_call）

配置说明

环境变量

工具开关

开发指南

添加自定义工具

修改智能体流程

部署

Docker部署（待实现）

生产环境部署

常见问题

1. 如何更换大模型？

3. 如何启用流式输出？

4. Pydantic v2 兼容性问题？

LangSmith 集成

功能特性

快速开始

追踪内容

相关文档

LangGraph Studio 集成

功能特性

快速开始

Studio 功能

相关文档

📄 许可证

🤝 贡献

📞 联系方式

⭐ Star History

🙏 致谢

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Packages