Technical Deep Dive: Building and Deploying Secure AI Agents

Securing an AI agent requires control at two different layers.

The first is inside the application: every relevant tool call must cross a point where identity-aware policy can make a decision. The second is in the runtime: the deployed agent needs its own noninteractive identity, a safe way to receive credentials, and an operational lifecycle that includes activation, rotation, and revocation.

Ory Agent Security calls these product surfaces Build and Deploy.

• Build connects an agent harness or SDK to authentication, delegation, permission checks, and activity reporting.
• Deploy registers a runtime identity, validates a supported agent-and-runtime combination, and packages the Agent Security configuration for an operator-controlled environment.

They are designed to meet at a clear contract. Build protects the action loop. Deploy gives that loop a trustworthy production identity.

Build starts at the tool boundary

Agents turn model output into effects through tools. A tool might read a file, execute a shell command, query a database, call an API, invoke an MCP server, or start another agent. That dispatch point is where Ory Agent Security can make a useful authorization decision: after the agent has selected an action, but before the action executes.

Ory supports two integration models.

Harness plugins

A harness plugin is appropriate when an existing agent product owns the control loop. Ory Agent Plugins integrate with the lifecycle primitives exposed by coding harnesses such as Claude Code, Codex, Gemini CLI, Cursor, OpenCode, and others.

Each harness exposes different events and block signals. One may use subprocess hooks and an exit code, another may return an in-process cancellation object, and another may expose a permission delegate. The Ory adapter translates those host-specific primitives into a common security lifecycle while preserving the harness's native behavior.

This matters because enforcement is not a prompt instruction. A denial has to reach the mechanism that actually stops the tool. Where a harness exposes only an advisory hook, only an enforceable companion boundary can provide a hard block.

Agent SDK integrations

An SDK integration is appropriate when developers own the application and its tool map. Ory publishes integrations across TypeScript and Python for frameworks including Vercel AI SDK, Anthropic Claude Agent SDK, Mastra, Cloudflare Agents, OpenRouter Agent SDK, Pi, LangChain and LangGraph, OpenAI Agents SDK, Pydantic AI, CrewAI, LlamaIndex, Google ADK, AWS Strands, and others.

The framework connection point may be a hook, middleware, guardrail, callback, or wrapper. The shape differs, but the requirement is the same: every protected executable tool must pass through the integration. A hosted tool that never crosses the local SDK hook, or an unwrapped callable invoked outside the framework lifecycle, cannot be secured by that interception point.

Build quickstarts therefore do more than show package installation. They identify the correct framework boundary, show where the OryAgentClient is initialized, and exercise an allowed tool call before verifying that a policy-denied call is reported but allowed in Observe.

The common agent security lifecycle

The TypeScript and Python integrations share a common logical sequence.

1. Start or resolve the session

An interactive harness session can authenticate the human user and enroll or resolve the machine runtime. A headless deployed agent instead starts from its Deploy-issued runtime proof and calls the runtime-context endpoint to obtain server-owned identity and lineage data.

That distinction prevents a production workload from pretending to be a human or inventing its own subject identifier. A preprovisioned root runtime receives its subject, agent type, deployment ID, and opaque root delegation from the server after authenticating.

2. Establish delegation

The root relationship answers: which person or automation sponsor is responsible for this agent? When supported sub-agents are created, Ory can issue each direct child a separate runtime identity and record immutable parentage.

The resulting graph is more useful than a shared workload account:

human or automation sponsor
└── root agent runtime
    └── sub-agent runtime
        └── guarded tool action

The child uses its own credential for delegation, permission, and event requests. It does not select its parent or owner from caller-supplied metadata.

3. Check permission before execution

Before the tool runs, the adapter sends a bounded permission request for the authenticated principal and target. Agent and shell tools are generally usable by default unless an explicit block applies. MCP access is grant-based.

The policy result is interpreted according to posture:

• In Observe, a denial is recorded but the supported tool call proceeds.
• In Enforce, a denial is translated to the framework or harness's native blocking signal.

Policies can apply to the project, human identity, registered agent, or sub-agent, and can address tool categories, individual tools, executable words, or custom tool groups.

