设置项说明

适用版本：4.0.8.1+

在工程环境里，我们通常希望行为可控、调试可复现，并能在不同组件之间共享配置。Agently 的设置项按层级继承：全局 → Agent → Request/Session，通过 set_settings 使用点号路径写入配置。

1. 配置方式

全局与局部覆盖：

python

from agently import Agently

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

agent = Agently.create_agent()
agent.set_settings("prompt.add_current_time", True)

OpenAICompatible 支持路径别名（OpenAICompatible / OpenAI / OAIClient）：

python

Agently.set_settings("OpenAICompatible", {
  "base_url": "https://api.openai.com/v1",
  "api_key": "YOUR_API_KEY",
  "model": "gpt-4o-mini"
})

环境变量占位符替换（从 .env/环境变量加载）：

python

Agently.set_settings(
  "OpenAICompatible",
  { "api_key": "${ENV.OPENAI_API_KEY}" },
  auto_load_env=True,
)

2. 基础设置

2.1 Storage (暂无作用)

设置项	默认值	作用
`storage.db_url`	`sqlite+aiosqlite:///localstorage.db`	本地存储的数据库地址。

2.2 Prompt

设置项	默认值	作用
`prompt.add_current_time`	`false`	为 `true` 时将当前时间写入 `info` 段，供模型参考。
`prompt.role_mapping`	见下	角色映射，控制 prompt 转为消息时的 role。
`prompt.prompt_title_mapping`	见下	各段标题映射，影响 prompt 拼接时的标题文本。

默认 prompt.role_mapping：

yaml

system: system
developer: developer
assistant: assistant
user: user
_: assistant

默认 prompt.prompt_title_mapping：

yaml

system: SYSTEM
developer: DEVELOPER DIRECTIONS
chat_history: CHAT HISTORY
info: INFO
tools: TOOLS
action_results: ACTION RESULTS
instruct: INSTRUCT
examples: EXAMPLES
input: INPUT
output: OUTPUT
output_requirement: OUTPUT REQUIREMENT

2.3 Response

设置项	默认值	作用
`response.streaming_parse`	`false`	结构化流式解析的全局开关。
`response.streaming_parse_path_style`	`dot`	流式解析产出的路径风格：`dot` 或 `slash`。

3. 运行与日志

设置项	默认值	作用
`runtime.raise_error`	`true`	抛出普通错误（否则仅记录日志）。
`runtime.raise_critical`	`true`	抛出致命错误（否则仅记录日志）。
`runtime.show_model_logs`	`false`	输出模型请求与响应日志。
`runtime.show_tool_logs`	`false`	输出工具调用日志。
`runtime.show_trigger_flow_logs`	`false`	输出 TriggerFlow 执行日志。
`runtime.httpx_log_level`	`WARNING`	`httpx/httpcore` 日志级别。

调试快捷开关：

设置项	取值	作用
`debug`	`true/false`	一键开关 `show_*_logs` 并同步调整 `httpx_log_level`。

4. 插件激活

通过 plugins.<Type>.activate 指定当前插件实现：

插件类型	默认值
`plugins.PromptGenerator.activate`	`AgentlyPromptGenerator`
`plugins.ModelRequester.activate`	`OpenAICompatible`
`plugins.ResponseParser.activate`	`AgentlyResponseParser`
`plugins.ToolManager.activate`	`AgentlyToolManager`

5. OpenAICompatible 配置

命名空间：plugins.ModelRequester.OpenAICompatible（可用别名 OpenAICompatible / OpenAI / OAIClient）。

参数覆盖顺序、tools 两种机制、temperature 等常见问题详解： /openai-api-format

5.1 模型与接口

