Agent调用外部服务时版本不兼容：API版本协商与适配器模式实践

一、问题起源：Agent调用外部服务时的版本兼容坑

做过智能对话、自动化任务类Agent开发的人，大概率都碰到过这样的糟心事：你写的Agent明明在测试环境跑的好好的，上线后调用第三方天气接口、物流查询接口时，要么直接报404找不到地址，要么返回的字段名全变了，甚至连返回格式都从JSON变成了XML。更坑的是，第三方服务方说“我们半年前就升级到v2版本了，v1早就下线了”，可你翻遍代码，全是调用v1接口的逻辑——这就是典型的Agent调用外部服务时的版本不兼容问题。

别觉得这是小概率事件，现在的Agent大多是“调用狂”：要查天气得调用气象服务，要订外卖得调用餐饮平台接口，要查快递得调用物流服务商API，这些外部服务的维护方往往会根据业务迭代、安全升级、性能优化等需求更新版本，而Agent作为调用方，很难做到和所有外部服务的版本更新同步，一旦外部服务下线旧版本，Agent直接就“罢工”了。

二、核心解法：API版本协商与适配器模式

要解决这个问题，得从两个层面入手：一是调用前先和外部服务“谈妥”用哪个版本（也就是API版本协商），二是不管外部服务版本怎么变，Agent的核心逻辑不用改（也就是用适配器模式做适配）。

2.1 API版本协商：调用前先“约好”版本

很多人以为API版本协商就是写死一个版本号，比如把接口地址写成https://api.weather.com/v1/get，但这其实是最笨的方法——一旦v1下线，你就得改所有调用v1的代码。真正的版本协商，是让Agent和外部服务通过某种规则，自动匹配双方都能接受的版本，不用人工改代码。

举个简单的例子，现在主流的外部服务一般会同时支持多个版本，比如v1、v2、v3，只是旧版本会逐步下线。这时候Agent可以在调用时，先发送一个版本协商请求，告诉外部服务“我能支持v1、v2版本，你现在能提供哪个？”，外部服务返回自己当前支持的版本列表，Agent再选一个双方都支持的最高版本（兼顾新功能和兼容性）。

为了更直观，我们用Python写一个版本协商的示例，先明确技术栈：Python 3.8+、requests库。

import requests

# 外部服务的版本协商地址，一般服务方会提供这样的地址
NEGOTIATE_URL = "https://api.weather.com/negotiate"

def negotiate_api_version(agent_supported_versions: list) -> str:
    """
    与外部服务协商可用的API版本
    :param agent_supported_versions: Agent能支持的版本列表，比如["v1", "v2"]
    :return: 双方都支持的最高版本号，协商失败返回None
    """
    try:
        # 发送协商请求，把Agent支持的版本传给外部服务
        response = requests.post(
            NEGOTIATE_URL,
            json={"agent_supported_versions": agent_supported_versions},
            timeout=5  # 超时时间，避免Agent卡住
        )
        # 检查请求是否成功
        response.raise_for_status()
        # 解析外部服务返回的支持版本列表
        service_supported_versions = response.json().get("service_supported_versions", [])
        
        # 取双方都支持的版本中最高的那个（按版本号排序）
        common_versions = list(set(agent_supported_versions) & set(service_supported_versions))
        if not common_versions:
            return None
        # 按版本号升序排序，取最后一个（最高版本）
        common_versions.sort(key=lambda x: int(x[1:]))  # 把v1转成1，方便排序
        return common_versions[-1]
    except Exception as e:
        print(f"版本协商失败：{str(e)}")
        return None

# 测试版本协商
if __name__ == "__main__":
    agent_versions = ["v1", "v2"]
    selected_version = negotiate_api_version(agent_versions)
    if selected_version:
        print(f"协商成功，使用版本：{selected_version}")
    else:
        print("协商失败，无兼容版本")

这个示例里，Agent先告诉外部服务自己能支持v1和v2，外部服务返回自己当前支持的版本（比如v2、v3），然后Agent取双方都有的v2作为最终调用版本——这样就算外部服务以后下线v1，Agent只要更新自己支持的版本列表（比如改成["v2", "v3"]），就能自动适配，不用改调用逻辑。

