模型设置

模型配置最好一开始就从代码里分离出来。原型阶段把 base_url、api_key、model 写死在脚本里很快；到了服务、多人协作和 release 以后，它会变成最容易出错的地方。

Agently 的模型设置按 provider 协议层组织。先选协议层，再填对应设置。

先选 provider 协议层

Provider 插件	适合
OpenAICompatible	OpenAI Chat Completions 兼容端点：OpenAI、DeepSeek、Qwen、Ollama、Kimi、GLM、MiniMax、Doubao、SiliconFlow、Groq、ERNIE、Gemini-via-OpenAI 等
OpenAIResponsesCompatible	OpenAI Responses API 形态
AnthropicCompatible	Anthropic 原生 Messages API / Claude

多数服务商如果文档写着“OpenAI compatible”，就先从 OpenAICompatible 开始。

最小配置

OpenAI-compatible：

from agently import Agently

Agently.set_settings("OpenAICompatible", {
    "base_url": "https://api.openai.com/v1",
    "api_key": "${ENV.OPENAI_API_KEY}",
    "model": "${ENV.OPENAI_MODEL}",
})

DeepSeek：

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

Ollama：

Agently.set_settings("OpenAICompatible", {
    "base_url": "http://127.0.0.1:11434/v1",
    "model": "qwen2.5:7b",
})

本地服务不需要鉴权时可以省略 api_key。

Anthropic / Claude：

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

Claude 使用独立 requester 插件。它的请求体不是 OpenAI-compatible 形态，常见配置还包括 anthropic_version、anthropic_beta 和必填的 max_tokens。

全局设置和 Agent 级覆盖

Agently.set_settings(...) 设置全局默认。agent.set_settings(...) 只覆盖某个 agent。

Agently.set_settings("OpenAICompatible", {
    "base_url": "http://127.0.0.1:11434/v1",
    "model": "qwen2.5:7b",
})

agent = Agently.create_agent()

agent.set_settings("OpenAICompatible", {
    "model": "qwen2.5:14b",
})

这个 agent 只覆盖 model，没有覆盖的 base_url 继续沿用全局设置。更完整的分层规则见 设置。

环境变量和 .env

设置里可以写 ${ENV.NAME}。Agently 读取设置时会替换为对应环境变量：

Agently.set_settings("OpenAICompatible", {
    "base_url": "${ENV.OPENAI_BASE_URL}",
    "api_key": "${ENV.OPENAI_API_KEY}",
    "model": "${ENV.OPENAI_MODEL}",
})

项目里建议把设置放进 settings.yaml，启动时加载：

from agently import Agently

Agently.load_settings("yaml_file", "settings.yaml", auto_load_env=True)

auto_load_env=True 会先加载工作目录下的 .env，再解析 ${ENV.*}。

Typed settings 什么时候用

dict 是长期兼容写法。需要编辑器提示和提前校验时，可以使用 typed helper：

from agently import Agently
from agently.types.settings import OpenAICompatibleSettings

Agently.set_settings(
    OpenAICompatibleSettings(
        base_url="https://api.deepseek.com/v1",
        api_key="${ENV.DEEPSEEK_API_KEY}",
        model="deepseek-chat",
        request_options={"temperature": 0},
    )
)

typed helper 只负责构造和校验，进入 Agently 后仍然存成同一个 provider namespace 下的 dict。配置文件、生成式配置和 YAML/TOML/JSON 仍建议用 dict。

多模型路由和 key pool

团队里常见的情况是：客服聊天用一个模型，复杂推理用另一个模型，同一 provider 还要轮换多个 API key。

这时用三层配置：

Agently.set_settings("model_pool", {
    "support-chat": "deepseek-chat-prod",
    "reasoning": "deepseek-reason-prod",
})

Agently.set_settings("model_profiles", {
    "deepseek-chat-prod": {
        "provider": "OpenAICompatible",
        "base_url": "https://api.deepseek.com/v1",
        "model": "deepseek-chat",
        "api_key_pool": "deepseek-prod",
    },
    "deepseek-reason-prod": {
        "provider": "OpenAICompatible",
        "base_url": "https://api.deepseek.com/v1",
        "model": "deepseek-reasoner",
        "api_key_pool": "deepseek-prod",
        "request_options": {"temperature": 0},
    },
})

Agently.set_settings("api_key_pools", {
    "deepseek-prod": {
        "selection": {"strategy": "round_robin"},
        "failover": {
            "strategy": "try_next",
            "max_attempts": 2,
            "retry_status_codes": [401, 403, 429],
        },
        "keys": [
            {"id": "a", "value": "${ENV.DEEPSEEK_API_KEY_A}"},
            {"id": "b", "value": "${ENV.DEEPSEEK_API_KEY_B}"},
        ],
    }
})

agent = Agently.create_agent()
agent.activate_model("reasoning")

selection 控制一次新请求开始前怎么选 key，支持 fixed、random、round_robin、least_used。failover 控制 provider 请求失败后是否尝试下一个 key。没有声明 failover 时，Agently 不会自动换 credential。

默认建议只把 401、403、429 这类鉴权或额度相关状态码放进 retry_status_codes。405 和 422 很多时候代表 endpoint、method、payload 或模型能力不匹配，不应该默认重试换 key。

怎么判断配置已经正确

先跑一个最小请求：

agent = Agently.create_agent()
result = agent.input("用一句话打招呼。").get_result()
text = await result.async_get_text()
print(text)

如果这里失败，先不要继续写 Output Control、Actions 或 TriggerFlow。模型配置是所有能力的入口。

常见误用

• 把 API key 写进 Python 源码。
• Claude 配置还走 OpenAICompatible。
• 本地 Ollama 没设 base_url 到 /v1 兼容端点。
• 没有声明 failover，却以为 key pool 会自动切换。
• 把 endpoint/payload 不匹配的 405、422 当成默认 key 失败重试。

下一步

• 设置层级和日志开关：设置
• 多文件项目布局：项目结构
• Provider 列表：模型概览
• 第一次结构化请求：快速开始