【Agent从入门到实践】16 接口与网络：API调用、HTTP请求，Agent与外部交互的基础

文章目录

- 前言
- [一、先搞懂：API 到底是个啥？（人话版）](#一、先搞懂：API 到底是个啥？（人话版）)
- [二、HTTP 到底在干嘛？（Agent 视角）](#二、HTTP 到底在干嘛？（Agent 视角）)
- - [1）一次完整 HTTP 交互（Agent 视角）](#1）一次完整 HTTP 交互（Agent 视角）)
  - [2）最常用的 4 种 HTTP 方法（Agent 必懂）](#2）最常用的 4 种 HTTP 方法（Agent 必懂）)
- [三、Python 发 HTTP 请求：3 个主流库（2025 最新推荐）](#三、Python 发 HTTP 请求：3 个主流库（2025 最新推荐）)
- - 1）requests（最经典、最常用）
  - [2）httpx（现代替代，支持同步 + 异步）](#2）httpx（现代替代，支持同步 + 异步）)
  - 3）aiohttp（纯异步，高并发专用）
- [四、实战 1：GET 请求（查数据）------Agent 查天气](#四、实战 1：GET 请求（查数据）——Agent 查天气)
- - 场景
  - [代码（httpx 同步版）](#代码（httpx 同步版）)
  - [requests 等价写法（几乎一样）](#requests 等价写法（几乎一样）)
  - [Agent 怎么用？](#Agent 怎么用？)
- [五、实战 2：POST 请求（提交数据）------Agent 调用大模型](#五、实战 2：POST 请求（提交数据）——Agent 调用大模型)
- - 场景
  - [代码（httpx + OpenAI v1+ 接口）](#代码（httpx + OpenAI v1+ 接口）)
  - [关键点（Agent 开发必注意）](#关键点（Agent 开发必注意）)
- [六、实战 3：异步请求（Agent 高并发场景）](#六、实战 3：异步请求（Agent 高并发场景）)
- - 场景
  - [代码（httpx 异步版）](#代码（httpx 异步版）)
  - [为什么异步对 Agent 重要？](#为什么异步对 Agent 重要？)
- [七、Agent 开发中 API 调用的 5 个"坑"与最佳实践](#七、Agent 开发中 API 调用的 5 个“坑”与最佳实践)
- - 1）一定要加超时（timeout）
  - [2）统一错误处理（Agent 要"懂失败"）](#2）统一错误处理（Agent 要“懂失败”）)
  - [3）请求头 Headers 别乱省](#3）请求头 Headers 别乱省)
  - 4）敏感信息不要硬编码
  - [5）日志 + 监控（Agent 可观测）](#5）日志 + 监控（Agent 可观测）)
- [八、总结：API/HTTP 对 Agent 意味着什么？](#八、总结：API/HTTP 对 Agent 意味着什么？)

目前国内还是很缺AI人才的，希望更多人能真正加入到AI行业，共同促进行业进步。想要系统学习AI知识的朋友可以看看我的教程http://blog.csdn.net/jiangjunshow，教程通俗易懂，风趣幽默，从深度学习基础原理到各领域实战应用都有讲解。

前言

各位小伙伴，前面咱们把 Agent 的"感知、决策、执行、记忆、工具调用、协作"都讲了个遍，也知道了 Python 是开发 Agent 的首选语言。但有个最底层、最关键的东西还没系统聊------Agent 怎么跟外面的世界"说话"？

不管是查天气、调大模型、连数据库、发消息，本质上都是：Agent 发一个请求 → 外部系统回一个响应 。这就是今天要讲的：API 调用 + HTTP 请求------Agent 与外部交互的"通用语言"。

全程大白话 + 最新 Python 实践（requests / httpx / aiohttp），不讲玄学，只讲你写 Agent 真正用得上的东西。

一、先搞懂：API 到底是个啥？（人话版）

API = Application Programming Interface（应用程序编程接口）

你可以把它理解成：外部系统给你留的"官方操作按钮"。

你不用知道对方内部怎么实现（数据库在哪、代码怎么写）
你只需要按它规定的"格式"发请求
它按规定的"格式"给你返回结果

生活里的类比：

外卖 App 点单 → 调用"下单 API"
微信发消息 → 调用"发消息 API"
查快递 → 调用"物流查询 API"

对 Agent 来说：

想知道天气 → 调用天气 API
想生成文案 → 调用大模型 API（OpenAI / 通义千问 / 文心一言）
想发邮件 → 调用邮件 API
想查订单 → 调用订单系统 API

一句话：Agent 要和外部世界交互，99% 都是通过 API，而 API 底层基本都是 HTTP。

二、HTTP 到底在干嘛？（Agent 视角）

HTTP 就是一套**"请求-响应"的通信规则**，就像 Agent 和外部系统的"对话协议"。

1）一次完整 HTTP 交互（Agent 视角）

Agent 发请求（Request）
- 用什么方法：GET / POST / PUT / DELETE
- 发给谁：URL（地址）
- 带什么：参数 / 数据 / 头部（Headers）
- 身份：Token / API Key（很多 API 要鉴权）
服务器处理
服务器回响应（Response）
- 状态码：200=成功 / 401=没权限 / 404=找不到 / 500=服务器挂了
- 数据：JSON / XML / 文本 / 文件
- 头部：告诉 Agent 数据类型、缓存、编码等

2）最常用的 4 种 HTTP 方法（Agent 必懂）

GET：拿数据（查天气、查订单、查资料）
POST：提交数据（下单、发消息、创建任务）
PUT：更新数据（修改用户信息、更新配置）
DELETE：删除数据（取消订单、删除记录）

写 Agent 时，GET 和 POST 占 90% 以上。

三、Python 发 HTTP 请求：3 个主流库（2025 最新推荐）

1）requests（最经典、最常用）

优点：简单、生态成熟、文档全
缺点：同步（阻塞），高并发场景一般

2）httpx（现代替代，支持同步 + 异步）

优点：API 跟 requests 几乎一样，支持 HTTP/2、异步
推荐：新项目优先用 httpx，兼容性好、更现代

3）aiohttp（纯异步，高并发专用）

优点：异步性能强，适合大量并发请求
缺点：API 风格和 requests 差异大，学习成本稍高

下面我们用 httpx 做示例（兼顾简单 + 现代），同时给 requests 等价写法。

四、实战 1：GET 请求（查数据）------Agent 查天气

场景

Agent 要查"北京"当前天气，调用一个公开天气 API（演示用）。

代码（httpx 同步版）

python 复制代码

import httpx

def get_weather(city: str) -> dict:
    """
    GET 请求：查询城市天气（演示接口，实际项目替换为真实 API）
    """
    # 1. 构造 URL + 参数
    base_url = "https://api.openweathermap.org/data/2.5/weather"
    params = {
        "q": city,
        "appid": "你的API_KEY",  # 去 openweathermap 注册免费获取
        "units": "metric",       # 摄氏度
        "lang": "zh_cn"          # 中文描述
    }

    try:
        # 2. 发送 GET 请求
        with httpx.Client(timeout=10) as client:
            response = client.get(base_url, params=params)

        # 3. 检查状态码
        response.raise_for_status()  # 4xx/5xx 直接抛异常，方便 Agent 做错误处理

        # 4. 解析 JSON 数据
        data = response.json()
        return {
            "city": data["name"],
            "temp": data["main"]["temp"],
            "desc": data["weather"][0]["description"],
            "humidity": data["main"]["humidity"]
        }

    except httpx.HTTPStatusError as e:
        return {"error": f"HTTP 错误: {e.response.status_code}"}
    except Exception as e:
        return {"error": f"请求失败: {str(e)}"}

# 测试
if __name__ == "__main__":
    result = get_weather("Beijing")
    print("天气信息：", result)

requests 等价写法（几乎一样）

python 复制代码

import requests

def get_weather(city: str) -> dict:
    base_url = "https://api.openweathermap.org/data/2.5/weather"
    params = {
        "q": city,
        "appid": "你的API_KEY",
        "units": "metric",
        "lang": "zh_cn"
    }
    try:
        response = requests.get(base_url, params=params, timeout=10)
        response.raise_for_status()
        data = response.json()
        return {
            "city": data["name"],
            "temp": data["main"]["temp"],
            "desc": data["weather"][0]["description"],
            "humidity": data["main"]["humidity"]
        }
    except requests.HTTPError as e:
        return {"error": f"HTTP 错误: {e.response.status_code}"}
    except Exception as e:
        return {"error": f"请求失败: {str(e)}"}

Agent 怎么用？

感知模块：调用这个函数，把天气作为"环境信息"
决策模块：根据温度决定"要不要提醒用户带伞/穿外套"
执行模块：把结果通过语音/消息告诉用户

五、实战 2：POST 请求（提交数据）------Agent 调用大模型

场景

Agent 要生成一段"奶茶推荐文案"，调用 OpenAI Chat Completions API（2025 最新接口）。

代码（httpx + OpenAI v1+ 接口）

python 复制代码

import httpx
from typing import Optional

def generate_milk_tea_recommendation(
    user_request: str,
    api_key: Optional[str] = None
) -> str:
    """
    POST 请求：调用 OpenAI API 生成奶茶推荐文案
    """
    api_key = api_key or "你的OPENAI_API_KEY"
    url = "https://api.openai.com/v1/chat/completions"

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    # POST 提交的 JSON 数据
    payload = {
        "model": "gpt-3.5-turbo",  # 也可以用 gpt-4o-mini / gpt-4o
        "messages": [
            {
                "role": "system",
                "content": "你是一个专业的奶茶推荐师，语言亲切、简短，给出具体甜度/冰量/配料建议。"
            },
            {
                "role": "user",
                "content": user_request
            }
        ],
        "temperature": 0.7,
        "max_tokens": 300
    }

    try:
        with httpx.Client(timeout=30) as client:
            response = client.post(url, headers=headers, json=payload)

        response.raise_for_status()
        data = response.json()
        return data["choices"][0]["message"]["content"].strip()

    except httpx.HTTPStatusError as e:
        return f"API 调用失败: {e.response.status_code} - {e.response.text}"
    except Exception as e:
        return f"请求异常: {str(e)}"

# 测试
if __name__ == "__main__":
    user_input = "夏天喝，要清爽、少糖、少冰，推荐一款奶茶"
    result = generate_milk_tea_recommendation(user_input)
    print("奶茶推荐：\n", result)

关键点（Agent 开发必注意）

鉴权：几乎所有商用 API 都要 Authorization: Bearer <API_KEY>
Content-Type ：POST JSON 必须带 application/json
超时：一定要设 timeout，否则 Agent 可能卡死
错误处理：401=密钥错 / 429=限流 / 500=服务器问题，Agent 要能识别并重试/上报

六、实战 3：异步请求（Agent 高并发场景）

场景

Agent 要同时查 3 个城市的天气，用异步更快（不阻塞）。

代码（httpx 异步版）

python 复制代码

import httpx
import asyncio

async def get_weather_async(city: str, client: httpx.AsyncClient) -> dict:
    """异步 GET：查单个城市天气"""
    base_url = "https://api.openweathermap.org/data/2.5/weather"
    params = {
        "q": city,
        "appid": "你的API_KEY",
        "units": "metric",
        "lang": "zh_cn"
    }
    try:
        response = await client.get(base_url, params=params)
        response.raise_for_status()
        data = response.json()
        return {
            "city": data["name"],
            "temp": data["main"]["temp"],
            "desc": data["weather"][0]["description"]
        }
    except Exception as e:
        return {"city": city, "error": str(e)}

async def batch_get_weather(cities: list[str]) -> list[dict]:
    """批量异步查天气"""
    async with httpx.AsyncClient(timeout=10) as client:
        tasks = [get_weather_async(city, client) for city in cities]
        results = await asyncio.gather(*tasks)
    return results

# 测试
if __name__ == "__main__":
    cities = ["Beijing", "Shanghai", "Guangzhou"]
    results = asyncio.run(batch_get_weather(cities))
    for res in results:
        print(res)

为什么异步对 Agent 重要？

Agent 可能要同时查多个 API（天气 + 订单 + 库存 + 大模型）
同步串行：总时间 = 各请求时间之和
异步并发：总时间 ≈ 最慢那个请求的时间
高并发场景下，异步能让 Agent 响应更快

七、Agent 开发中 API 调用的 5 个"坑"与最佳实践

1）一定要加超时（timeout）

不设超时：网络波动时 Agent 会"卡死"，影响整个流程
建议：timeout=10~30 秒，根据业务调整

2）统一错误处理（Agent 要"懂失败"）

401：API Key 错误/过期 → 记录日志 + 告警
429：请求超限 → 重试 + 限流控制
500/502/503：服务器问题 → 指数退避重试（1s → 2s → 4s...）
网络错误：重试 2~3 次，仍失败则上报决策模块"无法完成"

3）请求头 Headers 别乱省

User-Agent：标明"是谁在请求"（很多服务器会拦截无 UA 的请求）
Authorization：API 密钥（注意：不要硬编码在代码里，用环境变量/配置文件）
Content-Type：POST JSON 必须带

示例（推荐）：

python 复制代码

headers = {
    "User-Agent": "MilkTeaAgent/1.0 (https://your-domain.com)",
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

4）敏感信息不要硬编码

API Key / 密码 / 密钥 → 用环境变量或 .env 文件
Python 用 python-dotenv 管理：

python 复制代码

# .env 文件
OPENAI_API_KEY=sk-xxxxxx
WEATHER_API_KEY=yyyyyy

# 代码中
from dotenv import load_dotenv
import os

load_dotenv()
openai_api_key = os.getenv("OPENAI_API_KEY")
weather_api_key = os.getenv("WEATHER_API_KEY")

5）日志 + 监控（Agent 可观测）

记录：请求 URL、方法、耗时、状态码、是否成功
方便排查："为什么 Agent 昨天还能查天气，今天不行了？"

简单日志示例：

python 复制代码

import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("agent_api")

# 在请求前后打日志
logger.info(f"GET {base_url} params={params}")
# ... 请求 ...
logger.info(f"Response status={response.status_code} time={response.elapsed.total_seconds():.2f}s")

八、总结：API/HTTP 对 Agent 意味着什么？

API = Agent 的"外部能力接口"：没有 API，Agent 就是"信息孤岛"
HTTP = Agent 与外部交互的"通用语言"：99% 的系统都支持
Python + httpx/requests = 最快落地方式：简单、强大、生态全

对 Agent 架构来说：

感知模块：用 HTTP/API 采集外部数据（天气、新闻、订单、库存）
工具调用模块：用 HTTP/API 调用各种服务（大模型、支付、地图、邮件）
协作模块：用 HTTP/API 实现 Agent 之间的通信（REST/gRPC）

一句话：不会 HTTP/API，你写的 Agent 只能在本地"自娱自乐"；会了 HTTP/API，你的 Agent 才能真正"联网干活"。