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 targets SDK 3.2.0, Server 3.2.0, and Python 3.10 or newer, including the guardrail decision corrections from 2.8.5. SDK 3.0.0 removed 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 3.2.0 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.

The 3.2.0 release notes cover two-run agent registration, deferred activation, registration e-mails, and the registered_by setting. The 3.1.0 release notes cover the current agent workspace, runtime identity, and optional server-managed LangGraph execution. The worker and gateway need their own deployment upgrade.

Install

Install the core package for configuration, direct HTTP calls, guardrails, RAG, and Agentic governance:

python -m pip install --upgrade "deepintshield==3.2.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
`runtime`	Cryptography and durable key storage for gateway runtime authentication
`runtime-aws`	Runtime-key support plus AWS outbound identity federation
`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.2.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

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.

First governed agent

For Microsoft configuration from the beginning and test2.py running against http://localhost:8080, follow Microsoft Entra with a local gateway. The gateway stores the Entra credentials; the SDK enrolls a runtime key and keeps the native LangGraph application code.

Follow the simple-math-agent walkthrough to register a LangGraph workload, prove its identity, review its code, and grant the two tool actions it needs. Keep one stable agent name and workload identity for each logical agent and environment across runs and replicas.

Identity providers configures token verification. Provisioning → Authorize provisioning separately attaches customer-approved management access and inherits the verifier’s settings. A new shared Entra verifier can start with an empty explicit identity list; it admits nobody until identities are added. Identity creation and a successful provider check do not replace workload proof or access approval. See workload identity setup for credential delivery and recovery.

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

Configuration & transport

Constructors, environment variables, endpoints, headers, lifecycle, and raw requests.

Open →

Chat & guardrails

Native chat clients, explicit evaluation, stages, decisions, and blocking behavior.

Open →

RAG

Chunk contracts, filtering, retriever hooks, and embedder hooks.

Open →

Agents & Agentic

Explicit agent guards, PDP enforcement, identity, registration, and framework boundaries.

Open →

MCP

Official MCP sessions, third-party adapters, and stable coded failures.

Open →

Providers & frameworks

Supported builders, binders, endpoint choices, and optional dependencies.

Open →

Multimodal inference

Image, PDF, audio, video, file and streaming examples, with current inspection coverage.

Open →

Error codes

Central catalog, structured exception handling, retry guidance, and the stable-code contract.

Open →

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.