Architecture Overview

ShieldAgent enforces security at the boundary between AI agents and the tools they use. Where exactly that boundary sits in your stack is flexible — deploy the proxy inline between agent and upstream, or use the SDK's Verdict API to scan requests from within your own server code before executing them.

Where to Position ShieldAgent

ShieldAgent can be inserted at several points in the agent-to-tool call chain. The right position depends on what you own in your stack and the level of visibility you need. All positions use the same multi-stage security pipeline; only the integration method differs. Positions 2 and 3 use the SDK's Verdict API — your code sends request payloads to ShieldAgent for scanning and enforces the returned verdict.

Recommended

Position 1 — Proxy between Agent and MCP

The agent points its MCP client at the ShieldAgent proxy instead of the upstream server directly. No code changes to the agent or the MCP server. The proxy intercepts every tool call, runs the full security pipeline, and forwards approved requests. This is the primary deployment model and the one that gives you complete visibility into all tool calls.

Best when: you do not own the agent or MCP server, or you want zero-touch deployment. Network segmentation should enforce that agents cannot bypass the proxy.

Verdict API

Position 2 — Verdict API in your own API

If your agents call a REST API that you own and operate, use the ShieldAgent SDK to scan each incoming request before executing it. Your server calls client.scan() with the request payload. ShieldAgent runs the full multi-stage security pipeline and returns a verdict (allow / block / human_review). Your code enforces the verdict — execute if allowed, reject if blocked. The security pipeline runs on the ShieldAgent proxy, not in-process.

Best when: you own the API layer your agents call and want to add security scanning without changing your traffic flow. Your code stays in control — ShieldAgent scans and returns a verdict, you enforce it.

TypeScript

your-api-handler.ts

import { ShieldAgentClient } from '@shieldagent/sdk';

const client = new ShieldAgentClient({
  baseUrl: 'https://proxy.shieldagent.io',
  apiKey: '{your-api-key}',
});

async function handleAgentRequest(agentId: string, method: string, path: string, body: unknown) {
  const verdict = await client.scan({
    tenantId: '{your-tenant-id}',
    agentId,
    toolName: `api:${method}:${path}`,
    params: { method, path, body },
    context: { transport: 'rest' },
  });

  if (verdict.action === 'block') {
    throw new Error(`Request blocked by ShieldAgent: ${verdict.reason}`);
  }

  if (verdict.action === 'human_review') {
    return { status: 'pending_review', reviewId: verdict.reviewId };
  }

  return executeRequest(method, path, body);
}

Python

your_api_handler.py

from shieldagent import ShieldAgentClient

client = ShieldAgentClient(
    base_url="https://proxy.shieldagent.io",
    api_key="{your-api-key}",
)

async def handle_agent_request(agent_id: str, method: str, path: str, body: dict):
    verdict = await client.scan(
        tenant_id="{your-tenant-id}",
        agent_id=agent_id,
        tool_name=f"api:{method}:{path}",
        params={"method": method, "path": path, "body": body},
        context={"transport": "rest"},
    )

    if verdict.action == "block":
        raise HTTPException(status_code=403, detail=verdict.reason)

    if verdict.action == "human_review":
        return {"status": "pending_review", "review_id": verdict.review_id}

    return execute_request(method, path, body)

Verdict API

Position 3 — Verdict API in your own MCP server

If you operate an MCP server that agents connect to, add a client.scan() call before each tool handler. When an agent requests a tool, your server sends the tool name and arguments to ShieldAgent for scanning. ShieldAgent returns a verdict — your code executes the tool only if allowed. This gives you deep visibility and policy enforcement at the point where tools are defined, while keeping ShieldAgent centralized.

Best when: you build and maintain the MCP server and want security enforcement at the tool definition layer. Your server stays in control — ShieldAgent scans, you enforce. Richer context for policy evaluation than external proxy positioning.

TypeScript

your-mcp-server.ts

import { ShieldAgentClient } from '@shieldagent/sdk';

const client = new ShieldAgentClient({
  baseUrl: 'https://proxy.shieldagent.io',
  apiKey: '{your-api-key}',
});

