# Search Agent 使用指南

## 简介

智能搜索 AI Agent 是一个基于大语言模型的搜索代理，能够理解用户查询意图、自动规划搜索策略、从多个来源获取信息，并生成高质量、有来源引用的答案。

## 架构

- **基础镜像**: `agnettaiji.azurecr.io/ai-agents/search-agent:v1.0`
- **支持平台**: linux/amd64, linux/arm64
- **端口**: 8080
- **协议**: HTTP/REST API

## 功能特点

- 🧠 **智能查询理解**: 分析用户意图，提取关键实体
- 📋 **搜索规划**: 智能分解问题，制定搜索策略
- 🔎 **多源搜索**: 支持 Web 搜索和新闻搜索
- 📄 **内容提取**: 智能提取网页核心内容
- 🎯 **结果排序**: 基于相关性重排搜索结果
- ✍️ **答案生成**: 综合信息生成结构化回答
- 🔄 **自我反思**: 评估答案质量，决定是否迭代

## 环境变量配置

### 必需配置

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `LLM_BASE_URL` | LLM API 基础URL | `https://apis.openroutex.com/openai/deployments/xchat52` |
| `LLM_API_KEY` | LLM API 密钥 | `sk-xxx` |
| `SERPER_API_KEY` | Serper API 密钥（Google搜索） | `xxx` |
| `JINA_API_KEY` | Jina API 密钥（内容提取和重排序） | `jina_xxx` |

### 可选配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `LLM_MODEL` | LLM 模型名称 | `xchat52` |
| `MAX_ITERATIONS` | 最大迭代次数 | `3` |
| `MAX_RESULTS_PER_QUERY` | 每次搜索最大结果数 | `10` |
| `CONTENT_MAX_LENGTH` | 内容最大长度 | `5000` |
| `LOG_LEVEL` | 日志级别 | `INFO` |
| `TIMEOUT` | 超时时间（秒） | `30` |

## 部署方式

### 方式 1: 通过 agent-manager Web API

```bash
curl -X POST http://localhost:8000/api/v2/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-search-agent",
    "template_type": "search_agent",
    "image": "agnettaiji.azurecr.io/ai-agents/search-agent:v1.0",
    "replicas": 1,
    "env_vars": {
      "LLM_BASE_URL": "https://apis.openroutex.com/openai/deployments/xchat52",
      "LLM_API_KEY": "your-llm-key",
      "LLM_MODEL": "xchat52",
      "SERPER_API_KEY": "your-serper-key",
      "JINA_API_KEY": "your-jina-key",
      "MAX_ITERATIONS": "3",
      "LOG_LEVEL": "INFO"
    },
    "resources": {
      "cpu_request": "500m",
      "memory_request": "512Mi",
      "cpu_limit": "1000m",
      "memory_limit": "1Gi"
    }
  }'
```

### 方式 2: 直接使用 kubectl

```bash
# 创建命名空间（如果不存在）
kubectl create namespace agents

# 应用 YAML 配置
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-search-agent
  namespace: agents
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-search-agent
  template:
    metadata:
      labels:
        app: my-search-agent
    spec:
      imagePullSecrets:
      - name: acr-secret
      containers:
      - name: search-agent
        image: agnettaiji.azurecr.io/ai-agents/search-agent:v1.0
        ports:
        - containerPort: 8080
        env:
        - name: LLM_BASE_URL
          value: "https://apis.openroutex.com/openai/deployments/xchat52"
        - name: LLM_API_KEY
          value: "your-llm-key"
        - name: SERPER_API_KEY
          value: "your-serper-key"
        - name: JINA_API_KEY
          value: "your-jina-key"
---
apiVersion: v1
kind: Service
metadata:
  name: my-search-agent
  namespace: agents
spec:
  selector:
    app: my-search-agent
  ports:
  - port: 8080
    targetPort: 8080
EOF
```

### 方式 3: 使用 Docker 本地测试

```bash
docker run -p 8080:8080 \
  -e LLM_BASE_URL='https://apis.openroutex.com/openai/deployments/xchat52' \
  -e LLM_API_KEY='your-llm-key' \
  -e SERPER_API_KEY='your-serper-key' \
  -e JINA_API_KEY='your-jina-key' \
  agnettaiji.azurecr.io/ai-agents/search-agent:v1.0
```

## API 接口

### 健康检查

```bash
GET /health

# 响应示例
{
  "status": "healthy",
  "pod_name": "search-agent-xxx",
  "template_type": "search_agent",
  "configured": true,
  "timestamp": "2026-01-13T04:45:00.000000"
}
```

### 获取状态

```bash
GET /status

# 响应示例
{
  "status": "running",
  "pod_name": "search-agent-xxx",
  "template_type": "search_agent",
  "configured": true,
  "timestamp": "2026-01-13T04:45:00.000000"
}
```

