05. nanobot 源码解读:LLM API 调用

05. nanobot 源码解读：LLM API 调用

文档内容基于 HKUDS/nanobot: "🐈 nanobot: The Ultra-Lightweight Personal AI Agent" 的 main 分支 3c20d16 提交进行说明。

nanobot 作为超轻量级个人 AI Agent 框架，其 Agent Loop 的核心能力依赖于 LLM API 调用。自出现 litellm 供应链投毒攻击事件后，许多框架都倾向于自行实现 LLM API 调用逻辑，而不是依赖第三方库以降低安全风险。nanobot 也不例外，它自行封装了一套 LLM API 调用机制。

LLM API 规范

一般讨论意义上的 LLM API 规范主要有以下几种：

OpenAI Chat API（chat/completions）

当前业界的事实标准，大多数模型提供商都会兼容这种格式。以 DeepSeek 为例：

OpenAI Responses API

对比 OpenAI Chat API 主要有以下区别：

1. 带状态：入参如果提供 previous_response_id，后续对话则只需要提供增量消息，而不是像 OpenAI Chat API 一样每次调用接口都要拼接历史消息
2. 内置工具：如果大模型认为需要调用工具且工具是 OpenAI Responses API 内置的，则在大模型服务端完成工具调用

Anthropic Messages API

URL、鉴权、请求结构、响应结构都与 OpenAI Chat API 存在差异。模型厂商也可能会兼容这种格式，如 DeepSeek：

关键要点：不同的 LLM API 规范在参数格式、鉴权方式、响应结构等方面存在显著差异，nanobot 需要提供统一的抽象来处理这些差异。

LLM API 调用抽象

nanobot 使用了 Provider 来抽象 LLM API 调用逻辑（相关源码位于 nanobot/providers/ 包）。

Provider，即 LLM 服务提供商。

nanobot 在配置文件 config.json 有两个设置：

• 配置 provider
• 为 agent.defaults 指定 model + provider

这里的 provider 配置对应了 LLM API 调用逻辑。

nanobot 会根据 provider 配置匹配到内部的 ProviderSpec。

nanobot/providers/registry.py 文件中预定义了许多 ProviderSpec。这些 ProviderSpec 在 nanobot 启动时被加载到内存，读取 config.json 后再进行 provider 匹配操作。

下面是预定义的 zhipu（智谱）provider：

    # Zhipu (智谱): OpenAI-compatible at open.bigmodel.cn    ProviderSpec(        name="zhipu",        keywords=("zhipu", "glm", "zai"),        env_key="ZAI_API_KEY",        display_name="Zhipu AI",        backend="openai_compat",        env_extras=(("ZHIPUAI_API_KEY", "{api_key}"),),        default_api_base="https://open.bigmodel.cn/api/paas/v4",    ),

关键字段说明：

• env_key: env_key 对应的环境变量值会被设置成 api_key
• backend: backend 对应 nanobot 内部的 LLMProvider 实现类，此处的 openai_compat 是兼容 * OpenAI Chat API* 规范的实现
• env_extras: env_extras 是一个 key-value 列表，表示 key 对应的环境变量要被设置成 value (占位符会替换为具体值)
• default_api_base：没有在 config.json 对应 provider 显示指定 api_base 时，就会使用这个默认值

匹配到 ProviderSpec 后，会根据 backend 字段决定使用 LLMProvider 抽象类的具体实现类，然后用其它字段辅助创建 LLMProvider 实例。

LLMProvider 抽象类

nanobot/providers/base.py 中定义了抽象类 LLMProvider承载LLM API 调用逻辑。该类定义了两个抽象方法：

• chat：LLM API 调用流程，包括参数构造、接口调用、结果解析等步骤，返回类型是 nanobot 设计的 LLMResponse
• get_default_model：获取默认模型名称

