How agentlas-ai/agentlas-os works
Purpose and entry points
Agentlas OS is a local-first, model-neutral agent operating layer. It compiles portable agent/team packages, discovers local/private/public agents, executes through the user’s host runtime, and records verification evidence. Primary shell entry points are bin/hephaestus, bin/hep-build, bin/hep-network, bin/hep-storm, bin/hep-cloud, and bin/ontology; Python entry points include agentlas_cloud/__main__.py, ontology/__main__.py, and career_graph/__main__.py.
Host adapters and distribution boundary
The canonical engine is Python plus shell launchers; host-specific command/skill surfaces are thin adapters rather than separate engines. Claude, Codex, Gemini, Cursor, Antigravity, OpenCode, and others receive runtime-specific plugins, commands, hooks, and workflow files. The substantial duplicated trees under claude/plugins/agentlas-core-engine-meta-agent/ and codex/plugins/agentlas-core-engine-meta-agent/ are packaged runtime copies of core assets; treat root agentlas_cloud/, ontology/, schemas, templates, and bin/ as the likely source-side architecture.
Key paths: scripts/install-all-runtimes.sh, scripts/sync-adapters.sh, .claude/commands/agentlas.md, codex/prompts/agentlas.md.
Build pipeline and package contracts
The Meta-Agent Factory turns a natural-language request into a single agent, a team, or a distributable package. It first shapes requirements through the interview subsystem, then compiles package artifacts, routing information, contracts, and reusable templates. Package validity is structural: schemas and verification scripts enforce required artifacts rather than trusting model output.
Key paths: agentlas_cloud/interview/directive.py, agentlas_cloud/interview/scorer.py, agentlas_cloud/brief/compile.py, agentlas_cloud/package_contract.py, schemas/agentlas-brief.schema.json, templates/agent-card.json.tpl.
Agent graph, routing, and A2A boundary
Agent definitions are loaded, migrated, validated, cataloged, and queried as an agent graph. Routing uses cards/contracts and supports A2A import/export and caller-gated invocation. This is the core portability boundary: packages express methods and runtime requirements, while the current host owns credentials, tools, permissions, and actual model execution.
Key paths: agentlas_cloud/agent_graph/kernel.py, agentlas_cloud/agent_graph/loader.py, agentlas_cloud/agent_graph/validator.py, agentlas_cloud/agent_graph/a2a.py, agentlas_cloud/global_router.py.
Workforce federation and execution
Network orchestration federates exact source scopes—local registry, owner Cloud, and public Hub—then validates host-authored staffing selection before preparing pinned releases. The execution fabric runs plans with policy/approval checks, journals progress, and produces receipts. Stormbreaker supplies the bounded decomposition, repair, and final verification gate.
Key paths: agentlas_cloud/workforce/selection.py, agentlas_cloud/workforce/execution.py, agentlas_cloud/networking/router.py, agentlas_cloud/networking/execution_fabric.py, agentlas_cloud/networking/stormbreaker_runner.py, agentlas_cloud/networking/run_journal.py.
Cloud, Hub, research, and updates
Cloud/Hub integration is a package transport and discovery layer, not server-side LLM execution. Authenticated clients invoke remote catalog/bundle operations with fallbacks; upload and repair flows manage package transfer. Research is an adapter-based acquisition subsystem with browser, HTTP, search, GitHub, RSS, Jina, and social-platform integrations, bounded by policy, credentials, redaction, evidence scoring, and receipts. Runtime updates are separate background/install concerns.
Key paths: agentlas_cloud/networking/hub_client.py, agentlas_cloud/networking/hub_invocation.py, agentlas_cloud/upload.py, agentlas_cloud/research/engine.py, agentlas_cloud/research/adapters/, agentlas_cloud/update.py.
Local knowledge and governed memory
The ontology runtime ingests local documents into SQLite/FTS-backed retrieval with parser adapters, local embeddings, ranking, and graph-oriented retrieval. Governed memory separates contracts/hooks/import from federated memory and experience privacy controls; it is delivered to hosts through runtime hooks without making cloud search a source of local project content. Bundled Model2Vec assets enable offline semantic vectors.
Key paths: ontology/runtime.py, ontology/parsers.py, ontology/embeddings.py, agentlas_cloud/memory_contract.py, agentlas_cloud/memory_hook.py, assets/model2vec/potion-base-8M-int8/manifest.json.
Main entry points: global_router.py Global router · kernel.py Agent graph kernel · install-all-runtimes.sh Host adapters · compile.py Brief compiler
Components 20
Host Distribution
- Host adapters · Thin commands, plugins, hooks, and workflows for supported hosts.
scripts/install-all-runtimes.sh - Adapter sync · Installs and synchronizes packaged host surfaces.
scripts/sync-adapters.sh
Package Factory
- Requirements interview
agentlas_cloud/interview/directive.py - Brief compiler · Builds agents, teams, routes, contracts, and artifacts.
agentlas_cloud/brief/compile.py - Package contract · Enforces required package artifacts rather than trusting model output.
agentlas_cloud/package_contract.py - Brief schema
schemas/agentlas-brief.schema.json - Agent card template
templates/agent-card.json.tpl
Agent Runtime
- Agent graph kernel · Loads, migrates, catalogs, and queries portable agent definitions.
agentlas_cloud/agent_graph/kernel.py - Agent validator
agentlas_cloud/agent_graph/validator.py - A2A import/export · Exchanges cards and contracts while the host retains execution authority.
agentlas_cloud/agent_graph/a2a.py - Global router · Selects agents using cards, contracts, and caller-gated invocation.
agentlas_cloud/global_router.py
Federation & Execution
- Workforce selection · Federates local, owner Cloud, and public Hub scopes into host-approved staffing.
agentlas_cloud/workforce/selection.py - Network router
agentlas_cloud/networking/router.py - Execution fabric · Runs approved plans with policy checks and pinned releases.
agentlas_cloud/networking/execution_fabric.py - Stormbreaker · Performs bounded decomposition, repair, and final verification.
agentlas_cloud/networking/stormbreaker_runner.py - Run journal · Records progress and receipts.
agentlas_cloud/networking/run_journal.py - Cloud/Hub transport · Authenticated catalog and bundle operations with fallbacks.
agentlas_cloud/networking/hub_client.py
Local Knowledge & Memory
- Research engine · Policy-bounded adapter research with evidence scoring and receipts.
agentlas_cloud/research/engine.py - Ontology runtime · Indexes local documents into SQLite/FTS retrieval with embeddings and graph-oriented ranking.
ontology/runtime.py - Governed memory hook · Delivers contracts and privacy-governed federated memory through host hooks.
agentlas_cloud/memory_hook.py
Connections 20
- Adapter sync → Host adapters: installs and syncs
- Host adapters → Global router: invokes
- Requirements interview → Brief compiler: shapes requirements
- Brief compiler → Package contract: produces package
- Brief schema → Package contract: defines brief validity
- Agent card template → Brief compiler: renders card artifacts
- Package contract → Agent graph kernel: admits valid definitions
- Agent graph kernel → Agent validator: validates graph
- Agent graph kernel → A2A import/export: imports and exports
- Agent validator → Global router: supplies validated agents
- A2A import/export → Global router: exposes portable contracts
- Global router → Workforce selection: requests staffing
- Workforce selection → Network router: approved source selection
- Cloud/Hub transport → Network router: remote catalog and bundles
- Network router → Execution fabric: prepares pinned releases
- Execution fabric → Stormbreaker: executes bounded work
- Stormbreaker → Run journal: verification evidence
- Research engine → Run journal: research receipts
- Ontology runtime → Governed memory hook: local retrieval context
- Governed memory hook → Host adapters: delivers host hooks