agent_management/plans/jina_search_agent_plan.md

Jina Search Agent 实施计划

概述

创建一个基于Jina Reader API的网站内容搜索Agent，以HTTP服务模式运行，接收用户请求后调用Jina API搜索网站内容并返回结果。Agent将被打包成Docker镜像并部署到Azure Container Registry (ACR)。

架构设计

flowchart LR
    subgraph User
        A[用户请求]
    end
    
    subgraph K8s Cluster
        B[Agent Manager]
        C[Jina Search Agent Pod]
    end
    
    subgraph External
        D[Jina Reader API]
        E[目标网站]
    end
    
    A --> B
    B -->|创建/管理| C
    C -->|HTTP请求| D
    D -->|抓取内容| E
    E -->|返回内容| D
    D -->|返回结果| C
    C -->|响应| A

环境变量设计

变量名	必填	默认值	说明
JINA_API_KEY	是	-	Jina API密钥
POD_NAME	否	unknown	Pod名称，由K8s注入
TEMPLATE_TYPE	否	jina_search_agent	模板类型标识
SERVICE_PORT	否	8080	HTTP服务端口
SERVICE_HOST	否	0.0.0.0	HTTP服务监听地址

API设计

1. 健康检查

GET /health

返回服务状态

2. 搜索网站内容

POST /search
Content-Type: application/json

{
    "url": "https://www.example.com",
    "options": {
        "timeout": 30
    }
}

3. 直接获取URL内容

GET /fetch?url=https://www.example.com

文件结构

agent_templates/
├── jina_search_agent.py          # Agent主程序
├── jina_search_agent.Dockerfile  # Docker构建文件
└── build_and_push.sh             # 更新构建脚本

实施步骤

阶段1: 创建Jina Search Agent代码

• 创建 agent_templates/jina_search_agent.py
  • 实现FastAPI HTTP服务
  • 实现 /health 健康检查端点
  • 实现 /search POST端点，接收URL并调用Jina API
  • 实现 /fetch GET端点，快速获取URL内容
  • 使用环境变量配置JINA_API_KEY
  • 添加错误处理和日志记录

阶段2: 创建Dockerfile

• 创建 agent_templates/jina_search_agent.Dockerfile
  • 基于 python:3.11-slim
  • 安装必要依赖：fastapi, uvicorn, requests
  • 设置环境变量
  • 暴露服务端口

阶段3: 更新Agent Manager

• 更新 k8s_manager.py

  • 在 image_map 中添加 jina_search_agent 映射
  • 添加环境变量注入支持（JINA_API_KEY等）

• 更新 app.py

  • 在 valid_templates 列表中添加 jina_search_agent
  • 支持在创建Agent时传入自定义环境变量

阶段4: 更新构建脚本

• 更新 agent_templates/build_and_push.sh
  • 添加Jina Search Agent的构建和推送命令

阶段5: 构建并推送Docker镜像

• 登录ACR: az acr login --name agnettaiji
• 构建镜像: docker build -f jina_search_agent.Dockerfile -t agnettaiji.azurecr.io/ai-agents/jina-search-agent:latest .
• 推送镜像: docker push agnettaiji.azurecr.io/ai-agents/jina-search-agent:latest

阶段6: 测试验证

• 本地测试Agent代码
• 通过Agent Manager API创建Jina Search Agent
• 验证Agent Pod正常运行
• 测试搜索功能

代码示例

jina_search_agent.py 核心逻辑

import os
import requests
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

JINA_API_KEY = os.getenv("JINA_API_KEY", "")
JINA_BASE_URL = "https://r.jina.ai"

app = FastAPI(title="Jina Search Agent")

class SearchRequest(BaseModel):
    url: str
    options: dict = {}

@app.post("/search")
async def search(request: SearchRequest):
    headers = {"Authorization": f"Bearer {JINA_API_KEY}"}
    response = requests.get(
        f"{JINA_BASE_URL}/{request.url}",
        headers=headers,
        timeout=request.options.get("timeout", 30)
    )
    return {"content": response.text, "status_code": response.status_code}

创建Agent时传入环境变量

curl -X POST "http://localhost:8000/agents" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-jina-agent",
    "template": "jina_search_agent",
    "config": {
      "env": {
        "JINA_API_KEY": "your-jina-api-key"
      }
    }
  }'

注意事项

1. 安全性: JINA_API_KEY应通过Kubernetes Secret或环境变量安全传递
2. 超时处理: Jina API调用可能需要较长时间，需要合理设置超时
3. 错误处理: 需要处理网络错误、API限流等情况
4. 日志记录: 记录所有请求和响应，便于调试

后续扩展

• 支持批量URL搜索
• 添加缓存机制
• 支持更多Jina API参数（如代理、自定义headers等）
• 集成LangChain实现更复杂的搜索Agent