4. Record outcomes

Authorization is only half of an audit trail. After execution, the adapter records completion and, where the framework lifecycle exposes the required hook, failure. Client-generated event IDs and server-computed immutable payload hashes make exact delivery retries idempotent while rejecting altered replay data.

The event model is intentionally bounded. Raw prompts, credentials, headers, arbitrary command contents, tool inputs, and tool outputs are not accepted as free-form metadata. That reduces the chance that an observability pipeline becomes an accidental copy of sensitive agent context.

Thin adapters, shared security cores

Ory's integration architecture keeps framework packages thin. Shared TypeScript and Python cores implement the difficult, reusable behavior:

• human and runtime authentication
• session initialization
• agent and child-agent enrollment
• delegation registration
• permission checks
• observe and enforce behavior
• activity completion and failure reporting
• project-scoped durable event delivery
• runtime credential and configuration handling

The framework adapter translates local events into that core contract. This is valuable for consistency: changing from one supported SDK to another does not require designing a new identity model.

It is also a useful review boundary. Teams can inspect a small amount of framework-specific wiring while relying on a shared implementation for security-sensitive behavior.

From local Build to headless runtime

During development, an interactive agent can use a browser login to associate a person with the session. A production workload cannot depend on a developer being present to complete that flow. It also should not carry a copied human OAuth token.

Deploy bridges that gap by creating a runtime identity ahead of time. The application code remains focused on its SDK integration. Runtime-specific identity material and routing arrive through deployment configuration.

The contract is deliberately asymmetric:

• The application knows how to attach Ory to its complete tool lifecycle.
• Agent Security knows the registered runtime identity, owner, agent type, and credential state.
• The deployment controller knows how to launch the customer's workload and deliver runtime configuration.
• The infrastructure platform knows how to schedule, isolate, and operate that workload.

No single component has to impersonate another.

A catalog, not a matrix of assumptions

Agent frameworks and execution environments evolve independently. Supporting an SDK does not automatically mean every runtime and credential method is valid for it.

Deploy models these as separate catalog dimensions:

• Agent type identifies the SDK or harness integration.
• Runtime identifies the execution environment, such as generic Docker, Kubernetes, E2B, or another supported provider.
• Package recipe and version identify the server-owned packaging contract.
• Credential method identifies how the runtime authenticates.

The live Agent Security server owns compatibility. Before creation, the browser or ory-agent CLI checks that the selected agent type, runtime, recipe, version, and credential method are compatible. The create API remains authoritative.

This design prevents stale client-side assumptions from becoming production configuration. A checked-in example can demonstrate a pattern, but the live catalog determines whether a combination is currently deployable.

The declarative deployment workflow

The standalone ory-agent CLI supports a manifest-driven workflow. A typical manifest captures intent rather than a cloud-provider script:

api_version: agent-security.ory.sh/v1
kind: AgentDeployment
name: support-agent
agent_type: openai-agents
runtime_id: e2b
package_recipe: e2b-sandbox
package_recipe_version: v1
credential_method: talos_api_key

The exact fields and available values come from the current CLI and live catalog. Unknown manifest fields are rejected, which helps catch configuration drift and typos before credential issuance.

A practical workflow uses these commands:

ory-agent validate
ory-agent deployment plan
ory-agent deployment ensure
ory-agent deployment run -- ./trusted-controller
ory-agent deployment wait --for active

The stages have distinct purposes:

• validate checks manifest structure.
• plan resolves authentication and confirms catalog compatibility without creating a deployment.
• ensure creates or safely reuses a compatible deployment and writes protected runtime material.
• run starts a trusted controller and sends runtime configuration over anonymous standard input.
• wait --for active confirms that the runtime has authenticated and the deployment is active.

Reuse is intentionally strict. The CLI verifies immutable fields, acceptable deployment state, and credential expiry. If a local binding points to a deployment with different intent, the operator must revoke it explicitly rather than silently replacing identity.

Runtime credentials and trust boundaries

Deploy supports three runtime authentication patterns, subject to the selected catalog entry.

Talos API keys

