keenagents.aiTechnical Architecture

TECHNICAL ARCHITECTURE

How Keen Agents Runs in Production

A technical view of the runtime, developer workflow, isolation model, and operational controls behind production AI agents.

Isolated
client runtimes
IDE
native builder
Debug
step-through runs
Any LLM
provider-flexible
Live
telemetry & audit

Public technical overview

Build in the IDE -> deploy to an isolated runtime -> observe every execution -> improve safely with human review paths.

SYSTEM OVERVIEW

How It All Connects

Three surfaces matter to technical evaluators: the control plane, the isolated runtime, and the developer environment where agents are built and debugged.

1Create client environment
2Configure model access and limits
3Build agent flows in the IDE
4Debug against the remote runtime
5Deploy reviewed agent packages
6Observe executions and improve safely

Operations Control Plane

Central administration for companies, environments, model access, usage, billing signals, and audit trails. The point is governance: operators can see what is running, what it costs, and where access is allowed.

Isolated Client Runtime

Each company runs in a dedicated environment with its own application runtime, database, cache, ingress, and execution boundary. The point is simple: client work does not share a runtime with another client.

Developer Workspace

Developers build flows visually from the IDE, debug against the remote runtime, and deploy without moving agent logic through a separate no-code portal. The workflow stays close to how engineering teams already work.

CONTROL PLANE

Operational Governance

A production agent platform needs more than a builder. Operators need access control, usage visibility, model governance, cost guardrails, and audit trails across client environments.

Budget and Usage Controls

Allocate usage per company, monitor consumption, and apply limits before experiments turn into uncontrolled spend.

Model Access Governance

Control which providers and models are available for each company or use case. The system can move between model providers without hard-wiring the product to one LLM vendor.

Execution and Cost Visibility

Track usage, latency, cost, and agent activity at the level operators need for review, support, and continuous improvement.

ISOLATED RUNTIME

Client Work Runs in Its Own Boundary

For enterprise AI, the important question is not how many internal services exist. It is where client data runs, who can access it, and how the runtime is controlled.

Repeatable Provisioning

  • Environment creation follows a repeatable infrastructure template
  • Firewall, DNS, SSL, and ingress are configured as part of setup
  • New client environments are created consistently
  • Operations teams do not rely on manual server setup

Dedicated Runtime Boundary

  • Client workloads run in their own environment
  • Database, cache, and execution state are not shared across clients
  • Ingress terminates through the controlled runtime boundary
  • Internal services communicate inside the environment
  • Health checks protect startup order and runtime availability

Security Boundaries

  • No cross-client runtime access by default
  • Only controlled HTTPS ingress is exposed
  • Internal Docker network isolation
  • Secure password hashing
  • Two-factor access to cloud administration
  • Signed access tokens for remote debugging

DEVELOPER EXPERIENCE

Build and Debug Where Engineers Already Work

The technical value is not just that agents can be drawn on a canvas. It is that the work remains inspectable, versionable, debuggable, and close to an engineering workflow.

Visual Flow Builder

Agent orchestration inside the IDE: agents, scripts, conditions, loops, helper flows, and parallel branches in a visual workspace.

Remote Debugging

Step through execution against the remote runtime. Inspect state, follow node transitions, and debug the actual environment where the agent runs.

Controlled Deploy

Package and deploy reviewed agent projects to the runtime with signed authentication, validation, and rollback paths.

ARCHITECTURE MODEL

The Pieces a Technical Buyer Should Evaluate

The platform separates developer workflow, execution, data, and infrastructure concerns so teams can reason about where agents are built, where they run, and how production behavior is observed.

01

Build

How teams turn agent ideas into reviewable, versionable projects.

IDE extension
Project packaging
Schema validation
02

Run

Where reviewed agents execute and emit live runtime events.

Flow engine
Agent execution
Real-time events
03

Observe

How operators trace behavior, usage, cost, and execution history.

Execution traces
Usage analytics
Audit history
04

Operate

How deployments stay isolated, governed, and repeatable.

Tenant isolation
HTTPS ingress
Repeatable deployment

What to evaluate

The buyer should be able to verify these trust signals without needing access to internal repo counts or engineering vanity metrics.

