Content
# Intelligent Agent API Service (cus-ai-agent)
<div align="center">
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/psf/black)
[](CONTRIBUTING.md)
An intelligent agent system built on LangGraph, exposing OpenAPI interfaces through FastAPI to achieve agent orchestration functionality.
[Quick Start](docs/quickstart.md) • [Documentation](docs/README.md) • [API Reference](docs/api-reference.md) • [Contribution Guidelines](CONTRIBUTING.md)
</div>
---
## Features
- ✅ Agent orchestration based on LangGraph
- ✅ FastAPI provides RESTful API interfaces
- ✅ Supports tool invocation (calculator, text processing, API calls, etc.)
- ✅ Supports RAG knowledge base (Milvus vector database)
- ✅ **Supports independent Embedding API configuration** - Different APIs can be used for conversation and RAG
- ✅ **Supports MCP tools** - Configurable multiple MCP servers, can be enabled/disabled individually
- ✅ Supports streaming output (SSE)
- ✅ Automatic generation of OpenAPI documentation
- ✅ Structured logging
- ✅ Configurable management
- ✅ **LangSmith integration** - Complete observability and debugging capabilities
- ✅ **LangGraph Studio support** - Visual debugging and monitoring
## Tech Stack
- **Python 3.10+**
- **LangGraph**: Agent orchestration framework
- **LangGraph Studio**: Visual debugging tool
- **LangChain 0.3+**: LLM application development framework (Pydantic v2 compatible)
- **LangSmith**: Observability and debugging platform
- **FastAPI**: Web framework
- **Uvicorn**: ASGI server
- **Milvus**: Vector database
- **OpenAI**: Large model API
## Project Structure
```
cus-ai-agent/
├── docs/ # Documentation directory
│ ├── PRD.md # Product requirement document
│ └── architecture.md # Architecture design document
├── scripts/ # Scripts directory
│ ├── start.sh # Startup script
│ └── test_api.sh # API testing script
├── src/ # Source code directory
│ ├── agent/ # Core of the agent
│ │ ├── graph.py # LangGraph graph definition
│ │ ├── nodes.py # Node definitions
│ │ └── state.py # State definitions
│ ├── tools/ # Toolset
│ │ ├── api_caller.py # API calling tool
│ │ └── custom_tools.py # Custom tools
│ ├── api/ # API interfaces
│ │ ├── main.py # FastAPI main entry
│ │ ├── routes.py # Route definitions
│ │ └── models.py # Data models
│ ├── config/ # Configuration
│ │ └── settings.py # Configuration file
│ └── utils/ # Utility classes
│ └── logger.py # Logging utility
├── logs/ # Logs directory
├── requirements.txt # Python dependencies
├── .env.example # Environment variable example
└── README.md # Project description
```
## Quick Start
### 1. Environment Preparation
Ensure that Python 3.10 or higher is installed:
```bash
python3 --version
```
### 2. Clone the Project
```bash
git clone <repository-url>
cd cus-ai-agent
```
### 3. Configure Environment Variables
Copy the environment variable example file and edit it:
```bash
cp .env.example .env
```
Edit the `.env` file to configure the necessary environment variables:
#### Method 1: Use Configuration Wizard (Recommended)
```bash
bash scripts/setup_rag_config.sh
```
#### Method 2: Manual Configuration
```env
# Required configuration
OPENAI_API_KEY=your_openai_api_key_here
# LangSmith configuration (observability and debugging)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langsmith_api_key_here
LANGCHAIN_PROJECT=cus-ai-agent
# RAG knowledge base configuration (optional)
ENABLE_RAG_TOOL=true
# Independent Embedding API configuration (recommended: use DeepSeek for conversation, OpenAI for embedding)
# If not set, the above OPENAI_API_KEY will be used
RAG_OPENAI_API_KEY=your_openai_api_key_for_embedding
RAG_OPENAI_API_BASE=https://api.openai.com/v1
# Optional configuration
MODEL_NAME=gpt-4-turbo-preview
TEMPERATURE=0.7
API_PORT=8000
```
**💡 Cost Optimization Suggestion**:
- Use DeepSeek for conversation ($0.14/1M tokens)
- Use OpenAI for embedding ($0.02/1M tokens)
- Total cost savings of approximately 99%
For detailed configuration instructions, please refer to:
- [RAG Embedding Configuration Guide](docs/rag_embedding_config.md)
- [Configuration Examples](docs/rag_config_examples.md)
- [MCP Tool Configuration Guide](docs/mcp_tools_configuration.md)
**Getting LangSmith API Key:**
1. Visit [LangSmith](https://smith.langchain.com/)
2. Register/Login
3. Go to Settings → API Keys
4. Create a new API Key
#### MCP Tool Configuration (Optional)
If you need to use MCP (Model Context Protocol) tools:
```bash
# Copy configuration example
cp config/mcp_tools.example.yaml config/mcp_tools.yaml
# Edit the configuration file
vim config/mcp_tools.yaml
```
Configuration example:
```yaml
global:
enabled: true # Enable MCP tools
servers:
- name: filesystem
enabled: true
url: http://localhost:3000
tool_prefix: fs_
```
For detailed configuration instructions, please refer to: [MCP Tool Integration Solution](docs/solutions/mcp-tools-integration.md)
### 4. Install Dependencies
#### Method 1: Use Installation Script (Recommended)
```bash
chmod +x scripts/install.sh
./scripts/install.sh
```
#### Method 2: Manual Installation
```bash
# Create a virtual environment
python3 -m venv venv
# Activate the virtual environment
source venv/bin/activate # Linux/Mac
# or
venv\Scripts\activate # Windows
# Upgrade pip
pip install --upgrade pip
# Install dependencies
pip install -r requirements.txt
```
#### Encountering Dependency Conflicts?
If you encounter dependency conflict errors during installation, you can use the fix script:
```bash
chmod +x scripts/fix_dependencies.sh
./scripts/fix_dependencies.sh
```
For detailed instructions, please refer to: [Dependency Conflict Resolution Guide](docs/troubleshooting/dependency-conflicts.md)
### 5. Start the Service
#### Method 1: Use Python Startup Script (Recommended)
```bash
# Ensure dependencies are installed
python run.py
```
#### Method 2: Use Shell Script
```bash
chmod +x scripts/start.sh
./scripts/start.sh
```
#### Method 3: Run Directly
```bash
# If using a virtual environment, activate it first
source venv/bin/activate
# Start the service
python -m uvicorn src.api.main:app --host 0.0.0.0 --port 8000 --reload
```
### 6. Access the Service
- **API Documentation**: http://localhost:8000/docs
- **ReDoc Documentation**: http://localhost:8000/redoc
- **OpenAPI Specification**: http://localhost:8000/openapi.json
## API Interface Description
### 1. Health Check
```bash
GET /api/v1/health
```
### 2. Regular Conversation
```bash
POST /api/v1/chat
Content-Type: application/json
{
"message": "Help me calculate 123 + 456",
"session_id": "user-123",
"config": {
"temperature": 0.7
}
}
```
### 3. Streaming Conversation
```bash
POST /api/v1/chat/stream
Content-Type: application/json
{
"message": "Hello",
"session_id": "user-123"
}
```
## Usage Examples
### Python Example
```python
import requests
# Regular conversation
response = requests.post(
"http://localhost:8000/api/v1/chat",
json={
"message": "Help me calculate 123 + 456",
"session_id": "test-session"
}
)
print(response.json())
```
### cURL Example
```bash
# Regular conversation
curl -X POST "http://localhost:8000/api/v1/chat" \
-H "Content-Type: application/json" \
-d '{
"message": "Help me calculate 123 + 456",
"session_id": "test-session"
}'
# Health check
curl -X GET "http://localhost:8000/api/v1/health"
```
### Test Script
```bash
chmod +x scripts/test_api.sh
./scripts/test_api.sh
```
## Available Tools
### 1. Calculator Tool (calculator)
Perform mathematical calculations:
```
User: Help me calculate 123 + 456
Agent: Using the calculator tool, the result is 579
```
### 2. Text Processing Tool (text_process)
Process text (case conversion, reversal, length, etc.):
```
User: Please convert hello world to uppercase
Agent: Using the text processing tool, the result is HELLO WORLD
```
### 3. API Calling Tool (api_call)
Call external HTTP APIs:
```
User: Call https://api.example.com/data to get data
Agent: Using the API calling tool to fetch data...
```
## Configuration Description
### Environment Variables
| Variable Name | Description | Default Value |
|----------------|-------------|---------------|
| OPENAI_API_KEY | OpenAI API key | Required |
| MODEL_NAME | Model name | gpt-4-turbo-preview |
| TEMPERATURE | Temperature parameter | 0.7 |
| MAX_TOKENS | Maximum token count | 2000 |
| API_HOST | API host | 0.0.0.0 |
| API_PORT | API port | 8000 |
| LOG_LEVEL | Log level | INFO |
### Tool Switches
| Variable Name | Description | Default Value |
|----------------|-------------|---------------|
| ENABLE_API_TOOL | Enable API calling tool | true |
| ENABLE_SEARCH_TOOL | Enable search tool | false |
## Development Guide
### Adding Custom Tools
1. Create a new tool class in `src/tools/custom_tools.py`:
```python
from langchain.tools import BaseTool
class MyCustomTool(BaseTool):
name: str = "my_tool"
description: str = "Tool description"
def _run(self, query: str) -> str:
# Implement tool logic
return "Result"
```
2. Register the tool in `src/tools/__init__.py`:
```python
from .custom_tools import MyCustomTool
def get_available_tools():
tools = []
tools.append(MyCustomTool())
return tools
```
### Modifying Agent Workflow
Edit `src/agent/graph.py` and `src/agent/nodes.py` to customize the execution flow of the agent.
## Deployment
### Docker Deployment (To Be Implemented)
```bash
docker build -t cus-ai-agent .
docker run -p 8000:8000 --env-file .env cus-ai-agent
```
### Production Environment Deployment
Use Gunicorn + Uvicorn:
```bash
gunicorn src.api.main:app \
--workers 4 \
--worker-class uvicorn.workers.UvicornWorker \
--bind 0.0.0.0:8000
```
## Frequently Asked Questions
### 1. How to switch large models?
Modify the `MODEL_NAME` and related API configurations in the `.env` file.
### 2. How to enable streaming output?
Use the `/api/v1/chat/stream` interface, which returns a Server-Sent Events stream.
### 3. Pydantic v2 compatibility issues?
If you encounter Pydantic-related errors, run the upgrade script:
```bash
python scripts/upgrade_langchain.py
```
See [Troubleshooting Guide](docs/troubleshooting.md) for details.
## LangSmith Integration
### Features
- ✅ **Automatic Tracing**: Automatically trace all LLM calls and tool executions
- ✅ **Real-time Monitoring**: View performance metrics and errors in real-time
- ✅ **Call Chain Visualization**: Complete visualization of the call chain
- ✅ **Performance Analysis**: Token usage, response time statistics
- ✅ **Error Debugging**: Detailed error stack and context
### Quick Start
1. **Configure Environment Variables**
```bash
# In the .env file
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your_langsmith_api_key_here
LANGCHAIN_PROJECT=cus-ai-agent
```
2. **Start the Service**
```bash
python run.py
```
3. **View Tracing Data**
Access the [LangSmith Dashboard](https://smith.langchain.com/) to view real-time tracing data.
### Tracing Content
- LLM Calls (ChatOpenAI)
- Tool Executions (Calculator, TextProcess, API Call, RAG)
- Agent Decisions (LangGraph Nodes)
- Errors and Exceptions
- Performance Metrics (Response Time, Token Usage)
### Related Documentation
- [LangSmith Quick Start](docs/langsmith_quickstart.md)
- [LangSmith Integration Guide](docs/langsmith_integration.md)
- [Troubleshooting Guide](docs/troubleshooting.md)
## LangGraph Studio Integration
### Features
- ✅ **Visual Graph**: Intuitive view of the agent execution flow
- ✅ **Interactive Debugging**: Real-time testing and debugging of the agent
- ✅ **State Checking**: View state changes of each node
- ✅ **Performance Monitoring**: Execution time and token usage statistics
- ✅ **State Backtracking**: Check historical execution states
### Quick Start
1. **Install Dependencies**
```bash
pip install -r requirements.txt
```
2. **Start Studio**
```bash
# Use startup script (recommended)
chmod +x scripts/start_studio.sh
./scripts/start_studio.sh
# Or run directly using CLI
langgraph dev
```
**Encountering Port Conflicts?** Use the auto-fix script:
```bash
./scripts/fix_port_conflict.sh
```
3. **Access Studio UI**
The browser will automatically open or manually visit: http://localhost:8123
### Studio Features
- **Graph Visualization**: View relationships between nodes and edges
- **Interactive Testing**: Input messages and observe the execution process
- **State Tracking**: View input and output of each node
- **Debugging Tools**: Breakpoints, step execution, state backtracking
### Related Documentation
- [Studio Quick Start](docs/langgraph-studio-quickstart.md)
- [Studio Architecture Design](docs/langgraph-studio-architecture.md)
- [Complete Integration Solution](docs/solutions/langgraph-studio-integration.md)
- [Port Conflict Resolution Solution](docs/solutions/langgraph-studio-port-conflict-solution.md) ⚡
## 📄 License
This project is licensed under the [MIT License](LICENSE).
## 🤝 Contribution
We welcome all forms of contributions!
- 🐛 [Report Bugs](https://github.com/wssaidong/cus-ai-agent/issues/new)
- 💡 [Suggest Features](https://github.com/wssaidong/cus-ai-agent/issues/new)
- 📖 Improve Documentation
- 🔧 Submit Code
Please read the [Contribution Guidelines](CONTRIBUTING.md) for details.
## 📞 Contact
- GitHub Issues: [Feedback](https://github.com/wssaidong/cus-ai-agent/issues)
- Documentation: [Complete Documentation](docs/README.md)
## ⭐ Star History
If this project is helpful to you, please give us a Star!
## 🙏 Acknowledgments
Thanks to the following open-source projects:
- [LangGraph](https://github.com/langchain-ai/langgraph) - Agent orchestration framework
- [LangChain](https://github.com/langchain-ai/langchain) - LLM application development framework
- [FastAPI](https://github.com/tiangolo/fastapi) - Modern web framework
- [Milvus](https://github.com/milvus-io/milvus) - Vector database
---
<div align="center">
Made with ❤️ by the cus-ai-agent team
[⬆ Back to Top](#intelligent-agent-api-service-cus-ai-agent)
</div>
