AgentixAgentOptions

The single configuration object for all agent behavior. Pass it to query() or AgentixClient().

from agentix import AgentixAgentOptions

options = AgentixAgentOptions(
    name="my-agent",
    provider="anthropic",
    model="claude-sonnet-4-20250514",
    system_prompt="You are a helpful assistant.",
)

Identity & LLM

Field	Type	Default	Description
agent_id	str	Auto UUID	Unique agent identifier
name	str	"agent"	Agent display name
provider	str	"anthropic"	LLM backend: "anthropic", "openai", "openai_compatible", "gemini", "deepseek"
model	str | None	Auto	Model identifier; auto-filled from provider defaults
fallback_model	str | None	None	Fallback model if primary fails after all retries
system_prompt	str	""	System prompt
llm_options	dict	{}	Extra kwargs for the LLM client (e.g. api_key, base_url). base_url only used by openai_compatible and deepseek providers.
key_provider	Callable[[], str] | None	None	Called before each LLM request to return a fresh API key
betas	list[str]	[]	API beta feature flags

Default models:

Provider	Default model
anthropic	claude-sonnet-4-20250514
openai	gpt-4o
openai_compatible	gpt-oss-120b
gemini	gemini-2.5-flash
deepseek	deepseek-chat

Execution Limits

Field	Type	Default	Env Override	Description
max_tokens	int	4096	—	Max tokens per LLM response
max_iterations	int	20	—	Max agent loop iterations
tool_timeout	float	120.0	AGENTIX_TOOL_TIMEOUT	Seconds before a tool call is killed
web_fetch_timeout	float	15.0	AGENTIX_WEB_FETCH_TIMEOUT	HTTP timeout for web tools
script_timeout	float	30.0	AGENTIX_SCRIPT_TIMEOUT	Subprocess timeout
mcp_connect_timeout	float	60.0	AGENTIX_MCP_CONNECT_TIMEOUT	MCP server handshake timeout
max_context_tokens	int	16384	—	Token budget; older messages are summarized when exceeded
max_tokens_budget	int | None	None	—	Hard stop when total usage exceeds this
effort	str | None	None	—	"low", "medium", "high", "max" — thinking effort

Memory & Persistence

Field	Type	Default	Description
conversation_summarization_enabled	bool	True	Summarize old messages when the context window fills up; False = drop them instead
max_conversation_window	int	10	Recent messages always kept verbatim before summarization
memories_enabled	bool	False	Register the Memories tool at <cwd>/.agentix/memories; when allowed_tools is non-empty, Memories is also appended automatically unless denied
persistence_enabled	bool	True	Persist sessions to disk
storage_base_path	str	~/.agentix/projects	Session storage directory
storage_backend	StorageBackend | None	None	Custom storage backend
enable_file_checkpointing	bool	False	Reserved — not yet implemented; rewind_files() raises NotImplementedError

Resilience

Field	Type	Default	Description
retry_max_attempts	int	3	Max LLM call retries on transient failures
retry_base_delay	float	1.0	Initial retry delay (seconds, doubles each attempt)
retry_max_delay	float	30.0	Max retry delay cap
circuit_breaker_failure_threshold	int	5	Consecutive failures that trip the circuit breaker; 0 = disabled
circuit_breaker_cooldown	float	60.0	Seconds before a tripped circuit allows a probe

Sessions

Field	Type	Default	Description
resume	str | None	None	Resume a specific session by ID
continue_conversation	bool	False	Auto-resume the most recent session
fork_session	bool	False	Fork the session (copy to new ID)

continue_conversation and fork_session cannot both be True — raises ConfigurationError.

Tools & Permissions

Field	Type	Default	Description
allowed_tools	list[str]	[]	Tool allow-list (empty = allow all)
disallowed_tools	list[str]	[]	Tool deny-list (always overrides allow-list)
tools	list[str] | dict	[]	Alias for allowed_tools
permission_mode	str	"default"	Permission mode
can_use_tool	callback	None	Async permission callback
permission_prompt_tool_name	str | None	None	Tool name for inline permission prompts

Environment & Workspace

Field	Type	Default	Description
cwd	str | None	None	Working directory (None → process cwd)
add_dirs	list[str | Path]	[]	Extra directories to add to tool path
env	dict[str, str]	{}	Extra environment variables for subprocesses
env_pass_through	list[str]	[]	Ambient env vars forwarded to subprocesses
strict_env	bool	False	Start subprocesses from minimal platform-safe env
sandbox	SandboxSettings | None	None	Sandbox mode and network restrictions

Queuing & Streaming

Field	Type	Default	Description
max_queue_size	int | None	None	Max buffered messages; None = unlimited
include_partial_messages	bool	False	Yield StreamEvent partial tokens
output_format	dict | None	None	Structured output JSON schema
user	str | None	None	End-user identifier forwarded to the LLM API

Thinking & Extended Reasoning

Field	Type	Default	Description
thinking	dict | None	None	{"enabled": true, "budget_tokens": 10000} for Anthropic
effort	str | None	None	Shorthand: low=2k, medium=5k, high=10k, max=32k tokens

Multi-Agent

Field	Type	Default	Description
agents	dict[str, AgentDefinition] | None	None	Sub-agent definitions
is_sub_agent	bool	False	Mark as sub-agent
strict_agent_validation	bool	False	Raise on invalid definitions (recommended for CI)

Extension Points

Field	Type	Default	Description
hooks	dict[str, list]	{}	Hook matchers keyed by event name
plugins	list[dict]	[]	Plugin directory configs
mcp_servers	dict[str, Any]	{}	MCP server configs
setting_sources	list[str]	["user", "project", "local"]	JSON config layers to load
settings	dict	{}	Inline JSON overrides
trusted_plugin_paths	list[str]	[]	Plugin paths bypassing hash verification