13 KiB

Raw Blame History

iConsulting Agent 工具文档

本文档详细描述了 iConsulting 移民咨询 Agent 可使用的所有工具。

工具概览

工具名称	类别	描述
search_knowledge	知识与记忆	搜索移民知识库
check_off_topic	知识与记忆	检测离题问题
collect_assessment_info	知识与记忆	收集评估信息
generate_payment	知识与记忆	生成支付二维码
save_user_memory	知识与记忆	保存用户记忆
get_user_context	知识与记忆	获取用户上下文
get_current_datetime	实时查询	获取当前时间
web_search	实时查询	网络搜索
get_exchange_rate	实时查询	汇率查询
fetch_immigration_news	实时查询	获取移民新闻

知识与记忆工具

1. search_knowledge

搜索香港移民相关知识库，获取最新的政策信息和常见问题解答。

输入参数:

参数名	类型	必填	描述
query	string	✅	搜索查询内容
category	string	❌	移民类别代码

category 可选值:

QMAS - 优才计划
GEP - 专才计划
IANG - 留学IANG
TTPS - 高才通计划
CIES - 投资移民
TECHTAS - 科技人才入境计划

返回格式:

{
  "success": true,
  "content": "检索到的知识内容",
  "sources": [
    {
      "articleId": "xxx",
      "title": "文章标题",
      "similarity": 0.85
    }
  ],
  "userContext": ["用户相关记忆"],
  "relatedExperiences": ["相关系统经验"],
  "message": "找到 3 条相关知识"
}

实现说明:

调用 knowledge-service 的 /api/v1/knowledge/retrieve API
支持向量相似度搜索
自动关联用户记忆和系统经验
如 API 不可用，返回 success: false 并建议基于内置知识回答

2. check_off_topic

检查用户的问题是否与香港移民相关，用于判断是否需要拒绝回答。

输入参数:

参数名	类型	必填	描述
question	string	✅	用户的问题

返回格式:

{
  "isOffTopic": true,
  "confidence": 0.92,
  "suggestion": "这个问题似乎与香港移民无关。作为移民咨询顾问，我专注于香港各类移民政策的咨询。请问您有香港移民相关的问题吗？"
}

实现说明:

调用 knowledge-service 的 /api/v1/knowledge/check-off-topic API
使用向量相似度判断问题是否属于移民领域
confidence 表示判断置信度 (0-1)
如 API 不可用，默认返回 isOffTopic: false

3. collect_assessment_info

收集用户的个人信息用于移民资格评估。

输入参数:

参数名	类型	必填	描述
category	string	✅	用户感兴趣的移民类别
age	number	❌	用户年龄
education	string	❌	最高学历
university	string	❌	毕业院校
yearsOfExperience	number	❌	工作年限
currentJobTitle	string	❌	当前职位
industry	string	❌	所属行业
annualIncome	number	❌	年收入（人民币）
hasHKEmployer	boolean	❌	是否有香港雇主

返回格式:

{
  "success": true,
  "collectedInfo": {
    "category": "QMAS",
    "age": 35,
    "education": "硕士",
    "yearsOfExperience": 10
  },
  "message": "已记录您的信息。如需完整评估，请选择付费评估服务。",
  "nextStep": "payment"
}

实现说明:

收集的信息自动保存到用户记忆 (importance: 80)
用于后续付费评估服务
信息以 FACT 类型存储

4. generate_payment

为付费评估服务生成支付二维码。

输入参数:

参数名	类型	必填	描述
serviceType	string	✅	服务类型，目前仅支持 `ASSESSMENT`
category	string	✅	移民类别
paymentMethod	string	✅	支付方式

paymentMethod 可选值:

ALIPAY - 支付宝
WECHAT - 微信支付
CREDIT_CARD - 信用卡

各类别价格:

类别	价格 (CNY)
QMAS	99
GEP	99
IANG	79
TTPS	99
CIES	199
TECHTAS	99

返回格式:

{
  "success": true,
  "orderId": "ORD_1706012345678",
  "amount": 99,
  "currency": "CNY",
  "paymentMethod": "ALIPAY",
  "qrCodeUrl": "https://...",
  "expiresAt": "2024-01-23T12:30:00.000Z",
  "message": "请扫描二维码支付 ¥99 完成QMAS类别的移民资格评估服务"
}

实现说明:

