🌐 Español
AI Agent Security & Governance SDK
Deterministic governance, guardrails, cost tracking, and policy management for LLM applications. Open source. TypeScript + Python. Works with any provider.
Website · Documentation · Examples · Discord · Contributing
Install: npm install tealtiger or pip install tealtiger, then wrap one existing OpenAI call:
import { TealOpenAI } from 'tealtiger';
const client = new TealOpenAI({ apiKey: process.env.OPENAI_API_KEY, guardrails: { promptInjection: true } });
const res = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'Hello!' }] });
console.log(res.security?.decision ?? 'ALLOW');import os
from tealtiger import TealOpenAI
client = TealOpenAI(api_key=os.environ["OPENAI_API_KEY"], guardrails={"prompt_injection": True})
print(client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello!"}]).security.decision)ALLOW
Governance receipt emitted; cost and guardrails tracked.
Next: full Quick Start and examples.
Getting started in 5 minutes — from pip install to a governed agent with PII blocking, tool allowlists, and JSON decision output. No API key required.
pip install tealtiger
python examples/quickstart_governance.pyThe tutorial covers:
- Observe mode — wrap an OpenAI client in one line (
observe(client)) - PII policy — block SSNs in tool arguments
- Tool allowlist — only allow
searchandread_* - Decision output — structured JSON for every governance verdict
- MONITOR vs ENFORCE — log violations without blocking, then flip to block
See the full walkthrough in docs/quickstart.md.
One line adds cost tracking, audit logging, PII detection, and behavioral baselines to any LLM client. No config files, no policy definitions.
import { observe, freeze } from 'tealtiger';
const client = observe(new OpenAI()); // done — all calls are now instrumented
console.log(client.getCost()); // { totalCost: 0.0023, requestCount: 1, ... }from tealtiger.observe import observe, freeze
client = observe(OpenAI()) # done — all calls are now instrumented
print(client.get_cost()) # ObserveCostSummary(total_cost=0.0023, ...)What you get automatically: per-request cost tracking across 7 providers, structured audit log with correlation IDs, behavioral baseline (P50/P95/P99), PII detection in REPORT_ONLY mode, and an instant kill switch via freeze(). Under 5ms overhead per call.
See examples/observe-quickstart.ts and examples/observe_quickstart.py.
Real-time visibility into your AI agent fleet — security posture, cost governance, and behavioral alerts in one view.
What you see at a glance:
- KPI Row — Total requests, cost, governance denials, budget consumption with color-coded indicators
- Cost Velocity & Budget Forecast — Burn rate trends and exhaustion projection
- Defense Pipeline — 3-stage security evaluation flow with short-circuit rates and latency per stage
- Canary Alerts — Behavioral drift detection with agent freeze status and deviation percentages
- Agent Matrix — Fleet status table (active/idle/frozen) with per-agent request metrics
- Cost Savings — Optimization recommendations ranked by impact
- Model Routing — Source-to-target routing with per-request savings
- Protocol Governance — ENFORCE/MONITOR/REPORT_ONLY policy cards with denial counts
Every panel is independently data-fetched with fault isolation — one widget failure never cascades to others.
Run locally: cd dashboard/api && npm run dev then cd dashboard/web && npm run dev (API on :3100, UI on :3000)
| Level | Entry Point | What You Get |
|---|---|---|
| 0 | observe(client) |
Cost tracking, audit trail, PII detection, behavioral baseline, kill switch |
| 1 | + guardrails config | Prompt injection, content moderation, secret detection |
| 2 | + TealEngine policies | ENFORCE/MONITOR/REPORT_ONLY per rule, deterministic decisions |
| 3 | + TealFlow workflows | Org-level governance inheritance, declarative YAML |
TealTiger is an open-source SDK that provides deterministic governance for AI agents. It enforces security policies, tracks costs, and produces structured evidence — all at runtime, with no infrastructure required.
Looking for the source code? This is the hub repo. The SDK source lives in the language-specific repos:
- TypeScript SDK: tealtiger-typescript-prod
- Python SDK: tealtiger-python-prod
Or clone this repo with submodules:
git clone --recurse-submodules https://github.com/agentguard-ai/tealtiger.git
Unlike probabilistic safety filters, TealTiger uses deterministic policy evaluation: same input + same policy = same decision, every time. Every governance verdict is reconstructable, traceable to the human who authored the policy, and exportable as structured evidence (SARIF, JUnit XML, JSON).
Key principle: Governance should be an engineering property embedded in the runtime — not a document reviewed after the fact.
npm install tealtigerimport { TealOpenAI } from 'tealtiger';
const client = new TealOpenAI({
apiKey: process.env.OPENAI_API_KEY,
guardrails: {
piiDetection: true,
promptInjection: true,
contentModeration: true,
},
budget: {
maxCostPerRequest: 0.50,
maxCostPerDay: 10.00,
},
});
const response = await client.chat.completions.create({
model: 'gpt-4',
messages: [{ role: 'user', content: 'Hello!' }],
});
// Guardrails enforced. Cost tracked. Evidence produced.pip install tealtigerfrom tealtiger import TealOpenAI
client = TealOpenAI(
api_key=os.getenv("OPENAI_API_KEY"),
guardrails={
"pii_detection": True,
"prompt_injection": True,
"content_moderation": True,
},
budget={
"max_cost_per_request": 0.50,
"max_cost_per_day": 10.00,
},
)
response = client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "Hello!"}],
)
# Guardrails enforced. Cost tracked. Evidence produced.- PII Detection — Detect and redact sensitive information automatically
- Prompt Injection Prevention — Block malicious prompt injection attempts
- Content Moderation — Filter toxic, harmful, or inappropriate content
- Secret Detection — 500+ patterns across 9 categories with confidence scoring
- Custom Rules — Define your own security policies
- Budget Enforcement — Hard limits per request, session, and day
- Cost Tracking — Real-time monitoring across all providers
- Cost Alerts — Notifications at configurable thresholds
- Circuit Breakers — Prevent runaway cost loops automatically
- OpenAI — GPT-4, GPT-4o, GPT-3.5
- Anthropic — Claude 3.5, Claude 3
- Google Gemini — Multimodal support
- AWS Bedrock — Claude, Titan, Jurassic, Command, Llama
- Azure OpenAI — Deployment-based routing (shares OpenAI pricing)
- Cohere — Chat, RAG, embeddings
- Mistral AI — European data residency
- AWS Bedrock Agents — Native guardrail adapter
- AWS AgentCore — Pre/post action governance plugin
- Azure AI Agent Service — Tool-call pipeline middleware
- Deterministic Policy Evaluation — No LLM in the governance path
- Structured Evidence — Every decision produces a reconstructable record
- Cryptographic Proof — Merkle trees + RFC 3161 timestamping (TealProof)
- Non-Human Identity (NHI) — Agent lifecycle, scope enforcement, Zero Standing Privilege
- FREEZE Rules — Immutable emergency kill switches with tamper detection
- Correlation IDs — End-to-end traceability across the decision chain
- Policy Traceability — Every verdict traces to the human policy author
- OWASP Agentic Top 10 — Zero-config policy pack covering all 10 ASI risks
| Dimension | What it does | Module |
|---|---|---|
| 🛡️ Security | Secret detection (500+ patterns), prompt injection, PII, content moderation, Unicode normalization, encoded output detection | TealSecrets TealGuard |
| 🔑 Identity | Non-Human Identity lifecycle, scope enforcement, Zero Standing Privilege, agent attestation | TealEngine (NHI) |
| ⚡ Reliability | Circuit breakers, retry budgets, fallback chains, deterministic degradation | TealCircuit TealReliability |
| 🧠 Memory | Write provenance, instruction injection detection, exfiltration prevention, scope enforcement | TealMemory |
| 💰 Cost | Governance-owned ceilings, anomaly detection, reasoning-token budgets, per-agent attribution | TealMonitor |
| 📋 Evidence | Cryptographic receipts (Merkle + RFC 3161), SARIF export, OTel spans, SIEM integration | TealProof TealAudit |
| ⚙️ Policy | FREEZE rules, PLAN_ONLY mode, hot-swap bundles, anti-tamper, automation levels | TealEngine |
| 🔄 Workflow | Declarative YAML governance workflows, org-level inheritance, floor enforcement | TealFlow |
| 📊 Drift | Behavioral drift detection, statistical baselines, model output regression | TealDrift |
| ⏱️ Temporal | Session TTL, cooldown periods, time-of-day restrictions | TealTemporal |
| 🔍 Registry | MCP definition-drift monitoring, tool description scanning, adapter composition allowlist | TealRegistry |
| 🧠 Classification | Local ONNX ML inference (≤20ms), ensemble modes, regex+ML combination | TealClassifier |
Design principle: No LLM in the governance path. Same input + same policy = same decision, every time.
| Language | Source Code | Package | Install |
|---|---|---|---|
| TypeScript | tealtiger-typescript-prod | npm | npm install tealtiger |
| Python | tealtiger-python-prod | PyPI | pip install tealtiger |
TealTiger ships governance adapters for 13 agent frameworks. A selection:
| Framework | Package | Install |
|---|---|---|
| LangChain | langchain-tealtiger | pip install langchain-tealtiger |
| Vercel AI SDK | tealtiger-ai-sdk | npm install tealtiger-ai-sdk |
| PydanticAI | pydanticai-tealtiger | pip install pydanticai-tealtiger |
| Haystack | haystack-tealtiger | pip install haystack-tealtiger |
| CAMEL-AI | camelai-tealtiger | pip install camelai-tealtiger |
Also available: LangGraph, AG2, LlamaIndex, Mastra, OpenAI Agents, Google ADK, Semantic Kernel, OpenHands, CopilotKit. See packages/ for the full set.
- Why your AI agent needs a budget — cost governance for LLM apps
- OWASP Agentic Top 10 — practical defenses with TealTiger
- Getting Started in 5 Minutes
- Quick Start Guide
- Security Guardrails
- Cost Governance
- Provider Setup
- FAQ
- Why TealTiger?
- Cross-SDK Feature Parity Matrix
- Governance Event Store Indexes
- Error Code Reference
- Troubleshooting
- Contributing Guide
- Security Policy
- Code of Conduct
- Roadmap
Use the TealTiger badge to show that a project is governed by deterministic agent security and cost policies.
Light badge:
[](https://github.com/agentguard-ai/tealtiger)Dark badge:
[](https://github.com/agentguard-ai/tealtiger)Use examples/python/huggingface_tgi_quickstart.py to try the guarded
Hugging Face Text Generation Inference provider from the Python SDK.
export HF_API_TOKEN="your-hugging-face-token"
export HF_TGI_ENDPOINT="https://your-endpoint.endpoints.huggingface.cloud"
export HF_TGI_MODEL="meta-llama/Meta-Llama-3.1-8B-Instruct"
python examples/python/huggingface_tgi_quickstart.pyThe example enables guardrail and cost-tracking configuration, sends one sample
chat request, then prints the response, token usage, estimated cost, provider,
and correlation ID. Use placeholder values in docs and .env.example files;
never commit a real HF_API_TOKEN.
Use schemas/tealtiger-policy.schema.json for editor autocomplete and validation when authoring TealEngine policy JSON or YAML files. JSON policy files can include:
{
"$schema": "./schemas/tealtiger-policy.schema.json"
}For YAML policies, configure your editor's YAML schema mapping to point policy files such as tealtiger-policy.yml at ./schemas/tealtiger-policy.schema.json.
Use the policy validator script to check a TealTiger policy JSON file before using it in CI/CD or runtime governance:
npm install
npx ts-node scripts/validate-policy.ts ./my-policy.jsonYou can also run the npm script:
npm run validate:policy -- ./my-policy.jsonThe validator loads
schemas/tealtiger-policy.schema.json,
prints schema validation errors, exits 0 when the policy is valid, and exits
1 when the policy is invalid.
TealTiger is open source and we're looking for early contributors to shape the future of AI agent governance.
| Area | Examples | Difficulty |
|---|---|---|
| 🔍 Secret Detection | New detection patterns, custom categories | 🟢 Beginner |
| 📝 Documentation | Guides, examples, API docs, typo fixes | 🟢 Beginner |
| 🧪 Tests | Unit tests, property-based tests, integration tests | 🟡 Intermediate |
| 🔌 Integrations | LangChain, CrewAI, AG2, LlamaIndex middleware | 🟡 Intermediate |
| 💾 Memory Adapters | Redis, Pinecone, Weaviate, ChromaDB adapters | 🟡 Intermediate |
| 🔄 CI/CD Templates | Jenkins, Azure Pipelines, Bitbucket Pipelines | 🟡 Intermediate |
| 🏗️ Core Modules | Governance engine, evidence export, policy evaluation | 🔴 Advanced |
- 🏆 Named in CONTRIBUTORS.md and release notes
- 🎖️ "Founding Contributor" badge — first 25 merged PRs get permanent recognition
- 📣 Shoutout on TealTiger social channels (LinkedIn, X, Dev.to)
- 🔑 Early access to upcoming governance features before public release
- 💬 Direct access to the core team via GitHub Discussions
- 📝 Co-authorship opportunity on technical blog posts
# 1. Star this repo (it helps!)
# 2. Fork and clone the SDK you want to contribute to:
# TypeScript SDK:
git clone https://github.com/agentguard-ai/tealtiger-typescript-prod.git
# Python SDK:
git clone https://github.com/agentguard-ai/tealtiger-python-prod.git
# 3. Pick a "good first issue"
# https://github.com/agentguard-ai/tealtiger/issues?q=label%3A%22good+first+issue%22
# 4. Submit a PR
# 5. Join the team 🐯See CONTRIBUTING.md for detailed guidelines.
Current: v1.4.0 — Zero-Config Adoption & Governance Dashboard (Released July 9, 2026)
observe(client)— 1-line auto-instrumentation for 7 providers, zero configfreeze()/unfreeze()— instant kill switch, zero policy required- Behavioral baseline — P50/P95/P99 profiling built from first 100 requests
- PII detection in REPORT_ONLY mode — passive scanning without blocking
- Governance Dashboard — redesigned with light theme, security widgets, error isolation
- Under 5ms overhead per call — in-process, deterministic, offline-capable
Previous: v1.3.0 — Autonomous Agent Governance (Released May 18, 2026)
Planned: v1.5.0 — Enterprise Platform (Q4 2026)
- Multi-tenancy with complete data isolation
- RBAC (Owner, Admin, Policy Author, Viewer, Auditor)
- SSO via SAML 2.0 / OIDC (Okta, Azure AD, Google)
- SIEM export (Splunk, Elastic, Sentinel, Datadog)
- Policy staging, dry-run mode, canary deployments
- Scheduled compliance reports & executive dashboard
Future: v2.0.0 — SaaS Security Platform (Q1 2027)
- Full SaaS control plane (CSPM/CWPP model for AI agents)
- CISO executive console with governance health scoring
- TealTiger Operator & Agent for Kubernetes
- Shadow AI detection (discover ungoverned agents)
- Remote kill switch from SaaS console
- CloudEvents, OpenTelemetry, Backstage plugin
- Discord: Join TealTiger Community
- GitHub Discussions: Ask questions, share ideas
- LinkedIn: TealTiger
- X (Twitter): @TealtigerAI
- Documentation: docs.tealtiger.ai
- Blog: blogs.tealtiger.ai
- Playground: playground.tealtiger.ai
- Email: reachout@tealtiger.ai
TealTiger is committed to responsible open-source security practices.
For vulnerability reports, see our Security Policy.
TealTiger is Apache 2.0 licensed.
Built with ❤️ by the TealTiger team and contributors.
Want to contribute? Check out our CONTRIBUTING.md guide!
⭐ Star this repo if you believe AI agents need governance, not just guardrails.
Pricing data is from docs/cost-comparison.md (last updated April 2026).
Coverage shows whether TealTiger has verified cost tracking via the observe() API end-to-end.
- ✅ — Verified end-to-end via
observe()+ tested intest_property_20_cost_monotonicity.py - 🟡 — Imported in
observe()adapter, no property test yet - 🛠️ — Adapter example exists, no
observe()integration yet - ❌ — Listed in
cost-comparison.mdonly, no SDK hook yet (PRs welcome)