如何用Pydantic AI与Google Gemini构建强大的SWOT分析代理？惊人架构揭秘！

在当今快节奏的世界中，快速收集和综合信息变得至关重要。我构建了一个 AI 代理，以现代技术栈提供战略洞察。本文将带您了解这一过程，突出技术和设计选择，并演示您如何在 Google Cloud 上构建它。

一个 AI 代理 是一种能够感知其环境、推理并采取行动以实现特定目标的系统。我的代理分析网页，理解社区情绪，并将这些信息综合成一个连贯的 SWOT 分析。

给定一个 URL，我们的代理对该主题执行 SWOT 分析。SWOT（优势、劣势、机会、威胁）是一种广泛使用的战略规划技术，用于评估影响组织或项目的内部和外部因素。它有助于识别优势领域和需要改进的领域，最终推动明智的决策。

AI代理堆栈的基础

我的目标是构建一个强大且易于维护的AI代理。这需要使用能够确保清晰、简洁代码的框架，避免使用会模糊底层逻辑的“魔法”。我还优先考虑类型安全，利用Python的类型提示来及早捕获错误。最后，我希望代理能够在不需要大量基础设施管理的情况下处理波动的工作负载。这些原则指导了我的技术选择：

• Pydantic AI: 这个框架使我们的AI代理能够产生结构化和可预测的输出，使用Pydantic模型来定义预期的数据格式，提供强类型安全。
• FastAPI: 这个现代Python网络框架是我们应用程序的基础。它的速度、易用性和自动数据验证（得益于其依赖于Pydantic）使其成为构建高性能API的理想选择。我们使用它来创建与代理交互和展示结果的端点。
• HTMX: 为了实现动态用户界面，我们使用HTMX。它允许我们在不需要完全重新加载页面的情况下更新网页的特定部分。HTMX通过声明式方法实现这一点，最小化了对复杂JavaScript的需求。
• Tailwind CSS: 这个实用优先的CSS框架使快速样式设计成为可能，并确保整个应用程序的一致设计语言。它的预定义类允许快速原型设计和轻松定制，使用户界面的开发更加高效。
• Cloud Run: 对于部署，我们利用Google Cloud Run，这是一个完全托管的无服务器平台。这使我们能够在不担心基础设施管理的情况下部署我们的容器化应用程序。Cloud Run会根据需求自动扩展，确保我们的代理在重负载下仍然响应迅速，并且我们只为消耗的计算时间付费。

理解代理代码

代理的代码可以在 Google Cloud generative-ai GitHub 仓库 中找到。让我们探讨其核心组件。 Agent 是使用 Vertex AI 模型 定义的。系统提示设定了整体方向：

swot_agent = Agent(
    model=VertexAIModel(
        model_name=MODEL,
        service_account_file=SERVICE_ACCOUNT_FILE,
        project_id=PROJECT_ID,
        region=LOCATION,
    ),
    deps_type=SwotAgentDeps,
    result_type=SwotAnalysis,
    system_prompt="""
        You are a strategic business analyst tasked with performing SWOT analysis.
        Analyze the given URL, identify internal strengths and weaknesses,
        and evaluate external opportunities and threats based on market conditions
        and competitive landscape. Use community insights to validate findings.

        For each category:
        - Strengths: Focus on internal advantages and unique selling points
        - Weaknesses: Identify internal limitations and areas for improvement
        - Opportunities: Analyze external factors that could be advantageous
        - Threats: Evaluate external challenges and competitive pressures

        Provide a detailed analysis that synthesizes these findings into actionable insights.
    """,
    retries=RETRIES,
)

代理的输出是一个 SwotAnalysis 类，继承自 Pydantic BaseModel。该类将字段定义为注解属性，从而实现数据验证并为代理提供提示：

class SwotAnalysis(BaseModel):
"""Represents a SWOT analysis with strengths, weaknesses, opportunities, threats, and an overall analysis."""

strengths: List[str] = Field(
   description="Internal strengths of the product/service"
)
weaknesses: List[str] = Field(
    description="Internal weaknesses of the product/service"
)
opportunities: List[str] = Field(
    description="External opportunities in the market"
)
threats: List[str] = Field(
    description="External threats in the market"
)
analysis: str = Field(
    description="A comprehensive analysis explaining the SWOT findings and their implications"
)

为代理配备工具

