egisai.init()

egisai.init(
    *,
    api_key: str | None = None,
    app: str = "default",
    env: str = "production",
    base_url: str | None = None,
    on_block: str = "raise",
    semantic_on_outage: str = "allow",
    refresh_interval_seconds: float = 10.0,
    enable_sse: bool = True,
    enable_http_fallback: bool = True,
    auto_stack_hints: str = "loose",
    gateway: bool | None = None,
    gateway_on_outage: str = "local",
    quiet: bool = False,
) -> None

Activate egisai for the current Python process. After this call returns:

Supported direct provider SDKs (openai, anthropic, google-genai, google-generativeai, AWS Bedrock via boto3) are patched in place.
Supported agent frameworks (openai-agents, claude-agent-sdk, langchain / langgraph, crewai, autogen, agno, strands-agents, smolagents, llama-index, pydantic-ai, google-adk) are patched for identity attribution and gating where applicable.
Optionally, httpx and requests are wrapped for HTTP-level audit visibility.
Background workers are started for live updates and audit delivery.
egisai.shutdown() is registered with atexit to flush events on exit.

init() is idempotent. Calling it twice in the same process is a no-op after the first call.

Parameters

str | None

default:"None"

Your platform API key (the one starting with egis_live_ that you created on the dashboard’s API Keys page).If not provided, falls back to the EGISAI_API_KEY environment variable.Required — init() raises RuntimeError if neither source provides a key.

str

default:"\"default\""

Logical agent name. The platform auto-creates an Agent matching this name in your org if one doesn’t exist; subsequent calls from this SDK instance are attributed to it for auditing.Set this to a stable, machine-friendly identifier (e.g. "customer-support-bot") so it reads well on the dashboard.

str

default:"\"production\""

Free-form environment label ("dev", "staging", "prod", …). Used for segmentation on the dashboard. Has no effect on policy evaluation itself.

str | None

default:"None"

Override the platform URL. Defaults to EGISAI_BASE_URL if set, otherwise the hosted control plane.Only set this if directed to do so by EgisAI (for example for a regional deployment or an enterprise install).

"raise" | "stub"

default:"\"raise\""

How blocked calls are surfaced to your code:

"raise" — raise PermissionError.
"stub" — return a framework-shaped refusal object so the application keeps running.

See Blocking behavior for guidance.

"allow" | "block"

default:"\"allow\""

Behavior of semantic_guard (intent-judge) policies when the judge service can’t be reached:

"allow" (default, fail-open) — the rule is treated as a no-op so the user’s call still proceeds. Recommended for availability-sensitive workloads.
"block" (fail-closed) — the call is refused when the judge is unreachable. Recommended when semantic_guard is your primary defense for a workload and you’d rather pause than risk an unvetted call.

Deterministic local checks (PII, regex, model allow-lists, size caps) are unaffected by this setting — they always run locally.

float

default:"10.0"

How often to poll for policy changes if the live update channel is unavailable. Lower values mean faster picks-up of dashboard changes at the cost of more polling traffic.

bool

default:"True"

Subscribe to live policy and configuration updates when supported. Falls back to polling on connection failure. Disable if your environment blocks long-lived HTTP connections.

bool

default:"True"

Patch httpx and requests for HTTP-level audit visibility. Useful when your application calls model endpoints directly rather than through one of the official provider SDKs. See HTTP clients.

"loose" | "strict" | "off"

default:"\"loose\""

Controls the stack-frame inspector used by the agent identity resolver when it can’t find an identity any other way. Setting this affects only auto-detection — explicit egisai.set_context(agent=…) and with egisai.agent(…): always win.

"loose" (default) — walks a small number of stack frames looking for common identity hints (__egisai_agent__, agent_name, egisai_agent, or a string-typed agent local).
"strict" — only the explicit __egisai_agent__ marker is honored. Quieter; won’t accidentally pick up an enclosing test’s agent_name variable.
"off" — disables stack inspection entirely; the resolver moves straight to class-name introspection and below.

bool | None

default:"None"

Route OpenAI chat-completions calls through the platform’s inline Gateway instead of evaluating policies in-process. Your calling convention doesn’t change — the SDK reroutes the call and injects X-Egis-Api-Key (plus X-Egis-Agent when an explicit identity is active via set_context / with egisai.agent(…), and the other set_context fields as X-Egis-* context headers) automatically; enforcement and audit happen server-side, and the local gate is skipped for rerouted calls so nothing is governed twice.Everything the Gateway doesn’t carry — the Responses API, Anthropic / Google / Bedrock SDKs, agent frameworks, MCP — keeps the normal in-process governance path, and Azure OpenAI clients are never rerouted. Requires the inline_gateway feature on your plan.Defaults to False; also settable via the EGISAI_GATEWAY=1 environment variable.

"local" | "fail"

default:"\"local\""

Gateway mode only: what happens when the Gateway itself can’t be reached. Rerouting puts the Gateway inline on your call path, so this decides whether its availability becomes yours.

"local" (default) — re-run the call against your own provider client and govern it in-process from the last-known-good policy cache. Your traffic keeps flowing; governance degrades from server-side to client-side, and the audit row is written by the SDK.
"fail" — let the error propagate, keeping the Gateway a hard enforcement boundary.

Only “we never got an answer” qualifies: a transport failure, or HTTP 502 / 503 / 504. A 4xx is never retried locally — it’s a decision (policy block, auth, quota), and retrying it would turn an enforced refusal into an allowed call. A bare 500 also propagates, because unlike 502/503/504 it can be raised after the Gateway already forwarded your request upstream, where a retry could bill you twice.The fallback also requires that your client can reach the provider directly. In BYOK vault mode your provider key lives server-side, so there’s nothing to fall back to and the call fails with the Gateway’s own error rather than a confusing provider 401. The same applies to egisai.Client, which targets the Gateway by construction.Every fallback logs a warning and increments egisai.diagnostics()["gateway_fallback_total"]. Alert on that counter — a non-zero value means enforcement is running on cached policy rather than live policy.Also settable via the EGISAI_GATEWAY_ON_OUTAGE environment variable.

bool

default:"False"

Suppress the one-line ✓ [egisai] active … startup banner on stderr.

Returns

None. Side effects (patching, background workers) happen in place.

Raises

RuntimeError — when neither api_key= nor EGISAI_API_KEY provides a key.
ValueError — when on_block is not "raise" or "stub", when semantic_on_outage is not "allow" or "block", when gateway_on_outage is not "local" or "fail", or when auto_stack_hints is not "loose", "strict", or "off".

Example

import os
import egisai

egisai.init(
    api_key=os.environ["EGISAI_API_KEY"],
    app="customer-support-bot",
    env=os.environ.get("APP_ENV", "production"),
    on_block="raise",
)

Idempotence

egisai.init(api_key="…", app="bot")
egisai.init(api_key="…", app="bot")   # no-op; logged at debug level

If you need to re-activate with different parameters, call egisai.shutdown() first.

Reference

Parameters

Returns

Raises

Example

Idempotence

What’s next

set_context

Configuration guide

​Parameters

​Returns

​Raises

​Example

​Idempotence

​What’s next

set_context

Configuration guide

Parameters

Returns

Raises

Example

Idempotence

What’s next