Configuration & transport
Constructors, environment variables, endpoints, headers, lifecycle, and raw requests.
Python SDK overview
The deepintshield package is the supported Python entry point for routing native
provider and framework clients through DeepIntShield and for calling the explicit
guardrail, RAG, MCP, and Agentic APIs. This reference is audited against SDK
2.8.3 and Python 3.10 or newer, with the RAG contract updated for
3.0.0 and the guardrail decision corrections from 2.8.5. SDK 3.0.0
removes the former RAG acl_tags argument. Authorize documents in the application
before content safety evaluation; see the RAG migration notes.
allow_with_redaction is classified as allowed in 2.8.5 and later.
Use the native OpenAI SDK as the primary inference client for the gateway’s 29 provider identities, selecting each model’s supported operations. Frameworks retain orchestration and native provider clients remain optional for features outside the common API. The all-provider guide describes the 2.8.3 inference surface, including async inference and model operations.
Using GPT-6 Astra? Follow Astra with Responses for endpoint, request, output, and MCP filter examples. Changing only model in a Chat Completions example is insufficient when function tools are present, including schemas injected by the gateway. Astra does not support reasoning effort none.
Install
Section titled “Install”Install the core package for configuration, direct HTTP calls, guardrails, RAG, and Agentic governance:
python -m pip install --upgrade "deepintshield==3.0.0"The native OpenAI dependency is included in core for primary inference.
The openai extra remains an installation alias for compatibility. Other
provider and framework integrations are optional extras:
| Extra | Adds |
|---|---|
openai | Compatibility alias for the native OpenAI sync/async client included in core |
anthropic | Anthropic sync client |
anthropic-mcp | Anthropic’s maintained client-side MCP helpers plus the official MCP client |
bedrock | boto3 Bedrock Runtime client |
genai | Google GenAI client and managed Gemini context-cache wrapper |
litellm | LiteLLM completion helper |
langchain | LangChain model integration |
mcp | Official MCP Python SDK >=1.29,<2 and Streamable HTTP transport |
langchain-mcp | Maintained langchain-mcp-adapters integration plus the official MCP client |
langgraph | LangGraph and LangChain model/embedding binders |
pydanticai | PydanticAI model and agent builders |
openai-agents | OpenAI Agents SDK binder and enforcement integration |
llamaindex | LlamaIndex model/embedding binders and enforcement |
autogen | AutoGen/AG2 model binder and enforcement |
temporal | Durable activity enforcement; use native async inference inside activities |
strands, google-adk | Native model binders and automatic tool enforcement integrations |
azure | Azure Identity support for Entra workload identity |
dpop | Cryptographic support for workload-token proof of possession |
all | Compatible aggregate of provider and framework integrations |
For example:
python -m pip install --upgrade "deepintshield[langgraph]==3.0.0"OpenAI is constrained to >=2.32.0,<4 by this release. Install the optional
extras used by your application; some current frameworks require different
OpenAI major versions. See the dependency combinations
before combining frameworks in one environment.
The [all] aggregate supports Python 3.14 with compatible framework versions.
Pin the SDK version when installing it to prevent fallback to an older SDK.
Individual extras can select newer framework releases.
First guarded request
Section titled “First guarded request”export DEEPINTSHIELD_VIRTUAL_KEY="sk-ds-your-virtual-key"from deepintshield import DeepintShield
with DeepintShield.from_env() as shield: with shield.openai() as client: response = client.chat.completions.create( model="openai/gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}], ) print(response.choices[0].message.content)DeepintShield.from_env() defaults to https://app.deepintshield.com. Preparing
the default OpenAI connection does not discover models or issue inference
requests. identity=True opts into Agentic discovery/token acquisition, which
can perform I/O. Native provider clients own their lifecycle; close them
separately from shield.
Choose the right surface
Section titled “Choose the right surface”| Need | Public surface | Return type |
|---|---|---|
| Primary inference client | shield.openai(), .async_openai() | Native OpenAI / AsyncOpenAI |
| Application-owned inference client | shield.openai_config() | Native constructor settings |
| Optional native provider client | .anthropic(), .bedrock(), .genai() | Provider SDK object |
| Unified chat call | shield.chat(..., stream=False) / shield.chat(..., stream=True) | dict / ChatCompletionStream |
| Explicit content/tool guard | shield.guard(...), shield.agent.* | GuardrailResult or a blocking exception |
| RAG policy evaluation | shield.rag.evaluate(...), .filter(...) | Gateway response and/or allowed chunks |
| Native MCP protocol | shield.mcp.connect() | Official mcp.ClientSession and MCP result types |
| Framework MCP configuration | shield.mcp.connection() | DeepIntShield /mcp URL and guarded headers |
| Native framework transport | shield.bind("...") | A framework binder |
| Agentic PDP enforcement | shield.agentic.* | Decision, decorated tools, or framework integration objects |
| Manual gateway transport | shield.connection(), .create_headers(), .http_client() | URL/headers or httpx.Client |
The shield.agent and shield.agentic names are intentionally different:
agent is the explicit five-stage guardrail helper, while agentic is the
identity, policy-decision, registration, approval, and tool-enforcement layer.
Documentation map
Section titled “Documentation map”Chat & guardrails
Native chat clients, explicit evaluation, stages, decisions, and blocking behavior.
RAG
Chunk contracts, filtering, retriever hooks, and embedder hooks.
Agents & Agentic
Explicit agent guards, PDP enforcement, identity, registration, and framework boundaries.
MCP
Official MCP sessions, third-party adapters, and stable coded failures.
Providers & frameworks
Supported builders, binders, endpoint choices, and optional dependencies.
Multimodal inference
Image, PDF, audio, video, file and streaming examples, with current inspection coverage.
Error codes
Central catalog, structured exception handling, retry guidance, and the stable-code contract.
Runtime expectations
Section titled “Runtime expectations”The direct gateway helpers are synchronous; shield.async_openai() returns a
native asynchronous inference client. shield.mcp.connect() is an asynchronous
context manager because it yields the official asynchronous
mcp.ClientSession. Native provider objects retain their provider’s normal
sync/async behavior, and Agentic integrations support both synchronous and
asynchronous framework boundaries where the framework does. The SDK does not
add a general retry policy to request(), RAG, or MCP calls. Apply retries only
to catalog entries marked retryable, and keep a stable idempotency or tool-call
identifier for side-effecting operations.
Latency and throughput depend on the gateway deployment, selected policies, provider, payload, cache state, and network. Benchmark the complete path with your payloads and concurrency; SDK-local helpers and catalog lookups do not establish an end-to-end latency guarantee.