Integrations

Admina integrates with the most popular AI agent frameworks and orchestration tools, in two shapes: sidecar integrations that route traffic through the Admina proxy over HTTP, and in-process integrations that call the governance engines directly inside your own Python process.

OpenAI-compatible gateway

Since v0.11.0 the proxy exposes an OpenAI-compatible HTTP surface — POST /v1/chat/completions (streaming and non-streaming) and GET /v1/models — on the same port 8080 as /mcp. Any client, library or front-end that speaks the OpenAI chat-completions API can be pointed at Admina with no code change: set the base URL to http://localhost:8080/v1 and the API key to your ADMINA_API_KEY. Port 8080 is the proxy port under admina dev --stack; in the default zero-Docker local mode (admina dev) the same surface is on :3000. See Quick Start.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",   # Admina, not the provider
    api_key="<your ADMINA_API_KEY>",
)

resp = client.chat.completions.create(
    model="llama3.1:8b",
    messages=[{"role": "user", "content": "Summarise this clause…"}],
)

The request runs through the injection firewall, PII redaction, the egress stage and any pluggable governance guards before it leaves Admina — since v0.13.0 the firewall scans every string of the request body (tool definitions, response_format and tool call arguments included), and the pipeline runs in worker threads off the event loop. The completion is PII-redacted on the way back — streamed text through a 64-character windowed buffer per choice and field. Loop detection does not run on this surface. Each chat completion writes two forensic records, gateway_request and gateway_response.

See API Reference → OpenAI-compatible gateway for the full request/response contract (headers, error codes, routes, limits), and Configuration for the ADMINA_GATEWAY_* variables.

OpenClaw

Admina ships with a ready-to-use OpenClaw skill that routes all MCP tool calls from your agent through the Admina governance proxy. The setup steps below install the skill and route the agent's traffic via Admina.

How it works

The admina-governance SKILL.md routes all agent actions through /api/v1/validate and /api/v1/audit. Governed action types include:

• llm_call — LLM prompt and completion governance
• shell_exec — Shell command execution
• file_write — File system write operations
• http_request — Outbound HTTP requests
• message_send — Agent-to-agent or agent-to-user messages

Skill install

