30分钟打造智能天气助手：pydantic-ai零基础实战指南

你是否曾想过用AI轻松构建实用工具，却被复杂的代码和配置吓退？本文将带你从零开始，用pydantic-ai框架快速开发一个能实时查询多地天气的智能助手。无需深厚编程功底，只需跟随以下步骤，30分钟即可完成你的第一个AI应用。读完本文后，你将掌握：环境搭建、工具定义、Agent创建、流式响应处理以及Web界面开发的完整流程。

环境准备与安装

pydantic-ai支持Python 3.10+，推荐使用uv工具进行安装以获得最佳性能。打开终端执行以下命令：

# 基础安装（包含核心功能和所有模型依赖）
uv add pydantic-ai

# 如需仅安装示例所需依赖
uv add "pydantic-ai[examples]"

若需精简安装（仅包含OpenAI支持），可使用：

uv add "pydantic-ai-slim[openai]"

安装完成后，需配置模型访问密钥。以OpenAI为例：

export OPENAI_API_KEY="你的API密钥"

更多安装选项可参考官方文档：docs/install.md

核心概念解析：Agent与工具

在pydantic-ai中，Agent（智能体） 是连接大语言模型与工具的核心组件。它包含以下关键要素：

组件	描述
模型配置	指定使用的LLM（如openai:gpt-4.1-mini）
指令集	定义Agent行为模式的自然语言提示
工具集	可调用的函数集合，扩展AI能力
依赖管理	处理外部资源（如HTTP客户端）
输出类型	结构化响应格式定义

工具（Tool） 是Agent调用的函数，用于实现具体功能。pydantic-ai支持两种工具注册方式：

• @agent.tool：需访问上下文的工具
• @agent.tool_plain：无上下文依赖的工具

详细工具开发指南见：docs/tools.md

实战开发：天气查询助手

我们将构建一个能查询多城市天气的Agent，它需要两个工具：地理编码（获取经纬度）和天气查询。完整代码可参考：examples/pydantic_ai_examples/weather_agent.py

步骤1：定义数据模型与依赖

首先创建经纬度数据模型和HTTP客户端依赖：

from pydantic import BaseModel
from dataclasses import dataclass
from httpx import AsyncClient

# 经纬度数据模型
class LatLng(BaseModel):
    lat: float  # 纬度
    lng: float  # 经度

# 依赖容器
@dataclass
class Deps:
    client: AsyncClient  # HTTP客户端实例

步骤2：创建Agent实例

from pydantic_ai import Agent

weather_agent = Agent(
    model='openai:gpt-4.1-mini',
    instructions='Be concise, reply with one sentence.',  # 模型行为指令
    deps_type=Deps,  # 依赖类型声明
    retries=2  # 工具调用失败重试次数
)

步骤3：实现工具函数

地理编码工具

用于将城市名称转换为经纬度坐标：

@weather_agent.tool
async def get_lat_lng(ctx, location_description: str) -> LatLng:
    """获取地点的经纬度坐标
    
    Args:
        location_description: 地点描述（如城市名）
    """
    # 调用演示API获取坐标（实际项目中可替换为高德/百度地图API）
    response = await ctx.deps.client.get(
        'https://demo-endpoints.pydantic.workers.dev/latlng',
        params={'location': location_description}
    )
    response.raise_for_status()
    return LatLng.model_validate_json(response.content)

天气查询工具

根据经纬度获取天气数据：

@weather_agent.tool
async def get_weather(ctx, lat: float, lng: float) -> dict:
    """获取指定经纬度的天气信息
    
    Args:
        lat: 纬度
        lng: 经度
    """
    # 获取温度数据
    temp_response = await ctx.deps.client.get(
        'https://demo-endpoints.pydantic.workers.dev/number',
        params={'min': 10, 'max': 30}
    )
    
    # 获取天气描述
    desc_response = await ctx.deps.client.get(
        'https://demo-endpoints.pydantic.workers.dev/weather',
        params={'lat': lat, 'lng': lng}
    )
    
    return {
        'temperature': f'{temp_response.text} °C',
        'description': desc_response.text
    }

工具定义遵循以下最佳实践：

• 清晰的函数文档字符串（用于生成工具描述）
• 类型注解（确保参数类型安全）
• 异常处理（使用raise_for_status()处理HTTP错误）

运行与测试Agent

创建主函数执行Agent：

import asyncio

