Foldspace Architecture

A technical brief for engineers, architects, and CTOs evaluating Foldspace as the agentic interface layer for their AI-Native product.

1. Where Foldspace sits in the AI-Native stack

Every AI-Native product converges on three layers. We own the top one.

┌────────────────────────────────────────────────────────────┐
│  LAYER 2 — AGENTIC INTERFACE  (Foldspace)                  │
│                                                            │
│  Where user intent meets product execution.                │
│  Product Agent · Conversational Analytics · Trust Lab      │
│  Real-time context engine · Optimizer · Inference gateway  │
└─────────────────────────┬──────────────────────────────────┘
              SDK ↓              ↕ A2A + MCP
┌─────────────────────────┴──────────────────────────────────┐
│  LAYER 1 — ORCHESTRATION / AUTONOMOUS AGENTS               │
│  Background agentic loops, domain models, proprietary IP.  │
└─────────────────────────┬──────────────────────────────────┘
                          │
┌─────────────────────────┴──────────────────────────────────┐
│  LAYER 0 — DETERMINISTIC BACKEND                           │
│  APIs · Permissions · Business logic · Persistence         │
└────────────────────────────────────────────────────────────┘

Layer 0 doesn't go away in an AI-Native world — it becomes more important. The agent must execute through the same APIs and obey the same permissions a human user would. Layer 1 is where the customer's proprietary IP lives: orchestration loops, domain models, vertical reasoning. Foldspace is Layer 2 — what makes the connection conversational, contextual, and measurable.

2. Runtime components

Foldspace ships as three runtime pieces plus a control plane.

2.1 The SDK (in your app)

A JavaScript SDK embedded via a single tag. It:

• Renders the agent surface (chat, voice, Chatterblocks) inside your product, configurable for placement, appearance, and interaction mode.
• Captures user context in real time: screen state, session history, role, permissions, product state.
• Exposes a shared-state bridge so the agent can read and manipulate live page elements (the "Tandem" mode).
• Authenticates users via JWT or HMAC and binds every action to the user's existing identity and permission scope.
• Emits structured events for analytics, evals, and downstream observability.