async function handleToolCall(toolName: string, params: unknown, clientName?: string) {
  const verdict = await client.scan({
    tenantId: '{your-tenant-id}',
    clientHint: clientName,
    toolName,
    params,
    context: { transport: 'mcp' },
  });

  if (verdict.action === 'block') {
    throw new Error(`Tool blocked by ShieldAgent: ${verdict.reason}`);
  }

  if (verdict.action === 'human_review') {
    return { status: 'pending_review', reviewId: verdict.reviewId };
  }

  return executeToolHandler(toolName, params);
}

Python

your_mcp_server.py

from shieldagent import ShieldAgentClient

client = ShieldAgentClient(
    base_url="https://proxy.shieldagent.io",
    api_key="{your-api-key}",
)

async def handle_tool_call(tool_name: str, params: dict, client_name: str | None = None):
    verdict = await client.scan(
        tenant_id="{your-tenant-id}",
        client_hint=client_name,
        tool_name=tool_name,
        params=params,
        context={"transport": "mcp"},
    )

    if verdict.action == "block":
        raise MCPError(f"Tool blocked by ShieldAgent: {verdict.reason}")

    if verdict.action == "human_review":
        return {"status": "pending_review", "review_id": verdict.review_id}

    return execute_tool(tool_name, params)

Position	What you need to own	Agent code changes	Sees outbound tool calls	Latency impact	Enforcement
1 — Inline Proxy	Nothing	Point at proxy URL	Yes	+5-15ms	Infrastructure
2 — Verdict API (REST)	Your API server	Add SDK scan()	Yes	+5-15ms	Customer code
3 — Verdict API (MCP)	Your MCP server	Add SDK scan()	Yes	+5-15ms	Customer code

Positions 1-3 cover the main integration patterns for ShieldAgent SaaS.

Passthrough vs. Verdict API

Two SDK integration patterns exist for customers who own their server. Choose based on whether ShieldAgent needs to forward traffic to a separate upstream.

Scenario	Pattern	How it works
Your server is a gateway to a different upstream	Passthrough (apiProxy / mcpProxy)	SDK sends request to ShieldAgent proxy. Proxy scans, then forwards to the real upstream and returns the response.
Your server IS the tool provider (no separate upstream)	Verdict API (scan)	SDK sends the payload to ShieldAgent. ShieldAgent returns a verdict (allow/block/human_review). Your server executes or rejects locally.

Enforcement Model

All deployment positions run the same multi-stage security pipeline — detection, policy evaluation, risk scoring, and audit are always handled by ShieldAgent. What differs is who enforces the verdict. Position 1 provides infrastructure-enforced blocking: ShieldAgent sits inline and stops the request before it ever reaches upstream. Positions 2 and 3 use the Verdict API: ShieldAgent detects threats and returns a verdict; your server code enforces it. This shared responsibility model is standard in the security industry — analogous to AWS WAF Count vs. Block mode or CrowdStrike Detect vs. Prevent mode.

Enforcement Comparison

Position	Enforced by	Block mechanism	Guarantee
1 — Inline Proxy	ShieldAgent	Proxy drops / rejects the request	Infrastructure — cannot be bypassed
2 — Verdict API (REST)	Your server code	Your handler throws or returns error	Code-level — depends on implementation
3 — Verdict API (MCP)	Your server code	Your tool handler rejects	Code-level — depends on implementation

Responsibility Matrix

Responsibility	Position 1 (Inline Proxy)	Positions 2 & 3 (Verdict API)
Threat detection	ShieldAgent	ShieldAgent
Policy evaluation	ShieldAgent	ShieldAgent
Risk scoring	ShieldAgent	ShieldAgent
Audit trail	ShieldAgent	ShieldAgent
Compliance documentation (Annex IV)	ShieldAgent	ShieldAgent
Blocking threats	ShieldAgent — infrastructure-guaranteed	Customer — code-level, verified via confirmExecution()
Enforcement verification	Automatic (proxy blocks before forwarding)	Optional — call confirmExecution() to close the audit loop

Compliance Framework Impact

