获客 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）

启动

本地运行

python run_api_server.py

Docker 运行

# 构建镜像
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. 列出可用工具

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

响应示例：

{
  "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. 调用查找邮箱工具

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"
      }
    }
  }'

响应示例：

{
  "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 方式调用：

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 格式：

{
  "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 字符串）：

{
  "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": [...]
    }
  }
}

失败响应

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32603,
    "message": "无效的 LinkedIn URL，格式应为：https://www.linkedin.com/in/username"
  }
}

或

{
  "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. 健康检查

curl http://localhost:8000/health

响应：

{
  "status": "healthy",
  "service": "获客 Agent API"
}

2. 查看服务信息

curl http://localhost:8000/

响应：

{
  "service": "获客 Agent API",
  "status": "running",
  "tools": ["find_email_from_linkedin"]
}

3. MCP 接口测试（推荐）

3.1 列出工具

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 调用工具查找邮箱

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 测试（可选）

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 - 容器化部署