Tenant-isolated runtime
IDE-native build path
Remote step-through debugging
Provider-flexible model access
Observable execution traces
Controlled deployment package
Auditable operator actions
Human review checkpoints

JavaScript / TypeScript

The agent projects stay readable to web engineering teams. TypeScript gives structure without forcing teams into a niche agent DSL.

Code-First, Not No-Code

Flows are saved as focused project files, so engineers can review changes, version them in Git, and understand what will run before deployment.

LLM-Agnostic

Model access is configurable, so teams can choose providers by cost, latency, data policy, or task quality instead of being locked to one model.

Machine-Readable by Design

Prompts, flow structure, and node configuration are intentionally inspectable by humans and AI review tools.

FLOW BUILDER DEEP DIVE

How Agents Are Built

14 Node Types

Flow Control
Start FlowEnd Flow
AI
Agent
Logic
ScriptConditionAssignmentLoop
Composition
Run FlowJump Flow
Parallelism
Parallel InParallel FlowParallel ContextJoin
Visual
Group

Engine Capabilities

  • Dictionary pattern: shared key-value state across all nodes
  • Dynamic node inputs with {dictionary.key} injection
  • Reusable helper flows shared across projects
  • Built-in SDK libraries: file I/O, message streaming, structured logging
  • Parallel execution with context isolation per branch
  • Agent prompts as markdown files on disk (00-system.md, 01-user.md)
  • $schema declarations on every config file
  • Human-readable node IDs alongside generated ones

Split Format: 3 Files Per Flow

instructions.json
Graph structure — nodes and edges
Reviewable flow shape
positions.json
Layout and viewport state
UI state kept separate
node-settings.json
Per-node configuration
Behavior isolated for review
  • Git-friendly diffs (no 12K-char single-line JSON)
  • Code-reviewable in standard PR workflows
  • LLMs can read and generate flows natively
  • No proprietary UI required to understand the project

PRODUCTION READINESS

Production Controls Developers Expect

A production AI agent platform needs visibility, rollback paths, debugging, and evaluation. Without those controls, every failure turns into guesswork.

M

Monitoring

  • Real-time telemetry via Socket.io
  • node:enter / node:exit event streams
  • LLM call tracking with latency metrics
  • Performance profiling per flow execution
  • Dashboard-ready metric exports
L

Logging

  • Structured log events
  • Audit trails for compliance
  • Per-flow execution traces
  • Searchable history with filters
  • Correlation IDs across the runtime
D

Debugging

  • Live engine step-through execution
  • Conditional breakpoints (debux.js)
  • Remote debugging — nothing local
  • Dictionary state inspection at every step
  • Flow-scoped breakpoint persistence
  • Attach from VS Code or Chrome DevTools
E

Evaluation

  • Agent output quality assessment
  • LLM response validation gates
  • Cost tracking per model and per execution
  • Execution success rate monitoring

The technical claim is not that the system has many moving parts. The claim is that operators can see, debug, control, and improve what those parts do.

OPERATIONS

How Deployments Stay Controlled

Terraform

Repeatable environment creation for client runtimes and cloud resources.

Docker Compose

Runtime packaging with health checks and predictable service startup.

NATS

Event-driven coordination for async runtime behavior.

GCP

Cloud-hosted environments managed through repeatable infrastructure.

CI/CD Pipeline

  • Security token authentication for deploys
  • Compile → Package (.zip) → Deploy to sandbox engine
  • Remote deployment from the extension command palette
  • No manual SSH or file transfers
  • Rollback via previous deployment packages

Testing & Quality

  • Automated regression checks for critical flows
  • TypeScript strict mode everywhere
  • End-to-end tests around deployment and execution paths
  • Adversarial QA with CLI probing and browser automation
  • State machine abuse, concurrency attacks, cross-tenant isolation tests

IN PRODUCTION

Shipping Real Work

Live
production workflows
3
verticals validated
Human
review paths
Remote
debug and deploy
Isolated
client runtimes
Tracked
usage and execution
UnimastersEuropean LTL logistics — 11 agents, 58 document types, Salesforce integration
Keos BulgariaRenault/Dacia distributor — on-prem Electron app, PDF→Excel automation
UchMagEducational retail — 40K+ products, automated price matching, catalog management

