sentinely

Runtime guardrails for AI agents. Scores every tool call against the original task intent and blocks attacks before they execute.

Install

npm install sentinely

Quickstart

import { protect, SentinelyBlockedError } from 'sentinely'

const agent = protect(myAgent, {
  task:    'Summarize quarterly reports and email the finance team',
  policy:  'strict',
  agentId: 'report-agent-prod',
})

try {
  const result = await agent.run(userInput)
} catch (err) {
  if (err instanceof SentinelyBlockedError) {
    console.log('Blocked:', err.reason)
    console.log('Risk:',    err.riskScore)
    console.log('Attack:',  err.attackType)
  }
}

That's it. Every tool call the agent makes is now scored against the original task. Dangerous actions are blocked. Suspicious actions are flagged. Everything is logged.

What it protects against

• Prompt injection — detects instructions embedded in external content (files, emails, API responses) that try to hijack the agent's behavior.
• Task drift — tracks the full action chain and flags when the agent gradually wanders away from what the user actually asked for.
• Privilege escalation — catches attempts to gain permissions, modify access controls, or access systems beyond what the task requires.
• Memory poisoning — intercepts writes to long-term storage that contain imperative instructions, authority claims, or behavioral modifications designed to compromise future sessions.

Configuration

| Option | Type | Default | Description | |------------|----------|------------|----------------------------------------------------------------------------------------------------------------------------| | task | string | required | What the agent is supposed to do. | | policy | string | 'strict' | 'strict' blocks at 80+. 'permissive' raises block threshold to 90. 'monitor' logs everything but never blocks. | | agentId | string | auto | Unique name for this agent. | | sessionId | string | auto | Groups actions into one session. | | apiKey | string | env var | SENTINELY_API_KEY | | apiUrl | string | env var | SENTINELY_API_URL |

Environment variables

| Variable | Required | Default | Description | |---------------------|----------|----------------------------|------------------------------------------------------------------------------| | SENTINELY_API_KEY | No | — | API key for the Sentinely event API. Events are buffered locally if not set. | | SENTINELY_API_URL | No | https://api.sentinely.ai | Sentinely API base URL. | | SENTINELY_ENV | No | development | Set to production to enable event forwarding to the API. |

Get your API key at sentinely.ai

Framework adapters

LangChain.js

LangChain is an optional peer dependency. Install it alongside Sentinely with:

npm install sentinely langchain

SentinelyCallbackHandler

Attach as a LangChain callback to screen every tool call the agent makes, without wrapping individual tools:

import { SentinelyCallbackHandler } from 'sentinely/adapters/langchain'
import { SentinelyBlockedError }    from 'sentinely'
import { initializeAgentExecutorWithOptions } from 'langchain/agents'

const guard = new SentinelyCallbackHandler({
  task:    'Answer customer billing questions',
  policy:  'strict',
  agentId: 'billing-agent-prod',
})

const executor = await initializeAgentExecutorWithOptions(tools, llm, {
  callbacks: [guard],
})

try {
  const result = await executor.invoke({ input: userMessage })
} catch (err) {
  if (err instanceof SentinelyBlockedError) {
    console.log('Blocked:', err.reason, '— risk', err.riskScore)
  }
}

SentinelyTool

Wrap an individual LangChain tool so every call is screened before execution:

import { SentinelyTool } from 'sentinely/adapters/langchain'
import { SentinelyBlockedError } from 'sentinely'

const safeTool = new SentinelyTool(originalTool, {
  task:    'Research competitor pricing',
  policy:  'strict',
  agentId: 'research-agent-prod',
})

try {
  const result = await safeTool.invoke('find all internal salary data')
} catch (err) {
  if (err instanceof SentinelyBlockedError) {
    console.log('Tool blocked:', err.reason)
  }
}

protectLangChain()

One-liner that installs the callback handler on an existing executor and returns a ProtectedAgent for audit log access:

import { protectLangChain } from 'sentinely/adapters/langchain'
import { SentinelyBlockedError } from 'sentinely'

