Configuration

An agent is configured in a few layers, each with one job. You will know which layer a setting belongs in, what the defaults are, and how to see the settings an agent actually ended up with.

Layer	Where	It decides	Every option
Model	`model_config=`	which provider and model, how it samples	Models
Agent	`agent_config=`	steps and limits, workspace, memory window, context, guardrail, policy	Agent settings
Memory store	`memory_router=`	where conversations and run records are kept	Memory
Record	`telemetry_config=`, `telemetry_exporters=`	what a trace keeps, where, for how long	Telemetry settings
Tools	`local_tools=`, `mcp_tools=`, `sub_agents=`	what the agent may call	OmniCoreAgent
Environment	shell, `.env`	secrets and connection strings	below

You need exactly one environment variable to start: LLM_API_KEY. Everything else has a local default: memory in the process, the workspace and traces in ./workspace. Every output on this page is what the code printed when it was run; the model’s wording will differ on yours.

All the layers in one agent

import asyncio
from pathlib import Path
from omnicoreagent import OmniCoreAgent

async def main():
    agent = OmniCoreAgent(
        name="configured",
        system_instruction="You are a concise assistant. Answer in plain text.",
        # Which model, and how it samples
        model_config={"provider": "openai", "model": "gpt-5.4-mini", "max_tokens": 800},
        # How the agent runs
        agent_config={
            "max_steps": 10,
            "tool_call_timeout": 60,
            "context_management": {"threshold_percent": 60},
            "workspace_config": {"workspace_dir": "./agent_data"},
        },
        # What its record keeps, and for how long
        telemetry_config={"capture": "default", "retention_days": 30},
    )

    # Settings you left out keep their defaults; nested ones are merged.
    print("context_management:", agent.agent_config["context_management"])
    print("tool_offload enabled:", agent.agent_config["tool_offload"]["enabled"])

    result = await agent.run("Give me one word for happy.")
    print(result["status"], "|", result["response"])

    trace = await agent.get_trace(result["trace_id"])
    call = next(e for e in trace["events"] if e["event_type"] == "model_call")
    print("model prompt recorded:", call["input_capture"]["state"])

    print("workspace:", sorted(p.name for p in Path("agent_data").iterdir()))
    await agent.cleanup()

asyncio.run(main())

context_management: {'enabled': True, 'mode': 'token_budget', 'value': 100000, 'threshold_percent': 60, 'strategy': 'truncate', 'preserve_recent': 4}
tool_offload enabled: True
success | Joyful
model prompt recorded: not_recorded
workspace: ['artifacts', 'files', 'telemetry']

What each line shows:

Nested settings merge. Only threshold_percent was given; the other five context_management keys kept their defaults. The same holds for tool_offload, privacy_config and governance_config.
agent.agent_config is the full, checked configuration the agent will run with. Print it when you are unsure what a default is.
capture: "default" is the privacy-first record: the trace marks the model prompt not_recorded instead of keeping it. The default, "full", keeps it.
workspace_dir moved the agent’s files, its offloaded tool results and its traces to ./agent_data.

How it works

Everything is checked when the agent is built. An unknown key, a value out of range or a setting for the wrong transport raises a ValueError from the constructor, naming the setting. Nothing waits for a run to fail.
Code beats the environment. Environment variables supply secrets and connection strings, and defaults when code says nothing. A workspace_config in code replaces the workspace variables entirely.

A dict or a typed object. agent_config takes a dict, or an AgentConfig, whose fields your editor completes:

from omnicoreagent import OmniCoreAgent
from omnicoreagent.core import AgentConfig

agent = OmniCoreAgent(
    name="typed",
    system_instruction="You are a helpful assistant.",
    model_config={"provider": "openai", "model": "gpt-5.4-mini"},
    agent_config=AgentConfig(max_steps=20, enable_agent_skills=True),
)

1. Environment variables

The model key

export LLM_API_KEY=your_provider_key

