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.5.1 and Python 3.10 or newer.

Install

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

pip install deepintshield

Provider and framework integrations are optional extras:

Extra	Adds
`openai`	OpenAI sync client
`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 client 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
`crewai`	CrewAI binder and enforcement integration
`openai-agents`	OpenAI Agents SDK binder and enforcement integration
`llamaindex`	LlamaIndex model/embedding binders and enforcement
`autogen`	AutoGen/AG2 model binder and enforcement
`temporal`, `strands`, `google-adk`	Durable/plugin runtime enforcement integrations
`azure`	Azure Identity support for Entra workload identity
`all`	Every optional integration above

For example:

pip install "deepintshield[openai,langgraph]"

First guarded request

export DEEPINTSHIELD_VIRTUAL_KEY="sk-ds-your-virtual-key"

from deepintshield import DeepintShield

with DeepintShield.from_env() as shield:
    client = shield.openai()
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello"}],
    )
    print(response.choices[0].message.content)

DeepintShield.from_env() defaults to https://app.deepintshield.com. Creating the SDK client does not contact the gateway. Calls, provider construction that needs a key, Agentic discovery, and identity resolution can perform I/O.

Choose the right surface

Need	Public surface	Return type
Native provider client	`shield.openai()`, `.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 →

Error codes

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

Open →

Runtime expectations

The SDK is synchronous at its core; 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.