Skip to main content

1. Overview & Architecture

What is AgentID?​

AgentID is a security, compliance, and observability System of Record for AI systems. It is not just a prompt filter. It is a control plane plus runtime enforcement layer that sits between your application and the LLM execution path to enforce policy, capture telemetry, and generate audit evidence.

Get Started​

1) Create your system​

  1. Sign in at https://app.getagentid.com.
  2. Create an AI system.
  3. Copy:
    • AGENTID_API_KEY
    • AGENTID_SYSTEM_ID

2) Install SDK​

Node.js / TypeScript

npm install agentid-sdk

Vercel AI SDK wrapper

npm install ai agentid-vercel-sdk @ai-sdk/openai

Python

pip install agentid-sdk

3) Configure environment variables​

export AGENTID_API_KEY="sk_live_..."
export AGENTID_SYSTEM_ID="00000000-0000-0000-0000-000000000000"
export OPENAI_API_KEY="sk-proj-..."

4) Basic runtime flow​

Run guard() before model execution and log() after completion:

App Input -> guard() -> allow/block -> LLM call -> log(model + usage + latency)

Use these guides for full examples and wrappers:

Current Production Topology​

The public runtime path is now split into a thin edge-facing route and a dedicated guard engine:

Client -> Vercel /api/v1/guard -> Fly guard engine -> verdict
                                   |
                                   +-> Vercel background side effects
                                       (ai_events, system_metrics, async AI audit)

This is intentional.

  • Vercel remains the public API surface and owns auth, routing, rollout flags, and background persistence.
  • Fly.io runs the hot guard engine with warm in-memory runtime, WASM matcher, and preflight blockers.
  • Supabase remains the system-of-record for configuration and event storage.

Shadow Mode vs Blocking Mode​

AgentID has two distinct runtime behaviors:

Blocking mode​

  • /guard is called synchronously.
  • The client waits for the verdict before the LLM call.
  • This is the production enforcement path for prompt injection, DB access, code execution, and PII leakage.

Shadow mode​

  • The public route can return an immediate allowed response while still marking shadow_mode=true.
  • The upstream guard call, metadata enrichment, DB logging, and async AI audit continue in the background.
  • This is the recommended path when you want a zero-latency audit layer without affecting end-user UX.

Operationally, zero-latency behavior is strictly conditional on shadow_mode=true. Blocking systems still use the synchronous path.

The Two-Plane Architecture​

To guarantee zero-trust security without bottlenecking your application, AgentID operates on a strict two-plane design:

  • Control Plane: Dashboard and backend logic where you define system configurations, API keys, RBAC, guardrail policies, and compliance workflows.
  • Data Plane: Runtime endpoints (/guard, /agent/config, /ingest, /ingest/finalize) that process live traffic, enforce deterministic pre-execution checks, and trigger async deep-scan audit jobs.

Control Plane vs Data Plane Artifacts​

AgentID policy detection is split into authoring and runtime execution:

  • Control-plane authoring tables: pattern_catalog, pattern_overrides, pattern_exceptions
  • Compiled artifact storage: policy_pack_artifacts
  • System pointer: ai_systems.policy_pack_version and ai_systems.policy_pack_updated_at

Runtime reads a precompiled policy pack instead of building regex/trie structures per request.

Runtime Cache Layers​

The hot path uses layered caches:

  • L1 in-memory cache: per-process, fastest path
  • L2 cache: optional cross-instance cache
  • DB fallback: authoritative source for systems, API keys, and policy-pack metadata

Production warmup now primes:

  • public agent/config lookup
  • public guard auth/config preflight
  • direct Fly allow path
  • direct Fly blocking path

This is why the first request after deploy is now much closer to steady-state than earlier versions.

Dual-Phase Evaluation Model​

Phase 1: Deterministic Fast Path​

When your app calls guard(), the payload is evaluated by the deterministic policy engine:

  • prompt-injection blockers
  • DB-access detection
  • code-execution detection
  • PII leakage detection
  • compiled policy-pack matching

This path is optimized for low latency and returns an allow/block verdict before model execution.

Phase 2: Async Semantic Deep Scan​

After the model finishes, log() or SDK wrappers persist lifecycle telemetry and trigger asynchronous deep AI audit. This layer enriches the stored event with semantic risk signals without blocking the runtime path.

SDK Execution Model​

Official SDKs default to backend-first enforcement:

  • /guard is the authority for prompt injection, DB access, code execution, and PII leakage.
  • Optional local preflight exists only for explicit fail-close or clientFastFail use cases.
  • log() persists the post-execution lifecycle row.
  • /ingest/finalize can attach sdk_ingest_ms after the primary ingest write.

Important scope rule:

  • Automatic protection/logging applies only to the SDK-wrapped runtime surfaces.
  • For OpenAI wrappers today, that means chat.completions.create.
  • For Vercel AI SDK applications, use agentid-vercel-sdk so generateText() / streamText() stay unchanged while still running the same AgentID lifecycle.
  • If your application uses responses.create, Assistants, or a custom provider path, call guard() and log() explicitly unless you have a dedicated integration wrapper.

See the dedicated guide:

Cost and ROI Measurement​

Cost and ROI dashboards are based on completion telemetry, not guard checks. The integration must preserve provider token usage on the final model event.

Required signals for spend-bearing LLM rows:

  • actual provider model id
  • input and output token counts
  • completion latency when available
  • event_type: complete

AgentID calculates cost_usd from token usage and model pricing. It calculates projected savings from cost_usd plus system business context (human_hourly_rate and human_time_per_task_min). If an integration omits usage tokens, the request can still appear in Activity while Total Spend and ROI remain empty.

Latency Semantics​

Activity latency reflects synchronous processing, not async audit wall time.

  • processing_time_ms: synchronous request runtime shown in Activity
  • ai_audit_duration_ms: async post-processing duration
  • SDK metadata may also include:
    • sdk_config_fetch_ms
    • sdk_local_scan_ms
    • sdk_guard_ms
    • sdk_ingest_ms

The first request after deploy or version switch can still be slower than steady state, but current production warmup is designed to keep that cold-start tax bounded instead of multi-second on every allow/block path.

Warmup and Cron Strategy​

AgentID production can optionally call the internal warm route on a schedule:

/api/internal/guard/warm

That route is intended to keep:

  • Vercel auth/config resolution warm
  • Fly guard runtime warm
  • representative allow and block branches hot

It is an operational stabilizer, not a substitute for correct cache behavior.