What Is a Bundle?

A Bundle is your application package. It combines Python backend code with optional TypeScript UI widgets and views into a single deployable unit. The package becomes a bundle by subclassing the platform's base class (BaseEntrypoint or a derived variant) and registering with @agentic_workflow.

App sources live in git. The platform's assembly descriptor points to a git repo, ref, and subdirectory. On deploy, the CLI or CI pipeline pulls the ref and registers the bundle. You can update a running deployment by pushing a new ref and re-running the deploy step — no service restart required.

Most example bundles use the ReAct agent (ReactStateV2), but a bundle does not have to. You can use any LangGraph graph, a simple request→response pipeline, or no LLM at all.

Example Bundles

Start from the examples folder in sdk/examples/bundles/. The concrete reference bundle used on this page is versatile@2026-03-31-13-36 — a production-style sample that combines ReAct orchestration, bundle-local tools, widget decorators, REST operations, and a custom main UI.

Platform Architecture for Bundle Developers

See also: Platform Overview

KDCube is a multi-tenant AI application platform. It provides the infrastructure for deploying conversational AI agents at scale — with streaming, storage, economics, tooling, and extensibility all built in.

A Bundle is your unit of deployment. It's a Python package that plugs into the platform and defines how your AI agent thinks, what tools it uses, how it stores data, what UI widgets it exposes, and how it bills users.

Big Picture: How It All Fits Together

Two Services, One Platform

Bundle Anatomy

A bundle is a Python package with a required entrypoint.py and optional supporting files:

Minimal Entrypoint

from kdcube_ai_app.infra.plugin.agentic_loader import agentic_workflow
from kdcube_ai_app.apps.chat.sdk.solutions.chatbot.entrypoint import BaseEntrypoint
from langgraph.graph import StateGraph, START, END
from typing import Dict, Any

BUNDLE_ID = "my-bundle"

@agentic_workflow(bundle_id=BUNDLE_ID)
class MyBundle(BaseEntrypoint):

    @property
    def configuration(self) -> Dict[str, Any]:
        return {
            "role_models": {
                "solver.react.v2.decision.v2.strong": {
                    "provider": "anthropic",
                    "model": "claude-sonnet-4-6"
                }
            }
        }

    def on_bundle_load(self, **kwargs):
        # Called ONCE per process when bundle first loads.
        self.logger.info("Bundle loaded!")

    async def execute_core(self, state, thread_id, params):
        graph = StateGraph(dict)
        graph.add_node("run", self._run_node)
        graph.add_edge(START, "run"); graph.add_edge("run", END)
        return await graph.compile().ainvoke(state)

    async def _run_node(self, state):
        await self._comm.delta(text="Hello from my bundle!", index=0, marker="answer")
        return {"final_answer": "Done", "followups": []}

BaseEntrypoint Lifecycle

Bundle Lifecycle

A bundle goes through a well-defined lifecycle from discovery to shutdown. Understanding these phases helps you place initialization logic, manage state, and handle configuration changes correctly.

Discovery and Loading

Bundle source lives in git. On deployment the platform clones the configured repo and ref, imports the module, and finds the class decorated with @agentic_workflow. The loader extracts interface metadata (decorators for widgets, APIs, message handler) and builds a BundleInterfaceManifest that the REST layer uses for routing.

Singleton Instance Model

By default each incoming turn or operation creates a fresh entrypoint instance. When the registry sets singleton=true, the platform caches and reuses one instance per loaded bundle spec in the current process.

Initialization Hooks

on_bundle_load() must be deterministic and idempotent. It runs before any request depends on the bundle and is the right place for heavy preparation work. Do not store request-local state there.

Hot-Reload on Config Change

When you update a bundle's ref in bundles.yaml and re-apply, the platform detects the configuration change via a content hash of the bundle directory. The updated bundle is loaded in the current process without a service restart. on_bundle_load() runs again for the new version, and subsequent requests are served by the refreshed instance.

Shutdown and Cleanup

The platform does not expose a dedicated shutdown hook. Because bundle state should live in external storage (Redis, S3, local shared storage), process termination is safe by design. Transient per-invocation state in OUT_DIR / workdir is scoped to the request and cleaned up automatically.

Storage Surfaces Across Phases

Interface: In & Out

Using the Communicator

# Stream answer text
await self._comm.delta(text="chunk...", index=0, marker="answer")

# Announce a step
await self._comm.step(step="web_search", status="started", title="Searching the web...")
await self._comm.step(step="web_search", status="completed")

# Emit follow-up suggestions
await self._comm.followups(["Tell me more", "Show examples"])

# Final complete signal
await self._comm.complete(data={"answer": "..."})

REST Operations (for UI Widgets)

Your bundle exposes additional REST operations via the Operations API hosted by the Processor:

