LiteAgents SDK：逐轮模型路由、安装与迁移指南

修复登录错误并不是一种单一工作。定位原因、编写防御性修改、检查测试、解释拉取请求，分别需要不同的能力。全过程都使用同一个大型模型可能浪费预算；全部交给最便宜的模型，也可能因为重试和人工修正而付出更高代价。

LiteAgents SDK 把模型选择纳入智能体运行过程。本文聚焦具体落地问题：什么叫“逐轮”，应该安装哪个包，怎样编写自定义路由，Jev 回退实际如何工作，以及从 Claude Agent SDK 迁移时哪些部分必须重新验证。

来源核查日期：2026年9月25日。涉及实现的结论对应 BerriAI/liteagents 提交 539a6e2。示例已与源码核对，但不是连接真实模型服务的性能测试，也不表示 Wavect 已为客户部署该 SDK。

LiteAgents SDK 是什么？它与 LiteLLM 有什么关系？

LiteAgents 是 BerriAI 的 Python SDK，让智能体通过熟悉的 query() 接口使用不同模型服务商。LiteLLM 产品页介绍的核心思路是：根据当前工作选择模型，而不是把整个智能体永久绑定到同一个模型。

发布说明以登录修复为例，安排 Claude Opus 4.8 规划、GPT-5.4 mini 编写实现和测试、Claude Sonnet 4.6 起草 PR 描述。应将其视为角色分工示例，而不是经过基准测试证明的模型排名，也不是“一个提示词必然触发这一精确顺序”的承诺。

本次审查的 SDK README描述了固定模型、自定义路由、Jev 分级选择、有状态客户端、MCP 工具适配器及独立的 fusion 模式。LiteLLM 提供底层模型访问层，LiteAgents 在其上管理对话和工具循环。

本文讨论的是这个具体 SDK 的集成。更广泛的基础设施选择可参阅 LLM 网关与路由器比较；决策模型本身则见 Jev 技术评测。这些是不同层次的架构决策，不应混为一谈。

LiteAgents 会在每次工具调用后切换模型吗？

本次审查的 Jev 路由器不会自动这样做。用户轮次与模型调用轮次不是同一个单位。客户端实现会在每次 agent.query(prompt) 调用时增加用户轮次计数，而一次查询内部可能包含多次模型调用和工具返回。

工具循环实现会在每一轮模型调用前询问路由器。但 Jev 路由器实现按 context.turn 缓存已选模型，同一用户轮次中的后续调用会复用该选择。自定义路由器可以检查当前历史并采用不同策略；内置 Jev 路径不会逐个重新分类工具结果。

还要区分保留的对话上下文与分类器实际收到的上下文。Jev 适配器发送当前提示词和各级描述，不发送完整对话历史。因此，“继续做下一部分”给分类器的信息少于一段完整、可独立理解的任务描述。建议每个客户端创建自己的路由器，不要未经验证就在独立会话间共享按轮次编号缓存的实例。

怎样安装正确的 LiteAgents 包？

复制安装命令之前，先核对仓库身份。审查的 BerriAI 包元数据声明 Python 3.10 及以上和版本 0.1.0。核查当天，PyPI 上名为 liteagents 的公开条目却显示另一个项目，版本 0.0.2，发布于2025年1月。名称相同不代表软件相同。

为明确对应本次源码审查，可以使用干净环境并直接指定仓库提交。以下命令需要 Git 和 POSIX 风格的 shell。固定提交只能确定安装的是哪份代码，不能证明代码或依赖已经通过安全审计。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install \
  "liteagents @ git+https://github.com/BerriAI/liteagents.git@539a6e2a9669433ffa9034ae262718e30c4f80b6"
python -c "from liteagents import LiteAgentOptions, LiteAgentClient; print('SDK imports OK')"

pip 的 VCS 安装文档说明了如何使用完整提交哈希的直接引用。正式采用时应重新核对厂商发布渠道，并锁定、审查传递依赖。不要直接沿用已经装有同名其他项目的生产环境。

遇到 ImportError: cannot import name 'LiteAgentOptions'，先检查 python -m pip show liteagents、当前 Python 解释器，以及本地 liteagents.py 是否遮蔽了真正的包。导入失败不等于模型服务商的 API 密钥错误。

不使用 Jev，怎样实现模型路由？

实现异步 route(context) 方法，返回获准使用的模型标识即可。如果应用本身知道当前工作阶段，就不需要额外分类服务。这也是引入概率路由前很有价值的比较基线。

把 LITEAGENTS_REASONING_MODEL、LITEAGENTS_FAST_MODEL 和 LITEAGENTS_BALANCED_MODEL 设置为账户可用、包含服务商前缀的模型标识，并分别配置各服务商凭据。这些标签描述应用角色，不是对模型能力的保证。

下面是完整 Python 示例，在三个显式轮次间保留同一个对话。它只生成文本草稿，没有连接仓库、shell、测试执行器或 GitHub 发布工具。超时和输出限制约束单次请求；生产任务仍然需要总期限和总费用上限。

