Server-managed agent execution

DeepIntShield Server 3.2.1 and Python SDK 3.2.1 support optional server-managed onboarding for standalone LangGraph programs. When your operator enables it on the gateway, the SDK saves the supported program for review and one isolated server run. Your client can exit while an administrator completes identity, runtime-key, code, and access approval. Read the result in the agent’s Review → Runtime access → Server run panel.

Local execution remains the default. Managed execution requires Business or higher Agentic access, a gateway where the operator has enabled it, and a configured worker runtime. The operator can enable it for every workspace at once; limiting it to selected workspaces is optional. Installing the SDK does not enable a worker or change an existing hosted deployment.

Submit once and finish review

1. Install an SDK that supports managed submission. Use Python 3.10 or newer and install the extras used by your workload; the SDK, Python and package releases on the client never need to match the worker image:

   python -m pip install --upgrade "deepintshield[runtime,langgraph]==3.2.1"

   Keep DEEPINTSHIELD_BASE_URL, the active Virtual Key, and a stable DEEPINTSHIELD_AGENT_NAME configured. Use the simple-math-agent example as a minimal source-file workflow. The managed adapter supports autonomous gateway-runtime identity; direct credentials and delegated/requester flows need the corresponding local execution path.

2. Run the saved Python file once. At the supported LangGraph invocation boundary, the SDK submits its bounded source, dependency versions, and Python version. A pending governance error reports that setup needs an administrator. It does not cancel the saved job. Graph nodes have not executed locally. The pending result also e-mails the registering developer (DEEPINTSHIELD_REGISTERED_BY) and the approvers; see Registration notifications.

3. Open Agentic → Agents → Needs attention → Registrations. Select the agent’s Review, or Review next agent for the next pending registration. Closing it returns to the queue with its filters. Complete its six sections:

   Section	Operator action
   Identity & owner	Select the active human owner; create or link the expected workload identity and verify its provider.
   Code & changes	Review complete source evidence and the completed scan for the submitted revision.
   Tools & access	Classify each executable action and select its exact tool and resource permissions.
   Runtime access	Authorize the highlighted server runtime key and inspect the server-run setup state.
   Validate changes	Resolve readiness or access-plan conflicts and inspect the current checks.
   Review & decide	Preview the exact changes and choose Confirm approval and access, or deny with a reason.

   Provisioning and runtime-key approval do not grant tool access. Approving the server’s key does not authorize an offline client’s private runtime key. Follow workload identity setup for provider and management-connection prerequisites.

4. Read the server outcome. The worker verifies its own identity, current blueprint, runtime compatibility, and access before executing the saved script. Server run shows progress through Identity, Runtime, Approval, and Run, with run details and saved output. Agentic → Activity → Runs and Decisions explain the governed execution; failed or uncertain jobs also appear under Needs attention → Run incidents.

Startup executes in both environments

Code before the first intercepted graph invocation still runs on the client. The worker starts the saved script from the beginning. Keep startup free of payments, writes, messages, or other business side effects. Client files, environment variables, command-line arguments, interactive input, local databases, and private runtime keys are not transferred.

Captured 10 October 2026 with synthetic demonstration data.

Supported program and runtime

Requirement	Supported behavior
Framework	Standalone Python LangGraph programs using shield.agentic.langgraph and DeepintShield.from_env().
Identity	Autonomous gateway-broker runtime identity. Requester/OBO/delegation context is unsupported for this adapter.
Source	Explicit static local Python imports, at most 64 files and 64 KiB combined source; request envelope at most 2 MiB.
Dependencies	Every package the program imports must already be installed in the approved worker image. The worker runs its own Python, SDK and package releases; the client’s versions are recorded as evidence, not matched.
Isolation	Operator-provided immutable worker image, bounded runtime/resources, and an enforced worker network policy.
Unsupported inputs	Notebooks, computed imports/loaders, arbitrary local data files, interactive programs, and other framework adapters.

The worker checks that every imported package is installed before submitted code executes. Runtime compatibility pending means the submission is still saved; ask the operator to add the missing package to the worker image. Jobs never install packages from submitted source and never silently fall back to running locally.

The executor is either an operator-managed Docker host or, on platforms without Docker such as Cloud Run and Kubernetes, a worker service the gateway calls over HTTPS. Both need HTTPS reachability to the gateway. Worker enablement and infrastructure are deployment responsibilities; confirm availability with your service operator before selecting managed execution.

An operator can enable server runs for every workspace at once. A workspace is then offered them when its identity provider’s Runtime authentication is Gateway exchanges Entra token, and only for agents that are new, still pending, or already running on the server. An agent the gateway already knows keeps running where it runs, and so does one whose last server run was cancelled or could not start because the worker image lacks a package it needs. A current SDK keeps a program local when the server cannot take it.

