Architecture

Architecture

Components

01

Dashboard App (apps/app/)

Laravel 13 + Blade + SCSS + Laravel Reverb (WebSocket). The core product used daily. Authenticated users see agent runs, event streams, errors, costs, and alerts in real time. The ingest API receives events from both SDKs.

Key routes:

• POST /api/ingest — ingest events from the SDK (API key auth, 200 req/min)
• GET /dashboard — real-time agent status overview
• GET /dashboard/{run} — full event stream for a single run
• GET /agents — agent registry with config versioning
• GET /alerts — alert rules management
• GET /costs — cost tracking dashboard
• GET /settings/api-keys — manage API keys
• /login, /register — authentication

02

Python SDK (packages/sdk/)

pip package that instruments existing agent frameworks. Wraps LangGraph and CrewAI agents and sends lifecycle events to the ingest API. Includes callback handler for per-node/tool events and HITL support.

pip install agent-os-sdk

03

JavaScript SDK (packages/sdk-js/)

npm package that provides the same observability capabilities for JavaScript/TypeScript agents. Uses native fetch, zero external dependencies.

npm install agent-os-sdk

04

Brand Site (apps/brand-site/)

Next.js 16 / React 19 / TypeScript marketing website. Value proposition, use cases, pricing. Deployed on Vercel with Analytics and SpeedInsights.

05

Docs (apps/docs/)

Astro 6 with Starlight. This documentation site. SDK reference, guides, API docs, FAQ. Deployed on Cloudflare Pages.

Data flow

Agent (Python or JavaScript)
    │
    │  HTTP POST /api/ingest
    │  Header: Authorization: Bearer <api-key>
    │  Body: { event_type, sdk_run_id, payload, occurred_at }
    │
    ▼
Laravel App (apps/app/)
    │
    ├─► Postgres — persist AgentEvent + update AgentRun
    ├─► AlertService — check rules, dispatch notification jobs
    └─► Laravel Reverb — broadcast to WebSocket channel user.{userId}
    │
    ▼
Dashboard (Blade + JavaScript)
    └─► WebSocket listener updates UI in real time

Database schema

Table	Key fields	Description
users	id, name, email, password	Standard Laravel auth
user_settings	user_id, provider, model, temperature	LLM provider/model preferences
api_keys	user_id, name, key, expires_at, last_used_at	Per-user API keys (32-byte hex)
agents	user_id, name, framework, total_runs, budget_usd, tags	Registered agents with budget
agent_configs	agent_id, version, config (JSON), changelog, is_active	Agent config versioning
agent_runs	user_id, external_id, agent_name, status, cost_usd, model, tokens	Individual agent runs
agent_events	run_id, user_id, event_type, payload (JSON), occurred_at	All events within a run
alert_rules	user_id, name, trigger_type, channel, target, config, enabled	User-defined alert rules

Tech stack

Component	Technology	Port
Dashboard App	Laravel 13, Blade, SCSS, Laravel Reverb	8080 (app), 8082 (WebSocket)
Brand Site	Next.js 16, React 19, TypeScript, Tailwind, GSAP	3000
Docs	Astro 6, Starlight, React	3002
Python SDK	Python 3.10+, httpx	—
JS SDK	TypeScript, native fetch	—
Agents Service	Python, FastAPI, LangGraph	8081
Database	SQLite (dev) / Postgres (prod)	—
Real-time	Laravel Reverb (WebSocket)	8082

Services

Agents Service (services/agents/)

A FastAPI backend that powers the /improve feature in the dashboard. Uses LangGraph to detect programming languages and suggest code improvements.

• POST /improve — analyze and improve code (requires X-Agent-Secret header)
• GET /providers — list available LLM providers
• GET /health — health check

Supports Groq, OpenAI, and Anthropic as LLM providers.