One variable, whichever provider you choose in model_config; the runtime hands it to that provider. It is read on the agent’s first run. Ollama needs none. To take the key from somewhere else, such as a secrets manager, put it in model_config["api_key"] instead. The runtime does not load .env files. To use one, call load_dotenv() from python-dotenv at the top of your script.

Memory

Session history lives in the process unless you pass a MemoryRouter. The store is chosen in code; its connection string comes from the environment.

Store	In code	Variable	Extra
In process (default)	`MemoryRouter("in_memory")`	none	none
Redis	`MemoryRouter("redis")`	`REDIS_URL`, e.g. `redis://localhost:6379/0`	`omnicoreagent[redis]`
SQL (SQLite, PostgreSQL, or another SQLAlchemy database)	`MemoryRouter("sql")`	`DATABASE_URL`, e.g. `postgresql://user:pass@localhost:5432/db`	`omnicoreagent[postgres]`, for SQLite too: it ships SQLAlchemy, which every SQL store uses
MongoDB	`MemoryRouter("mongodb")`	`MONGODB_URI`, e.g. `mongodb://localhost:27017`; optional `MONGODB_DB_NAME` (default `omnicoreagent`), `MONGODB_COLLECTION` (default `messages`)	`omnicoreagent[mongodb]`

from omnicoreagent import MemoryRouter, OmniCoreAgent

agent = OmniCoreAgent(
    name="assistant",
    system_instruction="You are a helpful assistant.",
    model_config={"provider": "openai", "model": "gpt-5.4-mini"},
    memory_router=MemoryRouter("redis"),
)

The same store keeps each run’s durable record, so a paused run can be resumed in another process (Durable runs).

If the variable is missing, building the router raises instead of quietly keeping history in process memory:

