- Supported direct provider SDKs (
openai,anthropic,google-genai,google-generativeai, AWS Bedrock viaboto3) 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,
httpxandrequestsare wrapped for HTTP-level audit visibility. - Background workers are started for live updates and audit delivery.
egisai.shutdown()is registered withatexitto flush events on exit.
init() is idempotent. Calling it twice in the same process is a no-op
after the first call.
Parameters
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.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.Free-form environment label (
"dev", "staging", "prod", …). Used for
segmentation on the dashboard. Has no effect on policy evaluation itself.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).How blocked calls are surfaced to your code:
"raise"— raisePermissionError."stub"— return a framework-shaped refusal object so the application keeps running.
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 whensemantic_guardis your primary defense for a workload and you’d rather pause than risk an unvetted call.
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.
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.
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.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-typedagentlocal)."strict"— only the explicit__egisai_agent__marker is honored. Quieter; won’t accidentally pick up an enclosing test’sagent_namevariable."off"— disables stack inspection entirely; the resolver moves straight to class-name introspection and below.
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.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.
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.Returns
None. Side effects (patching, background workers) happen in place.
Raises
RuntimeError— when neitherapi_key=norEGISAI_API_KEYprovides a key.ValueError— whenon_blockis not"raise"or"stub", whensemantic_on_outageis not"allow"or"block", whengateway_on_outageis not"local"or"fail", or whenauto_stack_hintsis not"loose","strict", or"off".
Example
Idempotence
egisai.shutdown() first.
What’s next
set_context
Attach per-call metadata after init.
Configuration guide
Walks each option in plain English.