AI Agents · 课时

代理使用的 HTTP 客户端：httpx 与 requests

Q: 「代理使用的 HTTP 客户端：httpx 与 requests」这节课中我会学到什么？

同步与异步 HTTP 请求、会话管理和请求头。 你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

同步与异步 HTTP 请求、会话管理和请求头。

代理使用的 HTTP 客户端：httpx 与 requests 是 CoddyKit 上的免费 AI Agents 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。

为什么 HTTP 客户端对智能体很重要

智能体经常需要从外部来源获取数据，例如 API、网站和服务。可靠的 HTTP 客户端是任何智能体工具集的核心工具。

Python 有两个常用的 HTTP 库：requests（同步且简单）和 httpx（同时支持同步和异步）。理解何时使用它们各自的功能，对于构建高效的智能体至关重要。

使用 requests 发起基本 GET 请求

requests 库让简单的 HTTP 调用变得很容易。使用 requests.get(url) 获取资源并检查响应。

使用响应正文前，请始终检查状态代码，以避免失败被静默忽略。

import requests

url = 'https://api.example.com/data'
response = requests.get(url)

print(response.status_code)  # 200
print(response.text)         # raw string body
print(response.json())       # parsed JSON dict

添加请求头和超时

大多数 API 都要求提供身份验证请求头。headers= 参数允许您传入请求头字典。请始终设置 timeout=，以防智能体在响应缓慢的服务器上无限期挂起。

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
}

response = requests.get(
    'https://api.example.com/items',
    headers=headers,
    timeout=10  # seconds
)

data = response.json()
print(data)

raise_for_status() — 遇到错误立即失败

response.raise_for_status() 会针对 4xx 和 5xx 状态代码引发 HTTPError。如果不使用它，404 或 500 响应就会被静默地当作成功处理。

这是构建智能体时的最佳实践：明确报告失败，以便智能体知道应当重试还是报告错误。

import requests

try:
    response = requests.get('https://api.example.com/missing', timeout=10)
    response.raise_for_status()  # raises if status >= 400
    data = response.json()
except requests.HTTPError as e:
    print(f'HTTP error: {e}')
except requests.RequestException as e:
    print(f'Network error: {e}')

httpx 简介

httpx 是一种现代 HTTP 客户端，拥有与 requests 相同的 API，并额外支持异步操作。它还默认强制执行超时，因此用于生产环境中的智能体时更加安全。

请使用 pip install httpx 安装它。同步用法与 requests 几乎完全相同。

import httpx

response = httpx.get(
    'https://api.example.com/data',
    headers={'Authorization': 'Bearer YOUR_KEY'},
    timeout=10.0
)

response.raise_for_status()
data = response.json()
print(data)

使用 httpx.AsyncClient 进行异步 HTTP 通信

当您的智能体运行在异步上下文中（例如使用 FastAPI 或 asyncio 时），请使用 httpx.AsyncClient，以避免阻塞事件循环。请将它放在 async with 中，以确保连接得到正确关闭。

import httpx
import asyncio

async def fetch_data(url: str) -> dict:
    async with httpx.AsyncClient(timeout=10.0) as client:
        response = await client.get(
            url,
            headers={'Authorization': 'Bearer YOUR_KEY'}
        )
        response.raise_for_status()
        return response.json()

# result = asyncio.run(fetch_data('https://api.example.com/data'))

并发发起多个异步请求

异步 HTTP 的一项主要优势是使用 asyncio.gather() 同时获取多个 URL 的内容。对于需要在响应前从多个端点获取数据的智能体，这可以显著提升速度。

import httpx
import asyncio

async def fetch_all(urls: list) -> list:
    async with httpx.AsyncClient(timeout=10.0) as client:
        tasks = [client.get(url) for url in urls]
        responses = await asyncio.gather(*tasks)
        return [r.json() for r in responses]

urls = [
    'https://api.example.com/item/1',
    'https://api.example.com/item/2',
    'https://api.example.com/item/3'
]
# results = asyncio.run(fetch_all(urls))

会话复用与连接池

每次请求都创建新的 HTTP 连接会很慢。这两个库都支持连接池：requests.Session 和 httpx.Client 会复用 TCP 连接，并在多个请求之间共享请求头和 Cookie。

对于需要多次调用同一个 API 的智能体，这尤其有用。

import httpx

# Create once, reuse for many requests
client = httpx.Client(
    base_url='https://api.example.com',
    headers={'Authorization': 'Bearer YOUR_KEY'},
    timeout=10.0
)

response1 = client.get('/users')
response2 = client.get('/items')
response3 = client.get('/orders')

client.close()  # always close when done

使用 JSON 请求体发送 POST 请求

智能体经常不仅需要读取数据，还需要发送数据。使用 json= 参数可以自动序列化 Python 字典，并设置正确的 Content-Type 请求头。

import httpx

payload = {
    'query': 'latest AI news',
    'max_results': 5,
    'language': 'en'
}

response = httpx.post(
    'https://api.example.com/search',
    json=payload,
    headers={'Authorization': 'Bearer YOUR_KEY'},
    timeout=15.0
)

response.raise_for_status()
results = response.json()
print(results['items'])

解析响应：text、json 和 content

响应对象有三个主要的正文属性：

.text — 解码后的字符串（HTML、XML 或纯文本）
.json() — 将 JSON 解析为 Python 字典或列表
.content — 原始字节（用于图像或二进制文件）

请根据 API 的内容类型选择合适的属性。

import httpx

response = httpx.get('https://api.example.com/report', timeout=10.0)

# For JSON APIs
data = response.json()            # dict or list

# For HTML or plain text
html = response.text              # str

# For binary files
image_bytes = response.content    # bytes

print(type(data), type(html), type(image_bytes))

整合应用：智能体 HTTP 获取工具

下面是一个完整且可复用的获取函数，智能体可以将其作为工具调用。它能够妥善处理错误、记录请求，并返回结构化数据。

这种模式是构建任何网页获取智能体工具的可靠基础。

import httpx
import logging

logger = logging.getLogger(__name__)

def agent_fetch(url: str, headers: dict = None) -> dict:
    try:
        response = httpx.get(
            url,
            headers=headers or {},
            timeout=10.0
        )
        response.raise_for_status()
        logger.info(f'Fetched {url} -> {response.status_code}')
        return {'success': True, 'data': response.json()}
    except httpx.HTTPStatusError as e:
        return {'success': False, 'error': str(e)}
    except httpx.RequestError as e:
        return {'success': False, 'error': f'Network error: {e}'}

知识检查：HTTP 客户端

请检验您对智能体 HTTP 客户端的理解。

回顾：面向智能体的 HTTP 客户端

在本课中，您学习了如何为智能体配备可靠的 HTTP 获取能力：

使用 requests 进行简单的同步获取
使用 httpx.AsyncClient 发起非阻塞的异步请求
始终设置 timeout= 并调用 raise_for_status()
向同一主机发起多次调用时复用会话或客户端
根据响应类型使用 .json()、.text 或 .content

编写良好的获取工具是连接智能体与网络的桥梁。

常见问题解答

「代理使用的 HTTP 客户端：httpx 与 requests」课时是免费的吗？

是的 — 「代理使用的 HTTP 客户端：httpx 与 requests」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。

「代理使用的 HTTP 客户端：httpx 与 requests」这节课中我会学到什么？

同步与异步 HTTP 请求、会话管理和请求头。你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Agents 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「代理使用的 HTTP 客户端：httpx 与 requests」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Agents 课中编写并运行代码吗？

能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Agents