agents/search_agent/API_DOCUMENTATION.md

智能搜索AI Agent API接口文档

基础信息

• 服务名称: Intelligent Search AI Agent
• 版本: 1.0.0
• 基础URL: 域名
• Content-Type: application/json

---

核心接口

执行搜索

POST /search

执行智能搜索，根据查询返回答案和相关来源。

请求参数:

字段	类型	必填	说明
query	string	是	搜索查询
llm_api_key	string	是	LLM API密钥（用户的API密钥）
user_id	string	否	用户ID（用于计费回调）

请求示例:

{
  "query": "什么是人工智能？",
  "llm_api_key": "your-llm-api-key",
  "user_id": "user123"
}

响应示例:

{
  "query": "什么是人工智能？",
  "answer": "人工智能（AI）是计算机科学的一个分支，致力于创建能够执行通常需要人类智能的任务的系统...",
  "sources": [
    {
      "index": 1,
      "title": "人工智能 - 维基百科",
      "url": "https://zh.wikipedia.org/wiki/人工智能"
    },
    {
      "index": 2,
      "title": "什么是AI？",
      "url": "https://example.com/ai-introduction"
    }
  ],
  "confidence": "high",
  "iterations": 2,
  "total_sources": 5,
  "search_queries": [
    "什么是人工智能",
    "AI定义"
  ],
  "timestamp": "2024-01-01T00:00:00.000000"
}

响应字段说明:

字段	类型	说明
query	string	原始查询
answer	string	生成的答案内容（Markdown格式）
sources	array	来源列表
sources[].index	integer	来源索引
sources[].title	string	来源标题
sources[].url	string	来源URL
confidence	string	置信度："high" / "medium" / "low"
iterations	integer	迭代次数
total_sources	integer	参考来源总数
search_queries	array[string]	使用的搜索查询列表
timestamp	string	时间戳（ISO格式）

错误响应:

400 Bad Request（参数错误）:

{
  "detail": "llm_api_key 是必须的参数"
}

500 Internal Server Error（服务器错误）:

{
  "detail": "搜索失败: {错误详情}"
}

---

聊天接口

POST /chat

聊天接口，是 /search 接口的别名，功能和参数完全相同。

请求参数: 与 /search 接口相同

请求示例: 与 /search 接口相同

响应示例: 与 /search 接口相同

---

其他接口

健康检查

GET /health

检查服务健康状态。

请求示例:

GET /health

响应示例:

{
  "status": "healthy",
  "pod_name": "search-agent",
  "template_type": "search_agent",
  "configured": true,
  "llm_base_url": "https://api.example.com",
  "llm_model": "xchat52",
  "timestamp": "2024-01-01T00:00:00.000000"
}

---

获取状态

GET /status

获取服务状态信息。

请求示例:

GET /status

响应示例:

{
  "status": "running",
  "pod_name": "search-agent",
  "template_type": "search_agent",
  "configured": true,
  "timestamp": "2024-01-01T00:00:00.000000"
}

---

使用说明

重要提示：

• 用户只需要传递 query 和 llm_api_key 参数
• llm_base_url、llm_model 等配置参数已通过环境变量在部署时配置，不需要在请求中传递
• user_id 为可选参数，用于计费回调

请求参数说明：

• query - 搜索查询内容（必填）
• llm_api_key - 用户的LLM API密钥（必填）
• user_id - 用户ID（可选）

---

错误码说明

HTTP状态码	说明
200	请求成功
400	请求参数错误
500	服务器内部错误