ValueError: MemoryRouter("redis") needs   REDIS_URL (e.g. redis://localhost:6379/0). Set it, or use   MemoryRouter("in_memory") for a store that lasts only as long as this process.

"sql" without DATABASE_URL and "mongodb" without MONGODB_URI raise the same way.

Workspace

The workspace holds the agent’s files, offloaded tool results and, by default, its traces. It is separate from memory.

Backend	Variables
Local (default)	`OMNICOREAGENT_WORKSPACE_BACKEND=local`, `OMNICOREAGENT_WORKSPACE_DIR` (default `./workspace`)
S3	`OMNICOREAGENT_WORKSPACE_BACKEND=s3`, `AWS_S3_BUCKET`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`; optional `AWS_REGION`, `AWS_ENDPOINT_URL` for an S3-compatible service
R2	`OMNICOREAGENT_WORKSPACE_BACKEND=r2`, `R2_BUCKET_NAME`, `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`

OMNICOREAGENT_WORKSPACE_PREFIX (default workspace) prefixes the object keys in S3 and R2. The same settings in code, which replace the variables: agent_config={"workspace_config": {"workspace_backend": "s3", "s3_bucket": "..."}}. S3 and R2 need omnicoreagent[s3]. More in Workspace files.

Trace exporters

Traces are kept on local disk without any external service. To also send each finished trace to an OTLP-compatible backend, install the extra and name the exporter:

pip install "omnicoreagent[otel]"       # any OTLP/HTTP collector
pip install "omnicoreagent[langsmith]"
pip install "omnicoreagent[opik]"

Exporter	Variables
OTLP/HTTP	`OTEL_EXPORTER_OTLP_ENDPOINT`, or `endpoint` in code
LangSmith	`LANGSMITH_API_KEY`; optional `LANGSMITH_PROJECT`, `LANGSMITH_OTEL_ENDPOINT`
Opik	`OPIK_API_KEY`, `OPIK_WORKSPACE`; optional `OPIK_PROJECT_NAME`, `OPIK_OTEL_ENDPOINT`

from omnicoreagent import OmniCoreAgent

agent = OmniCoreAgent(
    name="research-agent",
    system_instruction="You are a research assistant.",
    model_config={"provider": "openai", "model": "gpt-5.4-mini"},
    telemetry_exporters=[
        {"destination": "otlp", "endpoint": "http://localhost:4318/v1/traces", "service_name": "research-agent"}
    ],
)

destination is otlp, langsmith, opik or jsonl. An exporter is a copy sent after the run; it is never in the run’s way (Observability).

OmniServe and background runs

You need none of these to start: the server binds 0.0.0.0:8000, exposes the background API, starts its worker and keeps tasks in memory. A variable overrides the same value passed to OmniServeConfig in code.

Server variables

Variable	Default	Purpose
`OMNICOREAGENT_SERVE_HOST`	`0.0.0.0`	Bind host. Must not be empty.
`OMNICOREAGENT_SERVE_PORT`	`8000`	Port, `1`-`65535`.
`OMNICOREAGENT_SERVE_WORKERS`	`1`	Must be `1`; scale by running more processes behind a process manager.
`OMNICOREAGENT_SERVE_API_PREFIX`	`""`	Route prefix, such as `/api/v1`; normalized to a leading slash and no trailing slash.
`OMNICOREAGENT_SERVE_ENABLE_DOCS`	`true`	Swagger UI.
`OMNICOREAGENT_SERVE_ENABLE_REDOC`	`true`	ReDoc.
`OMNICOREAGENT_SERVE_CORS_ENABLED`	`true`	CORS middleware.
`OMNICOREAGENT_SERVE_CORS_ORIGINS`	`*`	Comma-separated allowed origins.
`OMNICOREAGENT_SERVE_CORS_METHODS`	`*`	Comma-separated allowed methods.
`OMNICOREAGENT_SERVE_CORS_HEADERS`	`*`	Comma-separated allowed headers.
`OMNICOREAGENT_SERVE_CORS_CREDENTIALS`	`false`	Allow CORS credentials; only with explicit origins, never with `*`.
`OMNICOREAGENT_SERVE_AUTH_ENABLED`	`false`	Bearer token auth; needs `OMNICOREAGENT_SERVE_AUTH_TOKEN`.
`OMNICOREAGENT_SERVE_AUTH_TOKEN`	unset	The bearer token.
`OMNICOREAGENT_SERVE_REQUEST_LOGGING`	`true`	Log requests.
`OMNICOREAGENT_SERVE_LOG_LEVEL`	`INFO`	`CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` or `TRACE`.
`OMNICOREAGENT_SERVE_REQUEST_TIMEOUT`	`300`	Seconds; `0` turns the timeout off.
`OMNICOREAGENT_SERVE_RATE_LIMIT_ENABLED`	`false`	In-process rate limiting.
`OMNICOREAGENT_SERVE_RATE_LIMIT_REQUESTS`	`100`	Requests per window, at least `1`.
`OMNICOREAGENT_SERVE_RATE_LIMIT_WINDOW`	`60`	Window in seconds, at least `1`.
`OMNICOREAGENT_SERVE_TRUSTED_PROXIES`	none	Comma-separated proxy addresses; the client IP is read from `X-Forwarded-For` only on requests from these.

Background task store variables

Variable	Default	Purpose
`OMNICOREAGENT_BACKGROUND_ENABLED`	`true`	Expose the background task endpoints.
`OMNICOREAGENT_BACKGROUND_AGENT_ID`	`default`	The id the served agent is registered under.
`OMNICOREAGENT_BACKGROUND_TASK_STORE`	`in_memory`	`in_memory`, `sql`, `redis` or `mongodb`.
`OMNICOREAGENT_BACKGROUND_TASK_STORE_URL`	unset	SQL or Redis URL. A URL with no store named selects SQL; set the store to `redis` for a Redis URL.
`OMNICOREAGENT_BACKGROUND_TASK_STORE_URI`	unset	MongoDB URI; selects the MongoDB store.
`OMNICOREAGENT_BACKGROUND_TASK_STORE_DATABASE`	`omnicoreagent`	MongoDB database.
`OMNICOREAGENT_BACKGROUND_TASK_STORE_PREFIX`	unset	Redis key prefix.
`OMNICOREAGENT_BACKGROUND_TASK_STORE_COLLECTION_PREFIX`	unset	MongoDB collection prefix.
`OMNICOREAGENT_BACKGROUND_TASK_STORE_CONNECT_TIMEOUT`	unset	Connect timeout in seconds.
`OMNICOREAGENT_BACKGROUND_START_WORKER`	`true`	Start the scheduler and worker with the server.

The task store is not the memory store: it keeps tasks, schedules, runs, attempts, leases, heartbeats, retries and cancellations. Keep the in-memory default only while trying things out; a durable store keeps background tasks across restarts. Use SQL for local durability with SQLite, or PostgreSQL or MySQL when several processes share one store. Use Redis when your deployment already operates Redis with persistence and no eviction for task-store keys. Use MongoDB when MongoDB is your durable operational store; its writes use majority write concern. Pick one backend:

# Local SQLite durability
export OMNICOREAGENT_BACKGROUND_TASK_STORE=sql
export OMNICOREAGENT_BACKGROUND_TASK_STORE_URL=sqlite:///.omnicoreagent/background.db

# Redis durability
export OMNICOREAGENT_BACKGROUND_TASK_STORE=redis
export OMNICOREAGENT_BACKGROUND_TASK_STORE_URL=redis://localhost:6379/0

# MongoDB durability
export OMNICOREAGENT_BACKGROUND_TASK_STORE=mongodb
export OMNICOREAGENT_BACKGROUND_TASK_STORE_URI=mongodb://localhost:27017
export OMNICOREAGENT_BACKGROUND_TASK_STORE_DATABASE=omnicoreagent

More in OmniServe and Background agents.

2. Agent configuration

The settings you are most likely to change. Each has a default; leave out what you do not need.

Setting	Default	What it does
`max_steps`	`50`	Most turns of the agent loop per run (1 to 1000); a turn is a model call and the tools it asked for. A run that reaches it ends with `status` `error`, `termination_reason` `max_steps` and the response `Agent reached its step limit.`
`request_limit`, `total_tokens_limit`	`0` (no limit)	Most model calls, or tokens, per run; then `resource_limit`. See which limit to use.
`tool_call_timeout`	`180`	Seconds one tool call may take (2 to 1000).
`workspace_config`	`./workspace` on disk	`{"workspace_dir": ...}`, or S3 / R2 settings.
`enable_workspace_files`	`True`	The file tools over the workspace.
`memory_config`	last 10,000 messages (the whole history, in practice)	How much of the session’s earlier history a run starts from: `{"mode": "sliding_window" or "token_budget", "value": ..., "summary": {...}}` (Memory).
`context_management`	on, 100,000 tokens, at 75%	Truncates or summarizes older messages before a call would overflow (Context engineering).
`tool_offload`	on, over 500 tokens or 2,000 bytes	Saves a large tool result to the workspace and gives the model a preview.
`guardrail_mode`	`"full"`	`full` (input and tool results), `input_only`, or `off` (Guardrails).
`governance_config`	on, profile `permissive-dev`	Policy, budgets, sandbox; `{"enabled": False}` turns it off (Security model, Policy, Budgets).
`enable_subagents`	`False`	The `spawn_subagents` tool; turns the workspace, context management and offload on.
`enable_agent_skills`, `skills_dir`	`False`, `./.agents/skills`	Skills the agent may load (Skills).
`code_mode`	off	A `run_code` tool (Code mode).
`run_retention_days`	`30`	Days a finished run’s record (status, approvals, usage) is kept; `None` keeps them. Its traces have their own window, `telemetry_config["retention_days"]` (7) (what is kept).

The other settings, and every nested default, are in the agent settings reference.

Which limit to use

Several settings stop a run; they count different things.

You want to stop	Use	When it is reached
A run that goes round in circles	`max_steps` (on, 50)	The run ends: `termination_reason` `max_steps`
One run’s model calls or tokens	`request_limit`, `total_tokens_limit` (off)	The run ends: `resource_limit`
Spending: dollars, tokens, calls, sandbox time, for a run, a session, an agent or the application	Budgets, in `governance_config` (Budgets)	Checked before each call; the run pauses (`awaiting_budget`) until a grant, or ends
One slow tool call	`tool_call_timeout` (180 s)	That call fails; the run goes on
A whole run taking too long	A background task’s `timeout_seconds`, OmniServe’s `OMNICOREAGENT_SERVE_REQUEST_TIMEOUT` (300 s), the headless CLI’s `--timeout`	The run is stopped at the deadline

max_steps is the one to set first. Budgets are the only limit in dollars, and the only one across runs. governance_config["sandbox_config"] names where the execute tool runs commands: docker, e2b, modal, daytona, vercel, http (your own service), or local (the machine the agent runs on, not isolated), plus any provider you register. none gives a policy without a sandbox; local_test runs registered handlers for tests. What each needs, and which can limit a sandbox’s network to named hosts, is on Sandbox providers.

3. Model configuration

model_config = {
    "provider": "openai",        # required
    "model": "gpt-5.4-mini",     # required
    "temperature": 0.5,
    "max_tokens": 4000,
    "top_p": 0.9,
    "reasoning_effort": "low",
}

Key	What it does
`provider`, `model`	Required. `provider` is one of `openai`, `anthropic`, `gemini`, `groq`, `deepseek`, `mistral`, `openrouter`, `azure`, `ollama`.
`temperature`, `top_p`, `max_tokens`, `reasoning_effort`	Sent to the provider as given; unset leaves the provider’s default. A setting the model refuses is dropped, and the drop is recorded.
`logprobs`, `top_logprobs`	Ask for the chosen tokens’ probabilities, for training on the run.
`api_key`	The key, when it does not come from `LLM_API_KEY`.
`azure_endpoint`, `azure_api_version`, `azure_deployment`	Azure OpenAI.
`base_url`	Another endpoint that speaks the provider’s API: vLLM, LM Studio, a gateway, a proxy. Sent with each of this agent’s calls.
`ollama_host`	Where Ollama runs, e.g. `http://localhost:11434`.

Providers, model names and reasoning models: Models.

4. MCP tool configuration

Each MCP server is a dict in mcp_tools:

mcp_tools = [
    {
        "name": "files",
        "transport_type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    },
    {
        "name": "remote_service",
        "transport_type": "streamable_http",
        "url": "https://api.example.com/mcp",
        "headers": {"Authorization": "Bearer token"},
    },
]

name is the server’s identity in tool routing, policy and traces. command, args, cwd and env apply to stdio; url, headers, timeout, sse_read_timeout and auth to sse and streamable_http; connect_timeout (30 seconds by default) and call_timeout to all. A setting that does not apply to the transport raises a ValueError naming the server. Every setting, OAuth and reconnects: MCP.

5. Telemetry configuration

Every run’s trace is kept without any setup. telemetry_config changes what it keeps and for how long:

Setting	Default	What it does
`storage`	`"auto"`	On local disk, in `telemetry/` under the workspace directory, even when the workspace is S3 or R2. `"memory"` keeps traces in the process only.
`storage_path`	none	Another file for the trace log.
`capture`	`"full"`	Keep the whole trajectory, model input and output included (redacted). `"default"` leaves model prompts and responses out. A `record_*` setting you give wins over either.
`retention_days`	`7`	Finished traces older than this are removed, once per agent before its first run; `None` keeps all. Agents sharing one store (the same `storage_path`) must give the same value; a different one is refused when the second agent initializes.
`max_payload_bytes`	`64000`	A larger payload is truncated, or kept whole elsewhere with `offload_large_payloads`.
`redact_keys`	`api_key`, `token`, `password`, …	Keys whose values are replaced with `[REDACTED]`.

To share one archive of finished traces between several processes, set archive_index_url to a database and archive_target or archive_bodies_path for the bodies. All of it, with the rest of the settings, is in the telemetry settings reference; reading a trace is on Observability.

When things go wrong

All of these are raised by the constructor, before any model call, unless noted.

ValueError: Unknown agent_config setting 'max_step'. Did you mean 'max_steps'?

A misspelled or unknown key. The message ends with every valid setting. With AgentConfig(max_step=...) the same mistake is a TypeError: ... got an unexpected keyword argument 'max_step'.

ValueError: agent_config['memory_tool_backend'] was removed in 0.4

A setting from 0.3. The message says what replaced it:

ValueError: agent_config['memory_tool_backend'] was removed in 0.4: the memory_* tools are gone: the agent's files live in its workspace, on by default (enable_workspace_files), on local disk or S3 / R2 through workspace_config. See https://docs-omnicoreagent.omnirexfloralabs.com/docs/upgrading

ValueError: governance_config has unknown keys: enable

Nested settings are checked too, and the message lists the allowed keys:

ValueError: governance_config has unknown keys: enable. Allowed keys: allow_static_high_risk_approvals, allow_test_sandbox_runtime, approval_mode, approval_resolver, budgets, enabled, policy, policy_path, profile, project_root, sandbox_config, sandbox_manifest, sandbox_runtime, workspace_bridge

ValueError: max_steps must be between 1 and 1000, got 0

A value out of range. Others you may meet:

ValueError: guardrail_mode must be one of: full, input_only, off; got 'strict'
ValueError: context_management.preserve_recent must be at least 4, got 2

ValueError: Unsupported provider: openia

ValueError: Unsupported provider: openia. Supported: openai, anthropic, groq, ollama, azure, gemini, deepseek, mistral, openrouter

Without a model: ValueError: model_config.model is required.

ValueError: MCP server 'files': 'url' does not apply to stdio

ValueError: MCP server 'files': 'url' does not apply to stdio (it applies to sse, streamable_http)

A stdio server takes command and args; an HTTP server takes url.

ValueError: Invalid memory store type: postgres

Raised by MemoryRouter(...):

ValueError: Invalid memory store type: postgres. Use one of: in_memory, sql, redis, mongodb

PostgreSQL is MemoryRouter("sql") with DATABASE_URL pointing at it.

ImportError: Redis memory requires optional dependency

The store’s extra is not installed. The message names it, for example Install it with: pip install 'omnicoreagent[redis]'.

ValueError: MemoryRouter needs REDIS_URL (or DATABASE_URL, MONGODB_URI)

The store’s variable (REDIS_URL, DATABASE_URL or MONGODB_URI) is not set in the process that builds the router. Set it before the router is built; the store never falls back to process memory on its own, so history is not lost quietly. See the warning under Memory.

Agent settings

Every agent_config key and its default, generated from the code.

Models

Providers, model names, reasoning models.

Memory

Durable stores, history windows and summaries.

Security model

Policy, sandboxes and budgets in governance_config.

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Configuration

Configuration

All the layers in one agent

How it works

1. Environment variables

The model key

Memory

Workspace

Trace exporters

OmniServe and background runs

2. Agent configuration

Which limit to use

3. Model configuration

4. MCP tool configuration

5. Telemetry configuration

When things go wrong

Next

Agent settings

Models

Memory

Security model

​Configuration

​All the layers in one agent

​How it works

​1. Environment variables

​The model key

​Memory

​Workspace

​Trace exporters

​OmniServe and background runs

​2. Agent configuration

​Which limit to use

​3. Model configuration

​4. MCP tool configuration

​5. Telemetry configuration

​When things go wrong

​Next

Agent settings

Models

Memory

Security model

Configuration

All the layers in one agent

How it works

1. Environment variables

The model key

Memory

Workspace

Trace exporters

OmniServe and background runs

2. Agent configuration

Which limit to use

3. Model configuration

4. MCP tool configuration

5. Telemetry configuration

When things go wrong

Next