2.2 适配器模式：不管版本怎么变，Agent逻辑不用改

就算协商好了版本，还有个问题：不同版本的API，返回的字段名、格式可能不一样。比如v1的天气接口返回的是{"temp": 25, "city": "北京"}，v2可能改成{"temperature": 25, "city_name": "北京"}，甚至v3返回的是{"data": {"temp": 25, "city": "北京"}}——这时候如果Agent的核心逻辑是按v1的字段解析，换了v2就会报错。

适配器模式就是解决这个问题的：你可以把不同版本的API都适配成Agent能识别的“标准格式”，不管外部服务用哪个版本，Agent拿到的都是一样的内容，核心逻辑完全不用改。

还是用Python做示例，技术栈同上：Python 3.8+、requests库。

首先，我们定义一个“标准响应格式”，也就是Agent核心逻辑能识别的格式：

# 标准响应格式：Agent核心逻辑只认这个格式
class StandardWeatherResponse:
    def __init__(self, temperature: int, city: str):
        self.temperature = temperature  # 温度，单位：摄氏度
        self.city = city  # 城市名

    def to_dict(self):
        # 转成字典方便Agent处理
        return {"temperature": self.temperature, "city": self.city}

然后，我们写不同版本的适配器，每个适配器对应一个外部服务版本，负责把该版本的响应转成标准格式：

# 适配器基类：所有版本适配器都继承这个，统一接口
class WeatherAdapter:
    def adapt(self, raw_response: dict) -> StandardWeatherResponse:
        """
        把外部服务的原始响应转成标准格式
        :param raw_response: 外部服务返回的原始响应
        :return: 标准响应对象
        """
        raise NotImplementedError("子类必须实现adapt方法")

# v1版本适配器：适配v1的响应格式
class WeatherV1Adapter(WeatherAdapter):
    def adapt(self, raw_response: dict) -> StandardWeatherResponse:
        # v1响应格式：{"temp": 25, "city": "北京"}
        temp = raw_response.get("temp")
        city = raw_response.get("city")
        return StandardWeatherResponse(temperature=temp, city=city)

# v2版本适配器：适配v2的响应格式
class WeatherV2Adapter(WeatherAdapter):
    def adapt(self, raw_response: dict) -> StandardWeatherResponse:
        # v2响应格式：{"temperature": 25, "city_name": "北京"}
        temp = raw_response.get("temperature")
        city = raw_response.get("city_name")
        return StandardWeatherResponse(temperature=temp, city=city)

# v3版本适配器：适配v3的响应格式
class WeatherV3Adapter(WeatherAdapter):
    def adapt(self, raw_response: dict) -> StandardWeatherResponse:
        # v3响应格式：{"data": {"temp": 25, "city": "北京"}}
        data = raw_response.get("data", {})
        temp = data.get("temp")
        city = data.get("city")
        return StandardWeatherResponse(temperature=temp, city=city)

最后，我们写一个适配器工厂，根据协商好的版本号，自动选择对应的适配器：

# 适配器工厂：根据版本号返回对应的适配器
class WeatherAdapterFactory:
    @staticmethod
    def get_adapter(version: str) -> WeatherAdapter:
        """
        根据版本号返回对应的适配器
        :param version: 协商好的版本号，比如"v1"、"v2"
        :return: 对应的适配器实例
        """
        adapter_map = {
            "v1": WeatherV1Adapter(),
            "v2": WeatherV2Adapter(),
            "v3": WeatherV3Adapter()
        }
        return adapter_map.get(version)

现在，Agent的调用逻辑就可以写成这样，完全不用管外部服务的版本：

# Agent调用外部服务的核心逻辑
def get_weather(agent_supported_versions: list, city: str) -> dict:
    # 第一步：协商版本
    selected_version = negotiate_api_version(agent_supported_versions)
    if not selected_version:
        return {"error": "无兼容版本"}
    
    # 第二步：获取对应的适配器
    adapter = WeatherAdapterFactory.get_adapter(selected_version)
    if not adapter:
        return {"error": "无对应适配器"}
    
    # 第三步：调用对应版本的API
    api_url = f"https://api.weather.com/{selected_version}/get?city={city}"
    try:
        response = requests.get(api_url, timeout=5)
        response.raise_for_status()
        raw_response = response.json()
        
        # 第四步：用适配器转成标准格式
        standard_response = adapter.adapt(raw_response)
        return standard_response.to_dict()
    except Exception as e:
        return {"error": f"调用失败：{str(e)}"}