Agent Security can issue an actor-bound Talos key scoped to Agent Security runtime calls. The one-time secret is returned to the deployment flow, while Agent Security stores its identifier rather than the secret. Runtime requests are verified against the configured Ory project and matched to an active local registration.

This is the simplest option for many hosted and sandboxed workloads. It still requires careful delivery: the key should not be baked into a container image, committed to source, or copied into an immutable sandbox template.

Customer-managed X.509 mTLS

For supported administrative deployments, an operator can register the exact SHA-256 fingerprint of a customer-managed leaf certificate. The private key remains with the operator. Agent Security's private listener authenticates the certificate presented directly over TLS; it does not trust forwarded identity headers.

Replacing the leaf certificate changes its fingerprint, so replacement requires a new deployment registration.

SPIFFE X.509 SVIDs

In a supported SPIFFE deployment, the operator supplies the workload identity and operates the SPIFFE control plane. Agent Security verifies the SVID chain and exact SPIFFE URI on its direct mTLS listener. It does not install or operate SPIRE, issue SVIDs, or own workload attestation.

This is a strong fit for Kubernetes environments that already use workload identity and need rotating credentials without embedding static secrets. The generated configuration can reference mounted SVID, key, and trust-bundle files so runtime rotation remains visible.

What is in a deployment package?

An Agent deployment package is the bridge between registration and the operator's runtime. Depending on the recipe and credential method, it contains an immutable manifest, protected environment material, operator guidance, and target-specific configuration.

It does not contain:

• customer application source
• a generated agent implementation
• model-provider credentials
• a dependency manifest for the application
• a container build file for the application
• cloud or cluster provisioning

That boundary is intentional. Agent Security packages identity and security configuration; the runtime platform still builds and runs the workload.

Ory Talos and customer-PKI packages cannot be downloaded again. If the only copy is lost, the safe response is to revoke and recreate the deployment. Supported SPIFFE packages are secret-free and recoverable with integrity verification.

Safe handoff to an operator-controlled runtime

The ory-agent deployment run flow demonstrates the intended credential boundary.

1. Create a package only when no valid deployment is already bound.
2. Persist non-secret state and a mode-0600 runtime credential file.
3. Start a trusted child process.
4. Deliver credential bytes through anonymous standard input.
5. Remove deployment-administration credentials from the child environment.
6. Wait for the runtime to become active after the controller succeeds.

The trusted child might be a controller that launches a local container, injects secrets into an E2B command, or updates an existing secret-management system. It should parse the credential bundle in memory, pass only the required runtime values to the agent process, and avoid logging or persisting plaintext.

This separation limits what the deployed agent receives. It needs runtime proof, not the credential used to administer deployments.

Example: OpenAI Agents SDK on E2B

An ephemeral sandbox makes the Build/Deploy split concrete.

Build

The Python application uses the Ory OpenAI Agents integration on its function tools and attaches the corresponding run hooks. A guarded Greet tool crosses the Ory input guardrail before execution and reports lifecycle activity afterward.

Only protected FunctionTool instances cross this local boundary. Hosted or built-in tools that bypass the guardrail need a different control point.

Deploy

The operator builds and pins a credential-free E2B template. The deployment manifest selects the OpenAI Agents type, E2B runtime, E2B sandbox recipe, and Talos credential method.

An external trusted controller holds E2B administration credentials and receives Agent Security runtime values. It starts a sandbox command with only the values required by the agent, constrains egress, and kills the credentialed sandbox after use rather than pausing, snapshotting, or forking it.

Verify

The workload authenticates, resolves its server-owned runtime context, completes an LLM turn that requests the guarded tool, and reaches active deployment state. A separate runtime verification endpoint can test deployment-bound authentication without invoking a model or customer tool.

Example: an agent on Kubernetes with SPIFFE

For a long-running Kubernetes agent, Build remains framework-specific: the application connects its complete tool map to the appropriate Ory adapter.

Deploy selects Kubernetes, a catalog-compatible package recipe, and the SPIFFE credential method. The operator supplies the existing trust relationship, workload SPIFFE ID, and Agent Security mTLS origin. Kubernetes projects the SVID, private key, and trust bundle into a read-only directory without subPath, allowing rotations to become visible to the workload.