### 配置 Agent（如果未通过环境变量配置）

```bash
POST /configure
Content-Type: application/json

{
  "llm_base_url": "https://apis.openroutex.com/openai/deployments/xchat52",
  "llm_api_key": "your-llm-key",
  "llm_model": "xchat52",
  "serper_api_key": "your-serper-key",
  "jina_api_key": "your-jina-key",
  "max_iterations": 3,
  "max_results_per_query": 10,
  "content_max_length": 5000,
  "log_level": "INFO",
  "timeout": 30
}
```

### 执行搜索

```bash
POST /search
Content-Type: application/json

{
  "query": "什么是 Kubernetes？",
  "auto_configure": false
}

# 响应示例
{
  "query": "什么是 Kubernetes？",
  "answer": "Kubernetes 是一个开源的容器编排平台...",
  "sources": [
    {
      "index": 1,
      "title": "Kubernetes 官方文档",
      "url": "https://kubernetes.io/docs/"
    }
  ],
  "confidence": "high",
  "iterations": 1,
  "total_sources": 5,
  "search_queries": ["Kubernetes 是什么", "Kubernetes 容器编排"],
  "timestamp": "2026-01-13T04:45:00.000000"
}
```

### 聊天接口（别名）

```bash
POST /chat
Content-Type: application/json

{
  "query": "Python 和 Go 语言的区别是什么？"
}
```

## 使用示例

### Python 客户端

```python
import requests

# Agent 服务地址
agent_url = "http://my-search-agent.agents.svc.cluster.local:8080"

# 执行搜索
response = requests.post(
    f"{agent_url}/search",
    json={
        "query": "什么是微服务架构？",
        "auto_configure": False
    }
)

result = response.json()
print(f"答案: {result['answer']}")
print(f"来源数: {len(result['sources'])}")
print(f"置信度: {result['confidence']}")
```

### cURL 示例

```bash
# 搜索
curl -X POST http://my-search-agent:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Docker 容器的优势是什么？"
  }'

# 健康检查
curl http://my-search-agent:8080/health
```

## 构建和推送

### 构建镜像

```bash
cd /home/taiji/tools/agent-manager/agent_templates
./build_search_agent.sh v1.0
```

### 推送到 ACR

在构建过程中选择 `y` 推送，或手动推送：

```bash
# 登录 ACR
az acr login --name agnettaiji

# 构建并推送
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -f search_agent.Dockerfile \
  -t agnettaiji.azurecr.io/ai-agents/search-agent:v1.0 \
  --push \
  .
```

## 测试

### 使用测试脚本

```bash
cd /home/taiji/tools/agent-manager/agent_templates
./test_search_agent.sh
```

### 手动测试

```bash
# 1. 创建 Agent
curl -X POST http://localhost:8000/api/v2/agents \
  -H "Content-Type: application/json" \
  -d @search_agent_config.json

# 2. 查看状态
curl http://localhost:8000/api/v2/agents/my-search-agent

# 3. 测试搜索
curl -X POST http://my-search-agent:8080/search \
  -H "Content-Type: application/json" \
  -d '{"query": "测试查询"}'

# 4. 删除 Agent
curl -X DELETE http://localhost:8000/api/v2/agents/my-search-agent
```

## 故障排查

### 查看日志

```bash
kubectl logs -n agents deployment/my-search-agent
```

### 查看 Pod 状态

```bash
kubectl get pods -n agents -l app=my-search-agent
kubectl describe pod -n agents <pod-name>
```

### 常见问题

1. **Agent 无法启动**
   - 检查环境变量是否正确配置
   - 确认 ACR secret 已创建
   - 查看 Pod 事件和日志

2. **搜索失败**
   - 确认 API keys 有效
   - 检查网络连接
   - 查看日志中的错误信息

3. **健康检查失败**
   - 确认端口 8080 正常监听
   - 检查容器资源是否充足
   - 查看启动日志

## 相关文件

- `/home/taiji/tools/agent-manager/agent_templates/search_agent.py` - 主程序
- `/home/taiji/tools/agent-manager/agent_templates/search_agent.Dockerfile` - Dockerfile
- `/home/taiji/tools/agent-manager/agent_templates/build_search_agent.sh` - 构建脚本
- `/home/taiji/tools/agent-manager/agent_templates/test_search_agent.sh` - 测试脚本
- `/home/taiji/tools/agent-manager/agent_manager/templates/search_agent.yaml` - K8s 模板

## 技术栈

- **语言**: Python 3.11
- **框架**: FastAPI, Uvicorn
- **LLM**: xchat52 (GPT-5.2)
- **搜索**: Serper API (Google 搜索代理)
- **内容提取**: Jina Reader
- **重排序**: Jina Reranker
- **异步**: asyncio

## 许可

遵循项目主许可证。