Configuration Guide

OmniCoreAgent supports configuration through environment variables, Python dictionaries, and specialized configuration objects.

1. Environment Variables

Environment variables are the best way to manage sensitive data like API keys and connection strings. For the first working agent, set only LLM_API_KEY. Memory and events default to in-memory storage, workspace files default to local disk, and OmniServe settings have server-side defaults. Add backend variables only when you are intentionally moving from local defaults to persistent or cloud infrastructure.

LLM API Key

OmniCoreAgent uses one public environment variable for hosted model credentials:

export LLM_API_KEY=your_provider_key

Set model_config["provider"] to choose the provider. The runtime reads LLM_API_KEY and internally passes it to LiteLLM for the selected provider. Do not configure provider-specific key names in OmniCoreAgent examples.

Optional Memory Backends

The default memory backend is in-memory and needs no environment variables. Set these only when conversation history must live outside the current process.

Backend	Variable	Example
Redis	`REDIS_URL`	`redis://localhost:6379/0`
SQL Database	`DATABASE_URL`	`postgresql://user:pass@localhost:5432/db`
MongoDB	`MONGODB_URI`	`mongodb://localhost:27017`

Optional MongoDB memory variables:

Variable	Purpose
`MONGODB_DB_NAME`	MongoDB memory database name. Defaults to `omnicoreagent`.
`MONGODB_COLLECTION`	MongoDB memory collection name. Defaults to `messages`.

Workspace Storage

Workspace storage is separate from memory storage. Memory stores conversation history. Workspace storage stores files, scratchpads, artifacts, subagent outputs, and tool offloads.

Backend	Variables
Local	`OMNICOREAGENT_WORKSPACE_BACKEND=local`, `OMNICOREAGENT_WORKSPACE_DIR=./workspace`
S3	`OMNICOREAGENT_WORKSPACE_BACKEND=s3`, `AWS_S3_BUCKET`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
R2	`OMNICOREAGENT_WORKSPACE_BACKEND=r2`, `R2_BUCKET_NAME`, `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`

Optional workspace variables:

Variable	Purpose
`OMNICOREAGENT_WORKSPACE_PREFIX`	Key prefix for S3/R2 workspace objects.
`AWS_REGION`	AWS region for S3 workspaces.
`AWS_ENDPOINT_URL`	Custom S3-compatible endpoint.

Optional Telemetry Export

Telemetry events and traces work in-process by default. Set exporter variables only when traces should leave the process for an OTLP-compatible backend.

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

Install the matching extra before exporting:

pip install "omnicoreagent[otel]"
pip install "omnicoreagent[langsmith]"
pip install "omnicoreagent[opik]"

Python configuration can pass exporters directly:

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",
        }
    ],
)

OmniServe

OmniServe reads these variables through OmniServeConfig. Environment variables override values passed in code. You do not need any OmniServe environment variables to start. Defaults bind the server to port 8000, enable the background API, start the background worker, and use an in-memory task store. Set only the values you want to override.

Variable	Default	Purpose
`OMNICOREAGENT_SERVE_HOST`	`0.0.0.0`	Server bind host. Must not be empty.
`OMNICOREAGENT_SERVE_PORT`	`8000`	Server port. Must be `1`-`65535`.
`OMNICOREAGENT_SERVE_WORKERS`	`1`	Direct OmniServe worker count. Must be `1`; run multiple processes behind a process manager for horizontal scaling.
`OMNICOREAGENT_SERVE_API_PREFIX`	`""`	API route prefix, such as `/api/v1`. Normalized to a leading slash with no trailing slash; whitespace is invalid.
`OMNICOREAGENT_SERVE_ENABLE_DOCS`	`true`	Enable Swagger UI.
`OMNICOREAGENT_SERVE_ENABLE_REDOC`	`true`	Enable ReDoc.
`OMNICOREAGENT_SERVE_CORS_ENABLED`	`true`	Enable 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`	`true`	Allow CORS credentials.
`OMNICOREAGENT_SERVE_AUTH_ENABLED`	`false`	Enable Bearer token auth. Requires a non-empty `OMNICOREAGENT_SERVE_AUTH_TOKEN` value.
`OMNICOREAGENT_SERVE_AUTH_TOKEN`	unset	Bearer token value used when auth is enabled.
`OMNICOREAGENT_SERVE_REQUEST_LOGGING`	`true`	Log incoming requests.
`OMNICOREAGENT_SERVE_LOG_LEVEL`	`INFO`	Server log level: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, or `TRACE`.
`OMNICOREAGENT_SERVE_REQUEST_TIMEOUT`	`300`	Request timeout in seconds. Set `0` to disable timeout middleware.
`OMNICOREAGENT_SERVE_RATE_LIMIT_ENABLED`	`false`	Enable in-process rate limiting.
`OMNICOREAGENT_SERVE_RATE_LIMIT_REQUESTS`	`100`	Requests per rate-limit window. Must be at least `1` when rate limiting is enabled.
`OMNICOREAGENT_SERVE_RATE_LIMIT_WINDOW`	`60`	Rate-limit window in seconds. Must be at least `1` when rate limiting is enabled.
`OMNICOREAGENT_BACKGROUND_ENABLED`	`true`	Expose background task endpoints.
`OMNICOREAGENT_BACKGROUND_AGENT_ID`	`default`	Agent id used when OmniServe registers the served agent for background work.
`OMNICOREAGENT_BACKGROUND_TASK_STORE`	`in_memory`	Background control-plane store: `in_memory`, `sql`, `redis`, or `mongodb`.
`OMNICOREAGENT_BACKGROUND_TASK_STORE_URL`	unset	SQL or Redis URL. A URL with no backend selects SQL; use `OMNICOREAGENT_BACKGROUND_TASK_STORE=redis` for Redis URLs.
`OMNICOREAGENT_BACKGROUND_TASK_STORE_URI`	unset	MongoDB URI. Setting this selects the MongoDB task store.
`OMNICOREAGENT_BACKGROUND_TASK_STORE_DATABASE`	`omnicoreagent`	MongoDB database name.
`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	Optional backend connect timeout in seconds.
`OMNICOREAGENT_BACKGROUND_START_WORKER`	`true`	Start the scheduler and worker loop during server lifespan.

