This document outlines the core architecture models for integrating NjiraAI into your agent stack. Use this as a map to understand the boundary between your infrastructure and the Njira security control plane.

Integration Architecture

NjiraAI supports two primary integration models. Choose the model that best fits your engineering constraints:

1. Transparent Gateway (Proxy Plane)

Design: The agent's LLM client is pointed to the Njira Gateway URL instead of OpenAI/Anthropic directly. Njira intercepts, audits, and enforces policies on the wire.
Best for: Remote agents, third-party black-box tools, or applications where code changes must be minimized.
Advantage: Zero code changes required for the agent's internal reasoning logic. Completely language-agnostic.

2. SDK Client (Deep Plane)

Design: You import the NjiraAI SDK and manually wrap tools, LLM calls, and async boundaries using the library's enforce() methods.
Best for: Complex internal workflows, specific enforcement points (e.g., stripping PII from a database before the LLM sees it), and highly granular custom telemetry.
Advantage: Extreme precision. Allows you to define exactly what constitutes the "Input" and "Output" of a specific capability.

The SDK Interface Model

If you choose the deep architecture, both the @njiraai/sdk (TypeScript) and njiraai (Python) libraries expose a unified client interface.

Core Subsystems:

Enforcement Engine: enforcePre(), enforcePost() — Calculate verdicts at capability boundaries.
Telemetry Engine: trace.startSpan(), trace.event(), trace.flush() — Record observability data spanning across the agent lifecycle.
Context Engine: runWithContext() — Bind operational request_id values across async boundaries.

Enforcement State Machine

Every enforcement call (whether over the Gateway or SDK) evaluates traffic against the matching Policy Pack. It returns a normalized decision payload that your application must handle.

The possible verdict states are:

ALLOW: Forward the request.
BLOCK: Halt the request and return an error to the agent.
MODIFY: Safe to forward only if you use the patched modifiedInput / modifiedOutput payload.
REQUIRE_APPROVAL: Halt execution to seek human confirmation.

Enforcement Modes

How the agent reacts to a verdict depends on its active binding mode:

Active (active): The agent must strictly obey BLOCK or MODIFY verdicts. The upstream request is halted if blocked.
Shadow (shadow): A test mode where the system logs what it would have done to the Traces console, but returns a transparent ALLOW back to the active application software.

Trace Taxonomy

Njira models agent execution using standard distributed tracing concepts. Underneath the hood, every LLM call, tool use, or reasoning step is a Span.

llm, tool, chain, retriever spans provide native support for standard agent framework actions.
custom spans provide an escape hatch for bespoke business logic.

Architecture Reference