POST /bundles/{tenant}/{project}/{bundle_id}/operations/{operation}
GET  /bundles/{tenant}/{project}/{bundle_id}/operations/{operation}

The explicit bundle_id form is now the preferred route. The processor resolves the target method from the bundle’s decorator-discovered interface surface rather than assuming every operation is just workflow.run(). A default-bundle compatibility shortcut still exists at POST /bundles/{tenant}/{project}/operations/{operation}.

Continuation Types

Classic vs. Interactive Turn Execution

Storage

KDCube is a distributed, multi-tenant system. Three storage tiers are available to your bundle:

Cloud Storage (AIBundleStorage)

from kdcube_ai_app.apps.chat.sdk.storage.ai_bundle_storage import AIBundleStorage

storage = AIBundleStorage(
    tenant="my-tenant", project="my-project",
    ai_bundle_id="my-bundle@1-0",
    storage_uri="s3://my-bucket"  # or file:///data/bundle-storage
)

storage.write("reports/latest.json", data='{"count": 42}')
content = storage.read("reports/latest.json", as_text=True)
keys = storage.list("reports/")

Local FS (Shared Bundle Storage)

# In entrypoint or workflow
root = self.bundle_storage_root()  # pathlib.Path
index_path = root / "knowledge_index"
index_path.mkdir(exist_ok=True)

Path namespaced: {BUNDLE_STORAGE_ROOT}/{tenant}/{project}/{bundle_id}/. Ideal for knowledge indexes, model weights, large caches. In production, mount an EFS volume.

Redis Cache

# Low-level Redis client (aioredis)
await self.redis.set("my:key", "value", ex=3600)
val = await self.redis.get("my:key")

# KVCache wrapper
await self.kv_cache.set("user_prefs", {"theme": "dark"}, ttl=86400)

Workflow Orchestration

The platform uses LangGraph for workflow orchestration. Your execute_core builds and invokes a StateGraph. For common patterns, use BaseWorkflow:

from kdcube_ai_app.apps.chat.sdk.solutions.chatbot.base_workflow import BaseWorkflow

class MyWorkflow(BaseWorkflow):
    def __init__(self, *args, bundle_props=None, **kwargs):
        super().__init__(*args, bundle_props=bundle_props, **kwargs)

    async def process(self, payload):
        scratchpad = self.start_turn(payload)
        try:
            react = await self.build_react(
                scratchpad=scratchpad,
                tools_module="my_bundle.tools_descriptor",
                skills_module="my_bundle.skills_descriptor",
            )
            result = await react.run(payload)
            self.finish_turn(scratchpad, ok=True)
            return result
        except Exception as e:
            self.finish_turn(scratchpad, ok=False); raise

BaseWorkflow Key Parameters

Simplest Agentic Workflow Pattern

A bundle can use any orchestration pattern — it is not required to use the ReAct agent. This is one common pattern that combines a Gate agent with the ReAct agent:

Tools System

# tools/my_tools.py
from typing import Annotated
import semantic_kernel as sk
from semantic_kernel.functions import kernel_function

class MyTools:
    @kernel_function(name="search", description="Search product catalog")
    async def search(self,
        query: Annotated[str, "Search query"],
        limit: Annotated[int, "Max results"] = 5
    ) -> str:
        # your logic here
        return "results..."

# tools_descriptor.py
TOOLS_SPECS = [
    # SDK built-in tool modules (installed package)
    {"module": "kdcube_ai_app.apps.chat.sdk.tools.web_tools", "alias": "web_tools", "use_sk": True},
    {"module": "kdcube_ai_app.apps.chat.sdk.tools.exec_tools", "alias": "exec_tools", "use_sk": True},
    # Bundle-local tools ("ref" = path relative to bundle root, works in Docker too)
    {"ref": "tools/my_tools.py", "alias": "my_tools", "use_sk": True},
]
# Tool IDs: web_tools.web_search, exec_tools.execute_code_python, my_tools.search

# Optional: per-tool runtime overrides
TOOL_RUNTIME = {
    "web_tools.web_search": "local",       # subprocess sandbox
    "exec_tools.execute_code_python": "docker",  # Docker container
}

# tools_descriptor.py
MCP_TOOL_SPECS = [
    {"server_id": "web_search", "alias": "web_search", "tools": ["web_search"]},
    {"server_id": "docs", "alias": "docs", "tools": ["*"]},  # all tools
    {"server_id": "stack", "alias": "stack", "tools": ["*"]},
]
# Tool IDs: mcp.docs.some_tool, mcp.stack.some_tool

# bundles.yaml config section — how to connect
config:
  mcp:
    services:
      mcpServers:
        docs:
          transport: http
          url: https://mcp.example.com
          auth:
            type: bearer
            secret: bundles.my-bundle.secrets.docs.token
        stack:
          transport: stdio
          command: npx
          args: ["mcp-remote", "mcp.stackoverflow.com"]