The background task store is separate from MemoryRouter. MemoryRouter stores conversation/session history. The task store stores scheduler/runtime state: tasks, schedule cursors, runs, attempts, leases, heartbeats, retries, and cancellation flags. Defaults are intentionally light. Use sql, redis, or mongodb when background tasks must survive process restarts. Choose one durable backend per deployment. Use SQL/SQLite for local durability or simple single-node services. 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. For Redis durability, enable Redis persistence and keep task-store keys out of eviction. MongoDB task-store writes use majority write concern. Durable background examples. 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

2. Agent Configuration

The AgentConfig handles the runtime behavior of the agent, such as reasoning steps and resource limits.

agent_config = {
    "tool_call_timeout": 30,         # Max seconds per tool execution
    "max_steps": 15,                 # Max reasoning loops per run()
    "request_limit": 0,              # 0 = unlimited
    "total_tokens_limit": 0,         # 0 = unlimited
    "enable_subagents": True,        # Dynamic focused workers
    "enable_workspace_files": True,  # Default: workspace files for notes/logs/scratchpads
    "enable_agent_skills": True,     # Enable local skill discovery
    "enable_advanced_tool_use": True, # Enable BM25 tool retrieval
    "context_management": {"enabled": True},
    "tool_offload": {"enabled": True}
}

agent = OmniCoreAgent(
    ...
    agent_config=agent_config
)

When enable_subagents is true, OmniCoreAgent automatically enables workspace files because spawned workers write output, todos, logs, and scratchpads into the active workspace. For full harness-style workloads, pair dynamic subagents with context management and tool offloading. Context management checks the prompt before each model call; tool offloading keeps large tool payloads in workspace artifacts instead of feeding the full payload back into the loop.

3. Model Configuration

The model_config defines which LLM to use and its sampling parameters.

model_config = {
    "provider": "openai",
    "model": "gpt-4o",
    "temperature": 0.5,
    "max_tokens": 4000,
    "top_p": 0.9,
}

Supported provider values are: openai, anthropic, groq, ollama, azure, gemini, deepseek, mistral, openrouter, and cencori. Provider-specific runtime options currently supported by OmniCoreAgent are:

Azure: azure_endpoint, azure_api_version, azure_deployment
Ollama: ollama_host

4. MCP Tool Configuration

MCP tool servers are configured as a list of dictionaries. OmniCoreAgent only loads tools from MCP servers.

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

5. Persistence Configuration

Pass a MemoryRouter to customize conversation memory. Runtime evidence is recorded through telemetry, which defaults to in-memory storage.

from omnicoreagent import MemoryRouter

agent = OmniCoreAgent(
    ...
    memory_router=MemoryRouter("redis")
)

Best Practices

Use .env: Use a library like python-dotenv to load your environment variables during development.
Model Selection: Use smaller models (gpt-4o-mini) while building and testing your agent logic to save costs.
Limit Steps: Always set a reasonable max_steps to prevent the agent from entering infinite reasoning loops in case of tool failures.

Documentation Index

​Configuration Guide

​1. Environment Variables

​LLM API Key

​Optional Memory Backends

​Workspace Storage

​Optional Telemetry Export

​OmniServe

​2. Agent Configuration

​3. Model Configuration

​4. MCP Tool Configuration

​5. Persistence Configuration

​Best Practices