模型概览

模型配置最常见的错误，是把“provider 名字”和“协议插件”混在一起。Agently 不按厂商硬编码请求路径，而是按协议层选择 requester 插件，再把 provider 的 base URL、model、api key 填进去。

先选协议，再填 provider recipe。

三个内置协议插件

Agent / ModelRequest
        |
        v
ModelRequester 插件
  |-- OpenAICompatible           Chat Completions 形态
  |-- OpenAIResponsesCompatible  Responses API 形态
  |-- AnthropicCompatible        Claude / Anthropic Messages 形态
        |
        v
provider HTTP endpoint

你在调用	用
OpenAI Chat Completions、Azure OpenAI、DeepSeek、Qwen、Kimi、GLM、MiniMax、Doubao、ERNIE、SiliconFlow、Groq	OpenAICompatible
Ollama、vLLM、LM Studio、llama.cpp server 等本地 OpenAI 兼容服务	OpenAICompatible
OpenAI Responses API 或说 Responses API 的私有网关	OpenAIResponsesCompatible
Anthropic / Claude 原生 Messages API	AnthropicCompatible
团队自建 OpenAI Chat Completions 兼容网关	OpenAICompatible
团队自建 Anthropic Messages 兼容网关	AnthropicCompatible

如果端点文档里写的是 messages: [{"role": ..., "content": ...}] 和 Chat Completions，一般走 OpenAICompatible。如果写的是 Anthropic Messages、anthropic-version、max_tokens 必填，走 AnthropicCompatible。

最小配置

from agently import Agently

Agently.set_settings("OpenAICompatible", {
    "base_url": "https://api.deepseek.com/v1",
    "api_key": "${ENV.DEEPSEEK_API_KEY}",
    "model": "${ENV.DEEPSEEK_MODEL}",
})

agent = Agently.create_agent()
result = (
    agent
    .input("把这段报错解释成中文。")
    .output({"answer": (str, "解释", True)})
    .get_result()
)
answer = await result.async_get_data(ensure_keys=["answer"])

${ENV.*} 是环境变量占位。这样密钥不进入代码，也便于开发、测试、生产使用不同配置。

Anthropic 配置长这样：

Agently.set_settings("AnthropicCompatible", {
    "base_url": "https://api.anthropic.com",
    "api_key": "${ENV.ANTHROPIC_API_KEY}",
    "model": "${ENV.ANTHROPIC_MODEL}",
    "max_tokens": 4096,
})

max_tokens 是 Claude 路径上需要特别关注的字段。完整字段见 AnthropicCompatible。

配置可以放在哪

范围	用法	适合
全局	Agently.set_settings(...)	应用默认模型
Agent	agent.set_settings(...)	某个 agent 固定使用更快或更强模型
请求	agent.create_request(...) 或请求链覆盖	单次任务临时切模型

全局配置让项目能跑起来。Agent 级配置适合角色固定的模型，比如“分类 agent 用小模型，写作 agent 用强模型”。请求级覆盖适合临时路由，不适合散落在业务代码里到处写默认配置。

多模型：用 model_pool 管别名

业务代码里最好使用有意义的模型别名，而不是到处写 provider 模型名。

agent = Agently.create_agent()
agent.set_settings("model_pool", {
    "fast-router": "qwen2.5:7b",
    "deep-reasoner": "deepseek-chat",
})
agent.set_settings("key_pool", {
    "local": "ollama",
    "deepseek-main": "${ENV.DEEPSEEK_API_KEY}",
    "deepseek-backup": "${ENV.DEEPSEEK_BACKUP_API_KEY}",
})
agent.set_settings("key_pool_strategy", {
    "qwen2.5:7b": {"mode": "fixed", "pool": ["local"]},
    "deepseek-chat": {"mode": "round_robin", "pool": ["deepseek-main", "deepseek-backup"]},
})

result = (
    agent
    .activate_model("deep-reasoner")
    .input("Summarize this incident.")
    .output({"summary": (str, "incident summary", True)})
    .get_result()
)
summary = await result.async_get_data(ensure_keys=["summary"])

activate_model(...) 影响这个 Agent 后续创建和持有的请求，包括链式 agent.input(...) 和 agent.create_execution()。只想覆盖单次请求时，用请求级配置。

key pool 的选择策略可以是 fixed、random、round_robin 或 least_used。provider 错误后的 failover 需要在 api_key_pools.<pool>.failover 显式开启；没有 failover 策略时，provider 错误会直接暴露。

选择模型时的工程判断

任务	常见选择
分类、路由、字段提取	小模型或本地模型，配结构化输出
起草、复杂推理、评审	更强模型，配清晰 schema 和校验
embedding	embedding 模型，作为 embedding agent 用于知识库
工具调用	确认 provider 的 tool calling 协议支持
流式 UI	确认该 provider 的流式格式能被插件解析

模型能力会随 provider 更新。官网 recipe 提供配置形状；具体可用模型名和价格，以 provider 当前文档和团队自己的验证为准。

读什么

• 要按厂商填配置：Providers
• 端点说 OpenAI Chat Completions：OpenAICompatible
• 端点说 Anthropic Messages：AnthropicCompatible
• 入门级配置说明：模型设置
• 环境变量、全局 / Agent / 请求级设置：设置层级