用户付费意向自动保存到记忆 (INTENT 类型, importance: 90)
二维码有效期 30 分钟
TODO: 对接实际支付服务

5. save_user_memory

保存用户的重要信息到长期记忆，以便后续对话中记住用户情况。

输入参数:

参数名	类型	必填	描述
memoryType	string	✅	记忆类型
content	string	✅	要记住的内容
category	string	❌	相关的移民类别

memoryType 可选值:

FACT - 用户陈述的事实（如：年龄、学历、工作经验）
PREFERENCE - 用户偏好（如：偏好的移民方式）
INTENT - 用户意图（如：计划移民的时间）

importance 自动设置:

FACT: 70
INTENT: 80
PREFERENCE: 60

返回格式:

{
  "success": true,
  "memoryId": "mem_xxx",
  "message": "已记住您的信息，下次对话时我会记得"
}

实现说明:

调用 knowledge-service 的 /api/v1/memory/user API
数据存储到 PostgreSQL + Neo4j
支持跨会话记忆

6. get_user_context

获取用户的历史背景信息和之前的对话记忆，帮助提供更个性化的建议。

输入参数:

参数名	类型	必填	描述
query	string	✅	当前问题，用于检索相关记忆

返回格式:

{
  "success": true,
  "memories": [
    {
      "type": "FACT",
      "content": "用户35岁，硕士学历，10年工作经验",
      "importance": 80
    },
    {
      "type": "INTENT",
      "content": "用户对QMAS优才计划感兴趣",
      "importance": 75
    }
  ],
  "message": "找到 2 条用户背景信息"
}

实现说明:

并行获取相关记忆和重要记忆
相关记忆：基于 query 向量搜索 (limit: 3)
重要记忆：按 importance 排序 (limit: 5)
自动去重合并

实时查询工具

7. get_current_datetime

获取当前的日期和时间，用于回答与时间相关的问题。

输入参数:

参数名	类型	必填	描述	默认值
timezone	string	❌	时区	Asia/Hong_Kong
format	string	❌	返回格式	full

format 可选值:

full - 完整日期时间
date - 仅日期
time - 仅时间

返回格式:

{
  "success": true,
  "datetime": "2024年1月23日星期二 14:30:00",
  "timezone": "Asia/Hong_Kong",
  "timestamp": "2024-01-23T06:30:00.000Z",
  "message": "当前Asia/Hong_Kong时间: 2024年1月23日星期二 14:30:00"
}

实现说明:

使用 JavaScript Intl.DateTimeFormat
支持任意 IANA 时区
默认使用香港时区

8. web_search

搜索互联网获取最新信息，用于查询移民政策变更、新闻动态等实时内容。

输入参数:

参数名	类型	必填	描述	默认值
query	string	✅	搜索关键词	-
site	string	❌	限定搜索网站	-
language	string	❌	搜索语言	zh-CN

language 可选值:

zh-CN - 简体中文
zh-TW - 繁体中文
en - 英文

常用 site 值:

immd.gov.hk - 香港入境事务处
talentservicewindow.gov.hk - 香港人才服务窗口

返回格式:

成功时:

{
  "success": true,
  "query": "香港优才计划最新政策",
  "results": [
    {
      "title": "优秀人才入境计划 - 入境事务处",
      "url": "https://www.immd.gov.hk/...",
      "snippet": "优秀人才入境计划是一项设有配额的移民吸纳计划..."
    }
  ],
  "resultCount": 5,
  "message": "找到 5 条相关结果"
}

降级时:

{
  "success": false,
  "query": "香港优才计划最新政策",
  "results": [],
  "message": "搜索服务暂时不可用。建议您访问以下官方网站获取最新信息：",
  "suggestedSites": [
    { "name": "香港入境事务处", "url": "https://www.immd.gov.hk" },
    { "name": "香港人才服务窗口", "url": "https://www.talentservicewindow.gov.hk" },
    { "name": "投资推广署", "url": "https://www.investhk.gov.hk" }
  ]
}

环境变量:

GOOGLE_SEARCH_API_KEY - Google Custom Search API Key
GOOGLE_CSE_ID - Google Custom Search Engine ID

实现说明:

优先使用 Google Custom Search API
如未配置 API Key，返回官方网站建议
每次请求返回最多 5 条结果

9. get_exchange_rate

