Configuration

The SDK is configured at three layers. From highest to lowest precedence:

Keyword arguments to egisai.init(...).
Environment variables read by egisai.init().
Defaults built into the package.

Most applications only need to set EGISAI_API_KEY and pass app= / env= to init(). Everything else has a sensible default.

Initialization parameters

egisai.init(
    *,
    api_key=None,
    app="default",
    env="production",
    base_url=None,
    on_block="raise",
    semantic_on_outage="allow",
    refresh_interval_seconds=10.0,
    enable_sse=True,
    enable_http_fallback=True,
    auto_stack_hints="loose",
    gateway=None,
    quiet=False,
)

Parameter	Default	What it does
`api_key`	—	Required. Your SDK API key (`egis_live_…`). Falls back to `EGISAI_API_KEY`.
`app`	`"default"`	Logical agent name — appears as an Agent on the dashboard.
`env`	`"production"`	Environment label for segmentation (`"dev"`, `"staging"`, `"prod"`, …).
`base_url`	Hosted control plane	Override only when directed by EgisAI. Falls back to `EGISAI_BASE_URL`.
`on_block`	`"raise"`	`"raise"` to raise `PermissionError`, `"stub"` to return a refusal-shaped response.
`semantic_on_outage`	`"allow"`	What `semantic_guard` rules do when the intent judge is unreachable. `"allow"` fails open (preserves availability); `"block"` fails closed. Deterministic local rules are unaffected.
`refresh_interval_seconds`	`10.0`	Polling interval for policy updates when the live channel is unavailable.
`enable_sse`	`True`	Subscribe to live policy updates.
`enable_http_fallback`	`True`	Patch `httpx` / `requests` for HTTP-level audit visibility.
`auto_stack_hints`	`"loose"`	Controls the agent-identity stack-frame inspector: `"loose"` honors common hints, `"strict"` requires the explicit `__egisai_agent__` marker, `"off"` disables stack inspection.
`gateway`	`False`	Route OpenAI chat-completions calls through the inline Gateway — enforcement moves server-side, `set_context` still works. Falls back to `EGISAI_GATEWAY`.
`gateway_on_outage`	`"local"`	Gateway mode only: what happens when the Gateway is unreachable. `"local"` re-runs the call on your own provider client under in-process governance; `"fail"` propagates the error. A 4xx from the Gateway is a decision and is never retried locally. Falls back to `EGISAI_GATEWAY_ON_OUTAGE`.
`quiet`	`False`	Suppress the one-line startup banner on stderr.

Every parameter has a corresponding section in the init reference.

Environment variables

Variable	Purpose
`EGISAI_API_KEY`	SDK API key if not passed as `api_key=`.
`EGISAI_BASE_URL`	Override the control plane URL. Use only if directed to do so.
`EGISAI_GATEWAY`	Set `1` to enable gateway mode without a code change.
`EGISAI_GATEWAY_ON_OUTAGE`	`local` or `fail` — gateway-mode behavior when the Gateway is unreachable.
`EGISAI_AGENT_ENSURE_TIMEOUT_SECS`	Budget for the inline agent-registration round-trip (default `2`). Registration is best-effort; a call proceeds unattributed-but-governed if it can’t complete.
`EGISAI_AGENT_ENSURE_BACKOFF_SECS`	How long to wait before retrying a failed agent registration (default `60`). `0` retries on every call.
`EGISAI_RETRY_AFTER_MAX_SECS`	Ceiling on a server-supplied `Retry-After` the SDK will honor (default `5`).

Keep your API key out of source control. Use environment variables, a secrets manager, or your platform’s configuration store.

Recommended setups

Local development

export EGISAI_API_KEY="egis_live_…"

import egisai
egisai.init(app="dev-bot", env="dev")

Production with stub mode

import egisai
egisai.init(
    app="customer-support-bot",
    env="production",
    on_block="stub",
    quiet=True,
)

Strict / restricted networks

If your environment blocks long-lived HTTP connections, disable the live update channel and rely on polling:

egisai.init(
    app="bot",
    env="production",
    enable_sse=False,
    refresh_interval_seconds=30.0,
)

Fail closed on judge outages

If your workload uses semantic_guard as its primary defense for a sensitive category and you’d rather refuse a call than risk an unvetted one when the judge is unreachable, switch the policy from fail-open to fail-closed:

egisai.init(
    app="regulated-bot",
    env="production",
    semantic_on_outage="block",
)

Deterministic local checks (PII detection, regex denylists, model allow-lists, prompt-size caps) are unaffected — they always run locally.

Custom HTTP clients only

If your application doesn’t use any official provider SDK and instead calls endpoints directly via httpx or requests:

egisai.init(
    app="custom-llm-bot",
    env="production",
    enable_http_fallback=True,    # default; shown for clarity
)

If you don’t need HTTP fallback (because you only use official SDKs), turn it off to skip patching:

egisai.init(
    app="bot",
    env="production",
    enable_http_fallback=False,
)

Verifying configuration at startup

The startup banner echoes the resolved configuration:

✓ [egisai] active — app=customer-support-bot env=production on_block=raise integrations=[openai, anthropic] policies=12

If you don’t see this line, either init() was never called, or you passed quiet=True. Set quiet=False and re-run to confirm the SDK is active.

What’s next

Blocking behavior

Choose between raise and stub modes.

Multi-agent context

Distinguish several agents in one process.

Get started

Core concepts

Integrations

Gateway

Coverage

Guides

Operations

Initialization parameters

Environment variables

Recommended setups

Local development

Production with stub mode

Strict / restricted networks

Fail closed on judge outages

Custom HTTP clients only

Verifying configuration at startup

What’s next

Blocking behavior

Multi-agent context

​Initialization parameters

​Environment variables

​Recommended setups

​Local development

​Production with stub mode

​Strict / restricted networks

​Fail closed on judge outages

​Custom HTTP clients only

​Verifying configuration at startup

​What’s next

Blocking behavior

Multi-agent context

Initialization parameters

Environment variables

Recommended setups

Local development

Production with stub mode

Strict / restricted networks

Fail closed on judge outages

Custom HTTP clients only

Verifying configuration at startup

What’s next