Settings

In production you usually want consistent behavior, shared defaults, and controllable logs. Agently settings are hierarchical: global → Agent → Request/Session. Use set_settings with dot-path keys.

1. How to configure

Global and local overrides:

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 path alias:

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

Environment placeholder substitution (load from .env/environment):

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

2. Core settings

2.1 Storage (Not available now)

Key	Default	Description
storage.db_url	sqlite+aiosqlite:///localstorage.db	Local storage database URL.

2.2 Prompt

Key	Default	Description
prompt.add_current_time	true	Injects current time into the info section.
prompt.role_mapping	See below	Role mapping for prompt → message conversion.
prompt.prompt_title_mapping	See below	Section title mapping for prompt assembly.

Default prompt.role_mapping:

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

Default 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

Key	Default	Description
response.streaming_parse	false	Global switch for structured streaming parsing.
response.streaming_parse_path_style	dot	Path style for streaming output: dot or slash.

3. Runtime and logs

Key	Default	Description
runtime.raise_error	true	Raise normal errors (otherwise log only).
runtime.raise_critical	true	Raise critical errors (otherwise log only).
runtime.show_model_logs	false	Show model request/response logs.
runtime.show_tool_logs	false	Show tool invocation logs.
runtime.show_trigger_flow_logs	false	Show TriggerFlow execution logs.
runtime.httpx_log_level	WARNING	httpx/httpcore log level.

Debug shortcut:

Key	Value	Description
debug	true/false	Toggles show_*_logs and updates httpx_log_level.

4. Plugin activation

Use plugins.<Type>.activate to choose the active implementation:

Plugin type	Default
plugins.PromptGenerator.activate	AgentlyPromptGenerator
plugins.ModelRequester.activate	OpenAICompatible
plugins.ResponseParser.activate	AgentlyResponseParser
plugins.ToolManager.activate	AgentlyToolManager
plugins.Session.activate	AgentlyMemoSession

5. OpenAICompatible settings

Namespace: plugins.ModelRequester.OpenAICompatible (alias: OpenAICompatible).

5.1 Model and endpoints

Key	Default	Description
model_type	chat	Request type: chat/completions/embeddings.
model	null	Explicit model name; falls back to default_model.
default_model.chat	gpt-4.1	Default chat model.
default_model.completions	gpt-3.5-turbo-instruct	Default completions model.
default_model.embeddings	text-embedding-ada-002	Default embeddings model.
base_url	https://api.openai.com/v1	API base URL.
full_url	null	Full request URL (overrides base_url + path_mapping).
path_mapping.chat	/chat/completions	Chat endpoint path.
path_mapping.completions	/completions	Completions endpoint path.
path_mapping.embeddings	/embeddings	Embeddings endpoint path.

5.2 Auth and network

Key	Default	Description
api_key	null	API key shortcut.
auth	null	Custom auth structure (api_key/headers/body).
headers	{}	Extra request headers.
proxy	null	Proxy address (passed to httpx).
timeout	See below	httpx.Timeout config.
client_options	{}	Extra args for httpx.AsyncClient.

Default timeout:

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

5.3 Request options

Key	Default	Description
request_options	{}	Request body options (e.g. temperature), merged with prompt options.
stream	true	Use streaming (embeddings force false).

5.4 Response mapping

Key	Default	Description
content_mapping	See below	Map provider fields to unified events and values.
content_mapping_style	dot	Field path style: dot/slash.
yield_extra_content_separately	true	Emit extra fields as separate events.
strict_role_orders	true	Enforce role ordering when building messages.
rich_content	false	Enable rich content (attachments).

Default 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 and memo (Beta)

Key	Default	Description
session.memo.enabled	false	Enable memo updates.
session.memo.instruct	See below	Prompt instructions for memo updates.
session.resize.every_n_turns	8	Turn interval for resize decisions.
session.resize.max_messages_text_length	12000	Max character budget for current context.
session.resize.max_keep_messages_count	null	Keep last N messages (null means unlimited).

Default 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.

Legacy keys:

Legacy key	Equivalent
session.resize.max_current_chars	session.resize.max_messages_text_length
session.resize.keep_last_messages	session.resize.max_keep_messages_count

7. ChatSession recording (Deprecated)

Key	Default	Description
record_input_paths	[]	Input path list in (slot, path) format (empty means full input).
record_input_mode	all	Input record mode: all/first.
record_output_paths	[]	Output paths to record (empty means full output).
record_output_mode	all	Output record mode: all/first.

Paths use dot (e.g. a.b.c) or slash (e.g. a/b/c) style.