智能体接口测试要求怎么落地？用本地 HTTP 服务验证错误状态和坏 JSON 不算成功

智能体接口测试要求不能只写“能连通”。接口适配层必须区分HTTP失败、响应解析失败与有效结果，否则一段错误页面也可能被包装成成功。

准备验收智能体HTTP适配层的开发者。本文使用 Python 3.11 或以上版本的标准库，先验证一组人工构造的小样本。AI 负责提出实现或解释差异，结果由本地检查决定；这里没有把模型回答当成真实运行结果。

区分HTTP失败与结构化解析失败前，先定规则

本例只监听127.0.0.1随机空闲端口，响应完全由本地桩构造，没有调用模型、互联网或生产接口。

正常返回200和JSON；参数错误返回400；坏响应返回200但内容不是JSON。这三种场景必须有不同结论。

HTTP状态与内容格式都通过仍不证明业务成功，后续字段契约和结果回查应单独检查。

给 AI 的输入要包含什么

把下面这份输入说明和你的实际样本一起交给可用的 AI 编程助手。示例只含虚构数据；对真实材料先去除账号凭据和个人信息。

实现本地HTTP桩三个路径/ok、/bad-status、/bad-json。客户端必须设置timeout并检查status，再解析JSON。400与200坏JSON返回明确失败，不能返回空对象假成功；测试结束关闭服务。

要求模型保留检查条件，并把它认为缺少的业务定义列出来。若回答改变了输入字段、忽略异常分支或直接删除原材料，先要求修正，再运行。提示词的作用是缩小任务范围，验收仍以代码和数据为准。

保存并运行最小验证程序

下方程序把关键规则和验证用例放在同一个可复跑示例中，便于先理解输入如何变成输出，再用它检查 AI 给出的实现。

新建一个空目录，把下面代码保存为 check.py，在该目录打开终端，运行 python -X utf8 check.py。代码自带示例输入，不需要安装第三方库。

import json,threading
from http.server import HTTPServer,BaseHTTPRequestHandler
from urllib.request import urlopen
from urllib.error import HTTPError
class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        status=400 if self.path=='/bad-status' else 200
        body=b'not json' if self.path=='/bad-json' else b'{"result":"ok"}'
        self.send_response(status);self.send_header('Content-Length',str(len(body)));self.end_headers();self.wfile.write(body)
    def log_message(self,*args): pass
def request(url):
    try:
        with urlopen(url,timeout=2) as response:
            if response.status!=200: return 'http_error'
            return 'ok' if json.loads(response.read().decode('utf8'))=={'result':'ok'} else 'contract_error'
    except HTTPError: return 'http_error'
    except (json.JSONDecodeError,UnicodeDecodeError): return 'parse_error'
server=HTTPServer(('127.0.0.1',0),Handler)
thread=threading.Thread(target=server.serve_forever,daemon=True);thread.start()
try:
    base='http://127.0.0.1:'+str(server.server_port)
    results={path:request(base+path) for path in ['/ok','/bad-status','/bad-json']}
    assert results=={'/ok':'ok','/bad-status':'http_error','/bad-json':'parse_error'}
    print('local_results',results)
finally:
    server.shutdown();server.server_close();thread.join(timeout=2)

怎样判断结果符合要求

真实本地HTTP请求得到ok/http_error/parse_error三个类别。坏JSON即使状态200也不算成功。

下方是这份最小示例在本地执行得到的输出。它验证示例程序与断言的关系，不代表任何 AI 模型一次就能生成同样代码，也不构成性能或生产可靠性结论。

local_results {'/ok': 'ok', '/bad-status': 'http_error', '/bad-json': 'parse_error'}

示例只测三种确定响应，未模拟真实认证、限流、长响应、流中断和读超时。

客户端网络异常未在函数中吞掉，会继续抛错；需要业务统一异常映射时保持失败状态。

哪些失败必须停下来处理

http.server只用作本地桩，不能直接承载生产服务。

正式响应须限制读取字节数，错误体应脱敏，不向用户输出内部堆栈或凭据。

接入自己的任务前再核对一次

复用真实适配层跑同样三个桩用例，再追加超时、401/403/429和业务失败。

测试报告注明请求范围与断言，不能把本地桩通过写成在线服务验证通过。

资料与适用范围

HTTPServer和BaseHTTPRequestHandler能构建受控本地测试桩；http.server不推荐作生产服务器。以下链接核对于 2026-10-03；运行环境及额外依赖按本文前述说明。

• https://docs.python.org/3.11/library/http.server.html

相关基础可阅读 OpenAI API 集成怎么验收？认证、超时、重试与日志检查清单。本文的重点是区分HTTP失败与结构化解析失败，可以把两项检查作为不同步骤保留。