class LLMProvider(ABC):    # 其它代码略    @abstractmethod    async def chat(        self,        messages: list[dict[str, Any]],        tools: list[dict[str, Any]] | None = None,        model: str | None = None,        max_tokens: int = 4096,        temperature: float = 0.7,        reasoning_effort: str | None = None,        tool_choice: str | dict[str, Any] | None = None,) -> LLMResponse:        """        Send a chat completion request.        Args:            messages: List of message dicts with 'role' and 'content'.            tools: Optional list of tool definitions.            model: Model identifier (provider-specific).            max_tokens: Maximum tokens in response.            temperature: Sampling temperature.            tool_choice: Tool selection strategy ("auto", "required", or specific tool dict).        Returns:            LLMResponse with content and/or tool calls.        """        pass    @abstractmethod    def get_default_model(self) -> str:        """Get the default model for this provider."""        pass

LLMProvider 实现类说明：

不同的 LLM API 调用流程，就需要实现一个专门的 LLMProvider 子类。nanobot 提供了五种实现：

实现类	源码文件	支持的 API	特点
`AnthropicProvider`	`anthropic_provider.py`	Anthropic Messages API	完整支持 Claude 思考模式、prompt caching
`AzureOpenAIProvider`	`azure_openai_provider.py`	OpenAI Responses API	Azure 特有的 URL 规范
`OpenAICodexProvider`	`openai_codex_provider.py`	OpenAI Responses API	使用 OAuth 鉴权
`OpenAICompatProvider`	`openai_compat_provider.py`	OpenAI Chat API / Responses API	满足特定条件优先使用 Responses API，失败时降级到 Chat API
`GitHubCopilotProvider`	`github_copilot_provider.py`	OpenAI Chat API / Responses API	继承 OpenAICompatProvider，使用 GitHub OAuth 鉴权

下面以 AnthropicProvider 和 OpenAICompatProvider 为例，详细说明不同 API 规范的实现细节。

AnthropicProvider 实现

直接查看抽象方法 chat 的实现：

    async def chat(        self,        messages: list[dict[str, Any]],        tools: list[dict[str, Any]] | None = None,        model: str | None = None,        max_tokens: int = 4096,        temperature: float = 0.7,        reasoning_effort: str | None = None,        tool_choice: str | dict[str, Any] | None = None,) -> LLMResponse:        # 构造符合 Anthropic Messages API 规范的参数        kwargs = self._build_kwargs(            messages, tools, model, max_tokens, temperature,            reasoning_effort, tool_choice,        )        try:            # self._client 是 AsyncAnthropic 实例，直接通过 Anthropic 官方库调用接口            response = await self._client.messages.create(**kwargs)            return self._parse_response(response)        except Exception as e:            return self._handle_error(e)

实现要点：

1. 使用 Anthropic 官方 Python 库（AsyncAnthropic）进行 API 调用
2. 通过 _build_kwargs 方法构造符合 Anthropic Messages API 规范的参数
3. 异常处理通过 _handle_error 方法统一处理