# 测试Agent调用
if __name__ == "__main__":
    agent_versions = ["v1", "v2", "v3"]
    result = get_weather(agent_versions, "北京")
    print(result)

你看，不管外部服务用v1、v2还是v3，Agent的核心逻辑（协商版本→拿适配器→调用API→转标准格式）都不用改，只要新增版本时加一个对应的适配器就行，完全不影响Agent的正常运行。

三、应用场景与技术优缺点

3.1 应用场景

这两个技术组合起来，几乎能覆盖所有Agent调用外部服务的场景： 一是多服务商对接场景：比如Agent要对接10家不同的物流服务商，每家的API版本迭代节奏都不一样，用版本协商可以自动适配每家的最新兼容版本，用适配器模式可以把每家的响应转成Agent能识别的格式； 二是长期运行的Agent场景：比如智能客服Agent、自动化运维Agent，这些Agent要连续运行几个月甚至几年，外部服务的版本迭代是必然的，用这两个技术可以避免频繁修改Agent代码； 三是多环境部署场景：比如Agent要部署在测试环境、预发环境、生产环境，不同环境用的外部服务版本可能不一样，用版本协商可以自动适配不同环境的版本。

3.2 技术优缺点

先说说优点： 一是兼容性强：不管外部服务怎么升级，只要加适配器、更新支持的版本列表，就能自动适配，不用改核心逻辑； 二是维护成本低：新增版本时只要加一个适配器，不用修改Agent的调用逻辑、解析逻辑，代码耦合度低； 三是灵活性高：可以根据需求选择协商规则（比如选最高版本、选最稳定版本），也可以自定义标准响应格式，适配不同的业务需求； 四是扩展性好：如果要新增一个外部服务，只要加对应的适配器和协商规则，就能快速对接。

再说说缺点： 一是增加了代码量：要写适配器、协商逻辑、工厂类，比直接写死版本的代码多了不少； 二是依赖外部服务的协商机制：如果外部服务不提供版本协商接口，那协商逻辑就得自己写（比如根据版本号的支持周期判断），或者直接用适配器适配多个版本； 三是有一定的学习成本：如果是刚入行的开发者，可能需要花点时间理解适配器模式的原理，以及版本协商的逻辑。

3.3 注意事项

用这两个技术的时候，有几个坑要注意： 一是版本协商的超时设置：一定要加超时时间，不然如果外部服务的协商接口挂了，Agent会一直卡住； 二是适配器的测试：每个适配器都要做单元测试，确保能正确转成标准格式，不然会出现“看起来适配了，其实返回的字段不对”的问题； 三是版本列表的更新：Agent支持的版本列表要定期更新，比如外部服务要下线v1了，就要把v1从Agent的支持列表里去掉，不然会协商到已经下线的版本； 四是异常处理：不管是协商还是调用API，都要加异常处理，比如网络错误、响应格式错误，都要返回友好的错误信息，不能让Agent直接崩溃。

四、文章总结

Agent调用外部服务时的版本不兼容问题，本质上是“调用方和服务方的版本迭代不同步”导致的，而API版本协商和适配器模式就是解决这个问题的“黄金组合”：版本协商解决了“用哪个版本”的问题，适配器模式解决了“不同版本怎么适配”的问题。

这两个技术不仅能解决版本不兼容的问题，还能降低Agent的维护成本，提高扩展性，适合各种规模的Agent开发。当然，在实际使用时，要根据自己的业务场景调整规则，比如如果外部服务不提供协商接口，就可以直接用适配器适配多个版本，或者自己做一个版本判断逻辑；如果Agent的业务需求比较简单，也可以简化协商规则，不用写太复杂的逻辑。

总之，只要掌握了这两个技术，就能轻松搞定Agent调用外部服务时的版本兼容问题，让Agent更稳定、更灵活。