async def main():
    async with AsyncClient() as client:
        # 运行Agent并获取结果
        result = await weather_agent.run(
            'What is the weather like in London and Paris?',
            deps=Deps(client=client)
        )
        print('Response:', result.output)

if __name__ == '__main__':
    asyncio.run(main())

执行命令：

uv run -m pydantic_ai_examples.weather_agent

预期输出类似：

Response: London: 18°C, partly cloudy; Paris: 22°C, sunny

Agent工作流程如下：

sequenceDiagram
    participant User
    participant Agent
    participant LLM
    participant Tool

    User->>Agent: 查询伦敦和巴黎天气
    Agent->>LLM: 系统指令+用户查询
    LLM->>Agent: 需要调用get_lat_lng(London)
    Agent->>Tool: 执行地理编码
    Tool-->>Agent: 返回经纬度(51.5074, -0.1278)
    Agent->>LLM: 工具返回结果
    LLM->>Agent: 需要调用get_weather(51.5074, -0.1278)
    Agent->>Tool: 执行天气查询
    Tool-->>Agent: 返回天气数据
    Note over Agent,LLM: 重复巴黎查询流程
    LLM->>Agent: 生成最终回答
    Agent-->>User: 返回天气结果

添加Web交互界面

使用Gradio快速创建可视化界面，首先安装依赖：

uv add gradio>=5.9.0

创建weather_agent_gradio.py文件：

import gradio as gr
from pydantic_ai_examples.weather_agent import weather_agent, Deps
from httpx import AsyncClient

client = AsyncClient()
deps = Deps(client=client)

async def respond(message, chat_history):
    # 处理流式响应
    async with weather_agent.run_stream(message, deps=deps) as result:
        response = ""
        async for text in result.stream_text():
            response = text
            yield response

构建界面：

with gr.Blocks() as demo:
    gr.HTML("""<h1>智能天气助手</h1>""")
    chatbot = gr.Chatbot()
    msg = gr.Textbox()
    msg.submit(respond, [msg, chatbot], chatbot)

if __name__ == "__main__":
    demo.launch()

运行界面：

uv run -m pydantic_ai_examples.weather_agent_gradio

浏览器访问http://localhost:7860即可使用交互式天气查询界面。界面支持：

• 实时流式响应显示
• 工具调用过程可视化
• 多轮对话历史记录

调试与监控：Logfire集成

pydantic-ai内置与Logfire的集成，可实现Agent运行监控和调试。启用方式：

import logfire

# 配置Logfire
logfire.configure(send_to_logfire='if-token-present')
logfire.instrument_pydantic_ai()  # 自动 instrumentation
logfire.instrument_httpx(client)  # 监控HTTP请求

首次使用需进行认证：

logfire auth

在Logfire控制台中，你可以查看：

• Agent运行轨迹和耗时分析
• 工具调用参数和返回结果
• 模型输入输出和token使用量
• HTTP请求详情和错误日志

详细监控配置见：docs/logfire.md

项目扩展与优化建议

完成基础版本后，可考虑以下增强方向：

1. 工具扩展：

   • 集成真实天气API（如高德开放平台）
   • 添加城市搜索自动补全工具
   • 实现天气预警通知功能

2. 功能增强：

   • 添加多语言支持
   • 实现未来7天预报
   • 添加空气质量指数查询

3. 性能优化：

   • 使用本地缓存减少API调用
   • 实现工具调用超时控制
   • 添加请求限流保护

4. 部署选项：

   • 打包为Docker容器
   • 部署到云函数（如AWS Lambda）
   • 集成到现有应用（FastAPI/Flask）

更多示例可参考：docs/examples/weather-agent.md

总结与后续学习路径

通过本文，你已掌握使用pydantic-ai开发AI助手的核心流程：

1. 环境配置与依赖管理
2. Agent创建与模型配置
3. 工具定义与功能实现
4. 流式响应处理
5. Web界面开发
6. 监控与调试

建议后续学习资源：

• 官方文档：docs/agents.md
• 工具开发指南：docs/tools.md
• 高级功能：docs/advanced.md
• 完整示例库：examples/

现在，你已经具备构建更复杂AI应用的基础。尝试扩展这个天气助手，或开发全新的Agent应用（如智能客服、数据分析助手等）。如有疑问，欢迎在项目GitHub仓库提交issue或参与讨论。

点赞+收藏本文，关注作者获取更多pydantic-ai实战教程！下期预告：《多Agent协作系统设计与实现》