LLM 供应商

AgenticX 通过 BaseLLMProvider 实现路由对话与工具调用。国内主流云 API 有一方适配器；其余后端可经 LiteLLMProvider 接入（OpenAI 兼容端点或 LiteLLM 模型 ID）。

支持的供应商

ProviderResolver.PROVIDER_MAP 将配置键 openai、anthropic、ollama、zhipu、volcengine / ark、bailian、qianfan、kimi、minimax 映射到上表中的类。

用法示例

OpenAI

1from agenticx.llms import OpenAIProvider
2
3llm = OpenAIProvider(
4    model="gpt-4o",
5    api_key="sk-...",  # or rely on env / config
6)
7resp = llm.invoke("Summarize this in one line.")

Anthropic

1from agenticx.llms import AnthropicProvider
2
3llm = AnthropicProvider(
4    model="anthropic/claude-sonnet-4-20250514",
5    api_key="sk-ant-...",
6)
7resp = llm.invoke([{"role": "user", "content": "Hello"}])

Ollama（本地）

1from agenticx.llms import OllamaProvider
2
3llm = OllamaProvider(
4    model="ollama/qwen2.5:7b",
5    base_url="http://127.0.0.1:11434",
6)
7resp = llm.invoke("Ping")

MiniMax

1from agenticx.llms import MinimaxProvider
2
3llm = MinimaxProvider(
4    model="MiniMax-M2.5",
5    api_key="...",
6    # base_url defaults to https://api.minimax.chat/v1
7)
8resp = llm.invoke("Reply with OK.")

LiteLLM

1from agenticx.llms import LiteLLMProvider
2
3# Example: third-party OpenAI-compatible endpoint (e.g. SiliconFlow)
4llm = LiteLLMProvider(
5    model="openai/Qwen/Qwen2.5-7B-Instruct",
6    api_key="...",
7    base_url="https://api.siliconflow.cn/v1",
8)
9resp = llm.invoke("Hello")

鉴权配置轮换

AuthProfileManager（agenticx.llms.auth_profile）为同一供应商轮换多个 API 密钥（或逻辑 profile），并将冷却元数据持久化到 JSON 文件（先写 .tmp 再原子替换）。

• `get_current()` — 选取下一个可用 profile（优先可用项，按 last_used 排序；冷却中的 profile 按 cooldown_until 排队）。
• `mark_success(profile_name)` — 清除该 profile 的错误状态与冷却时间戳。
• `mark_failure(profile_name, failure_type)` — 递增 error_count、设置 failure_type，并对 cooldown_until 应用指数退避。
• `classify_failure(exc)` — 根据异常消息启发式映射为 billing、auth、rate_limit 或 other。

退避策略（在 _compute_cooldown_ms 中实现）：

BaseLLMProvider.invoke_with_profile(messages, api_key=...) 会转发到 invoke(..., api_key=api_key)，调用方可在不替换 provider 实例的情况下注入轮换后的密钥。

!!! tip

若需进程重启后仍保留冷却状态，请传入 persistence_path=Path("~/.agenticx/auth_profiles.json").expanduser()。

故障转移路由

`FailoverProvider` 包装两个 provider：主路与备路。对 invoke、ainvoke、stream、astream 和 stream_with_tools，除非主路处于冷却期，否则优先尝试主路。

• `failure_threshold`（默认 3）— 主路连续失败多少次后进入冷却。
• `cooldown_duration`（默认 60 秒）— 达到阈值后主路被旁路的时间窗口。
• 主路调用成功会重置失败计数并清除冷却。

1from agenticx.llms import FailoverProvider, OpenAIProvider, AnthropicProvider
2
3llm = FailoverProvider(
4    primary=OpenAIProvider(model="gpt-4o", api_key="..."),
5    fallback=AnthropicProvider(model="anthropic/claude-sonnet-4-20250514", api_key="..."),
6    failure_threshold=3,
7    cooldown_duration=120.0,
8)

响应缓存

`ResponseCache` 是内存存储，以 prompt 字符串的 SHA-256（截断）为键。条目带 TTL（`ttl_seconds`，默认 `300`）并采用 LRU 淘汰（`max_entries`，默认 `100`）。它不会自动接入 LiteLLMProvider；开发循环中需要降本时可自行包装调用。

1from agenticx.llms import OpenAIProvider, ResponseCache
2
3llm = OpenAIProvider(model="gpt-4o-mini", api_key="...")
4cache = ResponseCache(ttl_seconds=300, max_entries=100)
5
6def cached_invoke(text: str):
7    hit = cache.get(text)
8    if hit is not None:
9        return hit
10    out = llm.invoke(text)
11    cache.put(text, out)
12    return out

stats() 返回命中、未命中、条目数与命中率。

对话清洗器

模型调用前，`agent_runtime` 会对聊天历史执行 `_sanitize_context_messages`。该流水线在更广意义上是 provider 感知的：它强制合法的 assistant / tool 消息链，避免上游 API 看到孤立的 tool 行或未闭合的 tool_calls。

行为（简化）：

• `tool` 消息 仅在前序 assistant tool_calls 列表中存在对应 tool_call_id，且连续 tool 响应已全部满足时保留。
• 带 `tool_calls` 的 assistant 消息 仅当历史中每个 call id 都有匹配的 tool 响应时保留；否则剥离 tool_calls 并保留文本内容。

这可减少编辑、重试或部分持久化后工具环断裂导致的 provider 400 错误。

视觉与图片输入

当后端与模型支持多模态时，框架会传递相应内容。按厂商约束，MiniMax M2 对话系列（含 M2、M2.1、M2.5、M2.7 及 `*-highspeed` SKU；不含 id 中带 `vl` / `vision` 的型号）不接受图片或音频输入。

Studio 会在 completion 请求前为这些模型剥离 image_inputs。若附件必须送达 LLM，请选用支持视觉的模型。

!!! warning "MiniMax M2 与附件"

使用 minimax-m2* ID 时不要假设模型能看到图片。框架会为该系列移除图片载荷，除非切换模型，否则应将该轮视为纯文本。

供应商配置（环境变量）

下表为 AgenticX 配置加载器通常与 ~/.agenticx/config.yaml 中 providers.<name> 配对使用的变量。LiteLLM 还可能根据模型 id 读取额外变量。

Ollama 通常在 YAML 中配置 base_url（例如 http://localhost:11434）；本地推理无需密钥。

!!! tip

若希望使用合并后的文件配置而非手动构造，可一行调用 ProviderResolver.resolve() 解析 provider。