DEEP DIVE: DEBUGGING

How Remote Debugging Works

Two modes: active blocking step-through and passive monitoring streams. Nothing runs locally.

Step-by-step: what happens when you debug

1A project creates a stable debug entry point for flow execution
2Developer sets breakpoints on flow nodes in the extension viewport
3Breakpoints persist in .vscode/keen-project.json, mapped to node IDs
4Extension sends breakpoint state to the remote runtime over WebSocket
5Runtime inspector activates blocking step-by-step mode
6At each node: engine emits node:enter, checks for breakpoint, pauses if set
7Extension highlights active node (breakpoint-focus CSS class)
8Developer inspects dictionary state — all key-value pairs at this execution point
9Developer steps forward — engine proceeds, emits node:exit then next node:enter
10Inspector has configurable time limit — auto-disables to prevent resource leaks

Key Components

Breakpoint controller

Manages breakpoint lifecycle, attach, detach, and persistence

Viewport highlight layer

Marks breakpoint and active-node state inside the visual builder

Runtime inspector

Pauses execution safely and exposes state for the current run

Debug transport

Streams runtime events between the extension and the remote engine

Execution history

Stores messages, states, and run snapshots for post-hoc investigation

DEEP DIVE: ENGINE

The Dictionary Pattern

A shared key-value store scoped to each flow execution. Every node reads from and writes to the same dictionary.

Concrete Example: Document Processing Pipeline

1Start Flow
{ "input.file": "invoice-2024-001.pdf" }
2Script (extract)
{ "input.file": "...", "extracted.text": "Invoice #2024-001, Amount: EUR 1,500..." }
3Agent (classify)
{ "document.type": "invoice", "confidence": 0.97 }
4Condition (confidence > 0.9)
// branches based on dictionary.confidence
5Agent (extract fields)
{ "invoice.number": "2024-001", "invoice.amount": 1500, "currency": "EUR" }
6Script (push to CRM)
{ "salesforce.result": "created", "salesforce.id": "0061x00000..." }

Parallel Execution with State Isolation

  • Parallel In: snapshots the current dictionary, creates N copies
  • Each branch gets its own dictionary — writes are isolated from siblings
  • Parallel Context: read-only reference to the pre-fork state
  • Join: collects results from all branches, merges into combined dictionary
  • Configurable: fail-fast vs complete-all when a branch fails

DEEP DIVE: DEPLOYMENT

What Happens When You Click Deploy

1Developer triggers deploy from VS Code command palette
2Project manifest is validated before packaging
3Compiles: resolves flow references, validates agent configs, checks $schema
4Packages into .zip: flows/ + agents/ (markdown prompts) + scripts/ + SDK libs
5Security token authentication: signed access token for target sandbox
6HTTPS upload to the target runtime boundary
7Deployment service validates package integrity
8Unpacks flows into engine execution directory
9Runtime loads the new flows without restarting the full environment
10Operator registers the agent and assigns access
11End users access the deployed agent through the approved interface

Rollback

Previous packages preserved. Rollback = re-deploy the previous .zip. No git archaeology required.

Zero Local Execution

Nothing compiles or runs locally. The project is JSON configs + markdown prompts. All execution happens on the sandbox VM.

HOW WE WORK

AI-Assisted Engineering, Human-Owned Delivery

Keen uses AI inside its own engineering process, but senior engineers remain accountable for architecture, implementation review, testing, and release decisions.

1Architecture

Engineers define the target architecture, constraints, and risk model. AI is used to challenge assumptions and surface edge cases before implementation.

2Implementation

AI accelerates implementation, but engineers review code against architecture docs, product requirements, and runtime behavior.

3Testing

Automated tests cover critical paths, then adversarial QA probes behavior that normal happy-path tests miss.

4Code Review

Multiple rounds of AI-assisted code review with engineer oversight. Remediation plans executed and verified before merge.

5Deployment

First production deploy: core functionality operational on day one. The system has shipped real work for three clients across logistics, automotive, and educational retail.

The same principle applies to client agents: AI can move fast, but production systems need human-owned architecture, review, and operating controls.

Technical confidence comes from how the system runs, fails, recovers, and improves.

keenagents.ai