Build AI agents that are observable, controllable, and production-safe β not just demos.
Most AI systems today are:
- β Non-deterministic
- β Hard to debug
- β Unsafe in production
- β Expensive at scale
AgentOS fixes this.
- β Constraint-aware execution
- β Full observability (cost, latency, actions)
- β Deterministic agent workflows
- β Production-first architecture
User Input
β
Planner Agent (task decomposition)
β
Constraint Engine (policy enforcement)
β
Executor Agent (tool calls)
β
Memory Layer (RAG / context)
β
Response + Observability
- Policy-based execution control (DSL-driven)
- Blocks unsafe actions (delete, financial, etc.)
- Human-in-the-loop approvals
- Action-level enforcement (not just prompts)
policies:
- name: allow_read
action: read
effect: allow
- name: block_delete
action: delete
effect: deny
- name: financial_requires_approval
action: financial
effect: require_approval
- name: api_rate_limit
action: external_api
condition:
max_calls_per_minute: 60
effect: throttleimport yaml
class Policy:
def __init__(self, name, action, effect, condition=None):
self.name = name
self.action = action
self.effect = effect
self.condition = condition or {}
def load_policies(path: str):
with open(path, "r") as f:
data = yaml.safe_load(f)
return [Policy(**p) for p in data["policies"]]class ConstraintEngine:
def __init__(self, policies):
self.policies = policies
def evaluate(self, action: str, metadata: dict):
for policy in self.policies:
if policy.action == action:
return self._apply(policy, metadata)
return {"status": "allow"}
def _apply(self, policy, metadata):
if policy.effect == "deny":
return {"status": "blocked", "reason": policy.name}
if policy.effect == "require_approval":
return {"status": "pending_approval"}
if policy.effect == "throttle":
return {"status": "throttled"}
return {"status": "allow"}class ActionInterceptor:
def __init__(self, constraint_engine):
self.engine = constraint_engine
def execute(self, action, payload):
decision = self.engine.evaluate(action, payload)
if decision["status"] == "blocked":
raise Exception(f"Blocked by policy: {decision['reason']}")
if decision["status"] == "pending_approval":
return {"status": "waiting_human"}
return self._execute_action(action, payload)
def _execute_action(self, action, payload):
# call actual tool here
return {"status": "success", "data": payload}- Planner Agent (task decomposition)
- Executor Agent (tool execution)
- Modular agent architecture
- Typed, structured communication (no string chaos)
class PlannerAgent:
def plan(self, user_input: str):
return {
"tasks": [
{"action": "read", "target": "knowledge_base"},
{"action": "external_api", "target": "weather_api"}
]
}class ExecutorAgent:
def __init__(self, interceptor):
self.interceptor = interceptor
def execute(self, plan):
results = []
for task in plan["tasks"]:
result = self.interceptor.execute(
action=task["action"],
payload=task
)
results.append(result)
return resultsdef run_agent_system(user_input):
plan = planner.plan(user_input)
result = executor.execute(plan)
return result- Full trace of every action
- Cost per query tracking
- Latency monitoring (P95)
- Debuggable execution pipeline
def log_event(event_type, payload):
print(f"[LOG] {event_type}: {payload}")- No hidden behavior
- Every step logged + auditable
- Schema-validated outputs
- Reproducible workflows
- FastAPI-based service
- Dockerized deployment
- Scalable architecture
- Easy integration into existing systems
User Input
β
Planner Agent (task decomposition)
β
Constraint Engine (policy enforcement)
β
Executor Agent (tool execution)
β
Memory / External APIs
β
Response + Observability
- Breaks user input into structured tasks
- Ensures predictable execution flow
- Central policy enforcement layer
- Evaluates every action before execution
- Gatekeeper for all agent actions
- Applies constraint decisions in real-time
- Executes tasks via tools/APIs
- Handles retries, failures, fallbacks
- Logs all inputs/outputs/actions
- Enables debugging + monitoring
| Layer | Technology |
|---|---|
| API | FastAPI |
| Runtime | Python 3.11 |
| Containerization | Docker |
| Policy Engine | Custom DSL (YAML) |
| Testing | Pytest |
| Orchestration | Custom pipeline (LangGraph-ready) |
β
βββ README.md
βββ docs/
β βββ architecture.md
β βββ adr/
β β βββ ADR-001-orchestration.md
β β βββ ADR-002-memory.md
β β βββ ADR-003-constraint-engine.md
β βββ runbook.md
β βββ hardening-report.md
β
βββ apps/
β βββ api/ # FastAPI backend
β βββ worker/ # Background jobs
β βββ dashboard/ # Observability UI (optional)
β
βββ agentos/
β βββ agents/
β β βββ planner.py
β β βββ executor.py
β β βββ base.py
β β
β βββ orchestration/
β β βββ graph.py
β β βββ router.py
β β
β βββ memory/
β β βββ short_term.py
β β βββ long_term.py
β β βββ vector_store.py
β β
β βββ constraints/
β β βββ dsl.py
β β βββ parser.py
β β βββ engine.py
β β βββ policies/
β β βββ default.yaml
β β
β βββ observability/
β β βββ logger.py
β β βββ tracing.py
β β
β βββ tools/
β β βββ base.py
β β βββ registry.py
β β
β βββ utils/
β βββ schema.py
β
βββ tests/
β βββ test_constraints.py
β βββ test_agents.py
β βββ test_integration.py
β
βββ scripts/
β βββ run_local.sh
β βββ seed_data.py
β
βββ infra/
β βββ docker-compose.yml
β βββ terraform/
β
βββ requirements.txt
git clone https://github.com/yourname/agentos.git
cd agentosdocker compose up --buildcurl -X POST http://localhost:8000/run \
-H "Content-Type: application/json" \
-d '{"input": "get system info"}'policies:
- name: block_delete
action: delete
effect: deny
- name: financial_requires_approval
action: financial
effect: require_approval
- name: allow_read
action: read
effect: allowpytest tests/| Feature | Typical AI Apps | AgentOS |
|---|---|---|
| Safety | β Prompt-based | β Policy engine |
| Debugging | β Hard | β Fully traceable |
| Control | β Limited | β Action-level |
| Production Ready | β No | β Yes |
- AI copilots with safety constraints
- Autonomous workflows with approvals
- Enterprise AI systems (finance, ops)
- RAG + Agent systems with guardrails
- Cost-optimized AI pipelines
- LangGraph integration
- Redis memory layer
- Vector DB (RAG support)
- Role-based access control (RBAC)
- Audit logs (Postgres)
- SaaS dashboard
Pull requests welcome. For major changes, open an issue first.
MIT License
The future of AI is not just intelligent β it is safe, observable, and controllable.
AgentOS is the foundation for that future.