v0.4 · Apache 2.0

Scouter documentation.

Runtime authorization for AI agents. Install, declare intent, wrap your client — and every action is evaluated before it executes.

Overview

Scouter sits between your agent and the tools it calls. Every action is interpreted semantically, scored for risk, and either allowed, flagged, or blocked — before any side effect happens.

Traditional IAM checks who is calling. Scouter checks what is being done and whether it matches declared intent.
  • Zero-trust runtime. Agents cannot bypass governance checks.
  • JIT credentials. Purpose-scoped, short-lived access tokens.
  • Prompt analysis. Injection, jailbreak, and off-intent detection.
  • Risk scoring. Every action gets an explainable decision.
  • Execution guards. Hard blocks on destructive patterns in real time.
  • Signed audit trail. Tamper-evident records for SOC 2 & ISO 42001.

Architecture

Every action flows through triage, the consequence engine, and execution guards before it can hit an external system.

User Prompt
    │
    ▼
[Action Triage Classifier]
    │ SKIP (safe, fast-pass)   SCAN (needs evaluation)
    │                               │
    │                               ▼
    │                    [Consequence Engine]
    │                               │
    │         PASS_THROUGH   FLAG   ESCALATE   HARD_STOP
    │
    ▼
[Execution Guards]  ← ShellGuard · DatabaseGuard · APIGuard
    │
    ▼
  ALLOW / BLOCK / WARN

Installation

Scouter ships as a Python package and a Node / TypeScript package. Install whichever fits your stack.

# Python 3.10+ — https://pypi.org/project/scouter-ai/
$ pip install scouter-ai

# Node.js 18+ — https://www.npmjs.com/package/@scouter-ai/core
$ npm install @scouter-ai/core
The hosted backend is available at https://scouter.intellectmachines.com. Grab an API key from the Scouter Dashboard to get started.

Quick Start (Python)

Initialize the client, declare an intent, and wrap your OpenAI client. Every call is governed transparently.

from scouter.client import ScouterClient
from scouter.integrations.openai import wrap_openai
from openai import OpenAI

# 1. Init Scouter
scouter = ScouterClient(
    # backend_url defaults to the Scouter cloud endpoint
    api_key="your-api-key",
    mode="enforce",   # audit | enforce
)

# 2. Register agent intent (what it's allowed / not allowed to do)
intent = scouter.register_intent(
    agent_id="support-bot",
    natural_language="Answer customer questions about orders and products",
    permitted_actions=["lookup_order", "search_knowledge_base"],
    excluded_actions=["delete_order", "modify_payment"],
)

# 3. Wrap your OpenAI client — that's it
client = wrap_openai(OpenAI(api_key="..."), scouter=scouter, intent_id=intent.intent_id)

# 4. Use normally — Scouter governs every call transparently
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What's my order status for ORD-123?"}],
)

Quick Start (Node / TypeScript)

Same flow on Node. Zero runtime dependencies, native fetch.

import { ScouterClient } from "@scouter-ai/core";
import { wrapOpenAI } from "@scouter-ai/core/integrations/openai";
import OpenAI from "openai";

const scouter = new ScouterClient({
  // backendUrl defaults to the Scouter cloud endpoint
  apiKey: "your-api-key",
  mode: "enforce",
});

const intent = await scouter.registerIntent({
  agentId: "support-bot",
  naturalLanguage: "Answer customer support questions",
  permittedActions: ["lookup_order", "search_kb"],
  excludedActions: ["delete_data"],
});

const client = wrapOpenAI(new OpenAI(), { scouter, intentId: intent.intentId });

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Check my order" }],
});

Execution Guards

Deterministic, always-on blocks for patterns that are dangerous regardless of intent.

  • ShellGuard. Catches rm -rf, chmod 777, reads of /etc/shadow, and similar destructive shell ops.
  • DatabaseGuard. Catches DROP TABLE, DELETE without WHERE, classic SQL injection.
  • APIGuard. Catches credentials in URLs, PUT to /secrets, data exfiltration attempts.
  • Intent Engine. Blocks anything outside the agent's declared permitted_actions.

Supported Frameworks

Python. OpenAI · LangChain · CrewAI · AutoGen · PhiData

Node. OpenAI · Vercel AI SDK

Modes: audit observes without blocking. enforce blocks unsafe actions in real time.

# Python
$ pip install scouter-ai

# Node
$ npm install @scouter-ai/core

Configuration

Copy .env.example to .env and fill in your values:

SCOUTER_BACKEND_URL=https://scouter.intellectmachines.com
SCOUTER_API_KEY=your-api-key-here

Get your API key from the Scouter Dashboard.