Framework	Position 1 (Inline Proxy)	Positions 2 & 3 (Verdict API)
SOC 2 CC6.1 (Logical access controls)	ShieldAgent is the complete logical access control.	ShieldAgent provides detection + audit. Your enforcement code is part of the combined control evaluated by auditors.
ISO 42001 A.6.2.6 (AI system monitoring)	Fully compliant.	Fully compliant — monitoring is provided regardless of enforcement topology.
EU AI Act Art. 9 (Risk management)	ShieldAgent identifies, analyzes, evaluates, and mitigates threats.	ShieldAgent identifies, analyzes, and evaluates. You mitigate by enforcing verdicts. Both parties must be documented in Annex IV.
EU AI Act Art. 14 (Human oversight)	Human review via ShieldAgent dashboard.	Human review via dashboard + your explicit enforcement decision after receiving a human_review verdict.
EU AI Act Annex IV (Technical documentation)	Auto-generated with infrastructure-enforced blocking proof.	Auto-generated — must include your enforcement mechanism and confirmExecution() rates as supporting evidence.

Security Pipeline

Every intercepted request travels through the same ordered security pipeline regardless of which deployment position you use. Capabilities marked always run unconditionally; the rest are bypassed in shadow mode or when not configured.

Identity & Accessalways

Verifies credentials, identifies the tenant and agent, and determines whether shadow mode applies.

Rate Limiting

Applies configurable rate limits per tenant and per agent to protect upstream services from overload.

Policy Enforcement

Evaluates your configurable policy rules against each request — allow, deny, or escalate to human review. Shadow mode logs without blocking.

Threat Detectionalways

Detects prompt injection, data exfiltration, tool misuse, and other threats using pattern matching and machine learning.

Risk Scoring

Assigns a risk score to each agent based on behavior patterns. Blocks or escalates when risk exceeds your configured thresholds.

Audit Loggingalways

Records a tamper-evident audit event for every request and verdict, including denied requests. Never blocks the request path.

Capabilities run in sequence. Any step can short-circuit the pipeline by returning a deny decision. Audit logging always runs, even for denied requests.

Data Isolation & Multi-Tenancy

ShieldAgent's SaaS platform enforces strict logical isolation between all tenants. All infrastructure is fully managed — you choose where to position ShieldAgent in your stack, not how to operate it.

SaaS

Logical Multi-Tenant Isolation

All tenants share a single managed proxy. Isolation is enforced at every layer — JWT claims per request, row-level access controls, and per-tenant rate limits. Your data is never co-mingled with another tenant's data.

Topology	Isolation	Managed by	Applies to
Shared (SaaS)	Logical	ShieldAgent	All plans

Platform Capabilities

ShieldAgent provides a complete security platform for AI agent operations. All capabilities are fully managed — there is no infrastructure for you to configure or deploy.

Capability	What it does
Security Scanning	Scans every tool call and API request for threats including prompt injection, data exfiltration, and tool misuse before they reach your systems.
Policy Enforcement	Evaluate configurable policy rules against every request. Policies can allow, deny, or escalate to human review. Shadow mode lets you observe without blocking.
Dashboard & Monitoring	Real-time security dashboard for monitoring agent activity, managing policies, exploring audit logs, and registering agents.
Audit Trail	Tamper-evident audit log of every tool call and verdict. Export at any time via the dashboard or a configured webhook.
Risk Scoring	Continuous per-agent risk scoring with behavioral anomaly detection and configurable alert thresholds.
Compliance Reporting	Auto-generated compliance documentation for SOC 2, ISO 42001, and EU AI Act frameworks including Annex IV evidence.

Supported Transports

The proxy supports both network and process-based MCP transports. Choose based on how your agent framework communicates with MCP servers.

Transport	Protocol	Use case
HTTP/SSE	HTTP streaming	Network agents, multi-replica deployments
stdio	Standard I/O	Agent spawns proxy as child process (local dev, desktop apps)
REST API proxy	HTTP methods	Pass-through for non-MCP REST APIs with policy enforcement

How ShieldAgent Scales

Automatic scaling

ShieldAgent scales transparently to your traffic volume. Proxy capacity, session affinity, and database throughput are managed automatically — no configuration required on your end.

SSE connection reliability

Server-Sent Event connections are long-lived and handled with automatic reconnection routing. Session affinity is managed by the platform so your agents reconnect without data loss.

Audit throughput

The audit trail is designed for high throughput. Events are written asynchronously and never block the request path. Export at any time via the dashboard or a configured webhook.

Included in ShieldAgent SaaS

All infrastructure is operated by ShieldAgent. The following capabilities are included — nothing to deploy or maintain on your side.

Included

Security Scanning · Policy Enforcement · Dashboard & Monitoring · Audit Trail · Risk Scoring · Compliance Reporting