The skill lives at admina/integrations/openclaw/admina-governance/ and ships exactly three files: SKILL.md (the skill itself), admina.yaml (the sidecar's config) and setup.sh. Copy the directory into your OpenClaw skills directory, then run setup.sh: it starts the Admina proxy as a Docker container named admina-openclaw-sidecar on port 18790 (override with ADMINA_PORT), mounts the adjacent admina.yaml read-only at /app/admina.yaml, and waits for /health. The script then prints the ADMINA_PROXY_URL to export — the skill reads that variable for every /api/v1/validate and /api/v1/audit call, and refuses to act if the sidecar is unreachable.

# Start the Admina governance sidecar
cd admina/integrations/openclaw/admina-governance
chmod +x setup.sh
./setup.sh

# Point the skill at the sidecar
export ADMINA_PROXY_URL=http://127.0.0.1:18790

# Health check and teardown
./setup.sh --status
./setup.sh --uninstall

LangChain

The AdminaCallbackHandler is a drop-in callback for ChatOpenAI and any other LangChain model. It governs all LLM and tool events without changing your existing chain logic. It runs in-process — the firewall, PII redactor and loop breaker are called directly, so there is no proxy to start and no URL or API key to configure.

Governed events

• on_llm_start — Validates prompts before they reach the model
• on_llm_end — Scans completions for PII
• on_tool_start — Firewall, loop and PII check before tool execution
• on_tool_end — PII scan and audit trail of tool results

Configuration

The handler accepts the following parameters:

• session_id — Session identifier for loop detection across calls (default: an auto-generated langchain-… id)
• pii_redaction — Enable PII redaction, Data Sovereignty domain (default True)
• firewall — Enable the injection firewall, Agent Security domain (default True)
• loop_detection — Enable the loop breaker, Agent Security domain (default True)
• on_block — Behaviour when a request is blocked: "raise" (default) raises GovernanceBlockedError, "warn" logs and continues
• audit — Emit events to the governance event bus (default True)

loop_detection is on by default, and the Python loop breaker needs numpy and scikit-learn, which ship with [proxy], not [nlp] — hence [proxy,nlp] below. Alternatives: [rust] for the Rust loop breaker (which also moves the firewall to Rust under ADMINA_ENGINE=auto), or loop_detection=False. Without either package the first governed call raises an ImportError naming the extra. The same applies to the CrewAI step callback.

Example

pip install "admina[proxy,nlp]" langchain langchain-openai

from admina.integrations.langchain.callbacks import AdminaCallbackHandler
from langchain_openai import ChatOpenAI

handler = AdminaCallbackHandler(
    session_id="my-session",
    pii_redaction=True,
    firewall=True,
)
llm = ChatOpenAI(callbacks=[handler])

# Every call to llm.invoke() is now governed
response = llm.invoke("Summarize this document")

# handler.last_result → GovernanceResult for the most recent check
# handler.get_stats() → session_id, call_count, block_count, redact_count, features

CrewAI

Admina provides two callbacks for CrewAI: AdminaStepCallback fires after each agent step, and AdminaTaskCallback fires after task completion. Both are callables you instantiate per crew, and both run in-process — no proxy URL, no API key.

Callbacks

• AdminaStepCallback — Governs each agent step (tool calls, LLM calls, reasoning) with the firewall, PII redactor and loop breaker. Parameters: session_id, pii_redaction, firewall, loop_detection, on_block ("raise" or "warn") and audit.
• AdminaTaskCallback — Redacts and audits completed task outputs. Parameters: session_id, pii_redaction and audit only — it does not run the firewall or the loop breaker.

Example

pip install "admina[proxy,nlp]" crewai

from admina.integrations.crewai.callbacks import AdminaStepCallback, AdminaTaskCallback
from crewai import Crew, Agent, Task

researcher = Agent(
    role="Researcher",
    goal="Analyze market trends",
    backstory="Senior market analyst",
)
task = Task(
    description="Research Q4 revenue for ACME Corp",
    expected_output="Revenue summary",
    agent=researcher,
)

crew = Crew(
    agents=[researcher],
    tasks=[task],
    step_callback=AdminaStepCallback(session_id="my-crew"),
    task_callback=AdminaTaskCallback(session_id="my-crew"),
)

# Kick off — every step and task is governed
result = crew.kickoff()

The module also exports two ready-made instances with default settings, admina_step_callback and admina_task_callback, if you do not need to configure anything: Agent(step_callback=admina_step_callback) and Crew(task_callback=admina_task_callback).

n8n

The n8n-nodes-admina package adds three governance nodes to your n8n workflows:

Install

npm install n8n-nodes-admina

Nodes

• AdminaGovern — Inline governance node. Place it before any AI node in your workflow. Validates inputs, blocks non-compliant requests, and adds governance metadata to the output.
• AdminaAudit — Passive logging node. Place it after any AI node to log all requests and responses to the Admina audit trail without blocking.
• AdminaDashboard — WebSocket trigger node. Streams real-time governance events from Admina into n8n, enabling reactive workflows (alerts, Slack notifications, compliance reports).

Cheshire Cat AI

Admina integrates with Cheshire Cat AI as a Python plugin. The plugin hooks into the Cat's event system to govern agent actions at three critical points.

Governed hooks

• agent_fast_reply — Intercepts the agent's reply before it is sent to the user. Enables PII redaction, toxicity filtering, and compliance checks on outputs.
• before_cat_sends_message — Final checkpoint before the message leaves the Cat. Applied after all other plugins have processed the response.
• before_cat_recalls_memories — Governs memory recall to prevent leaking sensitive data from the vector store.

Install

The plugin lives at admina/integrations/cheshirecat/admina-plugin/. Its setup.sh starts the Admina proxy as a Docker sidecar on port 18790; copy the plugin folder into your Cat, point it at the sidecar with the ADMINA_PROXY_URL environment variable, and enable it from the admin panel. The plugin reads its configuration from the environment — ADMINA_PROXY_URL (default http://localhost:18790) and ADMINA_TIMEOUT in seconds (default 5) — not from a settings file.

# Start the Admina governance sidecar
cd admina/integrations/cheshirecat
./admina-plugin/setup.sh

# Copy the plugin into your Cat's plugins directory
cp -r admina-plugin/ <your-cheshire-cat>/plugins/admina-plugin/

# In the Cat's .env or docker-compose.yml
ADMINA_PROXY_URL=http://host.docker.internal:18790

GuardrailsAI

Admina ships GuardrailsAIGuard, a built-in governance guard (admina.plugins.builtin.guards.guardrailsai_guard, registered under the name guardrailsai) that wraps GuardrailsAI validators as a stage of Admina's own pipeline. You do not construct it yourself — the proxy discovers every built-in guard at startup and builds it with the matching plugin_config block from admina.yaml. All inference runs locally — no data leaves your infrastructure.

Install

# From a local wheel or mirror — PyPI itself will not serve it while
# the distribution is quarantined. Admina auto-detects it on startup.
pip install ./guardrails_ai-<version>-py3-none-any.whl

Wrapped validators

Four validator names are mapped to guardrails.hub classes; any other name raises ValueError. Extra keys on a validator entry are passed straight to the GuardrailsAI validator constructor, and on_fail defaults to "noop" so Admina — not GuardrailsAI — decides the action. Set on_fail explicitly on a validator entry and your value wins, which hands the action back to GuardrailsAI.

• toxic_language — guardrails.hub.ToxicLanguage: toxic or harmful language
• detect_pii — guardrails.hub.DetectPII: personally identifiable information
• detect_jailbreak — guardrails.hub.DetectJailbreak: prompt injection and jailbreak attempts
• bias_check — guardrails.hub.BiasCheck: biased content

Configuration

The guard is wired in the top-level plugin_config map of admina.yaml, keyed by the plugin name:

plugin_config:
  guardrailsai:
    inference_mode: local     # local only — see below
    validators:
      - name: toxic_language
        threshold: 0.5
      - name: detect_pii
        entities: ["EMAIL_ADDRESS", "PHONE_NUMBER", "IBAN"]
      - name: detect_jailbreak
        threshold: 0.8

There is no enabled switch: the guard is instantiated whenever the guardrails package imports successfully, and skipped with a warning when it does not. Note that admina.yaml.example also carries a domains.agent_security.domains.guardrailsai block — the config loader does not read it, so put your settings under plugin_config.

At request time the guard runs every configured validator over the payload's content field and returns action: "ALLOW" with risk_level: "LOW" when validation passes, or action: "BLOCK" with risk_level: "HIGH", the validator error string in details and the class names of GuardrailsAI's failed-validation entries in metadata.failed when it does not. Empty content is allowed without running anything. The guard blocks or allows — it never redacts. Since v0.13.0 it runs one validation at a time: the shared guardrails.Guard and its validators are used under a lock, because the gateway now calls guards from several worker threads at once (see the gateway section).

Model provider adapters

Where the framework integrations above govern agent traffic, model adapters let the SDK govern direct calls to an LLM provider: wrap a provider in GovernedModel and every prompt runs the full pipeline (loop → firewall → PII → egress → guards), with PII redaction applied to the completion. The loop stage runs only with loop_detection=True and a per-call session_id; the egress stage runs unless agent_security.egress.surfaces leaves out sdk (since v0.13.0). Each adapter is a built-in plugin that lazy-imports its provider SDK, so the dependency is only required when the adapter is actually used. Since v0.10.0 there are seven, installed via per-provider extras:

New in v0.11.0: real means the adapter implements BaseModelAdapter.send_stream() against the provider's own streaming API, so you get incremental deltas. fallback means it inherits the base implementation, which awaits the full response and yields it as a single chunk — functionally correct, but with no latency benefit. The v0.11.0 release notes recorded the three fallback adapters as pending a follow-on with native send_stream() implementations; as of v0.13.0 they are still on the fallback. Governance is identical either way — a single-chunk response still runs through the same redactor — so only the delta granularity changes when they land.

Two roll-up extras bundle them: [adapters] pulls every provider, and [all] is [proxy,nlp,telemetry,adapters,presidio] for a complete install. The older [full] extra is [proxy,nlp,telemetry] and does not include Presidio.

Fixed in v0.13.0: GovernedModel.ask() and stream() work with the bare SDK install (pip install admina plus a provider extra). Earlier releases built the Python loop breaker on every call and failed with ModuleNotFoundError: numpy; it is now built only when loop detection runs, and then needs [proxy] (numpy and scikit-learn) or [rust].

pip install "admina[anthropic]"

from admina.plugins.builtin.adapters.anthropic import AnthropicAdapter
from admina.sdk import GovernedModel

# The Anthropic call now runs through the full governance pipeline
model = GovernedModel(model_name="claude-sonnet-4-5", adapter=AnthropicAdapter())
resp = await model.ask("Summarise this contract clause…")
# resp.action → "ALLOW" | "REDACT" | "BLOCK"   (firewall + guards run by default since v0.10.0)

Streaming (v0.11.0)

GovernedModel.stream(prompt, **kwargs) is an async generator consumed with async for. It yields plain str deltas, already PII-redacted, and is async-only — there is no stream_sync(). Three kwargs are intercepted by stream() itself: context (the system prompt, handed to the adapter as its own context argument), stream_window_chars (default 64) and session_id (enables loop detection when the model was built with loop_detection=True) — the last two are never passed on; everything else is forwarded to the provider. Once the iterator is fully exhausted, model.last_stream_result is a plain dict — not a dataclass, so access it with ["action"], never .action — with exactly eight keys: action, pii_count, model, input_tokens, output_tokens, finish_reason, time_to_first_token_ms and duration_ms. input_tokens and output_tokens are always None: there is no token accounting on the streaming path. action is "ALLOW", "REDACT" (PII was found and masked) or "BLOCK". A blocked prompt yields zero deltas and returns normally — no exception is raised — with last_stream_result["action"] == "BLOCK" and finish_reason of content_filter.

from admina.plugins.builtin.adapters.ollama import OllamaAdapter
from admina.sdk import GovernedModel

model = GovernedModel(model_name="llama3.1:8b", adapter=OllamaAdapter())

async for delta in model.stream("Summarise this contract clause…"):
    print(delta, end="", flush=True)

# Read the outcome AFTER the iterator is exhausted
print(model.last_stream_result)
# → {'action': 'REDACT', 'pii_count': 1, 'model': 'llama3.1:8b',
#    'input_tokens': None, 'output_tokens': None, 'finish_reason': 'stop',
#    'time_to_first_token_ms': 41.2, 'duration_ms': 812.5}

StreamRedactor on your own stream

StreamRedactor is a public export — from admina.sdk import StreamRedactor — and is pure text-in/text-out with no I/O, so you can drive it over any stream you already own (a provider SDK you call directly, an SSE relay, a websocket) without going through GovernedModel. Its constructor is StreamRedactor(pii_redactor, window_chars=64): the first argument is any object implementing the PIIBridge protocol — i.e. exposing redact(text) returning a dict with redacted_text and count — and admina.engines.get_pii_engine() returns the configured one. window_chars below 1 raises ValueError.

Mind the parameter name. The constructor kwarg is window_chars; the GovernedModel.stream() kwarg for the same setting is stream_window_chars. They are not interchangeable, and both mistakes are quiet: StreamRedactor(engine, stream_window_chars=128) raises TypeError, while model.stream(prompt, window_chars=128) never reaches the redactor at all — stream() pops only stream_window_chars, so window_chars falls through into the kwargs handed to the adapter's send_stream() as an ordinary provider request parameter and the window stays at 64. What happens next is the provider SDK's business: it may reject the unknown parameter or ignore it, but either way the window was never changed.

Two methods drive it. feed(delta) takes one raw delta and returns a list[str] of 0 or more redacted, safe-to-emit deltas — the list is empty while the buffer is still inside the window, or while an entity straddles the emit boundary. finish() flushes the held window and returns a (final_redacted_tail, summary) tuple, where summary is {"pii_count": N} for the whole stream. Calling finish() is mandatory: skip it and the last window_chars characters of the response are never emitted.

from admina.engines import get_pii_engine
from admina.sdk import StreamRedactor

redactor = StreamRedactor(get_pii_engine(), window_chars=64)

for raw in my_provider_stream:          # any iterable of raw str deltas
    for safe in redactor.feed(raw):    # 0+ redacted deltas per call
        print(safe, end="", flush=True)

tail, summary = redactor.finish()        # always flush at end of stream
print(tail, end="")
print(summary["pii_count"])            # entities masked across the stream