设置项	默认值	作用
`model_type`	`chat`	请求类型：`chat`/`completions`/`embeddings`。
`model`	`null`	指定模型名，缺省则取 `default_model`。
`default_model.chat`	`gpt-4.1`	chat 模型默认值。
`default_model.completions`	`gpt-3.5-turbo-instruct`	completions 模型默认值。
`default_model.embeddings`	`text-embedding-ada-002`	embeddings 模型默认值。
`base_url`	`https://api.openai.com/v1`	API 基础地址。
`full_url`	`null`	完整请求地址（优先于 `base_url + path_mapping`）。
`path_mapping.chat`	`/chat/completions`	chat 端点路径。
`path_mapping.completions`	`/completions`	completions 端点路径。
`path_mapping.embeddings`	`/embeddings`	embeddings 端点路径。

5.2 认证与网络

设置项	默认值	作用
`api_key`	`null`	直接设置 API Key。
`auth`	`null`	自定义认证结构（`api_key`/`headers`/`body`）。
`headers`	`{}`	额外请求头。
`proxy`	`null`	代理地址（传入 httpx）。
`timeout`	见下	`httpx.Timeout` 配置。
`client_options`	`{}`	传入 `httpx.AsyncClient` 的额外参数。

默认 timeout：

yaml

connect: 30.0
read: 600.0
write: 30.0
pool: 30.0

5.3 请求参数

设置项	默认值	作用
`request_options`	`{}`	请求体参数（如 `temperature`/`top_p`），会与 prompt `options` 合并。
`stream`	`true`	是否使用流式请求（embeddings 自动强制为 `false`）。

5.4 响应映射

设置项	默认值	作用
`content_mapping`	见下	将供应商返回字段映射为统一事件与字段。
`content_mapping_style`	`dot`	字段路径风格：`dot`/`slash`。
`yield_extra_content_separately`	`true`	额外字段是否单独输出事件。
`strict_role_orders`	`true`	生成消息时严格遵循 role 顺序。
`rich_content`	`false`	是否启用富内容消息（附件等）。

默认 content_mapping：

yaml

id: id
role: choices[0].delta.role
reasoning: choices[0].delta.reasoning_content
delta: choices[0].delta.content
tool_calls: choices[0].delta.tool_calls
done: null
usage: usage
finish_reason: choices[0].finish_reason
extra_delta:
  function_call: choices[0].delta.function_call
extra_done: null

6. Session（v4.0.8.1+）

v4.0.8.1 的 Session 已重做，默认 Agent 使用 SessionExtension 进行会话注入与记录。

设置项	默认值	作用
`session.max_length`	`null`	会话窗口长度上限。为整数时触发默认 `simple_cut` 策略裁剪 `context_window`。
`session.input_keys`	`null`	请求结束后，记录输入时提取的键路径列表。`null` 表示记录完整请求文本。
`session.reply_keys`	`null`	请求结束后，记录输出时提取的键路径列表。`null` 表示记录完整输出。

说明：

session.input_keys / session.reply_keys 支持 dot 与 slash 路径风格
输入提取支持 .request.* 与 .agent.* 前缀
memo 更新不再依赖旧 session.memo.* 设置，推荐通过 Session.register_*_handler() 自定义

7. 兼容与弃用项

项	状态	说明
`set_debug_console(\"ON\")`	Deprecated	仅输出弃用警告，不再改变运行行为。
`ChatSessionExtension`	Deprecated	建议使用默认集成的 `SessionExtension`。

若你仍在使用旧快捷接口，建议统一迁移到：activate_session / deactivate_session + session.max_length + 自定义策略。

设置项说明 ​

1. 配置方式 ​

2. 基础设置 ​

2.1 Storage (暂无作用) ​

2.2 Prompt ​

2.3 Response ​

3. 运行与日志 ​

4. 插件激活 ​

5. OpenAICompatible 配置 ​

5.1 模型与接口 ​

5.2 认证与网络 ​

5.3 请求参数 ​

5.4 响应映射 ​

6. Session（v4.0.8.1+） ​

7. 兼容与弃用项 ​

设置项说明

1. 配置方式

2. 基础设置

2.1 Storage (暂无作用)

2.2 Prompt

2.3 Response

3. 运行与日志

4. 插件激活

5. OpenAICompatible 配置

5.1 模型与接口

5.2 认证与网络

5.3 请求参数

5.4 响应映射

6. Session（v4.0.8.1+）

7. 兼容与弃用项