为了进行分析，我们的代理需要从各种来源收集信息。这是通过集成在 Pydantic AI 框架内的一组 工具 实现的：

• 内容提取： 使用 httpx 和 BeautifulSoup4，代理可以获取并解析给定 URL 的 HTML 内容，提取相关文本进行分析。这使代理能够理解网站上呈现的核心产品和信息。
• 通过 Reddit API 获取社区洞察： 利用 praw，Python Reddit API 包装器，代理可以查询 Reddit 上特定的子版块，以评估与特定主题或产品相关的社区情绪和讨论。
• 由 Gemini 提供的竞争分析： 代理使用 Gemini API 进行竞争分析。通过提供产品名称和描述，代理可以利用 Gemini 强大的语言理解能力来识别主要竞争对手，分析他们的市场地位，并评估竞争优势和劣势。

以下是 Reddit 社区洞察工具的简化代码片段：

@swot_agent.tool(prepare=report_tool_usage)
async def get_reddit_insights(
    ctx: RunContext[SwotAgentDeps],
    query: str,
    subreddit_name: str = "googlecloud",
) -> str:
    """Gathers insights from a specific subreddit related to a query using PRAW."""
    subreddit = ctx.deps.reddit.subreddit(subreddit_name)
    search_results = subreddit.search(query)

    insights = []
    for post in search_results:
       insights.append(
           f"Title: {post.title}\n"
           f"URL: {post.url}\n"
           f"Content: {post.selftext}\n"
       )
    return "\n".join(insights)

构建应用程序

在核心 AI 代理逻辑定义后，下一步是开发 UI 和处理请求的服务器。

FastAPI 作为后端，提供前端交互的 API 端点。它使用 Python 类型提示，继承自 Pydantic，支持数据验证并自动生成交互式 API 文档。例如，/analyze 端点通过 POST 请求（在 main.py 中定义）接受一个 URL，触发代理的分析，并管理异步任务，更新状态和结果存储以跟踪进度。然后，前端使用 /status 和 /result 端点轮询更新并显示最终的 SWOT 分析。

@app.post("/analyze", response_class=HTMLResponse)
async def analyze_url(request: Request, url: str = Form(...)) -> HTMLResponse:
    """Analyzes the given URL using the SWOT analysis agent."""

    task = asyncio.create_task(run_agent_with_progress(session_id, url))
    running_tasks.add(task)
    task.add_done_callback(running_tasks.discard)

    return templates.TemplateResponse(
        "status.html",
        {"request": request, "messages": [ANALYZING_MESSAGE], "result": False},
    )

在前端，HTMX 通过实现动态更新而无需完全重新加载页面来增强用户体验。在 templates/index.html 中，hx-post、hx-get、hx-trigger 和 hx-target 属性定义了元素如何与 FastAPI 后端交互。

例如，提交表单会触发对 /analyze 的 POST 请求，响应会被替换到 #status div 中。同样，#status 和 #result div 会定期使用 hx-get 和 hx-trigger="every 1s" 轮询它们的端点，仅更新页面上必要部分的最新状态消息或完成的 SWOT 分析。

<div
    id="status"
    hx-get="/status"
    hx-trigger="load, every 1s"
    hx-swap="innerHTML transition:false"
    style="display: none"
    class="bg-white rounded-2xl shadow-lg p-6 mb-8"
>

Tailwind CSS 在整个应用程序中实现了一致的设计语言。Tailwind 的预定义类直接用于 HTML，而不是编写自定义 CSS，从而简化了样式过程并确保了统一的外观和感觉。HTML 模板利用 Tailwind 的实用类来创建吸引人且响应迅速的布局。

使用 Google Cloud Run 部署和扩展

在 Google Cloud Run 上部署代理非常简单，这得益于其容器化架构。Cloud Run 是一个完全托管的无服务器平台，自动处理扩展、网络和基础设施，让您可以专注于代码。您可以使用 README 中提供的命令直接从源代码进行部署：

gcloud run deploy swot-agent --source . --region us-central1 --allow-unauthenticated

此命令指示 Cloud Run 部署名为 swot-agent 的服务，从当前目录构建映像，并将其部署到 us-central1 区域。— allow-unauthenticated 参数使该服务在初始测试和演示目的下公开可访问。

Cloud Run 然后配置所需资源，在容器内运行 uvicorn ASGI 服务器，并根据传入流量自动扩展实例数量。请记得为敏感信息（如 API 密钥）配置秘密。