Artifact Path Families

Skills System

Skills are reusable instruction sets that give agents specialized capabilities. A skill bundles a natural-language instruction (SKILL.md), tool references, and source references.

Built-in Platform Skills

Custom Bundle Skill

# skills/my_skill/SKILL.md
You are an expert in our product catalog.
When asked about products, use the `product_search` tool to find relevant items.
Always include pricing and availability.

# skills/my_skill/tools.yaml
tools:
  - id: product_search
    role: search
    why: Search the product catalog

# skills_descriptor.py
AGENTS_CONFIG = {
    "solver": {
        "enabled_skills": ["my_skill", "pdf-press", "url-gen"],
        "disabled_skills": []
    }
}

Creating a SKILL.md File

Each skill lives in its own folder under the bundle's skills/ directory. The required file is SKILL.md (or skill.yml), which contains YAML front-matter and a natural-language instruction body.

# skills/product/SKILL.md
---
name: "Product Catalog Expert"
id: "kdcube"
namespace: "product"
description: "Search and present product information"
version: "1.0"
tags: ["catalog", "products"]
when_to_use: "When the user asks about products, pricing, or availability"
imports: []
---

You are an expert in the product catalog.
When asked about products, use the `product_search` tool.
Always include pricing and availability in your response.

Optional companion files in the same folder:

• compact.md — a shorter instruction variant for context-constrained agents
• sources.yaml — sources injected into sources_pool when the skill loads (referenceable as so:sources_pool[...])
• tools.yaml — recommended tools for the skill, used by planners and UX

Skill Visibility Configuration

The skills_descriptor.py file controls which skills are visible to which agent consumers. It exposes two key variables:

# skills_descriptor.py
import pathlib

BUNDLE_ROOT = pathlib.Path(__file__).resolve().parent

# Points to the skills folder layout: <root>/<namespace>/<skill_id>/SKILL.md
CUSTOM_SKILLS_ROOT = BUNDLE_ROOT / "skills"

AGENTS_CONFIG = {
    # Allow-list for the ReAct decision agent
    "solver.react.decision.v2": {
        "enabled": ["product.kdcube"]
    },
    # Deny-list for a generator agent
    "answer.generator.strong": {
        "disabled": ["public.*"]
    },
}

Skill Loading and Resolution

The runtime auto-detects <bundle_root>/skills as the custom skills root when CUSTOM_SKILLS_ROOT is not set. Skills are loaded into the skill registry and resolved by fully qualified id (namespace.skill_id). Consumer agents reference skills via short-id tokens (SKx) or explicit sk:<id> references. When a skill is loaded with react.read("sk:<skill>"), its sources are merged into sources_pool and citation tokens are rewritten to match.

Best Practices for Skill Authoring

• Keep SKILL.md instructions focused — one skill per capability domain
• Use when_to_use front-matter to help the agent decide when to activate the skill
• Include tools.yaml to pair skills with the tools they need
• Use AGENTS_CONFIG to restrict skill visibility rather than deleting skill files — this keeps skills available for future consumers
• Test visibility filtering per consumer: a skill hidden from solver.react.decision.v2 is still visible to unfiltered consumers

Widgets, APIs & Custom UI

Bundles now expose a decorator-discovered interface. Widgets and APIs are separate surfaces: widgets are UI entrypoints intended for the platform shell, while APIs are programmatic operations reachable under the integrations operations routes. A bundle may also define a custom main view and a dedicated message entrypoint.

Bundle Interface Decorators

Bundle identity can come from the registry entry or be declared explicitly with @bundle_id("my.bundle@version"). The loader uses the discovered bundle interface decorators as the HTTP and UI contract.

Example: Declare widget, API, and UI entrypoints

from kdcube_ai_app.infra.plugin.agentic_loader import agentic_workflow, bundle_id, api, ui_widget, ui_main, on_message

@agentic_workflow(name="my-bundle", version="1.0.0", priority=100)
@bundle_id("my.bundle@1.0.0")
class MyBundle(BaseEntrypointWithEconomics):

    @ui_widget(icon={"tailwind": "heroicons-outline:swatch"}, alias="dashboard", roles=("registered", "admin"))
    def dashboard_widget(self, **kwargs):
        return ["<div id='root'></div>"]

    @api(alias="refresh_dashboard", method="POST", roles=("registered", "admin"))
    def refresh_dashboard(self, **kwargs):
        return {"ok": True}

    @api(alias="telegram_webhook", method="POST", route="public", public_auth={"mode": "header_secret", "header": "X-Telegram-Bot-Api-Secret-Token", "secret_key": "telegram.webhook_secret"})
    async def telegram_webhook(self, **kwargs):
        return {"ok": True}

    @ui_main
    def main_view(self, **kwargs):
        return ["<div id='app'></div>"]

    @on_message
    async def run_message(self, **kwargs):
        return await self.run(**kwargs)

