Agents and Agentic governance
The SDK exposes two agent-related layers:
| Surface | Purpose | Gateway route |
|---|---|---|
shield.agent | Explicit input/output/action/MCP guardrail checks | /api/guardrails/evaluate |
shield.agentic | Identity-aware policy decisions, Agentic Registry discovery, blueprint attestation, approvals, obligations, and automatic tool enforcement | /api/agentic-new/* with older-gateway compatibility where implemented |
Use shield.agent when content/tool classification is enough. Use
shield.agentic when execution depends on the registered agent, acting user,
resource permission, delegation, tool/action, approval, or workload identity.
This reference targets SDK 3.2.3 with Server 3.2.3. The walkthrough below uses local execution. If your operator enables server-managed execution on the gateway (for every workspace at once, or for selected workspaces), follow Server-managed agent execution: submit the saved script once, complete its review, and read the result under Runtime access → Server run. With a gateway and SDK that support submission IDs, running the unchanged script again starts a new server run under the existing approved registration instead of running the graph locally. An active or uncertain run must be resolved first.
Plans and workspace security
Section titled “Plans and workspace security”Developer and Team workflows run without Agentic Security registration, blueprint review, or approval calls. On Business and above, security is enabled by default. A workspace administrator can turn Agentic Security off or on from Agentic → Agents → Needs attention.
The SDK reads the authenticated workspace setting before each new run. When
security is off, it executes the workflow without Agentic governance or run-ledger
calls. Existing activity remains available where the plan includes it; these
unguarded runs do not appear as governed runs. Gateway credentials, workspace
isolation, ordinary LLM guardrails, and Virtual Key tool restrictions still apply.
Turning security back on restores registration, blueprint, and approval checks
on the next invocation. Network and authentication failures never turn it off.
This requires a gateway and SDK version supporting /api/agentic-new/runtime-config;
older gateways retain their existing enforcement behavior.
An already-enabled Block runtime drift policy remains fail-closed even after a plan downgrade. Explicitly disable that policy before switching off Agentic Security; turning off security cannot silently bypass it. An enabled workspace requirement for task mandates follows the same rule: remove that requirement explicitly before disabling security. A supplied task mandate also requires an available, enabled Agentic runtime.
Explicit agent guardrails
Section titled “Explicit agent guardrails”shield.agent.check_input("user message")shield.agent.evaluate_tool( name="ledger_read", args={"account": "A-7"}, action_class="read",)shield.agent.check_output("assistant response")See Chat and guardrails for result and exception semantics.
Automatic Agentic enforcement
Section titled “Automatic Agentic enforcement”Constructing a live DeepintShield client installs idempotent guards for
supported framework modules already imported and watches supported late
imports. Current integrations cover LangGraph, LangChain, LlamaIndex,
AutoGen/AG2, PydanticAI, OpenAI Agents SDK, AWS Strands, Google ADK,
Temporal, and the Hermes tool dispatcher. A framework is inspected only after
its package has finished importing: a nested submodule import (for example a
helper that LangChain loads during its own initialization) defers the guard until
the enclosing import completes, avoiding instrumentation of partially
initialized modules. An unsupported version still stops with
governance_configuration_error rather than importing ungoverned.
LiteLLM completions are provider inference calls. They use the gateway’s normal
inference policies and do not create an Agentic tool registration or blueprint,
including when called inside shield.agentic.run(). Surrounding workflow/tool
guards and explicit shield.agentic.decide() calls still enforce Agentic policy.
Native Google GenAI clients returned by shield.genai() also govern automatic
Python callable tools. Keep the native config={"tools": [function]}, model,
chat, async, and streaming interfaces. The SDK reports the callable’s source
and checks authorization before executing it; denial, incomplete code, or
pending approval stops the call. Ordinary model requests and declarative tool
schemas keep the inference path. Disabling native automatic function calling
returns the model’s tool request without executing a local function.
This adapter covers Python callable tools. For remote MCP tools, use the
gateway-backed native session from shield.mcp.connect() so the gateway
enforces remote tool access; arbitrary external MCP sessions are a separate
boundary. See MCP integration.
from deepintshield import DeepintShieldfrom langgraph.graph import StateGraph
shield = DeepintShield.from_env()
builder = StateGraph(State)# Add your ordinary nodes and tools.app = builder.compile()app.invoke(initial_state)The framework remains a third-party object. At its supported build/run/tool boundary, the SDK reports bounded topology/source evidence, obtains the authoritative decision, applies supported obligations, and stops execution on deny or approval-required outcomes.
Source capture follows the application implementation, its decorators and bounded local helpers. SDK-owned instrumentation is identified by its actual implementation and target, so an editable SDK or virtual environment nested under the application directory does not become part of the application’s source bundle. A copied wrapper marker does not exempt application code. Use the same Python environment for installation and execution; a package version number alone does not confirm that a local source fix is installed.
Route native model traffic
Section titled “Route native model traffic”Keep the framework’s agent, tools, and runner, and use its native model binder for gateway inference:
from agents import Agent, Runner
async def run_support(shield): # shield has this workload's registered agent_name. async with shield.async_openai() as client: model = shield.bind("openai_agents").model( "openai/gpt-4o-mini", api="responses", openai_client=client ) agent = Agent( name="Support", instructions="Help with support questions.", model=model ) return await Runner.run(agent, "How can I track a refund?")Model binding configures inference; the live DeepintShield client installs
the supported tool-governance boundary. Neither the model binder nor plain
OpenAI inference enrolls or approves an agent. Keep shield alive during agent
execution, select the correct run scope when sharing a process, and close
native model clients at shutdown. See Providers and frameworks
for each binder’s API selector, capability fields, and dependency combination.
Durable and plugin runtime boundaries
Section titled “Durable and plugin runtime boundaries”| Runtime | Integration boundary |
|---|---|
| Temporal | Automatic activity interceptor; call native AsyncOpenAI inside an activity, outside deterministic workflow code |
| AWS Strands | Final tool dispatch; the current middleware terminal authorizes the final arguments after input middleware and before execution |
| Google ADK | Supported normal, live, and threaded tool dispatch; its model binder uses ADK’s public LiteLLM connector |
| Hermes | Load the DeepIntShield host plugin so the Python client can arm the central tool dispatcher |
| OpenClaw | Generated provider configuration for inference plus the separate TypeScript plugin for before_tool_call governance |
These runtimes keep their native execution and session lifecycle. Installing a model connector alone does not install a non-Python host plugin or grant tool access. Strands execution shapes the SDK cannot instrument fail closed.
Discovery labels the network with a detected framework. Detection reads the shape of the object you pass, so an ambiguous target - a bare list of callables, for example - can be filed under a framework you do not use. Pass the label explicitly when you know it:
shield.agentic.discover(tools, framework="generic", name="refund-network")Registration lifecycle
Section titled “Registration lifecycle”A new agent requires registration approval or a matching authorized enrolment policy. On first execution, the SDK captures bounded, credential-redacted implementation evidence. Changes to an approved agent follow the workspace’s blueprint policy. Common outcomes are:
agent_registration_pending: the agent is captured and waiting for an administrator. The SDK prints, once per process,Registration pending. Reference <registration id> · runtime key SHA256:<thumbprint>. Contact your administrator. You will be notified at <email>.The runtime-key clause is omitted when no key was enrolled, and the closing sentence,You will be notified at <email>., appears only when the gateway confirmed the address.registration_requester_mismatch: this agent is already being registered under a different registering e-mail. One registration keeps its first address. The message readsregistration_requester_mismatch: Registration refused: this agent is already being registered under a different email. Contact your administrator.When the gateway named the registration earlier in the same process, the line carriesReference <id>.before the last sentence. An e-mail-shapedrequesternever causes this refusal.agent_not_registered: capture did not persist; verify gateway connectivity and rerun discovery.blueprint_coverage_incomplete: executable source coverage was missing, partial, truncated, or omitted. Since SDK 3.2.1 two program shapes that used to end here are covered: a LangGraph node built from Runnables (aRunnableParallel, a chain such asitemgetter("messages") | model, aRunnableBranch, aToolNode, a compiled subgraph) is described by the composition it dispatches plus the source of every Python callable inside it, and a program with no application code of its own (an agent made of instructions, a model and an output type, with no tools, hooks or callbacks) reports its definition as the code to scan; anautogen_agentchator AG2 agent run on its own, without a team, is such a program and is discovered as one since 18 October (the generic discovery used to capture the framework’srunmethod, or nothing at all). A callable whose source cannot be read, or a source the SDK had to truncate, still leaves the node uncovered. With SDK 3.2.1 a composite LangGraph node was covered at discovery but attested by the framework method’s source at its first execution, which posted a second, incomplete capture and ended here; SDK 3.2.2 attests it by the composition the discovery reported. The gateway refuses a report with no artifact at all and quarantines the reporter, so an older SDK’s tool-less program cannot be enrolled; upgrade the SDK rather than adding a placeholder tool.blueprint_scan_unavailable: the required scan/registration acknowledgement could not be obtained.
The SDK traceback reports the specific blocker and asks the caller to contact
their administrator. It never waits for approval and never shows a review link,
and it does not require application users to navigate the administration UI.
registered_by is the explicit way to name the registering developer. Pass
registered_by="<work e-mail>" to the constructor or set
DEEPINTSHIELD_REGISTERED_BY (SDK 3.2.0 or newer) so the administrators see
who registered the agent and the developer is e-mailed when the decision is
made. The gateway maps the address to a person in the workspace directory,
created just in time when unknown and shown by the address, and e-mails it.
The address is not verified and grants nothing: the review shows
Registered by <email> with Given by the developer with the virtual key. Not verified.
The administrator confirms or changes the proposed owner. One registration
keeps its first address; a different address on a later run is refused with
registration_requester_mismatch. When it is unset, an e-mail-shaped
requester is only an advisory hint: the gateway uses it only for a person
the organization placed in the workspace and ignores it otherwise, without
refusing the run, so an application whose requester is an end user keeps
registering as before. Do not set requester to your own
e-mail in order to be notified: requester names the person the agent acts
for and changes authorization. Pass registered_by="" to send no registering
address. A pending registration remains distinct from no registration.
Missing source evidence keeps the blueprint_coverage_incomplete code because
it can also block a previously approved agent after a code change; it is not
relabeled as agent_not_registered. Administrators can use the code to review
registration, workload proof, and source evidence separately.
Review registrations and blueprint findings in Agentic before retrying. An unchanged approved blueprint avoids repeated scan work, but each governed tool still requires authorization (or a valid decision-cache hit) and therefore has workload-dependent request-path latency.
First run: simple math agent
Section titled “First run: simple math agent”This native LangGraph example adds two, then multiplies by three. It does not need an inference model or model provider key. Optional Model review in Blueprint protection is a separate server-side scanner setting.
Install deepintshield[langgraph] 3.2.0 or newer and supply four settings
through your environment or secret store: DEEPINTSHIELD_BASE_URL, an active
workspace DEEPINTSHIELD_VIRTUAL_KEY, DEEPINTSHIELD_AGENT_NAME=simple-math-agent,
and DEEPINTSHIELD_REGISTERED_BY=<your work e-mail> (your work e-mail; the gateway
maps it to a person in the workspace directory and e-mails you there). If DEEPINTSHIELD_REQUESTER is set, its acting identity and any required
delegation/resource permissions must also pass runtime policy. Use an approved
requester value; do not copy another user’s identity just to satisfy a check.
from typing import TypedDictfrom deepintshield import DeepintShieldfrom langgraph.graph import END, START, StateGraph
class State(TypedDict): number: int
def add_two(state: State): return {"number": state["number"] + 2}
def multiply_by_three(state: State): return {"number": state["number"] * 3}
with DeepintShield.from_env() as shield: builder = StateGraph(State) builder.add_node("add_two", add_two) builder.add_node("multiply_by_three", multiply_by_three) builder.add_edge(START, "add_two") builder.add_edge("add_two", "multiply_by_three") builder.add_edge("multiply_by_three", END) graph = builder.compile() print(graph.invoke({"number": 5}))For an unknown agent with Agentic Security enabled and no matching automatic enrolment policy, the first run stops before a node executes. Complete the following in the same workspace as its Virtual Key:
- Run 1 (developer). Run the saved script once. The SDK captures the
source, enrols its runtime key when the workspace offers a provisional Entra
provider or the identity is already declared, and prints
Registration pending. Reference <registration id> · runtime key SHA256:<thumbprint>. Contact your administrator. You will be notified at <email>.Keep the reference and thumbprint; there is no review link and you cannot approve your own agent. The administrators receive a review-needed e-mail. - One review sitting (administrator, not the owner). An administrator
validates the identity provider once (direct workload credentials or Entra
gateway runtime authentication; for the latter follow the complete
local gateway + Microsoft walkthrough -
Microsoft credentials stay on the gateway). Then open Agentic → Agents →
Needs attention → Registrations → Review for
simple-math-agent: the Accountable owner is proposed from the registering e-mail (select Confirm owner or choose another); create or link the identity in Identity & owner (the separate Agentic → Identities → Provisioning tab can create or link it through an approved management connection and deliver managed credentials to the customer’s secret manager); check that Submission credential shows Active credential; compare the Key fingerprint under Runtime access with the developer’s thumbprint and select Authorize runtime key. Review the completed Code scan and select bothadd_two/invokeandmultiply_by_three/invoke; for the pure arithmetic functions above, a reviewer can select action classreadand risklowafter inspecting their code. This example needs no custom resource permissions, new roles/groups, access profile, capabilities, or model; keep optional sections collapsed unless your workspace policy requires them. Under Validate changes, inspect the current checks; then open Review & decide, select Approve now, activates on the agent’s next run and confirm with Approve now · activates on next run. The Decision recorded card lists the actions that activation will grant, here bothinvokeactions. Provider validation and Declare alone do not authenticate Python. Leave Approve as VK-trusted (development only) unchecked when verified workload identity is required: it explicitly accepts an unattested agent, is offered only while the workspace allows it, and must not be used to hide a credential problem. See Workload setup. - Run 2 (developer). Run the same application again. The gateway verifies
the runtime key and identity, applies the recorded decision before
answering, and the graph prints
{'number': 21}: the decision grants every action the administrator selected, so the whole agent executes. Inspect Agentic → Activity → Runs and Decisions for outcomes. A script changed after the decision was recorded reports pending again and needs a new review. See Deferred activation.
On a gateway without deferred activation, the administrator authorizes the key, the developer runs again to collect proof, the administrator approves with Preview approval → Confirm approval and access, and the developer runs a third time. Resolve anything listed under Runtime setup needed, or use Resume saved approval if an access plan was interrupted.
If the scan reports 0 artifacts or incomplete executable source, refresh
alone cannot repair it. Confirm the Python interpreter running the script uses
the updated SDK (3.2.1 or newer covers composite LangGraph nodes and programs
without application code; 3.2.2 or newer also executes a composite node
without posting a second, incomplete capture), rerun the saved .py file,
and review the newly reported code. A quarantine that such a refusal caused is released by
approving the complete scan the next run files; until then every program of
that agent answers agent_quarantined.
Source that cannot be captured remains blocked; lowering risk labels or
changing identity providers does not supply missing code evidence.
For this graph, No tools found. No tool access needed. together with missing
source is incomplete discovery. Expect the two invoke actions above after
capture succeeds. Zero additional resource permissions does not mean zero
executable actions to review.
For this checkout, install the SDK into the interpreter that runs test2.py:
python -m pip install -e './deepintshield[langgraph,runtime]'The runtime extra supports gateway-managed runtime authentication. Direct
Entra workload authentication uses the azure extra instead; it is not
required for a laptop’s approved-key broker path. Supply
DEEPINTSHIELD_VIRTUAL_KEY through that process’s environment or secret manager.
For an autonomous graph, keep DEEPINTSHIELD_REQUESTER empty; a nonempty value
introduces human directory and authorization/delegation checks. If an existing script
assigns these environment variables directly, remove those assignments so
DeepintShield.from_env() uses the launch configuration. Keep credentials out
of the source file. The issuer UUID never needs to be repeated in individual
LangGraph nodes.
The Run setup → Copy settings helper supplies the gateway and friendly agent name. It does not provision provider credentials. An OIDC expected subject is not necessarily its client ID. Direct Entra authentication needs the appropriate host identity and optional SDK dependency; gateway mode needs the gateway blueprint credential and an approved runtime binding. Do not add a provider binding that the running workload cannot prove.
The registration route by identity type
Section titled “The registration route by identity type”Every identity type follows the same route: run 1, one review sitting, then the next run. What the sitting contains and what the developer needs before run 2 depend on how the agent proves who it is.
| Identity type | What the administrator does in the sitting | What the developer needs before run 2 | Runs | Server runs |
|---|---|---|---|---|
| Plain virtual key (VK-trusted) | Confirms the owner, reviews code and tools, and selects Approve as VK-trusted (development only), with or without a declared identity. The option is offered only while Allow VK-trusted approvals (development only) is on (Policy & Access → Runtime policy → Registration review). Keep that setting off in production workspaces. A VK-trusted approval is never recorded for later and never automatic. | Nothing new: the four settings and pip install deepintshield. | Two | No. Where server runs reach every workspace (*, the default), the program runs on the developer’s machine after its server run ends, and in this release that first local run asks for one more code review. In a workspace listed for server runs the agent cannot run (managed_gateway_runtime_required). |
| Microsoft Entra with gateway exchange | Confirms the owner, creates or links the identity, authorizes the runtime key by its thumbprint, reviews code and tools, and selects Approve now, activates on the agent’s next run. | The four settings and pip install 'deepintshield[runtime]' from run 1, on the same machine. | Two. Three when no runtime key arrived on run 1. | Yes. It is the only identity type that can finish a server run. |
| Microsoft Entra direct | Confirms the owner, declares or creates the identity, reviews code and tools, and records the decision. There is no runtime key to authorize. | An Azure host whose identity the agent blueprint trusts, the four settings and pip install 'deepintshield[azure]'. It never works from a laptop. | Two, on an Azure host | No, as for a plain virtual key. |
| Generic OIDC: Okta, Auth0, Keycloak and any issuer | Confirms the owner, declares the agent’s token subject, reviews code and tools, and records the decision. | The agent’s own client credential on the machine: OIDC_CLIENT_ID plus OIDC_CLIENT_SECRET, or OIDC_CLIENT_AUTH_METHOD=private_key_jwt with OIDC_PRIVATE_KEY_FILE. | Two, only when that credential is on the machine before run 2 | No, as for a plain virtual key. |
| ZeroID (experimental) | The provider is configured through the API beforehand. In the sitting, the same steps as Generic OIDC. | ZEROID_SUBJECT_TOKEN and ZEROID_EXCHANGE_ENDPOINT. | Two, when both are set before run 2 | No, as for a plain virtual key. |
| SPIFFE | Not available for registration. A SPIFFE provider cannot be created. | Not applicable | Not applicable | Not applicable |
For Generic OIDC, the issuer and its signing keys must be reachable at a
public https address on port 443. A Keycloak on a private network therefore
cannot be verified. The gateway accepts tokens that live one hour or less; set
the token lifetime at the issuer. The subject to declare depends on the
issuer: for Okta it is the client id, for Auth0 <client id>@clients, and for
Keycloak the service-account user id.
An administrator who registered an agent with their own sign-in e-mail cannot record its decision. While Require a separate reviewer for immediate approvals is on, they cannot approve it at all. In a one-person workspace, approve immediately after the agent’s next run (three runs), or register the agent with a different e-mail.
Provisioned workload credentials
Section titled “Provisioned workload credentials”Provision once for each logical agent and environment. The same identity serves
later runs and replicas; a new run ID does not require a new client ID. Keep the
friendly DEEPINTSHIELD_AGENT_NAME in the workload even when its provider-issued
subject differs. Provisioning tracks creation and lifecycle jobs; Identity
providers holds runtime verification settings. See
Workload identity
for the four connectors, customer authorization, and managed versus linked
identity restrictions.
For a new shared Entra verifier, Agent admission → Shared agents · explicit identity list allows setup before the first child exists. Its empty list admits nobody. After enabling, saving, and validating it, use Authorize provisioning to attach management access to that verifier; shared settings are inherited and shown read-only. Provisioning adds each child identity, so the workload keeps its own declared child and friendly agent name without another provider configuration per agent.
The Created & linked count includes provisioning records. Manual expected identity declarations are listed on the same tab as cards marked Declaration and are counted separately, so a zero count does not mean an identity is free to claim. Check the existing declaration before retrying a conflict. See provisioning records and recovery for safe release, re-enrolment, and updating an unused connection after its verifier changes.
For a secret-based Keycloak, Auth0, or Okta identity, give the workload its own
Vault authentication and render the selected KV v2 record to a protected file.
The workload must wait for ready: true; a staged secret is not usable yet.
Use the SDK’s examples/agentic/provisioned_oidc.py launcher from its checkout:
# Vault Agent renders the inner record (the KV v2 response's data.data object).# Keep gateway, virtual key, and friendly agent name in the normal environment.python examples/agentic/provisioned_oidc.py \ --provider keycloak --record /run/secrets/agent-oidc.json \ -- python examples/langgraph/transparent.pyThe launcher supplies OIDC_CLIENT_ID, OIDC_CLIENT_SECRET,
OIDC_TOKEN_ENDPOINT, OIDC_CLIENT_AUTH_METHOD=client_secret_post, and
space-separated OIDC_SCOPES to the child process without printing secrets.
Auth0 receives the record’s audience; Keycloak and Okta omit that request
parameter and rely on their configured token audience. The gateway’s audience
verification remains in force.
OIDC_SCOPES overrides the shared verification provider’s scope defaults in an
SDK build containing this feature. Leave it unset to retain those defaults;
set it to an empty string to request no scopes. This example does not retrieve
Vault secrets itself, handle public-key authentication, or set up Entra
federation. Management credentials and the gateway’s provisioning Vault token
must stay on the server. After credential delivery, rerun the workload to prove
its identity and complete code and access review.
Names are unique within an organization and workspace, not per human user.
Another workspace can register simple-math-agent independently. In the same
workspace an unassociated virtual key receives agent_name_conflict; use a
different agent key for an independent application. Authorized credentials for
the existing agent operate that agent, regardless of which human starts Python.
Repeated runs
Section titled “Repeated runs”Reuse the registered identity and refresh its short-lived tokens as needed; provisioning is not part of each execution.
A decision recorded while the agent was pending (Approve now, activates on the agent’s next run) is applied at the next run of the unchanged code: the gateway checks the runtime key, identity, source digest and scan against the recorded decision, activates the registration with every action the decision lists, and the run proceeds. Any code change re-opens review instead; the recorded decision becomes stale and a new one is needed.
Registration approval has no fixed duration or run count. It remains usable while the same canonical agent, workspace and associated active Virtual Key, accepted blueprint, workload identity, grants, and policies remain valid. Each protected action is still checked. Revocation, quarantine, missing requester access, expired delegation/task/action approval, or a policy change can block a later run. A short-lived approval preview or activation window is not the registration’s lifetime.
Under Policy & Access → Runtime policy → Blueprint protection, Block
runtime drift (blueprint_runtime_enforce) defaults to false. Off preserves
mandatory scanning and risk-based admission of clean code deltas against a
valid approved baseline. On quarantines every newly observed different digest
for review, even if scans find no new risk; returning to an older approved
digest also requires fresh review. Turning it off does not release an existing
quarantine. Select Save to apply the workspace setting.
This uses existing SDK change reporting and requires no SDK code change. Unchanged approved evidence does not cause scanner/model calls per action. Only reported code and gateway-observed tool definitions are covered before subsequent protected actions; filesystem or host-memory edits and unreported remote changes are not monitored. It does not sandbox arbitrary code or stop an action that has already begun. See Blueprint code review.
Check enrolment before serving traffic
Section titled “Check enrolment before serving traffic”status() asks the gateway what state this workload’s enrolment is in, so a
service can refuse to start rather than discover the answer one denied tool
call at a time:
state = shield.agentic.status()
if state["state"] != "live": log.error( "Agent is not ready (%s). Please contact your administrator.", state["state"], ) raise SystemExit(1)state | Meaning |
|---|---|
live | The agent is registered, approved, and its blueprint is current. Governed calls are decided normally. |
pending | The registration is captured and waiting for an operator in Agents → Needs attention. |
denied | The registration was denied. Review the reason with an operator, who can supersede the denial through the reviewed workflow. |
quarantined | A blueprint scan quarantined the agent. Review the scan findings to restore it. |
approved | The registration was approved but the agent’s governance profile is not enabled yet. |
not_registered | No registration exists for this agent on this Virtual Key. |
unknown | The gateway could not be reached, or answered with an error. reason carries the detail. |
status() never raises and never blocks a governed call - it is a read for
your own healthcheck. For recognized administrative states, reason and
action use the same short catalog messages. For pending, reason is the
line the first run printed, starting Registration pending. Reference, and
action is Contact your administrator. The resolved agent_subject and
registration_id remain available as metadata; the SDK never returns a review
link. It requires a Virtual Key; anything else comes back as unknown with the
reason.
Discovery reports the same lifecycle states on its own: when a discovery run
comes back pending, denied, quarantined, or coverage-incomplete, the SDK
logs one warning per state per process with a brief status and a request to
contact the administrator. It does not include UI navigation or review links. Ordinary
transport failures are not reported that way, so a flaky network does not turn
into a stream of governance warnings.
Direct decision probe
Section titled “Direct decision probe”decide() returns a Decision; it does not raise merely because the verdict is
DENY:
decision = shield.agentic.decide( tool="ledger.post", args={"amount": 12}, action="create_entry", action_class="write", prompt="Post the approved journal entry.",)
if not decision.proceed: print(decision.verdict, decision.decision_id)prompt is supplied for scanning at the PDP boundary. The SDK contract treats
it as scan-only, but applications should still avoid sending secrets that are
not necessary for the decision.
For full control, construct DelegationContext and ContextBag. Optional
application-observed signals include memory integrity, hallucination risk, goal
drift, inter-agent communication integrity, output manipulation, recovery cost,
and RAG provenance. These values influence policy only when your workspace
policy evaluates them; the SDK does not calculate their truth for you.
Govern one function
Section titled “Govern one function”@shield.agentic.tool( "ledger.post", action="create_entry", action_class="write", recovery_cost="high",)def post_entry(row: dict) -> dict: return ledger.insert(row)The decorator supports synchronous functions, coroutines, generators, and
async generators. It performs blueprint preflight and authorization before the
function body or iteration begins. shield_tool(tool=..., client=...) is the
standalone equivalent.
When exactly one live client exists, a bare decorator can resolve it. With
multiple clients, pass client= or bind a request-local run scope; ambiguity
fails closed.
Obligations
Section titled “Obligations”A verdict can Allow a call and attach an obligation: the tool runs, but with protected values redacted first. The SDK applies the obligations it can carry out locally before the function body sees its arguments.
| Obligation | Applies to |
|---|---|
mask:pii | Recognised personal-data fields. |
redact:secrets | Credential-shaped field names, and credential-shaped values anywhere in a string argument (issued API keys, personal access tokens, cloud access-key ids, JWTs, PEM private keys). |
redact:phi | Protected-health-information fields - diagnosis, medication, medical record number, patient and insurance identifiers. |
redact:card-numbers | Luhn-valid card numbers found in any string value. Ordinary long numbers such as order ids are left intact. |
redact:bank-accounts | Account number, IBAN, routing number, sort code, SWIFT/BIC. |
redact:value | Value-carrying fields (value, secret_value, plaintext, and similar). The secrets tool templates pair this with a result-side fingerprint-only rule, which the gateway enforces. |
mask:pii matches field names exactly - email, not customer_email.
Redaction covers positional and keyword arguments alike, so the calling
convention cannot change what gets protected - send(email) and
send(email=...) are redacted identically. Arguments the SDK cannot bind to a
parameter name (a builtin with no signature, *args packing) are passed
through unchanged rather than guessed at.
An obligation the SDK does not recognise is a local no-op; the gateway remains responsible for enforcing it. The argument digest sent to the PDP is computed from the original call, so redaction never invalidates an approval pinned to that digest.
Acting user and run scope
Section titled “Acting user and run scope”with shield.agentic.run( email="alice@example.com", session_id="checkout-req-018",) as run_id: app.invoke(initial_state)run() uses request/task-local context, restores nested state, and carries the
acting principal plus session grouping into governed calls. as_user() binds a
principal until changed; start_run()/end_run() manage a run override
manually. Prefer run() for shared clients and concurrent request handlers.
Identity resolution is designed to be fail-soft for directory creation: if the gateway cannot be reached, it returns a deterministic local subject. Tool authorization itself is fail-closed.
Task scopes and memory commitments
Section titled “Task scopes and memory commitments”Tasks optionally narrow an already authorized agent to exact actions, expiry, and an authorization budget. An operator issues the mandate under Policy & Access → Runtime policy → Task scope and authorization ancestry. See Task controls for issuance and revocation. The gateway’s signing secret stays on the gateway; workloads receive only their issued task token.
The SDK reads DEEPINTSHIELD_TASK_MANDATE when supplied. To scope the token to
one request explicitly, wrap the existing framework invocation:
import osfrom deepintshield.agentic import current_task_context, task_scope
with shield.agentic.run(session_id="report-request-018"): with task_scope(os.environ["DEEPINTSHIELD_TASK_MANDATE"]): result = app.invoke(initial_state) task = current_task_context() last_authorization_receipt = task.last_receiptThe mandate must cover the actual registered tool/action and resource request.
It cannot create a missing grant, satisfy an action approval, or replace
workload identity. Every permitted action consumes a unit, including an action
whose tool later fails. If a mandate is supplied while Agentic Security is
unavailable, the SDK stops with agent_task_security_unavailable.
task_scope() restores its caller’s context when it exits. Sequential actions
carry the latest authorization receipt as their predecessor. Parallel branches
inherit their own context snapshots; joining branches requires explicitly
passing their returned receipt IDs through task_scope(input_receipts=[...]).
Receipts attest authorization ancestry, not completed executions or safe outputs.
For memory-aware tasks, hash the bytes actually read and provide the recorded slot version. The application owns the memory storage and serialization:
from deepintshield.agentic import memory_reference, task_scope
# notes_bytes and notes_version come from the application's current storage.reference = memory_reference("notes", notes_bytes, notes_version)with task_scope( os.environ["DEEPINTSHIELD_TASK_MANDATE"], memory_inputs=[reference],): result = app.invoke(initial_state)After a governed writer has written memory, call
shield.agentic.commit_task_memory("notes", written_bytes, expected_version)
inside its active task scope. Use expected_version=0 only for a new slot.
The call hashes the supplied bytes and commits the next version against the
current writer authorization receipt; it does not write application storage.
If later authorizations have occurred, pass the writer’s explicit receipt_id
instead of relying on the most recent receipt. A writer receipt can commit once,
and the server compares the exact prior version to reject conflicting writes.
Task scope must permit the memory read/write slots. The server stores digests, versions, and receipt links; it does not receive the raw memory bytes through these APIs or independently establish their content safety. Inspect current commitments and their history in the UI’s Task evidence view.
Explicit integration factories
Section titled “Explicit integration factories”Automatic boundaries are preferred for supported versions. Compatibility and plugin APIs remain available:
| Method | Result |
|---|---|
guard() / callback() | LangChain callback handler |
govern(target) | Describe, report, and instrument a supported target |
langgraph(graph) | In-place LangGraph adapter |
openai_agents(target) | OpenAI Agents adapter |
llamaindex(tools) | LlamaIndex tool adapter |
autogen(target) | AutoGen tool adapter |
pydanticai(agent) | PydanticAI adapter |
temporal() | Temporal interceptor |
strands() | AWS Strands hook provider |
google_adk() | Google ADK plugin |
hermes(ctx) | Install hooks on a Hermes plugin context |
openclaw_config(...) | OpenClaw provider configuration; tool governance still requires its TypeScript plugin |
Error boundary
Section titled “Error boundary”Application-facing Agentic boundaries translate internal errors to marked standard exceptions:
PermissionErrorfor denials.ConnectionErrorfor gateway/unusable-response failures.RuntimeErrorfor approval, configuration, dependency, registration, and blueprint lifecycle failures.
Read the stable marker through the public error helper rather than coupling to private attribute names:
from deepintshield import get_error_definition, get_exception_error_code
try: post_entry({"amount": 12})except (PermissionError, ConnectionError, RuntimeError) as exc: code = get_exception_error_code(exc) definition = get_error_definition(code) if definition is None: raise log.error("Agentic operation stopped", extra={"code": code})See Error codes for trusted descriptions, retryability, operator actions, and stability guidance, and Agentic control-plane setup for registration and policy workflows.
Proof-of-possession
Section titled “Proof-of-possession”When a workspace identity provider requires proof-of-possession, the agent token is no longer a plain bearer: it carries the thumbprint of a key this process holds, and every request must present a fresh DPoP proof (RFC 9449) signed by that key. A token lifted from a log or a trace is then useless without the key.
Install the optional dependency to enable it:
pip install "deepintshield[dpop]==3.2.3" # or: pip install cryptographyThe key is generated per process and never written to disk - a restarted workload obtains a token bound to its new key. Required DPoP fails closed when the signing dependency or an issuer-bound token exchange is unavailable. Automatic acquisition uses the Generic OIDC adapter with a DPoP-capable issuer; the built-in Entra and ZeroID adapters reject required-DPoP configurations they cannot satisfy. See Agent workload identity for the workspace-side configuration.