查询实时货币汇率，用于投资移民金额换算等场景。

输入参数:

参数名	类型	必填	描述
from	string	✅	源货币代码
to	string	✅	目标货币代码
amount	number	❌	要转换的金额

常用货币代码:

CNY - 人民币
HKD - 港币
USD - 美元

返回格式:

实时汇率:

{
  "success": true,
  "from": "CNY",
  "to": "HKD",
  "rate": 1.0823,
  "amount": 3000000,
  "convertedAmount": 3246900,
  "lastUpdate": "2024-01-23T00:00:00Z",
  "message": "3000000 CNY = 3246900.00 HKD (汇率: 1.0823)"
}

降级汇率:

{
  "success": true,
  "from": "CNY",
  "to": "HKD",
  "rate": 1.08,
  "amount": 3000000,
  "convertedAmount": 3240000,
  "isEstimate": true,
  "message": "参考汇率 (可能有偏差): 1 CNY ≈ 1.08 HKD，3000000 CNY ≈ 3240000.00 HKD"
}

环境变量:

EXCHANGE_RATE_API_KEY - Exchange Rate API Key (可选)

降级汇率表:

From	To	Rate
CNY	HKD	1.08
CNY	USD	0.14
USD	HKD	7.78
USD	CNY	7.24
HKD	CNY	0.93
HKD	USD	0.13

实现说明:

优先使用 Exchange Rate API (v6 或 v4)
v4 API 免费，无需 API Key
如 API 不可用，使用内置降级汇率
降级汇率会标记 isEstimate: true

10. fetch_immigration_news

获取香港移民相关的最新新闻和政策公告。

输入参数:

参数名	类型	必填	描述	默认值
category	string	❌	移民类别	ALL
limit	number	❌	返回条数	5

category 可选值:

QMAS - 优才计划
GEP - 专才计划
IANG - 留学IANG
TTPS - 高才通计划
CIES - 投资移民
TECHTAS - 科技人才入境计划
ALL - 所有类别

返回格式:

动态新闻:

{
  "success": true,
  "category": "QMAS",
  "news": [...],
  "message": "获取到 3 条QMAS相关移民新闻"
}

静态参考:

{
  "success": true,
  "category": "QMAS",
  "news": [
    {
      "title": "优才计划持续接受申请",
      "summary": "香港优才计划无配额限制，全年接受申请。申请人需符合基本资格要求，并通过计分制评核。",
      "date": "2024-01",
      "source": "香港入境事务处"
    }
  ],
  "isStatic": true,
  "message": "以下是QMAS类别的参考信息。如需最新资讯，请访问香港入境事务处官网。",
  "officialSources": [
    { "name": "香港入境事务处", "url": "https://www.immd.gov.hk/hks/services/visas/admission_talents.html" },
    { "name": "香港人才服务窗口", "url": "https://www.talentservicewindow.gov.hk" }
  ]
}

实现说明:

优先从 knowledge-service 获取新闻
调用 /api/v1/news/immigration API
如服务不可用，返回静态参考信息
静态信息会标记 isStatic: true

工具调用流程

用户消息 → ClaudeAgentService.sendMessage()
    ↓
构建系统提示词 (含工具列表)
    ↓
调用 Claude API (带 tools 参数)
    ↓
Claude 决定是否调用工具
    ↓
如需调用 → ImmigrationToolsService.executeTool()
    ↓
工具执行返回结果
    ↓
结果注入对话上下文
    ↓
Claude 继续生成回复
    ↓
循环直到无需更多工具调用
    ↓
返回最终回复给用户

配置环境变量

# Knowledge Service
KNOWLEDGE_SERVICE_URL=http://knowledge-service:3003

# Google Search (可选)
GOOGLE_SEARCH_API_KEY=your_api_key
GOOGLE_CSE_ID=your_cse_id

# Exchange Rate (可选)
EXCHANGE_RATE_API_KEY=your_api_key

13 KiB Raw Blame History Unescape Escape

iConsulting Agent 工具文档

工具概览

知识与记忆工具

1. search_knowledge

2. check_off_topic

3. collect_assessment_info

4. generate_payment

5. save_user_memory

6. get_user_context

实时查询工具

7. get_current_datetime

8. web_search

9. get_exchange_rate

10. fetch_immigration_news

工具调用流程

配置环境变量

相关文件

13 KiB

Raw Blame History