2.2 Agent Studio (your team's control plane)

The no-code surface where product teams define agent behavior:

• Actions — natural-language → API-call mappings, with input Schemas and output handling.
• Chatterblocks — interactive UI components (forms, confirmation cards, dashboards, wizards) that render inline in the conversation.
• Knowledge — connect docs, help content, wikis; Foldspace handles chunking, retrieval, and grounded RAG and stays in sync as the product evolves.
• Routing & policies — when to ask for confirmation, when to escalate, what HITL safety nets apply.
• Versioning — actions and prompts are versioned; changes flow through Trust Lab before they hit production.

2.3 The AI Agent Core (Foldspace cloud)

The reasoning engine. Three responsibilities:

1. Context assembly — gathers user context, memory, knowledge, and product state into the prompt the model actually sees, selecting only the relevant knowledge and actions for each request rather than stuffing everything in. This is what holds accuracy up while keeping latency and token cost down. Foldspace owns this product-agent layer and shapes context before the model call; the system prompt is not exposed to the customer or the user.
2. Action routing — interprets intent and selects: direct action, confirmation-first, clarification, or escalation.
3. Inference gateway — multi-provider model routing, optimized per action for cost, quality, and latency. Drop-in upgrades to newer models without product changes.

2.4 Trust Lab, Analytics, and Optimizer (control + measurement)

• Trust Lab — built-in testing automation for agentic experiences, in the Foldspace SaaS UI. Tests the Foldspace agent — including flows where it calls the customer's own agents via A2A — so teams can launch complex, multi-step actions with confidence. Golden sets from real production conversations, shadow mode, canary rollouts, regression catches, full-loop evals that see both the LLM response and the resulting API call / state change. Directly de-risks the two things that block launch: switching models (validate a new model against real scenarios before flipping it on) and prompt/context changes (prove they improve the experience, not just pass a generic metric). Surfaces cost per action alongside quality. Foldspace-managed agents today; cross-platform compatibility (e.g. LangChain) on the roadmap.
• Conversational Analytics — the customer-facing module within Foldspace's broader AI-Native Analytics category — the new analytics category for agent-mediated products. Surfaces intent signals, gaps, HITL escalations, sentiment, and outcomes. Sitting alongside it are action analytics (usage, cost driver, latency, quality) and activation analytics that tie conversations to product outcomes.
• Optimizer — a discrete, self-learning capability that uses production signal to tune outcomes, accuracy, latency, and token cost continuously. Pairs with the inference gateway: the gateway routes, the Optimizer learns what to route where. The compounding engine behind the data flywheel.

3. The two integration directions

Foldspace connects out from the interface layer in two directions:

This split is deliberate. It lets a SaaS company adopt Foldspace without re-platforming their core, and it lets an AI-native startup focus engineering on their proprietary Layer-2 intelligence while Foldspace handles the interactive surface.

Commercially, we frame this as two parallel tracks (see overview.md):

• The Operator Track — what Foldspace builds. The agentic interface, real-time context, analytics, evals, inference routing, Optimizer.
• The Intelligence Track — what the customer builds. The proprietary agent loop on their domain data: vision, forecasting, optimization, vertical reasoning. Their R&D budget compounds here.

The architectural picture above is the same picture cut along a different axis: "where it sits" vs. "who builds it."

4. The request lifecycle

What actually happens when a user types or speaks an intent:

1. CAPTURE
   SDK captures the utterance + ambient context
   (screen, session, user identity, product state).

2. ASSEMBLE
   Agent Core retrieves relevant memory,
   grounds against the knowledge index (RAG),
   and assembles the prompt for the routed model.

3. ROUTE
   Inference gateway selects model + reasoning level
   based on action class, cost target, and latency budget.

4. DECIDE
   Agent interprets intent, selects an Action
   (or asks for confirmation / clarification).

5. EXECUTE
   Action runs against the customer's APIs (deterministic)
   or hands off to a backend agent via A2A.
   Same permissions as the human user. Audit trail preserved.

6. RENDER
   Response returns as text, voice, navigation,
   in-product manipulation, or a Chatterblock — whichever
   fits the intent class and user context.

7. OBSERVE
   Every step is logged: intent, context, action, outcome,
   cost, latency, quality. Feeds analytics, Trust Lab evals,
   and the data flywheel.

5. Trust, safety, and governance

Foldspace is built to deploy in regulated, enterprise environments.

• Identity & permissions — Every action is bound to the calling user's JWT/HMAC identity. The agent cannot exceed what the user is allowed to do in the UI.
• Action-scope controls — Granular policies define what actions are eligible, under what conditions, with what HITL requirements.
• PII handling — Masking, redaction, and configurable data residency.
• Audit trail — Full intent → action → outcome logging for every interaction.
• Compliance — ISO 27001, SOC 2 Type II, GDPR.
• Evaluation-driven deployment — Golden sets, shadow mode, and canary rollouts are first-class workflow stages, not afterthoughts. New actions ship the way infra changes ship in modern engineering orgs.

6. Deployment shape

• Embed. Single JS tag in your frontend; live in hours.
• Define. PM/growth team authors actions and Chatterblocks in Agent Studio over 2–4 weeks for the first wave.
• Validate. Trust Lab runs new actions in shadow mode against golden sets drawn from production conversations.
• Roll out. Canary at 5%, monitor quality + cost + outcome, expand on green.
• Iterate. Conversation analytics surface agent gaps and product opportunities; the next wave of actions is built from what users actually asked for.

No product rewrite. No new identity system. No separate data store. The agent runs alongside the product — and the product gets smarter every week because of it.

7. The data flywheel: goldmine in, two loops out

Foldspace doesn't just observe the customer's product. It assembles a continuously refreshed picture of three input streams and feeds them into two compounding loops that improve every conversation. This is what we mean when we say "Foldspace sits on a data goldmine."

The goldmine — three input streams

• User signals — real-time intent, memory, and behavior captured at the moment of use. Not aggregated nightly; observed live.
• Product data — screens, features, flows, in-flight workflow state. The agent learns the live product, not yesterday's documentation.
• Service surface — API endpoints and UI mapped continuously. No stale knowledgebase, no drift between what the docs say and what the product does.

Two compounding loops

Loop 1 — Agent generation (LEARN → GENERATE → DEPLOY) Foldspace generates agent capabilities — skills, visualizations, integrations — trained on the live product and the service surface. The agent that ships next week is built from this week's signal. Customer authoring paths today are no-code (Agent Studio) and developer (MCP / Skills / Plugins for Cursor and Claude Code). The agent builds the agent.

Loop 2 — Real-time context engine (OBSERVE → DECIDE → REFINE) Every interaction sharpens the next. The Optimizer (§2.4) reads outcomes, context combinations, model choices, latency and cost, and tunes them continuously. Higher accuracy, lower latency, lower cost — not traded off, optimized simultaneously.

The output is the smartest agentic layer the customer's product can have, with the best context (live product, live user, live signals) and the fastest path to generate (hours, not quarters).

8. Why this architecture matters

Three structural properties make Foldspace different from a chatbot SDK or an LLM proxy:

1. Bidirectional integration. SDK down to deterministic endpoints, A2A out to autonomous agents. The interface layer doesn't lock you into either side of the AI build vs. buy question.
2. Full-loop evaluation. Because we see both the LLM response and the resulting backend state change, Trust Lab catches failures that LLM-only eval frameworks miss.
3. Closed-loop data flywheel. Every interaction produces explicit intent signals, execution data, and outcome data — the richest training signal an agentic product can collect, and the foundation of a defensible moat.

Last updated: May 2026. Pair with overview.md for the product narrative and executive-summary.md for the business case.