How agentra-labs/agcl works
1. Overall shape
AGCL is a single Python package that exposes one core agent engine through multiple front doors: a terminal UI, a headless CLI, and an HTTP/SSE node server. The same runtime is reused across all modes, so the key architectural boundary is between the engine and the various interfaces/adapters.
2. Entry points and packaging
The main executable path is main.py, with the CLI wiring in agcl/cli.py and the packaged module mirrored under src/agcl/. That suggests the repo supports both editable local development and standard packaging/install flows. bin/agcl is the shell entry wrapper.
3. Core agent runtime
The central runtime appears to live across agcl/bot_runtime.py, agcl/runner.py, agcl/context.py, agcl/state.py, agcl/config.py, agcl/configurator.py, agcl/autoconfig.py, and agcl/orchestrator.py. This layer owns session state, configuration loading, execution flow, and task orchestration, and is what the CLI/TUI/node all call into.
4. Local-first model pipeline
A defining subsystem is the split between agcl/local_llm.py and agcl/cloud.py. The README describes a local llama.cpp model producing the first tokens quickly, then a cloud model continuing the same open assistant turn. agcl/pressure.py and agcl/usage.py likely mediate when to stay local, escalate to cloud, and how to meter the resulting provider usage.
5. Session, persistence, and secrets
Persistent runtime concerns are separated into agcl/secrets.py, agcl/state.py, and pieces of agcl/recursive/persistence.py and agcl/recursive/session.py. The README’s “idle behavior” implies sessions are flushed to disk and reloaded later, so the architecture includes durable session snapshots rather than purely in-memory chat state.
6. Interactive surfaces
There are three user-facing surfaces:
- agcl/tui.py for the long-running terminal app
- agcl/node.py for the HTTP + SSE node with bearer auth
- web_socket/ for the static browser console that connects to a node
The node is the backend for the browser UI, while the TUI bypasses HTTP entirely and talks directly to the engine.
7. Dashboard and live observability
agcl/dashboard.py exposes a lightweight /node/dashboard page focused on token usage and quotas. The web_socket/js/views/ area and agcl/usage.py suggest the system publishes runtime diagnostics, cost/accounting, and configuration state as part of the live UI rather than as a separate observability service.
8. Tooling and external capabilities
agcl/tools.py and the agcl/toolkit/ package are the boundary to external systems: LiteLLM, Ollama, vLLM, TGI, OpenAI-compatible APIs, Redis state, S3 storage, Cloudflare, WebRTC, Docker, Kubernetes, GCP, and registry/endpoints helpers. Architecturally, this is the adapter layer that turns infrastructure into callable agent tools or deployment targets.
9. Integrations and protocol bridges
agcl/integrations/ contains bridges for MCP, FastMCP, Slack Bolt, OpenAgents, OpenAPI export, and manifest generation. These adapters sit on top of the same tool registry and runtime, meaning AGCL can be embedded into other agent ecosystems without changing the core engine.
10. Plugin boundary
agcl/plugins.py plus the sample plugins/ directory provide a drop-in extension mechanism. Plugins can add routes, CLI commands, and tools, which makes the plugin layer a first-class architectural seam rather than a simple hook system.
11. Recursive multi-agent subsystem
The agcl/recursive/ package is a distinct subsystem for the “recursive cognition” layer described in the README. It includes agent/session/control/build/validate/persistence modules, suggesting an internal MAS pipeline with its own lifecycle, link handling, and training/validation steps. This layer is separate from the main chat runtime and appears to operate on latent representations and teacher-driven updates.
12. Mini-model subsystem
agcl/mini/ is a separate optional learning path: tokenizer, attention, model, runtime, trainer, strategies, and config. Based on the README, it trains a small local model from captured latents, so it functions as an auxiliary learner beneath the main agent loop rather than as the primary chat model.
13. Deployment and orchestration outputs
agcl/setup.py, agcl/setup_endpoints.py, agcl/templates.py, agcl/wizards.py, and the toolkit emit commands support artifact generation for Docker, K8s, GCP Cloud Run, and related environments. The agcl/orchestrator.py and agcl/runner.py modules indicate the repo can both execute locally and coordinate remote AGCL nodes via playbooks or structured headless runs.
14. Client and UI ecosystem
The clients/npm/ package is a TypeScript client for the node/toolkit surfaces, while web_socket/ is the static browser console. Together they form a second API surface around the Python backend, with SSE/HTTP as the integration contract and the node as the central server boundary.
15. Repository role split
The repo is not just an agent app; it is a platform with four major layers: core runtime, extension/integration adapters, deployment/tooling emitters, and multiple operator interfaces. For an architecture diagram, the most important arrows are: UI/CLI/node → core runtime → local/cloud model + tools → persistent state/usage, with the recursive MAS and mini-model as sidecar learning systems and the toolkit/integrations as outward-facing adapter rings.
Main entry points: bot_runtime.py Runtime · runner.py Runner · node.py Node · tools.py Tools
Components 24
Interfaces
User-facing entry points and clients
- Main · Top-level executable path
main.py - CLI · Headless command-line interface
agcl/cli.py - TUI · Long-running interactive terminal app
agcl/tui.py - Node · Bearer-auth backend for browser clients
agcl/node.py - Web console · Static browser UI for a node
web_socket/js/app.js - NPM client · Typed client for node and toolkit surfaces
clients/npm/src/index.ts - Dashboard · Lightweight runtime and quota dashboard
agcl/dashboard.py
Core runtime
Main agent engine, state, and control flow
- Runtime · Core execution engine reused by all front doors
agcl/bot_runtime.py - Runner · Coordinates runs and task execution
agcl/runner.py - Context · Conversation and working context
agcl/context.py - State · Durable runtime state and snapshots
agcl/state.py - Config · Configuration loading and normalized settings
agcl/config.py - Orchestrator · Higher-level task and session coordination
agcl/orchestrator.py
Model pipeline
Local/cloud generation and routing
Extensions
Plugins, integrations, and external adapters
- Toolkit · External capability and deployment adapters
agcl/toolkit/__init__.py - Tools · Tool boundary exposed to the agent runtime
agcl/tools.py - Integrations · MCP, Slack, OpenAPI, and manifest bridges
agcl/integrations/__init__.py - Plugins · Drop-in extension mechanism for routes, commands, and tools
agcl/plugins.py
Learning subsystems
Recursive cognition and mini-model training paths
- Recursive · Recursive cognition and session subsystem
agcl/recursive/__init__.py - Mini model · Small local model training and runtime path
agcl/mini/__init__.py
Deployment tooling
Commands and artifact generation for deployment
- Deploy · Wizards and endpoint/setup emitters
agcl/setup.py
Connections 28
- Main → CLI: invokes · Executable entry dispatches into CLI wiring
- CLI → Runtime: starts · CLI commands reuse the core engine
- TUI → Runtime: drives · Interactive terminal talks directly to runtime
- Node → Runtime: serves · HTTP/SSE node fronts the engine
- Web console → Node: connects · Browser console connects to a node backend
- NPM client → Node: calls · TypeScript client speaks to node endpoints
- Runtime → Runner: delegates · Engine hands off execution flow to runner
- Runner → Context: uses · Runner reads and updates conversational context
- Runner → State: persists · Execution updates durable session state
- Runner → Config: loads · Runtime is parameterized by configuration
- Orchestrator → Runner: coordinates · Higher-level orchestration wraps execution flow
- Runtime → Local LLM: generates · Core engine can request local token generation
- Runtime → Cloud: continues · Engine can hand off turn continuation to cloud models
- Pressure → Local LLM: favors · Policy keeps traffic local when appropriate
- Pressure → Cloud: escalates · Policy escalates to cloud when needed
- Usage → Pressure: informs · Accounting informs routing and escalation decisions
- Runtime → Tools: calls · Agent actions flow through the tool boundary
- Tools → Toolkit: adapts · Tool boundary is backed by provider and infra adapters
- Tools → Integrations: bridges · Tool registry is exposed to external protocols
- Plugins → Tools: extends · Plugins can contribute tools
- Plugins → CLI: extends · Plugins can add CLI commands
- Plugins → Node: extends · Plugins can add routes or node behavior
- Recursive → State: persists · Recursive subsystem stores session and control state
- Recursive → Runtime: feeds · Sidecar MAS layer interacts with the main engine
- Mini model → Recursive: trains on · Mini model learns from recursive latents and traces
- Deploy → Toolkit: emits · Setup and endpoint helpers generate deployable artifacts
- Dashboard → Node: renders · Dashboard is served from the node surface
- Dashboard → Usage: shows · Dashboard visualizes runtime accounting and quotas