Skip to content

Agents and Agentic governance

The SDK exposes two agent-related layers:

SurfacePurposeGateway route
shield.agentExplicit input/output/action/MCP guardrail checks/api/guardrails/evaluate
shield.agenticIdentity-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.

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.

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.

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 DeepintShield
from 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.

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.

RuntimeIntegration boundary
TemporalAutomatic activity interceptor; call native AsyncOpenAI inside an activity, outside deterministic workflow code
AWS StrandsFinal tool dispatch; the current middleware terminal authorizes the final arguments after input middleware and before execution
Google ADKSupported normal, live, and threaded tool dispatch; its model binder uses ADK’s public LiteLLM connector
HermesLoad the DeepIntShield host plugin so the Python client can arm the central tool dispatcher
OpenClawGenerated 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")

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 reads registration_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 carries Reference <id>. before the last sentence. An e-mail-shaped requester never 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 (a RunnableParallel, a chain such as itemgetter("messages") | model, a RunnableBranch, a ToolNode, 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; an autogen_agentchat or 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’s run method, 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.

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 TypedDict
from deepintshield import DeepintShield
from 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:

  1. 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.
  2. 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 both add_two/invoke and multiply_by_three/invoke; for the pure arithmetic functions above, a reviewer can select action class read and risk low after 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 both invoke actions. 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.
  3. 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:

Terminal window
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.

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 typeWhat the administrator does in the sittingWhat the developer needs before run 2RunsServer 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.TwoNo. 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 exchangeConfirms 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 directConfirms 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 hostNo, as for a plain virtual key.
Generic OIDC: Okta, Auth0, Keycloak and any issuerConfirms 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 2No, 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 2No, as for a plain virtual key.
SPIFFENot available for registration. A SPIFFE provider cannot be created.Not applicableNot applicableNot 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.

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:

Terminal window
# 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.py

The 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.

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.

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)
stateMeaning
liveThe agent is registered, approved, and its blueprint is current. Governed calls are decided normally.
pendingThe registration is captured and waiting for an operator in Agents → Needs attention.
deniedThe registration was denied. Review the reason with an operator, who can supersede the denial through the reviewed workflow.
quarantinedA blueprint scan quarantined the agent. Review the scan findings to restore it.
approvedThe registration was approved but the agent’s governance profile is not enabled yet.
not_registeredNo registration exists for this agent on this Virtual Key.
unknownThe 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.

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.

@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.

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.

ObligationApplies to
mask:piiRecognised personal-data fields.
redact:secretsCredential-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:phiProtected-health-information fields - diagnosis, medication, medical record number, patient and insurance identifiers.
redact:card-numbersLuhn-valid card numbers found in any string value. Ordinary long numbers such as order ids are left intact.
redact:bank-accountsAccount number, IBAN, routing number, sort code, SWIFT/BIC.
redact:valueValue-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.

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.

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 os
from 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_receipt

The 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.

Automatic boundaries are preferred for supported versions. Compatibility and plugin APIs remain available:

MethodResult
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

Application-facing Agentic boundaries translate internal errors to marked standard exceptions:

  • PermissionError for denials.
  • ConnectionError for gateway/unusable-response failures.
  • RuntimeError for 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.

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:

Terminal window
pip install "deepintshield[dpop]==3.2.3" # or: pip install cryptography

The 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.