zhanggangyong
6caa0a7481
- 更新环境变量说明，与模板保持一致（移除 LITELLM_GATEWAY_URL） - 强调 MCP 接口是主要使用方式，业务 API 为可选 - 调整使用示例顺序，MCP 接口示例放在前面 - 更新返回格式说明，详细说明 MCP JSON-RPC 格式 - 完善测试示例，重点展示 MCP 接口使用
350 lines
7.7 KiB
Markdown
350 lines
7.7 KiB
Markdown
# 获客 Agent
|
||
|
||
基于 **Pydantic AI** 和 **FastMCP** 的获客助手，可以通过 LinkedIn 个人资料 URL 查找工作邮箱地址。
|
||
|
||
## 功能
|
||
|
||
- `find_email_from_linkedin` - 通过 LinkedIn 个人资料 URL 查找工作邮箱地址
|
||
- 使用 RapidAPI Fresh LinkedIn to Email Finder 服务
|
||
- 返回邮箱地址、姓名、公司、职位等完整信息
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 必需 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| OPENAI_BASE_URL | 否 | LiteLLM Gateway URL | LLM Gateway URL（优先） |
|
||
| LLM_BASE_URL | 否 | LiteLLM Gateway URL | LLM Gateway URL（备选） |
|
||
| OPENAI_API_KEY | 否 | sk | LLM API Key |
|
||
| MODEL_NAME | 否 | taiji/gpt-4o-mini | 模型名称 |
|
||
| LITELLM_MODEL | 否 | taiji/gpt-4o-mini | 模型名称（兼容） |
|
||
| API_HOST | 否 | 0.0.0.0 | 服务监听地址 |
|
||
| API_PORT | 否 | 8000 | 服务端口 |
|
||
|
||
**硬编码配置**（无需环境变量）：
|
||
- RapidAPI Key（Fresh LinkedIn to Email Finder）
|
||
|
||
## 启动
|
||
|
||
### 本地运行
|
||
|
||
```bash
|
||
python run_api_server.py
|
||
```
|
||
|
||
### Docker 运行
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t huoke:latest .
|
||
|
||
# 运行容器
|
||
docker run -d -p 8000:8000 \
|
||
-e OPENAI_API_KEY=your-api-key \
|
||
-e LITELLM_MODEL=taiji/gpt-4o-mini \
|
||
--name huoke \
|
||
huoke:latest
|
||
```
|
||
|
||
## API
|
||
|
||
### MCP 端点（主要使用方式）
|
||
|
||
本 Agent 主要通过 **MCP (Model Context Protocol)** 接口提供服务。
|
||
|
||
- **`POST /mcp`** - MCP HTTP 端点（主要使用）
|
||
- `tools/list` - 列出所有可用工具
|
||
- `tools/call` - 调用工具（需要 API Key）
|
||
- `initialize` - 初始化 MCP 会话
|
||
- `ping` - 心跳检测
|
||
|
||
- **`GET /mcp/sse`** - MCP SSE 端点（Server-Sent Events）
|
||
- **`POST /mcp/sse`** - MCP SSE POST 端点
|
||
|
||
### 业务 API（可选）
|
||
|
||
- **`POST /api/v1/query`** - 业务 API 端点（可选，需要 API Key）
|
||
|
||
### 健康检查
|
||
|
||
- **`GET /`** - 服务信息和可用工具列表
|
||
- **`GET /health`** - 健康检查端点
|
||
|
||
## 使用示例
|
||
|
||
### MCP 接口（主要使用方式）
|
||
|
||
#### 1. 列出可用工具
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/mcp \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "tools/list"
|
||
}'
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"result": {
|
||
"tools": [
|
||
{
|
||
"name": "find_email_from_linkedin",
|
||
"description": "通过 LinkedIn 个人资料 URL 查找工作邮箱地址",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"linkedin_url": {
|
||
"type": "string",
|
||
"description": "LinkedIn 个人资料 URL"
|
||
}
|
||
},
|
||
"required": ["linkedin_url"]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2. 调用查找邮箱工具
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/mcp \
|
||
-H "Content-Type: application/json" \
|
||
-H "api-key: your-api-key" \
|
||
-d '{
|
||
"jsonrpc": "2.0",
|
||
"id": 2,
|
||
"method": "tools/call",
|
||
"params": {
|
||
"name": "find_email_from_linkedin",
|
||
"arguments": {
|
||
"linkedin_url": "https://www.linkedin.com/in/williamhgates"
|
||
}
|
||
}
|
||
}'
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 2,
|
||
"result": {
|
||
"content": [
|
||
{
|
||
"type": "text",
|
||
"text": "{\n \"success\": true,\n \"linkedin_url\": \"https://www.linkedin.com/in/williamhgates\",\n \"full_name\": \"Bill Gates\",\n \"email_found\": true,\n \"email\": \"bill.gates@gatesfoundation.org\",\n ...\n}"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意**：API Key 可以通过以下方式传递：
|
||
- Header: `api-key: your-api-key`
|
||
- Header: `api_key: your-api-key`
|
||
- Header: `Authorization: Bearer your-api-key`
|
||
|
||
### 业务 API（可选）
|
||
|
||
如果需要使用 REST API 方式调用：
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/query \
|
||
-H "Content-Type: application/json" \
|
||
-H "api-key: your-api-key" \
|
||
-d '{
|
||
"query": "https://www.linkedin.com/in/williamhgates"
|
||
}'
|
||
```
|
||
|
||
## 返回格式
|
||
|
||
### MCP 接口返回格式
|
||
|
||
#### 成功响应
|
||
|
||
MCP 接口返回 JSON-RPC 2.0 格式：
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 2,
|
||
"result": {
|
||
"content": [
|
||
{
|
||
"type": "text",
|
||
"text": "{\n \"success\": true,\n \"linkedin_url\": \"https://www.linkedin.com/in/williamhgates\",\n \"full_name\": \"Bill Gates\",\n \"email_found\": true,\n \"email\": \"bill.gates@gatesfoundation.org\",\n \"email_status\": \"VALID\",\n \"email_type\": \"professional\",\n \"company\": \"Gates Foundation\",\n \"job_title\": \"Co-chair\",\n \"full_data\": {...}\n}"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
其中 `result.content[0].text` 包含实际的工具返回结果（JSON 字符串）：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"linkedin_url": "https://www.linkedin.com/in/williamhgates",
|
||
"full_name": "Bill Gates",
|
||
"email_found": true,
|
||
"email": "bill.gates@gatesfoundation.org",
|
||
"email_status": "VALID",
|
||
"email_type": "professional",
|
||
"company": "Gates Foundation",
|
||
"job_title": "Co-chair",
|
||
"full_data": {
|
||
"success": true,
|
||
"response": {
|
||
"full_name": "Bill Gates",
|
||
"location": "Seattle, Washington, United States",
|
||
"job_title": "Co-chair",
|
||
"email": {
|
||
"is_found": true,
|
||
"email": "bill.gates@gatesfoundation.org",
|
||
"status": "VALID",
|
||
"email_deliverability": "DELIVERABLE",
|
||
"type": "professional",
|
||
"confidence": "0.8"
|
||
},
|
||
"company": {
|
||
"name": "Gates Foundation",
|
||
"industry": "Non-profit Organizations"
|
||
},
|
||
"work_experience": [...]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 失败响应
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 2,
|
||
"error": {
|
||
"code": -32603,
|
||
"message": "无效的 LinkedIn URL，格式应为：https://www.linkedin.com/in/username"
|
||
}
|
||
}
|
||
```
|
||
|
||
或
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 2,
|
||
"error": {
|
||
"code": -32001,
|
||
"message": "缺少 API Key"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| success | boolean | 请求是否成功 |
|
||
| linkedin_url | string | 输入的 LinkedIn URL |
|
||
| full_name | string | 完整姓名 |
|
||
| email_found | boolean | 是否找到邮箱 |
|
||
| email | string | 邮箱地址（如果找到） |
|
||
| email_status | string | 邮箱状态（VALID/INVALID） |
|
||
| email_type | string | 邮箱类型（professional/personal） |
|
||
| company | string | 公司名称 |
|
||
| job_title | string | 职位 |
|
||
| full_data | object | 完整的 API 响应数据 |
|
||
|
||
## 完整测试示例
|
||
|
||
### 1. 健康检查
|
||
|
||
```bash
|
||
curl http://localhost:8000/health
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"status": "healthy",
|
||
"service": "获客 Agent API"
|
||
}
|
||
```
|
||
|
||
### 2. 查看服务信息
|
||
|
||
```bash
|
||
curl http://localhost:8000/
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"service": "获客 Agent API",
|
||
"status": "running",
|
||
"tools": ["find_email_from_linkedin"]
|
||
}
|
||
```
|
||
|
||
### 3. MCP 接口测试（推荐）
|
||
|
||
#### 3.1 列出工具
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/mcp \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "tools/list"
|
||
}' | python3 -m json.tool
|
||
```
|
||
|
||
#### 3.2 调用工具查找邮箱
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/mcp \
|
||
-H "Content-Type: application/json" \
|
||
-H "api-key: sk-test-key-123" \
|
||
-d '{
|
||
"jsonrpc": "2.0",
|
||
"id": 2,
|
||
"method": "tools/call",
|
||
"params": {
|
||
"name": "find_email_from_linkedin",
|
||
"arguments": {
|
||
"linkedin_url": "https://www.linkedin.com/in/williamhgates"
|
||
}
|
||
}
|
||
}' | python3 -m json.tool
|
||
```
|
||
|
||
### 4. 业务 API 测试（可选）
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/v1/query \
|
||
-H "Content-Type: application/json" \
|
||
-H "api-key: sk-test-key-123" \
|
||
-d '{
|
||
"query": "https://www.linkedin.com/in/williamhgates"
|
||
}' | python3 -m json.tool
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
- **FastAPI** - Web 框架
|
||
- **Pydantic AI** - AI Agent 框架
|
||
- **FastMCP** - MCP 服务器实现
|
||
- **RapidAPI** - Fresh LinkedIn to Email Finder API
|
||
- **Docker** - 容器化部署
|