English mirror

This English page is generated from the current Chinese documentation so every route, anchor, code sample, and language switch stays available on agently.tech. Human-edited English copy can replace this generated body page by page.

Read the Chinese source page

设置

设置这件事，越早分层，后面越省事。全局模型配置、某个 agent 的模型覆盖、一次请求的 retry 参数、调试日志开关，如果都写在调用点，项目很快会变成一堆互相覆盖的魔法值。

Agently 的 settings 是分层 key-value 存储。低层覆盖高层，未覆盖的值沿用上层。

三个常用 scope

Scope	设置方式	影响范围
全局	Agently.set_settings(...)	此后创建的 agent / request
Agent	agent.set_settings(...)	这个 agent 创建的 request
单次调用	start(..., max_retries=...) 等参数	仅本次调用

from agently import Agently

Agently.set_settings("OpenAICompatible", {
    "base_url": "${ENV.OPENAI_BASE_URL}",
    "api_key": "${ENV.OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
})

agent = Agently.create_agent()
agent.set_settings("OpenAICompatible", {"model": "gpt-4o"})

这个 agent 只覆盖 model。base_url 和 api_key 继续来自全局设置。

常用设置路径

路径	含义
OpenAICompatible / OpenAI / OAIClient	plugins.ModelRequester.OpenAICompatible 的别名
OpenAIResponsesCompatible / OpenAIResponses / Responses	plugins.ModelRequester.OpenAIResponsesCompatible 的别名
AnthropicCompatible / Anthropic / Claude	plugins.ModelRequester.AnthropicCompatible 的别名
plugins.ModelRequester.<Name>	完整 provider 路径
prompt.default_output_format	.output(..., format=...) 省略时的默认格式
runtime.session_id	请求绑定的 session id
runtime.show_model_logs	模型请求和解析日志
runtime.show_action_logs	Action Runtime planning / execution 日志
runtime.show_trigger_flow_logs	TriggerFlow execution / signal 日志
runtime.show_runtime_logs	通用 observation 事件日志
runtime.show_deprecation_warnings	Agently deprecated API warning

provider 别名适合应用代码。插件开发或排查细节时，再看完整路径。

从文件加载

非琐碎项目建议把设置放进 settings.yaml：

OpenAICompatible:
  base_url: ${ENV.OPENAI_BASE_URL}
  api_key: ${ENV.OPENAI_API_KEY}
  model: ${ENV.OPENAI_MODEL}

runtime:
  show_model_logs: false

启动时加载：

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

auto_load_env=True 会先加载工作目录下的 .env，再解析 ${ENV.*}。文件里可以写顶层 provider 别名，也可以写完整路径。

读取设置

provider_settings = agent.settings.get(
    "plugins.ModelRequester.OpenAICompatible",
    {},
)
print(provider_settings.get("model"))

settings.get(path, default) 按点路径读取。找不到就返回 default。

Typed helper 和 dict 怎么选

dict 是最通用的设置形态，适合配置文件和生成式配置。typed helper 适合代码里需要编辑器提示和更早校验的场景：

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",
    )
)

helper 进入 settings store 前会转换回同一个 dict namespace。它不是另一套配置系统。

调试日志

开发时可以打开模型日志：

Agently.set_settings("runtime.show_model_logs", True)

运行时日志按 family 分开：

Agently.set_settings("runtime.show_model_logs", "simple")
Agently.set_settings("runtime.show_action_logs", "simple")
Agently.set_settings("runtime.show_trigger_flow_logs", "detail")
Agently.set_settings("runtime.show_runtime_logs", "detail")

这些开关接受：

• False / "off"：关闭。
• True / "simple"：打印摘要和 warning/error/critical。
• "detail"：打印该 family 的完整 observation 事件。

旧的 runtime.show_tool_logs 仍作为 runtime.show_action_logs 的兼容别名。新代码使用 show_action_logs。

Deprecation warning

如果生产环境明确保留某些兼容调用，可以关闭 Agently deprecation warning：

Agently.set_settings("runtime.show_deprecation_warnings", False)

这个开关只影响 Agently deprecated API warning。运行期错误、风险 scope warning、flow_data 这类告警不由它控制。

常见误用

• 每个调用点都手写 provider 配置。
• 在 agent 级设置里覆盖了模型，却忘了它仍然沿用全局 base_url。
• 把 .env 当公开配置提交。
• 开启 "detail" 日志后忘了在生产环境关闭。
• 用 runtime.show_tool_logs 写新代码。它是兼容别名。

下一步

• Provider 配置：模型设置
• 项目目录怎么摆：项目结构
• 输出格式默认值：输出控制
• 多轮 session 设置：会话记忆