import asyncio
import os
from dataclasses import dataclass

from liteagents import (
    AssistantMessage, LiteAgentClient, LiteAgentOptions,
    TextBlock, TurnContext,
)


def required(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise RuntimeError(f"Set {name} to an approved provider/model ID")
    return value


@dataclass(frozen=True)
class StageRouter:
    models: tuple[str, ...]

    async def route(self, context: TurnContext) -> str:
        index = context.turn - 1
        if not 0 <= index < len(self.models):
            raise RuntimeError("No approved model for this workflow stage")
        return self.models[index]


async def main() -> None:
    router = StageRouter(models=(
        required("LITEAGENTS_REASONING_MODEL"),
        required("LITEAGENTS_FAST_MODEL"),
        required("LITEAGENTS_BALANCED_MODEL"),
    ))
    options = LiteAgentOptions(
        model_router=router,
        system="Draft suggestions only. Never claim a tool or test was run.",
        max_tokens=1200,
        max_turns=4,
        model_kwargs={"timeout": 45, "num_retries": 0},
    )
    prompts = (
        "A login handler calls password.strip() before checking for None. "
        "Explain the failure and propose a defensive fix.",
        "Draft unit-test cases for that fix. Do not execute anything.",
        "Draft a PR description. Separate proposed changes from verified results.",
    )
    async with LiteAgentClient(options=options) as agent:
        for prompt in prompts:
            last = None
            async for event in agent.query(prompt):
                if isinstance(event, AssistantMessage):
                    last = event
                    print(f"model={event.model} stop={event.stop_reason}")
                    for block in event.content:
                        if isinstance(block, TextBlock):
                            print(block.text)
            if last is None or last.stop_reason not in {
                "end_turn", "stop", "stop_sequence",
            }:
                raise RuntimeError("Incomplete stage; do not continue automatically")


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

路由器和客户端 API 遵循 SDK 自定义路由接口。这个确定性示例会在出现意外的第四阶段时明确失败，而不是默默选一个模型；遇到不完整响应也不会自动继续。独立任务应使用独立客户端，不要在同一有状态客户端上并发执行查询。

Jev 自动路由怎样选择模型级别？

JevAgent 是便捷封装；需要组合其他选项时，可以在 LiteAgentOptions 中使用 JevModelRouter。开发者定义候选级别和回退模型。本次审查的适配器使用级别名称与描述进行分类，请求中没有实时模型价格或实测质量分数。因此，“最合适”是设计目标，不是全局成本最优的证明。

以下片段展示配置结构，不表示真实 Jev 集成已经验证。它显式读取 TYPESAFE_API_KEY，让缺失配置在初始化时直接暴露，避免无声进入回退路径。

import os
from liteagents import JevModelRouter, JevTier, LiteAgentOptions

router = JevModelRouter(
    tiers=(
        JevTier(name="FAST", model=os.environ["LITEAGENTS_FAST_MODEL"],
                description="Bounded edits and test-case drafting"),
        JevTier(name="BALANCED", model=os.environ["LITEAGENTS_BALANCED_MODEL"],
                description="Routine implementation and explanations"),
        JevTier(name="REASONING", model=os.environ["LITEAGENTS_REASONING_MODEL"],
                description="Ambiguous diagnosis and architecture"),
    ),
    fallback_model=os.environ["LITEAGENTS_REASONING_MODEL"],
    api_key=os.environ["TYPESAFE_API_KEY"],
    timeout=5.0,
)
options = LiteAgentOptions(model_router=router, max_tokens=1200, max_turns=4)

依赖这条路径之前，先验证端点契约。审查的适配器请求 /v1/classify，并将该 HTTP 契约注明为示意性、尽力适配的实现。TypeSafe 公开模型文档则记录 POST /v1/systemone。这项差异需要真实兼容性测试或适配器修正，不能直接推断某个未公开端点绝对不存在。

在完成验证前，可以使用上面的确定性路由器，或使用自行维护、已按正式 API 测试的适配器。不要为内置适配器编造置信度阈值：它只消费一个级别名称，并未暴露分类器的概率分布。

为什么 LiteAgents 总是选择 fallback_model？

收到完整回答，不代表自动路由成功。在本次审查的 Jev 实现中，缺少密钥、被处理的 HTTP 错误、无效 JSON 或未知级别，都可能触发 fallback_model。应用看起来仍能回答，但预期的路由节省可能已经消失。

检查凭据、端点兼容性、响应结构和级别名称。应通过可观测的适配器记录：路线来自正常分类、固定策略，还是错误后的回退。同时记录请求路线、AssistantMessage.model 和使用量。同一个模型既可能是正常选择，也可能是回退结果，仅看模型名称无法区分。

不要把 fallback 当作对所有异常的兜底。例如，审查代码期望包含 tier 字段的 JSON，对意外的顶层类型也应测试。分类器回退也不等于服务商故障转移：模型选定后，凭据、限流或生成请求仍然可能失败。LiteLLM 将服务商故障转移单独记录。

回退模型必须遵守同样的服务商与数据范围限制。“改用安全模型”不是授权决定，不能绕过地区、租户或保密约束。

LiteAgents 能直接替换 Claude Agent SDK 吗？

接口相似，不代表运行环境等价。修改导入语句可能很容易，但工具、权限、持久化和执行假设需要分别验证。Anthropic 的 Agent SDK 概览描述了基于 Claude Code 的运行环境，以及内置工具、权限、会话和钩子。

审查的 LiteAgents 配置和客户端界定了本地 API 边界，MCP 文档则明确把传输、认证与会话生命周期交给应用。适配器不是权限系统。智能体使用工具期间，要保持初始化后的 MCP 会话开放，并只暴露明确允许的工具列表。

LiteLLM 网关可以在智能体下层处理部署选择和可靠性。LiteLLM Router 文档说明了这层基础设施。安装智能体 SDK 不等于自动部署网关，也不等于已经启用全公司的费用控制。

“修复登录错误、增加测试并创建 PR”应该怎样运行？

应把阶段明确拆开。先借助可复现示例和只读仓库访问定位问题；再由实现阶段在隔离分支中生成范围受限的补丁；独立测试工具执行真实检查并返回退出码和输出；审查阶段评估变更及证据后，再由发布工具创建草稿 PR。

路由策略可以让推理模型负责诊断、较小模型处理狭窄修改、均衡模型解释结果。但这种分配只是需要验证的假设，不是普遍适用的处方。身份认证缺陷即使只涉及几行代码，也可能具有安全影响。

执行证据应独立于模型生成的描述。把提交标识、修改文件、测试命令、退出码和 PR 标识保存为工具结果。没有测试工具的模型说“测试通过”，不能作为验收证据。创建 PR 的权限应与合并和部署审批分开。

真实实现应使用新的工作目录、权限受限的仓库令牌、写路径限制和 PR 创建幂等键。这些是建议的应用控制，不是前述纯文本示例已经展示的功能。

Fusion 与模型路由有什么不同？

路由选择哪个模型处理某次调用；fusion 则让主智能体把子任务委派给拥有独立对话历史的辅助智能体。SDK 的 fusion 文档说明了通过 FusionOptions 配置辅助模型的方法。独立历史可以支持不同工作流，但本身不是成本下降的证明。

应将 fusion 与顺序切换分别测试，计算两边的输入输出、等待时间、重复调查及验证成本。客户端保留的历史也不是跨服务商可携带的缓存：新的服务商可以收到同一段对话，却不一定继承原服务商缓存的 token。应测量真实缓存命中，而不是假设交接免费。

对话增长可能抵消小模型的节省。使用与任务有关的证据和显式摘要，同时保留复现错误需要的信息。跨服务商路由也扩大了可能接收提示词或代码的系统范围，启用某一级别前应批准对应的数据流。

逐轮模型路由真的能降低智能体成本吗？

只有在达到要求的质量和延迟下，通过验收的工作变得更便宜，才算有效。单条回答价格下降还不够。评估窗口应纳入分类、生成、重试、工具、基础设施以及可归属的人工修正成本。

每项验收任务成本 = 所有尝试的可归属总成本 / 通过验收的任务数量

在这个虚构例子中，总支出下降25%，但每项验收任务成本上升20%，而且留下了更多未完成工作。选择正确的分母，会改变决策。

用同一组留出的评估任务比较四种方案：当前固定模型、更便宜的固定模型、确定性阶段路由和自动路由。保持工具、验收标准与最高预算一致，报告完成质量、修正时间、回退频率及端到端 p50/p95 延迟，而不只比较平均 token 价格。更完整的核算方法见 智能体单次行动成本指南。

LiteAgents 试点上线前需要证明什么？

从可撤销的任务和少量获准模型开始。先运行观察模式：记录路由器建议的选择，但仍让已知基线完成任务；随后在隔离副本上测试真实路由执行。这样可以验证路由，而不会让第一轮实验直接变成修改生产环境的授权。

尤其注意 max_turns。在 审查的工具循环中，工具使用期间达到上限不会自动生成最终答案。应跟踪最后一条助手消息，将 stop_reason="tool_use" 视为未完成。返回了消息流，不等于产生了合格的业务结果。

什么情况下值得评估 LiteAgents？

如果应用需要服务商灵活性，而且不同任务确实需要不同模型能力，LiteAgents 值得试验。如果一个便宜的固定模型已经满足需求，或者迁移会移除现有关键控制却没有替代方案，它的价值就没有那么明显。

合理路径应当渐进：确认包来源，复现固定模型行为，引入明确的阶段路由，再在接口和经济性都通过检查后加入自动分类。不要把吸引人的路由演示动画当成生产验收测试。

需要实施支持时，Wavect 的 AI 工程服务可覆盖应用集成与评估。Twinsoft AI 案例提供相关交付背景，不是 LiteAgents 部署证明。可以用 上线前 QA 检查清单定义验收门槛，或围绕真实工作流及当前基线 讨论模型路由试点。