The operator remains responsible for:

• installing and operating SPIRE or another compatible issuer
• workload attestation
• scheduling and updating the application
• network policy and egress restrictions
• server and workload certificate rotation
• model and third-party credentials

Agent Security remains responsible for matching the verified runtime proof to the registered project and deployment, resolving identity and lineage, authorizing guarded tools, and preserving audit activity.

CI/CD without a broad human credential

Deployment automation should not rely on a developer's long-lived login token. Agent Security supports a dedicated project-scoped deployment automation key with the exact deployment-administration scope and an active sponsoring identity.

The version-pinned GitHub Action installs and verifies the signed ory-agent release, creates or reuses a deployment, and can invoke a trusted deployment command. The generated workflow separates:

• the non-secret deployment ID, stored as configuration
• the protected runtime credential, stored as a secret
• the deployment automation key, exposed only to the action that needs it

This enables repeatable deployment without granting the agent workload permission to create or revoke other deployments.

Activation, verification, and revocation

Creation is not proof that a workload is functioning. Agent Security distinguishes package issuance from runtime activation:

• Ready means the deployment and its security relationships exist.
• Active means an authenticated runtime request has arrived.

Operators can wait for active state or call the deployment verification endpoint with the runtime proof. The verification endpoint checks deployment-bound authentication and records the result without running a model, plugin, or customer tool.

When a workload is retired or a credential may be exposed, revoke the deployment. Revocation excludes linked credentials locally before revoking linked Talos keys upstream and covers linked child credentials. The CLI does not revoke automatically after each run because durable production agents often span many sessions; lifecycle intent remains explicit.

Failure behavior is part of the design

Security integrations need predictable behavior when dependencies fail.

At the tool boundary, ordinary policy-service connectivity and rate-limit failures are designed to fail open so a temporary outage does not disable every integrated agent. The error remains observable. Explicit policy denials block only in Enforce and only at a supported enforcement point.

Runtime authentication is different. Invalid, expired, revoked, unregistered, or incorrectly scoped credentials fail closed. Agent Security also refuses to continue if it cannot durably create the server-side audit record for a broker request.

Credential issuance uses strict idempotency because one-time secrets cannot always be replayed safely. If an upstream issuance request times out without returning a credential identifier, Agent Security may preserve a degraded record for reconciliation rather than risk creating a second live credential. Operators should investigate and revoke any ambiguous upstream credential before retrying with a new idempotency key.

A production checklist

Before deploying a secured agent, verify the complete path:

• Every executable tool crosses the selected harness or SDK boundary.
• Allowed and denied calls have both been tested in Observe.
• Enforce behavior uses a real framework or harness block signal.
• The agent type, runtime, recipe, version, and credential method pass a live catalog plan.
• The application does not supply its own subject, owner, or delegation metadata.
• Runtime credentials are absent from source, images, templates, logs, and checkpoints.
• Deployment-administration credentials are not passed to the workload.
• The runtime reaches active state with a real authenticated request.
• Audit events arrive without sensitive prompt or tool payloads.
• Revocation has been tested and has a named operational owner.
• Infrastructure, model credentials, network controls, and workload updates have separate owners.

One security model from code to runtime

Build and Deploy address different failure modes. Build prevents an agent framework from becoming an ungoverned path to tools. Deploy prevents a production workload from depending on copied human credentials, caller-authored identity, or an ad hoc secret handoff.

Together, they establish a continuous chain:

deployment owner
→ authenticated runtime
→ server-owned agent context
→ delegated session or sub-agent
→ pre-tool authorization
→ tool outcome
→ durable audit activity

That chain is the foundation for applying least privilege to agents without tying security to one model vendor, one framework, or one runtime. Developers can use the SDK abstractions they already know. Operators can use the environments they already run. Security teams gain an identity-aware decision and accountability layer at the point where agent intent becomes action.

Learn more about Ory Agent Security, explore Ory Agent Plugins, and review the Agentic IAM documentation.