Skip to main content

2. Core Concepts

The Event Lifecycle​

A standard LLM interaction monitored by AgentID produces an event lifecycle that stitches together the pre-model and post-model phases using a unique Client Event ID.

  • The guard Phase: Your app sends the prompt to AgentID. The Guard engine evaluates the input and returns a verdict (allowed or blocked) along with an event correlation ID.
  • The Execution Phase: If allowed, your application executes the prompt against your chosen LLM (e.g., OpenAI, Anthropic).
  • The complete Phase: Your app sends the final generated output and latency metrics back to AgentID's Ingest endpoint.
  • Reconciliation: AgentID stitches the guard prompt and the complete output together into a single, immutable lifecycle record visible in your Dashboard.

(Note: Seeing two distinct network requests for one user action is the expected architecture. This guarantees that blocked prompts are recorded even if the LLM is never called).

Event Identity Contract (Required for clean correlation)​

Use this identity model for one end-to-end request:

  • client_event_id: stable external correlation ID.
  • guard_event_id: returned by guard and passed into ingest metadata.
  • event_id on ingest: idempotency key; canonicalized to client_event_id in SDK flows.

Recommended request flow:

  1. Send client_event_id in POST /guard.
  2. Read canonical client_event_id + guard_event_id from guard response.
  3. Send ingest with:
    • event_id = canonical client_event_id
    • metadata.client_event_id
    • metadata.guard_event_id
    • x-correlation-id = client_event_id
  4. Official SDKs may then call /ingest/finalize with the same client_event_id to attach sdk_ingest_ms without replaying the primary ingest write.

This prevents split rows, replay confusion, and broken prompt/output linkage.

Why some rows have no Complete​

Security Alert / prompt-only rows without a matching Complete row are expected when:

  • prompt was blocked and never executed,
  • request path intentionally ran guard-only,
  • ingest was not sent by caller.

In these cases metadata commonly shows has_complete_event=false and bidirectional_audit_status="prompt_only".

SDK Authority Model​

Official SDKs default to backend-first enforcement:

  • /guard is the source of truth for prompt injection, DB access, code execution, and PII leakage decisions.
  • clientFastFail / client_fast_fail is opt-in and enables local preflight before the backend call.
  • If backend guard is unreachable and the effective failure mode is fail_close, wrapped SDK flows can run local fallback enforcement before the final execution decision.
  • sdk_config_fetch_ms, sdk_local_scan_ms, sdk_guard_ms, and sdk_ingest_ms help explain where wrapper latency was spent.

Fail-Open vs. Fail-Closed Behavior​

AgentID gives developers strict control over how the system behaves during network partitions or infrastructure timeouts.

  • Strict Mode OFF (Fail-Open): The default behavior. If the AgentID Guard endpoint is unreachable or times out, direct guard() calls return fail-open and wrapped SDK flows continue execution. This keeps applications online during transient network issues.
  • Strict Mode ON (Fail-Closed): If explicitly enabled in the Dashboard or local SDK, direct guard() calls deny on backend outage. Wrapped SDK flows first try local fallback enforcement; local hits block, and the path still remains fail-close oriented for high-sensitivity environments.

API Keys & Tenant Isolation​

All Data Plane endpoints are secured via API keys (sk_live_...).

  • Keys are scoped at the Organization and System level.
  • Request identity and tenant context are cryptographically bound to the event metadata, ensuring total tenant isolation and forensic traceability.
  • Keys are hashed using a pepper strategy; raw keys are never stored.