Integrations REST Surface

Interface Manifest Discovery

Decorators on the bundle class are the source of truth for the bundle's HTTP and UI contract. At load time the loader scans the entrypoint class for @api, @ui_widget, @ui_main, and @on_message decorators and builds a typed BundleInterfaceManifest:

# Internal manifest shape (built automatically by the loader)
BundleInterfaceManifest(
    bundle_id="versatile@2026-03-31-13-36",
    ui_widgets=(UIWidgetSpec(alias="preferences", icon={...}, roles=(...)),),
    api_endpoints=(APIEndpointSpec(alias="preferences_exec_report", http_method="POST", route="operations", roles=(...)),),
    ui_main=UIMainSpec(method_name="main_ui"),
    on_message=OnMessageSpec(method_name="run"),
)

The manifest is returned by GET /api/integrations/bundles/{tenant}/{project}/{bundle_id} and drives all route resolution. Only decorated methods are remotely callable — there is no same-name fallback for undecorated methods.

Iframe Embedding Model for Widgets

Widget methods (@ui_widget) return HTML fragments that the platform shell renders inside an iframe panel. The widget fetch endpoint resolves the alias, checks role visibility, and invokes the method. If the same widget must also be callable through the operations route (for legacy clients), decorate it with both @ui_widget and @api:

@api(alias="preferences_widget", route="operations", roles=("registered",))
@ui_widget(alias="preferences", icon={"tailwind": "heroicons-outline:adjustments-horizontal"}, roles=("registered",))
def preferences_widget(self, **kwargs):
    return ["<div id='root'></div>"]

Static File Serving for Custom UIs

Bundles that ship a custom frontend (a Vite/React SPA in ui-src/) have their built assets served from a dedicated static route:

GET /api/integrations/static/{tenant}/{project}/{bundle_id}/{path}

The endpoint locates the correct bundle_storage_root via a content hash of the bundle directory, then returns files from its ui/ subdirectory. Missing paths fall back to index.html for client-side routing. A <base> tag is injected into index.html so relative assets resolve correctly.

Main View Configuration

To define a custom main view, declare ui.main_view in your bundle's configuration property and mark a method with @ui_main:

@property
def configuration(self):
    return {
        "ui": {
            "main_view": {
                "src_folder": "ui-src",
                "build_command": "npm install && OUTDIR=<VI_BUILD_DEST_ABSOLUTE_PATH> npm run build",
            }
        }
    }

The built SPA communicates with the backend through the bundle operations endpoint and receives runtime config (base URL, auth tokens, tenant/project) via postMessage from the host frame. The UI is a normal platform client — if it needs bundle-originated events targeting one exact connected peer, it must propagate the connected peer id on REST requests per the client communication contract.

Registry vs. Interface Discovery

GET /api/admin/integrations/bundles returns the configured bundle registry entries — id, repo, ref, module, path, version, and related deployment metadata. The richer interface discovery surface lives on the per-bundle integrations endpoint above, where the runtime scans decorators and returns the current manifest.

Platform Built-in Operations

Deploying Your Bundle

Option A: With the KDCube Platform

1. 1

   Push your bundle to Git

   git push origin v1.0.0

2. 2

   Add to bundles.yaml

   - id: "my-bundle@1-0"
     repo: "git@github.com:org/my-bundle.git"
     ref: "v1.0.0"
     module: "my_bundle.entrypoint"

3. 3

   Inject secrets and apply

   kdcube-setup --secrets-set GIT_HTTP_TOKEN=ghp_...
   kdcube-setup --secrets-prompt  # for LLM keys

   The bundle config is applied immediately via Redis — no restart needed. Change the ref and re-run to switch bundle versions on the fly.

4. 4

   Set as default bundle via the Admin Dashboard

   Open the AI Bundle Dashboard (/api/integrations/bundles/{tenant}/{project}/{bundle_id}/operations/ai_bundle). Your registered bundle appears in the list. Set it as the default_bundle_id for the tenant/project. The change is applied immediately via Redis — no restart needed.

Option B: Standalone (Without Platform)

Bundles can run outside the platform. The SDK is a plain Python package — build your own FastAPI app that imports and invokes it directly. Or build a custom Docker image that runs just your bundle with its own server. The platform's value is in hosting, auth, SSE, storage, economics, and UI — none of that is required for the core agent logic.

Bundle Git Auth

Example Bundles

Documentation Reference

Coming Soon & Current Status

Here's the current state of platform capabilities and what's next on the roadmap: