Configuration and transport
Constructors
Section titled “Constructors”Use keyword arguments directly or pass a ShieldConfig:
from deepintshield import DeepintShield, ShieldConfig
config = ShieldConfig( virtual_key="sk-ds-your-virtual-key", base_url="https://gateway.example.com/", timeout=20.0, app_name="support-copilot", agent_name="refund-agent", requester="alice@example.com", requester_role="support", persist=True, default_headers={"x-request-source": "web"},)
shield = DeepintShield.from_config(config)| Setting | Default | Meaning |
|---|---|---|
virtual_key | empty | Workspace virtual key. Key-dependent helpers raise if it is missing. |
base_url | https://app.deepintshield.com | Hosted or self-managed gateway root. Whitespace and trailing / are removed. |
timeout | 30.0 seconds | Timeout for the SDK-owned synchronous httpx.Client; also the default in native OpenAI constructor options. |
default_headers | empty | Headers merged into SDK and provider requests. |
app_name | deepintshield | Application attribution. |
agent_name | empty | Stable Agentic Registry lookup key. Required for Agentic governance - there is no default. |
requester | sdk-user | Default acting user/service identifier: the person or service the agent acts for. It takes part in authorization and does not name the registering developer (see registered_by). |
requester_role | member | Default role sent to guardrail/RAG evaluation. |
registered_by | None | The explicit way to name the registering developer: their work e-mail, sent as registered_by_email when the agent is registered. The gateway maps it to a person in the workspace directory and e-mails it; it is not verified and grants nothing. It is proposed as the accountable owner, which the administrator confirms or changes. One registration keeps its first address: a different one is refused with registration_requester_mismatch. With None, an e-mail-shaped requester is offered only as an advisory hint, which the gateway uses only for a person the organization placed in the workspace and ignores otherwise, without refusing. "" sends no registering address; any other value that is not an e-mail address is a configuration_error. |
persist | True | Default evidence-persistence flag on explicit evaluations. |
ShieldConfig.metadata is available as a configuration data field, but SDK
3.2.3 does not automatically attach it in DeepintShield.from_config(). Pass
metadata= to each guardrail or RAG evaluation that needs it.
Environment variables
Section titled “Environment variables”from deepintshield import DeepintShield
shield = DeepintShield.from_env()| Variable | Default |
|---|---|
DEEPINTSHIELD_VIRTUAL_KEY | empty |
DEEPINTSHIELD_BASE_URL | https://app.deepintshield.com |
DEEPINTSHIELD_GATEWAY_URL | legacy fallback when DEEPINTSHIELD_BASE_URL is unset |
DEEPINTSHIELD_TIMEOUT | 30 |
DEEPINTSHIELD_APP_NAME | deepintshield |
DEEPINTSHIELD_AGENT_NAME | empty |
DEEPINTSHIELD_REQUESTER | sdk-user |
DEEPINTSHIELD_REQUESTER_ROLE | member |
DEEPINTSHIELD_REGISTERED_BY | unset: no explicit registering address, and an e-mail-shaped DEEPINTSHIELD_REQUESTER is offered only as an advisory hint; set but empty: no registering address is sent |
DEEPINTSHIELD_PERSIST | true; 0, false, and no disable it |
An invalid DEEPINTSHIELD_TIMEOUT value fails during configuration parsing.
Environment values do not validate the key against the gateway until a request
is made.
DEEPINTSHIELD_REGISTERED_BY (constructor argument registered_by) is the
explicit way to name the developer who registers an agent. The gateway maps
the address to a person in the workspace directory and e-mails it. It is not
verified and grants nothing; the administrator confirms the owner. One
registration keeps its first address, and a different address is refused with
registration_requester_mismatch. DEEPINTSHIELD_REQUESTER keeps its own
meaning, the person the agent acts for, and changes authorization: do not set
it to your own e-mail in order to be notified. When no registering address is
set, an e-mail-shaped requester is only an advisory hint, which the gateway
uses only for a person the organization placed in the workspace and ignores
otherwise, without refusing the run. The
pending line ends with You will be notified at <email>. only when the gateway
confirmed the address. See
Registration lifecycle.
Workload identity credentials
Section titled “Workload identity credentials”The variables above configure the gateway connection. A governed agent also
needs proof for its selected identity provider. Direct mode supplies workload
credentials. For Entra, the SDK builds its credential from what the host
actually provides, each source tried once in this order: service-principal
environment variables (AZURE_CLIENT_ID and AZURE_TENANT_ID with a client
secret or certificate), workload identity federation
(AZURE_FEDERATED_TOKEN_FILE), then a managed identity. A host with none of
these fails fast with credential_host_identity_missing, printed once per
process and remembered for the credential’s lifetime; a failed exchange is
credential_exchange_failed and is retried after 60 seconds. When no
environment variable names an identity, the SDK probes the Azure instance
metadata endpoint once, for at most one second; set
DEEPINTSHIELD_ENTRA_SKIP_IMDS_PROBE=1 on laptops and CI runners to skip the
probe.
New Entra providers default to gateway exchange, so the workload needs no Azure
host identity: install the runtime extra and let an administrator authorize
the SDK’s durable runtime key; the gateway holds its separate blueprint
credential and exchanges the Entra token. See the complete
local gateway and math-agent setup.
Provisioning management credentials stay on the gateway server; they are
never workload credentials or the blueprint’s runtime credential.
For a provisioned Keycloak, Auth0, or Okta client using a secret, consume the
customer Vault record only after ready: true. The
SDK launcher example
maps it to OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_TOKEN_ENDPOINT, and the
appropriate token request options without printing secrets. Workload access to
Vault is configured separately.
OIDC_SCOPES supplies space-separated per-client scopes in SDK builds containing
the override. If unset, the SDK uses the verifier’s scope defaults; if explicitly
empty, it omits the token request’s scope parameter. For Entra federation,
public-key authentication, and audience settings, follow
Agent workload identity.
endpoint(provider) appends a gateway-mounted provider name without adding API
version segments:
shield.endpoint("openai") # https://app.deepintshield.com/openaishield.openai_base_url() # sameshield.anthropic_base_url() # .../anthropicshield.bedrock_endpoint_url() # .../bedrockshield.genai_base_url() # .../genaiThe dedicated compatibility helpers also expose /langchain, /litellm, and
/pydanticai. Passthrough helpers use these exact roots:
| Helper | Path |
|---|---|
openai_passthrough_base_url() | /openai_passthrough/v1 |
anthropic_passthrough_base_url() | /anthropic_passthrough |
genai_passthrough_base_url() | /genai_passthrough |
Header helpers
Section titled “Header helpers”shield.headers() is the minimal SDK header set: content-type, configured
defaults, and x-deepintshield-vk when a key is present.
shield.create_headers() adds transport attribution:
x-deepintshield-appx-deepintshield-agent- omitted entirely whenagent_nameis unset, rather than sent emptyx-deepintshield-requesterx-deepintshield-requester-role- optionally
X-Agent-Tokenwithidentity=True
from openai import OpenAI
client = OpenAI( base_url=shield.endpoint("openai"), api_key=shield.api_key(), default_headers=shield.create_headers(),)Explicit extra values take precedence over generated headers. Treat an
X-Agent-Token as a credential and never log the returned header dictionary.
identity=True can perform lazy Agentic discovery/token acquisition; it is off
by default so ordinary transport construction does not wait for identity.
Generic native-client wiring
Section titled “Generic native-client wiring”For native OpenAI clients, use the shared public constructor options:
from openai import OpenAI
with OpenAI(**shield.openai_config(max_retries=2)) as client: response = client.chat.completions.create( model="anthropic/claude-sonnet-4-5", messages=[{"role": "user", "content": "Hello"}], )openai_config() returns a fresh dictionary containing base_url, api_key,
timeout, and merged default_headers, plus your native constructor options.
It performs no model discovery or inference request; identity=True can trigger
identity lookup. It preserves callable API keys and caller-supplied transports.
The same options work with AsyncOpenAI. The request’s model ID selects the
provider; there is no per-provider OpenAI client configuration to maintain.
Use shield.openai() / shield.async_openai() when you also want the
SDK’s transport hooks for prompt caching and per-request agent-selector header
normalization. openai_config() supplies constructor settings only.
The installed OpenAI SDK chooses its compatible HTTP transport: supported
OpenAI 2.x uses httpx, while 3.x uses httpx2. A custom http_client must be
accepted by the installed native SDK. Do not pass shield.http_client() to a
library that requires a different transport implementation.
For other libraries accepting a URL/header pair or an httpx.Client:
base_url, headers = shield.connection(provider="openai")
with shield.http_client(provider="openai") as http: response = http.post( "/v1/chat/completions", json={"model": "gpt-4o-mini", "messages": []}, )http_client() returns a new httpx.Client; close it separately. A supplied
base_url= overrides the provider-derived URL. This helper is useful only for
libraries that accept an httpx.Client; prefer the typed provider builders when
available.
Raw SDK requests
Section titled “Raw SDK requests”payload = shield.request( "POST", "/api/guardrails/evaluate", json_body={ "stage": "input", "actor_type": "sdk_user", "actor_id": "alice@example.com", "input": "text to inspect", },)request() joins base_url and path, sends JSON through the SDK-owned client,
returns the decoded JSON value, and raises DeepintShieldError for HTTP status
400 or higher. For a non-JSON success response it returns
{"raw": response.text}.
It does not implement retries, pagination, file upload, incremental streaming,
or an asynchronous transport. Incremental chat is provided separately by
shield.chat(stream=True) and ChatCompletionStream.
Connection and timeout failures preserve their httpx.HTTPError or
httpx.TimeoutException type and receive SDK error metadata. Catch those
separately from DeepintShieldError, or read their annotation with
get_exception_error_code() as described in Error codes.
Lifetime and process use
Section titled “Lifetime and process use”Prefer a context manager or call close() during application shutdown:
with DeepintShield.from_env() as shield: result = shield.guard(stage="input", input="hello")close() is idempotent, unregisters the client from Agentic framework
resolution, and closes its connection pool. Do not use a closed instance for
new requests. If several live clients share a process, scope Agentic execution
with with shield.agentic.run(...): so automatic framework enforcement can
select the correct workspace and key.
Close native clients and framework-owned resources using their own lifecycle:
async def answer(): with DeepintShield.from_env() as shield: async with shield.async_openai() as client: response = await client.chat.completions.create( model="openai/gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}], ) return response.choices[0].message.contentClosing shield does not close a separately created OpenAI, AsyncOpenAI,
or framework model client. Reuse those native clients within the application’s
lifetime and close any partial streams before shutdown.
See Error codes for the complete structured transport-error contract.