Only an identity that uses gateway exchange can finish a server run. When an agent is approved as VK-trusted, or its identity is declared under a provider without gateway exchange, its server run ends before the program starts. Where server runs reach every workspace (*, the default), the program then runs on the developer’s machine. In this release that first local run asks for one more code review, because a server run fingerprints the whole program and a local run fingerprints each function; a fix is planned. In a workspace listed for server runs there is no local fall-back: such an agent cannot run there, and the SDK reports managed_gateway_runtime_required (Server runs in this workspace need an agent identity that uses gateway exchange. Please contact your administrator.). Use *, or an identity that uses gateway exchange. See the registration route by identity type.

Saved job states

UI state	Meaning and next action
Needs identity	Create or link the expected identity and finish verification.
Needs runtime access	Review the server runtime key and required runtime configuration.
Runtime compatibility pending	The worker image lacks a package the program imports; have the operator add it.
Server runtime unavailable	The gateway cannot reach or inspect the worker runtime. The submission stays saved and is checked again automatically; ask the operator to restore the worker runtime.
Awaiting approval	Finish source and exact access review.
Saved code needs review	The saved bundle and current review differ. Resolve that specific revision before approval.
Tool isolation review required	Review the agent’s tool ownership and isolation before continuing.
Checking setup, Queued, Preparing	The job is saved and the worker is checking prerequisites or preparing execution.
Running	The server worker is executing the script.
Complete	Inspect saved output and the linked execution evidence.
Run failed, Cancelled, Expired	The run is terminal. Inspect the details; it cannot be resumed by submitting the same script again.
Check run outcome	The result is uncertain. Reconcile completed external actions before any replacement run.

With a gateway and SDK that support submission IDs, running the unchanged script again creates a new execution under the existing approved registration. The server reuses its encrypted runtime credential and checks current identity, blueprint and access before executing. The SDK polls the same invocation for its output; a network retry with that submission ID cannot duplicate execution. Clients without submission IDs keep the original saved-job behavior.

An active or uncertain job must be resolved before another execution starts. Changed source, dependency versions, or Python versions still require review. For legacy completed jobs whose runtime keys were already deleted, approve the replacement server runtime key once; later executions reuse it.

A manager can use Cancel run while a job is waiting, queued, or preparing. The confirmation is bound to the current job revision; refresh if the job changes. Approval and access records remain saved after cancellation. The UI does not offer cancellation once execution is running, and stopping a run cannot reverse completed external side effects.

Action approvals during execution

Initial registration approval and a high-impact action approval are separate checks. A compatible 3.2.1 managed worker can hold the blocked action in its current Python call frame while an administrator reviews the exact request under Agents → Needs attention → Action approvals or Policy & Access → Action approvals. It rechecks current policy before executing that function; already completed graph nodes are not replayed.

Approval waits share a maximum four-minute budget across the script and remain bounded by the whole-job timeout. Denial, changed arguments, cancellation, or budget exhaustion stops execution. A terminal run, including one stopped by an older worker, cannot be resumed merely by approving afterward. Check outcomes before arranging another run.

Troubleshoot without resubmitting

• For managed_execution_identity_pending or managed_execution_runtime_pending, continue the saved identity/runtime review.
• No e-mail arrived: see Registration notifications for the platform no-reply sender and the per-registration delivery log.
• For managed_dependency_unavailable, have the operator add the missing package to the pinned worker image. Client SDK and Python versions do not need to match the worker. The bundle and runtime key remain saved while waiting.
• For managed_submission_changed, managed_job_changed, or managed_blueprint_changed, reopen the existing review and resolve the exact saved revision.
• For managed_execution_reconcile_required, verify external effects before continuing. Automatic replay could duplicate work.
• For managed_gateway_runtime_required, the workspace is listed for server runs and the agent’s identity cannot use gateway exchange. Ask the operator to use *, or give the agent an identity that uses gateway exchange.

Use the SDK error catalog for stable codes, descriptions, and retryability. The gateway, UI, and worker image must contain the managed execution implementation; the client only needs an SDK that can submit the managed contract, and its version never needs to match the worker. Updating documentation or the client alone does not upgrade a running worker.

API boundaries

All routes are relative to /api/agentic-new and stay scoped to the active workspace:

Method and route	Purpose
GET /managed-execution/capabilities	Discover whether this workspace supports managed execution.
POST /managed-execution/submissions	Submit a supported source bundle using the active reporting key.
GET /registrations/{id}/managed-execution	Read saved jobs using an authorized control-plane session.
POST /managed-execution/jobs/{id}/cancel	Cancel a cancellable revision using control-plane manager access.

Use the SDK and console for the complete submission and review contract. A Virtual Key that can submit source does not grant permission to inspect other jobs or perform administrative cancellation.