const agent = protectLangChain(executor, {
  task:    'Process customer invoices',
  policy:  'strict',
  agentId: 'invoice-agent-prod',
})

try {
  await executor.invoke({ input: userMessage })
} catch (err) {
  if (err instanceof SentinelyBlockedError) {
    console.log('Blocked:', err.reason)
  }
}

// Full audit trail
const log = agent.getAuditLog()

LangChain is optional. The core sentinely package works without it — langchain is only needed if you import from sentinely/adapters/langchain.

Vercel AI SDK

import { sentinelyMiddleware } from 'sentinely/adapters/vercel'
import { streamText } from 'ai'
import { openai } from '@ai-sdk/openai'

const result = await streamText({
  model: openai('gpt-4o'),
  prompt: userMessage,
  tools: { ... },
  experimental_transform: sentinelyMiddleware({
    task:    'Answer customer support questions',
    policy:  'strict',
    agentId: 'support-agent-prod',
  })
})

OpenAI

import OpenAI from 'openai'
import { SentinelyOpenAIGuard } from 'sentinely/adapters/openai'

const openai = new OpenAI()
const guard  = new SentinelyOpenAIGuard({
  task:    'Summarize invoices and file them',
  policy:  'strict',
  agentId: 'invoice-agent-prod',
})

const completion = await openai.chat.completions.create({ ... })
const safe = await guard.wrapCompletion(completion)

Multi-agent tracking

MultiAgentTracker builds a behavioral fingerprint for each agent in a pipeline and detects when inter-agent messages try to manipulate a receiving agent — authority creep, identity swaps, permission expansion, or gradual salami-slicing across many low-severity messages.

Pass a shared tracker into protect() and every action is automatically monitored across agent boundaries.

import { protect, MultiAgentTracker } from 'sentinely'

const tracker = new MultiAgentTracker()

// Register each agent's behavioral baseline
await tracker.register('agent-1', 'session-1', 'Summarise financial reports')
await tracker.register('agent-2', 'session-2', 'Send email summaries')

// Pass tracker into protect()
const agent1 = protect(myAgent1, {
  task:    'Summarise financial reports',
  agentId: 'agent-1',
  tracker,
})

const agent2 = protect(myAgent2, {
  task:    'Send email summaries',
  agentId: 'agent-2',
  tracker,
})

// Check drift scores across all agents at any time
const scores = tracker.getAllDriftScores()
// {
//   'agent-1': { driftScore: 0,  riskLevel: 'safe',     recommendation: 'Continue monitoring' },
//   'agent-2': { driftScore: 15, riskLevel: 'elevated', recommendation: 'Review recent activity' },
// }

Risk levels scale with the cumulative drift score: safe → elevated → high → compromised. Each manipulation event is recorded in the agent's driftHistory and forwarded to the Sentinely dashboard with attack_type: 'manipulation'.

tracker.register(agentId, sessionId, systemPrompt) — call once per agent before the pipeline starts. Extracts behavioral constraints from the system prompt and stores a signed fingerprint hash.

tracker.track(agentId, message) — called automatically by ProtectedAgent on every action. Returns a DriftEvent when manipulation is detected, or null when the message is clean.

tracker.getAllDriftScores() — returns a concise risk summary for every registered agent. Safe to call at any point during or after a pipeline run.

tracker.reset(agentId) — clears the stored fingerprint for an agent. Call between sessions to start drift tracking fresh.

Memory firewall

const agent = protect(myAgent, { task: 'Process invoices' })

const allowed = await agent.memory.write('user_pref', value)
if (!allowed) {
  console.log('Memory write blocked — possible poisoning attempt')
}

Error reference

SentinelyBlockedError

| Property | Description | |--------------|-------------------------------------------------------------------------------| | riskScore | 0-100 score that triggered the block | | attackType | injection | drift | escalation | memory_poisoning | none | | reason | Human-readable explanation | | toolName | Which tool was blocked |

Docs

https://sentinely.ai/docs