参数构造细节

    def _build_kwargs(        self,        messages: list[dict[str, Any]],        tools: list[dict[str, Any]] | None,        model: str | None,        max_tokens: int,        temperature: float,        reasoning_effort: str | None,        tool_choice: str | dict[str, Any] | None,        supports_caching: bool = True,) -> dict[str, Any]:        model_name = self._strip_prefix(model or self.default_model)        # Anthropic Messages API 的 system prompt 是独立于 messages 字段        system, anthropic_msgs = self._convert_messages(self._sanitize_empty_content(messages))        # tools 参数需要调整成符合规范的 json 格式        anthropic_tools = self._convert_tools(tools)        if supports_caching:            # prompt caching 功能：给 messages 和 tools 参数加上 cache_control 字段            system, anthropic_msgs, anthropic_tools = self._apply_cache_control(                system, anthropic_msgs, anthropic_tools,            )        max_tokens = max(1, max_tokens)        thinking_enabled = bool(reasoning_effort) and reasoning_effort.lower() != "none"        # claude-opus-4-7 完全废弃了 `temperature` 参数，若传该参数会报错        omit_temperature = "opus-4-7" in model_name        kwargs: dict[str, Any] = {            "model": model_name,            "messages": anthropic_msgs,            "max_tokens": max_tokens,        }        if system:            kwargs["system"] = system        if reasoning_effort == "adaptive":            # Adaptive thinking：模型自主决定何时以及如何思考            # 支持 claude-sonnet-4-6 和 claude-opus-4-6            # 同时自动启用工具调用之间的交错思考            kwargs["thinking"] = {"type": "adaptive"}            if not omit_temperature:                kwargs["temperature"] = 1.0        elif thinking_enabled:            budget_map = {"low": 1024, "medium": 4096, "high": max(8192, max_tokens)}            budget = budget_map.get(reasoning_effort.lower(), 4096)            kwargs["thinking"] = {"type": "enabled", "budget_tokens": budget}            kwargs["max_tokens"] = max(max_tokens, budget + 4096)            if not omit_temperature:                kwargs["temperature"] = 1.0        elif not omit_temperature:            kwargs["temperature"] = temperature        if anthropic_tools:            kwargs["tools"] = anthropic_tools            tc = self._convert_tool_choice(tool_choice, thinking_enabled)            if tc:                kwargs["tool_choice"] = tc        if self.extra_headers:            kwargs["extra_headers"] = self.extra_headers        return kwargs

参数构造关键点：

1. System Prompt 分离：Anthropic Messages API 的 system prompt 是独立于 messages 字段的，需要通过 _convert_messages 提取
2. Prompt Caching：支持 prompt caching 功能，给 messages 和 tools 参数加上 cache_control 字段
3. 思考模式支持：

• reasoning_effort == "adaptive"：Adaptive thinking，模型自主决定思考程度
• reasoning_effort 为 low/medium/high：启用 thinking 并设置 budget_tokens
• reasoning_effort 为 None 或 "none"：不启用思考

4. 温度参数兼容：claude-opus-4-7 废弃了 temperature 参数，需要特殊处理
5. Tool 转换：通过 _convert_tools 和 _convert_tool_choice 转换工具相关参数

OpenAICompatProvider 实现

OpenAICompatProvider 是一个更复杂的实现，它同时支持 OpenAI Chat API 和 OpenAI Responses API，还要针对各模型服务提供商的 API 进行额外处理。

直接查看 chat 方法实现：

    async def chat(        self,        messages: list[dict[str, Any]],        tools: list[dict[str, Any]] | None = None,        model: str | None = None,        max_tokens: int = 4096,        temperature: float = 0.7,        reasoning_effort: str | None = None,        tool_choice: str | dict[str, Any] | None = None,) -> LLMResponse:        try:            # 判断是否需要使用 OpenAI Responses API            if self._should_use_responses_api(model, reasoning_effort):                try:                    # 构造符合 OpenAI Responses API 规范的参数                    body = self._build_responses_body(                        messages, tools, model, max_tokens, temperature,                        reasoning_effort, tool_choice,                    )                    # self._client 是 AsyncOpenAI 实例，使用 OpenAI 官方库调用 Responses API                    result = parse_response_output(await self._client.responses.create(**body))                    self._record_responses_success(model, reasoning_effort)                    return result                except Exception as responses_error:                    if self._spec and self._spec.name == "github_copilot":                        # Copilot 网关仅通过 /responses 暴露 GPT-5/o-series                        # 降级到 /chat/completions 无法成功，会隐藏真实错误                        raise                    if not self._should_fallback_from_responses_error(responses_error):                        raise                    self._record_responses_failure(model, reasoning_effort)            # 构造符合 OpenAI Chat API 规范的参数            kwargs = self._build_kwargs(                messages, tools, model, max_tokens, temperature,                reasoning_effort, tool_choice,            )            # self._client 是 AsyncOpenAI 实例，使用 OpenAI 官方库调用 Chat API            return self._parse(await self._client.chat.completions.create(**kwargs))        except Exception as e:            return self._handle_error(e, spec=self._spec, api_base=self.api_base)