Notifications You must be signed in to change notification settings
Fork 0
Star 0
BranchesTags
Open more actions menu
Folders and files
NameName
Last commit message
Last commit date
Latest commit
History
71 Commits
71 Commits
.github/workflows
.github/workflows
api
api
assets
assets
dashboard
dashboard
docs
docs
examples
examples
scripts
scripts
sdk-ts
sdk-ts
sdk
sdk
.env.example
.env.example
.gitignore
.gitignore
CHANGELOG.md
CHANGELOG.md
CONTRIBUTING.md
CONTRIBUTING.md
LICENSE
LICENSE
PATENTS.md
PATENTS.md
README.md
README.md
docker-compose.yml
docker-compose.yml
ruff.toml
ruff.toml
Repository files navigation
AI agents can call APIs, execute code, browse the web, and make real-world decisions. Without guardrails:
🔄 A single misconfigured agent can enter an infinite loop
💸 A runaway agent can burn through $10,000+ in API credits overnight
💀 Agents can take destructive actions with zero visibility
SteerPlane fixes this with one line of code.
How It Works
from steerplane import guard
@guard( agent_name="support_bot", max_cost_usd=10.00, max_steps=50, denied_actions=["delete_*", "sudo_*"], enforcement="alert", alert_threshold=0.8, alert_timeout_sec=1800, ) def run_agent():
Your agent runs normally.
SteerPlane silently monitors every step.
Financial/runtime limits can pause for human approval.
Loops and policy violations still terminate immediately.
agent.run()
🚀 SteerPlane | Run Started Run ID: a3f8d2b1-... Agent: support_bot Limits: $10.00 cost / 50 steps ───────────────────────────────────────────── ✅ Step 1: query_database | 380 tokens | $0.0020 | 45ms ✅ Step 2: call_llm_analyze | 1240 tokens | $0.0080 | 320ms ✅ Step 3: search_knowledge | 560 tokens | $0.0030 | 89ms ✅ Step 4: generate_response | 1800 tokens | $0.0120 | 450ms ✅ Step 5: send_notification | 120 tokens | $0.0010 | 200ms ─────────────────────────────────────────────
✅ SteerPlane | Run COMPLETED Steps: 5 Cost: $0.0260 Tokens: 4,100 Duration: 1.1s
Features
Feature What It Does
🔄 Loop Detection O(W²) sliding-window algorithm catches single-action, alternating, and multi-step repeating patterns in sub-millisecond time — no LLM calls
💰 Cost Ceiling Per-run (SDK) / per-session (gateway) USD limits, checked after each step so overshoot is bounded to a single step. Built-in pricing for 25+ models across OpenAI, Anthropic, Google, Meta, and Mistral
🌊 Streaming Gateway Real-time SSE chunk forwarding with mid-stream cost kill — if the budget is exceeded during a stream, SteerPlane injects a termination event and cuts the connection
🛡️ Policy Engine Allow/deny lists with glob patterns and sliding-window rate limits
🌐 Gateway Proxy OpenAI-compatible API proxy — change only base_url for zero-code enforcement. The agent passes its provider key through the gateway, which forces all traffic through enforcement before forwarding upstream
🖥️ Real-Time Dashboard Next.js dashboard with auto-refresh, animated timelines, cost breakdowns, and policy management
🔧 CLI Tool steerplane runs list, steerplane status, steerplane keys create — manage everything from your terminal
📄 Config File .steerplane.yml auto-discovery — set defaults without hardcoding limits in source code
🔗 4 Framework Integrations LangChain, OpenAI Agents SDK, CrewAI, AutoGen — zero-config drop-in handlers
🐳 Docker Compose One command brings up API + Dashboard + PostgreSQL
🔌 Graceful Degradation If the API goes down, the SDK enforces all limits locally. Agents are never unprotected
🧪 CI/CD GitHub Actions pipeline — lint, test, build Docker on every push
Hosted/Enterprise tier: alert-mode human-approval workflows (with email/webhook notifications), server-side provider-key vaulting, and Redis-backed multi-worker gateway state are available on SteerPlane's hosted plan. The open-source SDK still exposes the enforcement="alert" client options so it works out of the box against a hosted or enterprise deployment — self-hosting only the free tier here runs kill-mode enforcement.
Quick Start
Option A: Docker (Recommended)
git clone https://github.com/vijaym2k6/SteerPlane.git cd SteerPlane cp .env.example .env docker compose up -d
API at localhost:8000 · Dashboard at localhost:3000 · PostgreSQL auto-configured.
Option B: Manual Setup
Install the SDK
pip install steerplane
Start the API
cd api && pip install -r requirements.txt uvicorn app.main:app --reload --port 8000
Start the Dashboard
cd dashboard && npm install && npm run dev
Option C: CLI
pip install steerplane[cli] steerplane status # Check API health steerplane runs list # List recent runs steerplane keys create -n prod # Generate API key
Run the Demo Agent
python examples/simple_agent/agent_example.py
Open localhost:3000 → See your agent run in real time.
SDK Reference
Python — Decorator API
from steerplane import guard
@guard( agent_name="my_bot", max_cost_usd=10.00, max_steps=50, max_runtime_sec=300, enforcement="alert", alert_threshold=0.8, denied_actions=["delete_*", "sudo_*"], allowed_actions=["search_*", "read_*", "generate_*"], rate_limits=[{"pattern": "call_llm*", "max_count": 20, "window_seconds": 60}], ) def run_my_agent(): agent.run()
Python — Context Manager API
from steerplane import SteerPlane
sp = SteerPlane(agent_id="my_bot")
with sp.run(max_cost_usd=10.0, max_steps=50) as run: run.log_step("query_db", tokens=380, cost=0.002, latency_ms=45) run.log_step("generate", tokens=1240, cost=0.008, latency_ms=320)
TypeScript
import { guard, GuardOptions } from 'steerplane';
const protectedAgent = guard(async (run) => { await run.logStep({ action: 'query_db', tokens: 380, cost: 0.002 }); await run.logStep({ action: 'generate', tokens: 1240, cost: 0.008 }); return 'done'; }, { agentName: 'support_bot', maxCostUsd: 10.0, maxSteps: 50, policy: { deniedActions: ['delete_*', 'sudo_*'], }, });
const result = await protectedAgent();
Exception Handling
from steerplane.exceptions import ( CostLimitExceeded, LoopDetectedError, StepLimitExceeded, PolicyViolationError, )
@guard(max_cost_usd=5, denied_actions=["delete_*"]) def run_agent(): try: agent.run() except CostLimitExceeded as e: print(f"Budget exceeded: {e}") except LoopDetectedError as e: print(f"Loop detected: {e}") except StepLimitExceeded as e: print(f"Step limit hit: {e}") except PolicyViolationError as e: print(f"Policy violation: {e.action} blocked by {e.rule}")
Config File (.steerplane.yml)
Set defaults in a .steerplane.yml at your project root instead of hardcoding limits:
api_url: http://localhost:8000 agent_name: my_bot
defaults: max_cost_usd: 25.0 max_steps: 100 max_runtime_sec: 1800 enforcement: alert loop_window_size: 10
policy: denied_actions:
- "delete_*"
- "drop_*"
rate_limits:
- pattern: "search_*"
max_count: 10 window_seconds: 60
alerts: email: [email protected] webhook_url: https://hooks.slack.com/... threshold: 0.8
Merge order: Explicit decorator params → .steerplane.yml → hardcoded defaults. The config file is auto-discovered by walking up from the current directory.
Framework Integrations
LangChain
from steerplane.integrations.langchain import SteerPlaneCallbackHandler
handler = SteerPlaneCallbackHandler( agent_name="research_bot", max_cost_usd=5.0, max_steps=30, )
llm = ChatOpenAI(model="gpt-4o", callbacks=[handler]) agent.run("Analyze this data", callbacks=[handler]) handler.finish()
OpenAI Agents SDK
from steerplane.integrations.openai_agents import SteerPlaneAgentHooks
hooks = SteerPlaneAgentHooks( agent_name="my_openai_agent", max_cost_usd=10.0, max_steps=100, )
Convenience wrapper
result = await hooks.run(agent, "Hello!")
Or manual lifecycle
hooks.start() result = await Runner.run(agent, "Hello!") hooks.finish()
CrewAI
from steerplane.integrations.crewai import SteerPlaneCrewMonitor
monitor = SteerPlaneCrewMonitor( agent_name="my_crew", max_cost_usd=25.0, max_steps=200, )
crew = Crew( agents=[researcher, writer], tasks=[research_task, write_task], step_callback=monitor.step_callback, )
result = monitor.kickoff(crew)
AutoGen
from steerplane.integrations.autogen import SteerPlaneAutoGenMonitor
monitor = SteerPlaneAutoGenMonitor( agent_name="my_autogen_group", max_cost_usd=15.0, max_steps=150, )
result = monitor.initiate_chat(user_proxy, assistant, message="Hello!")
Install only the integration you need:
pip install steerplane[langchain] # LangChain pip install steerplane[cli] # CLI tool pip install steerplane[yaml] # Config file support pip install steerplane[all] # Everything
Gateway Proxy (Zero-Code Mode)
For agents you can't modify, SteerPlane provides an OpenAI-compatible gateway proxy with real-time streaming and mid-stream cost enforcement:
from openai import OpenAI
client = OpenAI( base_url="http://localhost:8000/gateway/v1", api_key="sk_sp_your_steerplane_key",
The real provider key is sent to the gateway, which forwards it upstream.
default_headers={"X-LLM-API-Key": "sk-your-real-provider-key"}, )
Streaming works — chunks forwarded in real-time
for chunk in client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "Hello"}], stream=True, ): print(chunk.choices[0].delta.content, end="")
What the gateway enforces per request:
Policy rules (deny/allow/rate limits)
Session cost vs. ceiling (including mid-stream kill)
SHA-256 prompt-hash loop detection
Monthly budget tracking
Anthropic + OpenAI streaming support
Security model: The agent points its OpenAI client at the gateway and passes the real provider key in the X-LLM-API-Key header. The gateway authenticates the SteerPlane key, runs every request through enforcement (policy → cost → loop), and only then forwards it upstream with that provider key — so the agent can't reach the provider directly or bypass the guardrails.
Server-side provider-key vaulting (so the agent never sends X-LLM-API-Key) is available on the hosted/enterprise plan.
CLI Tool
pip install steerplane[cli]
Command Description
steerplane status Check API server health
steerplane runs list List recent runs (filter by --status)
steerplane runs inspect Full run detail with step-by-step table
steerplane runs kill Force-terminate a live run
steerplane keys list List all API keys
steerplane keys create --name prod Generate a new API key
steerplane keys revoke Revoke a key
steerplane logs --tail Live polling of running agents
Policy Engine
The policy engine runs before any cost is incurred, enforcing rules in strict priority order:
Deny List → Allow List → Rate Limits
Rule Type How It Works
Deny list Glob patterns (e.g. delete_*) — any match is blocked immediately
Allow list If set, action must match at least one pattern to proceed
Rate limits Sliding-window counters per pattern — blocks when count exceeds threshold
Available in Python and TypeScript SDKs, the dashboard UI, REST API, and .steerplane.yml config file.
Enforcement Mode
The self-hosted free tier runs kill mode: immediate, deterministic termination on any violation.
The SDK also exposes an enforcement="alert" option (pause → notify a human → approve/deny/extend → auto-terminate on timeout) — this requires the human-approval workflow backend, which is part of the hosted/enterprise plan. Pointed at the free self-hosted API, alert mode fails closed: it safely terminates the run with a clear error rather than continuing unprotected.
Safety invariant: Loop detection and policy violations always trigger immediate termination regardless of enforcement mode. These are non-overridable security constraints.
Docker Deployment
cp .env.example .env # Edit with your values docker compose up -d # Starts all 3 services
Service Image Port Purpose
postgres postgres:16-alpine 5432 Primary database
api steerplane-api 8000 FastAPI backend
dashboard steerplane-dashboard 3000 Next.js UI
Database migrations
[truncated for AI cost control]