设置项说明

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

1. 配置方式

全局与局部覆盖：

from agently import Agently

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

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

OpenAICompatible 支持路径别名：

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

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

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	true	将当前时间写入 info 段，供模型参考。
prompt.role_mapping	见下	角色映射，控制 prompt 转为消息时的 role。
prompt.prompt_title_mapping	见下	各段标题映射，影响 prompt 拼接时的标题文本。

默认 prompt.role_mapping：

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

默认 prompt.prompt_title_mapping：

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
plugins.Session.activate	AgentlyMemoSession

5. OpenAICompatible 配置

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

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：

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：

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 与 Memo (测试调整中)

设置项	默认值	作用
session.memo.enabled	false	是否启用 memo 更新。
session.memo.instruct	见下	memo 更新的提示词指令。
session.resize.every_n_turns	8	多少轮触发一次轻量压缩判断。
session.resize.max_messages_text_length	12000	当前上下文最大字符数阈值。
session.resize.max_keep_messages_count	null	保留最近消息条数（null 表示不限制）。

默认 session.memo.instruct：

- Update the memo dictionary based on the provided messages.
- Keep stable preferences, constraints, and facts that help future turns.
- Add new keys or update existing ones as needed.
- Return the updated memo dictionary.

兼容旧字段：

旧字段	等价字段
session.resize.max_current_chars	session.resize.max_messages_text_length
session.resize.keep_last_messages	session.resize.max_keep_messages_count

7. ChatSession 记录控制 (即将废弃)

设置项	默认值	作用
record_input_paths	[]	记录输入路径列表，格式为 (slot, path)（空表示记录完整输入）。
record_input_mode	all	输入记录模式：all/first。
record_output_paths	[]	记录输出路径（空表示记录完整输出）。
record_output_mode	all	输出记录模式：all/first。

路径使用 dot（如 a.b.c）或 slash（如 a/b/c）风格。