API de Veredicto

Resumen

La API de Veredicto está diseñada para clientes que poseen y operan su propia API o servidor MCP. En lugar de enrutar el tráfico del agente a través del proxy de ShieldAgent, tu servidor llama a client.scan() con el payload de la solicitud entrante. ShieldAgent ejecuta el pipeline completo multi-etapa y devuelve un veredicto — allow, block, o human_review. Tu código lo aplica.

El flujo de tráfico del agente permanece completamente sin cambios. El agente habla con tu servidor normalmente. Tu servidor realiza una llamada HTTP separada a ShieldAgent y decide si ejecutar la herramienta.

¿Cuándo usar la API de Veredicto?

Inicio rápido

TypeScript — servidor MCP

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

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

// Inside your MCP tool handler:
async function handleToolCall(toolName: string, params: unknown) {
  const verdict = await shield.scan({
    tenantId: '{your-tenant-id}',
    toolName,
    params,
    // agentId is optional — see "Agent Identity" section below
    context: { transport: 'mcp' },
  });

  if (verdict.action === 'block') {
    throw new Error(`Blocked: ${verdict.reason}`);
  }

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

  // verdict.action === 'allow'
  return executeToolLocally(toolName, params);
}

Python — manejador de API REST

from shieldagent import ShieldAgentClient

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

# Inside your API handler:
async def handle_request(agent_id: str, method: str, path: str, body: dict):
    verdict = await shield.scan(
        tenant_id="{your-tenant-id}",
        agent_id=agent_id,          # optional — omit if not known
        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_handler(method, path, body)

Solicitud de análisis

El SDK llama a POST /tenants/:tenantId/scan en el proxy de ShieldAgent (puerto 3100). Autentícate con una clave API de tenant (token Bearer).

{
  "agentId": "agent-uuid",          // OPTIONAL — omit if server cannot identify the agent
  "clientHint": "Claude Desktop",   // OPTIONAL — from MCP clientInfo.name, for best-effort matching
  "toolName": "read_file",
  "params": { "path": "/etc/passwd" },
  "include_findings": false,        // opt-in; requires verdictDetailedFindings tenant permission
  "context": {
    "transport": "mcp",             // "mcp" | "rest" | "custom"
    "sourceIp": "10.0.1.5",         // optional — used for rate limiting
    "sessionId": "sess-123"         // optional — enables excessive agency detection
  }
}

Respuesta de análisis

Por defecto (todos los tenants)

{
  "action": "block",                        // "allow" | "block" | "human_review"
  "reason": "Security threat detected",     // generic — no detection detail
  "riskScore": 87,
  "auditEventId": "evt-uuid",               // audit event was written
  "reviewId": null                          // set when action is "human_review"
}

Hallazgos detallados ((requiere include_findings: true + permiso del tenant))

{
  "action": "block",
  "reason": "Prompt injection detected in tool arguments",
  "findings": [
    {
      "type": "injection",
      "severity": "critical",
      "detail": "Path traversal pattern detected",
      "scanner": "regex"
    }
  ],
  "riskScore": 87,
  "auditEventId": "evt-uuid",
  "reviewId": null
}

Los hallazgos detallados están desactivados por defecto. Sin niveles, un atacante con acceso a la API de Veredicto podría sondear iterativamente qué escáner detectó su payload y elaborar intentos de evasión. Actívalo solo para herramientas internas de confianza mediante la configuración del tenant en el panel de ShieldAgent.

Etapas del pipeline

La API de Veredicto ejecuta el mismo pipeline multi-etapa que el proxy. La única diferencia: el paso de reenvío se omite y el veredicto se devuelve a tu código en su lugar.

Identidad del agente

agentId es opcional. El protocolo MCP no expone la identidad del agente — clientInfo del handshake de inicialización MCP initialize identifica el software cliente (p. ej., "Claude Desktop"), no al agente individual. Tu API o servidor MCP puede no saber qué agente específico está llamando.

Observabilidad de la aplicación

Dado que tu código aplica el veredicto (no la infraestructura de ShieldAgent), el registro de auditoría no puede confirmar automáticamente si se respetó un veredicto de block . Usa client.confirmExecution() para cerrar el ciclo.

// After executing or rejecting a tool call, confirm the outcome:
await shield.confirmExecution(verdict.auditEventId, {
  executed: false,   // true = tool ran; false = tool was blocked by your code
});

Modelo de responsabilidad compartida

La API de Veredicto transfiere la aplicación de la infraestructura de ShieldAgent a tu código. Esto es estándar en la industria de seguridad — análogo al modo Count de AWS WAF o al modo Detect de CrowdStrike. Las certificaciones de cumplimiento de ShieldAgent aplican a sus capacidades de detección y pipeline; si tu despliegue logra aplicación completa depende de tu integración.

Si tus requisitos de cumplimiento exigen bloqueo garantizado por infraestructura y posees tu servidor, considera la variante sidecar-of-server — ShieldAgent se ejecuta como sidecar junto a tu servidor y bloquea en línea antes de que tu manejador se ejecute. Contacta a tu equipo de cuenta para más detalles.

Referencia de API

Ambos endpoints están en el servicio proxy (puerto 3100), no en la API de Gestión. Autentícate con una clave API de ámbito de tenant (token Bearer). El proceso proxy aloja el pipeline completo — limitador de tasa, caché de políticas, clasificador ML, motor DLP, evaluador de riesgo.

Relacionado

• Resumen de arquitectura →Todas las posiciones de despliegue y patrones de integración
• SDK de TypeScript →Referencia del SDK incluyendo scan() y confirmExecution()
• SDK de Python →Referencia del SDK de Python
• Modelo de puntuación de riesgo →Cómo se calcula riskScore en la respuesta del veredicto
• Marcos de cumplimiento →Implicaciones del Art. 9 de la Ley de IA de la UE y Anexo IV para despliegues con API de Veredicto