Agentic Runtime in KDCube: What an Agent Gets

The useful unit of an AI system is larger than a model call and larger than an agent graph.

A production turn begins when a person, channel, automation, or event asks for work. It ends only after the result has been streamed, files have been hosted, state has been persisted, costs have been recorded on participating paths, and the conversation lane is ready for its next event. Between those points, the runtime must preserve identity and authority across async tasks, tools, subprocesses, and isolated execution.

KDCube's agentic runtime is the combination of three things: platform runtime services for identity, delivery, communication, storage, accounting, and execution; a framework-neutral agent harness for events, timeline, and turn workspace; and an adapter for a concrete agent implementation, such as KDCube ReAct, LangGraph, or a bespoke async loop. The distinction matters: KDCube can host several kinds of agent without pretending that they all have the same reasoning protocol.

One terminology note: current source and descriptors still use bundle in literal names such as bundle_id, bundles.yaml, and @bundle_entrypoint. In builder-facing prose, that deployable unit is an application or app.

Terms used below

00 Implementation highlights

01 The runtime is around the agent

KDCube does not require every agent to use one internal state machine. It separates the host contract from the reasoning contract, so the same hosted conversation can support a rich ReAct agent and a run-to-completion LangGraph agent without forcing either to imitate the other.

02 One hosted turn, end to end

For a conversational agent, the common entry is BaseEntrypoint.run() with @on_reactive_event. The decorator connects the app to ordered conversation delivery; the app implements an async execute_core(state, thread_id, params) behind it.

Same-conversation turns are serialized across workers. Different conversations can run in parallel. The platform tracks which lane event a turn is responsible for and ensures the reservation is finalized on success or error.

03 What an agent can receive from KDCube

The runtime offers a set of building blocks. Some arrive with the shared conversation entry; others become active only when the app declares and wires them.

The table is deliberately not labeled "automatic." Hosting an agent does not silently connect every server, reveal every namespace, or grant every user account. KDCube supplies the contracts and enforcement points; the app descriptor and user authority decide what becomes available to a particular agent.

04 The harness has three scopes

The shared agent harness lives under runtime/harness. Its three scopes stay separate because a file, a timeline item, and a resolvable object are related but not identical.

Events: resolve an object under trusted context

The events scope resolves canonical object refs into metadata, bytes, or actions. It does not schedule the Event Bus, which delivers and wakes work, and it does not decide whether an agent should react. A conversation file ref can look like:

conv:fi:conv_<conversation_id>.turn_<turn_id>.files/report.pdf

The ref is a locator, not a credential. Tenant, project, user, conversation, and authority are checked using trusted runtime context and the registered owner resolver. A chat, canvas, ReAct tool, or ported agent can therefore use the same file identity and download path. Other namespaces remain provider-owned: a mem: or task: provider declares its own schema, resolver, actions, and authorization policy rather than being hard-coded into one agent framework.

Timeline: keep the platform conversation record

The timeline scope turns accepted input and agent output into ordered blocks, turn logs, and client-facing turn views. ReAct writes a rich live timeline. A ported agent may write a smaller set of common blocks and rely on the framework-neutral fallback recorder. Both can reload through the same conversation APIs. The timeline is not the agent's private scratchpad and not automatically its working memory — a distinction important enough for its own section below.

Workspace: give each turn a sparse working view

The workspace scope maps durable conversation objects into a turn-local, OUTPUT_DIR-relative tree:

turn_<turn_id>/
  git/projects/     editable project state
  git/snapshots/    snapshots and diffs
  files/            produced deliverables
  attachments/      materialized user uploads
  external/         explicitly pulled external evidence

A new turn starts sparse. The agent sees metadata and refs for arriving files; it materializes bytes only when a tool or adapter asks for them. Produced files are detected, hosted, converted back to durable refs, and added to the conversation record. The two directions use the same durable conversation-storage lifecycle but remain semantically distinct:

user upload
  -> hosted before the turn
  -> conv:fi:conv_<conversation_id>.turn_<turn_id>.user.attachments/<name>

agent/tool output
  -> detected or returned after execution
  -> conv:fi:conv_<conversation_id>.turn_<turn_id>.files/<path>

Both can render as file cards. Resolving a button click is a client/app surface contract, not a harness operation: the reusable chat client or an app scene POSTs the app's scene_object_action(action, object_ref); the app routes the ref by its owning namespace (conv:fi to the harness event-ref resolver and conversation storage; a provider ref to the provider-owned resolver/action) and returns a download URL or an open/capabilities response. Only the conversation-file branch is relayed into the harness. The same ref can later be pulled into another turn workspace; file bytes are not embedded as base64 in the conversation record. This gives a ReAct agent and the worked LangGraph app the same path grammar and artifact lifecycle, and it prevents a fresh executor workspace from being mistaken for the durable source of truth.

05 Conversation record and agent memory are different

KDCube can preserve a conversation even when the hosted agent is not ReAct. The platform record can contain user and assistant turns; attachments and produced files; selected streamed panels and structured events; citations and suggested followups; turn timing and participating accounting events; a generated conversation title; and error turns that remain visible after reload. That record powers conversation listing, reload, cross-conversation search, file actions, and the chat view. It is not automatically the message history fed back into an arbitrary agent framework.

Cross-conversation search is a first-class read surface over that platform record. With scope="user" it searches only the bound user's conversations; scope="agent" narrows to turns owned by the current agent. An in-app ReAct agent uses react.memsearch, its convenience wrapper around the shared conversation-search engine; other adapters call the same engine through the conv named service:

The agent's working memory remains adapter-owned. For LangGraph, its durable async framework-state store — a checkpointer — should use a platform-scoped thread identity that includes the KDCube conversation plus the active app, agent, and user boundary. The worked app derives that key from tenant, project, agent, user, and conversation_id. An in-memory saver is not sufficient for scaled serving: a later turn can land on another worker or follow a process restart. An adapter may instead reconstruct prior messages from the platform record on every turn. Either design is valid. What is unsafe is silently treating browser-submitted history or process memory as the durable record.

06 Connections are registered once; tools are granted per agent

KDCube separates where a service is from which agent may use it.

surfaces.as_consumer.mcp.services
    connection registry: endpoint, transport, authentication mode

surfaces.as_consumer.agents.<agent_id>.tools
    agent inventory: which tools this agent may see and call, and as whom

For user-selectable capabilities, the effective set is the operator/app ceiling intersected with the user selection intersected with current grants and connected-account authority. This makes several arrangements possible without changing the agent core: two agents use the same MCP server but receive different allow-lists; one agent uses an app credential while another requires per-user consent; a ReAct agent calls a named-service provider directly while a LangGraph adapter reaches the same provider through a bound client or the managed MCP bridge; a capability is listed but unavailable until its consent is granted; revoking one agent's grant does not revoke its sibling's access.

One inventory can bind three tool origins

All three are first narrowed by the app's declared ceiling and the user's per-conversation selection. A plain app tool needs no additional platform grant unless its implementation crosses a guarded service boundary. KDCube and MCP tools keep the identity, claim, accounting, and execution behavior of the boundary they call.

Named services let any agent explore and operate a connected domain

A named service turns a connected domain into a small, predictable exploration-and-action interface. The provider owns the namespace, object schemas, refs, actions, and authorization; the agent uses the same generic operations whether the domain contains conversations, memories, tasks, mail, Slack messages, or another app's objects.

provider_about            discover what the domain contains
object_schema             inspect fields, links, allowed operations
list / search / get       find the objects needed for the task
upsert / delete / action  perform one schema-declared, bounded operation
host_file

"Explore" means discovering the provider's declared model rather than guessing API routes; "act" means satisfying a published schema or invoking a published bounded action, not receiving unrestricted access. The same tool family can be wrapped for ReAct, LangGraph, another hosted framework, generated code through the trusted named-services relay, or an external MCP client.

07 A capability includes teaching, not only a callable

Giving a model a function schema is not enough when the capability depends on a workspace contract, an object-ref grammar, a citation rule, or a multi-step execution path. The KDCube ReAct adapter composes its system instruction from blocks:

Stable instruction belongs in the cacheable system prefix. Current turn state — arriving files, workspace contents, the small active memory summary (the memory hotset), reactivated consents, and capability changes — belongs in the dynamic turn view. Instruction profiles make the stable part selectable per conversation: an app can offer a full profile and a distilled profile for a smaller local model; the picker carries only an id, label, and description while contents stay behind the runtime boundary. The contract can be used by any adapter, but the adapter must resolve the chosen id and apply the instructions. The worked LangGraph integration takes the narrower route: it adds the shared distributed-workspace guide to the original prompt so the agent understands fresh workspaces, refs, read_file, pull_files, and isolated execution without importing the whole ReAct protocol. Changing a model, tool catalog, namespace, subagent, or stable profile can invalidate the prompt cache, so KDCube treats these as declared conversation capabilities, not silent prompt mutations.

08 The hosted agent is not the user

When an agent acts on behalf of a signed-in person, the runtime does not hand the person's raw session to the agent. Each hosted agent has a deterministic delegated identity, kdcube-agent:<application>:<agent_id>, and a grant is scoped to the user, that agent identity, a configured resource, and claims. It is created and revoked through Connection Hub in its Delegated by KDCube registry; without the grant, a delegated tool remains unbound or returns a managed consent demand.

For example, a Slack-backed named-service call may require a per-agent KDCube grant such as named_services:use and slack:read, and the user's connected Slack account with the provider-side consent the concrete operation needs. Revoking either side stops the call. The agent receives neither the KDCube user session nor the Slack token; trusted runtime code resolves the bound capability at the operation boundary.

09 Context survives runtime boundaries without becoming model input

An agent turn can cross async tasks, provider calls, app-venv subprocesses, or split execution. On supported trusted-runtime hops, KDCube carries a small JSON-safe portable context and reconstructs trusted services on the other side. It can include request, tenant, project, app, user, role, and authority lineage; conversation, turn, execution, and agent identity; communication routing; accounting subject and dimensions; and app call context and named-service discovery policy. Narrower boundaries receive less. An app venv receives serializable call data, including context values passed by its trusted caller. The split executor receives a reduced, non-secret EXEC_CONTEXT with identifiers needed for the execution, but not the full portable spec, descriptor payloads, platform or provider credentials, secret-provider material, or live services. Its trusted supervisor retains the privileged context and brokers allowed calls.

These values come from the host. They are not accepted as ordinary model or tool arguments: a model can propose an object ref or operation, but it cannot choose a different tenant, user, authority, or economics subject by changing a parameter. Live database pools, Redis clients, credential providers, and model clients do not cross as serialized objects — trusted target runtimes rebuild them from validated configuration. This is also why app code should not use global or environment variables as request state: context belongs in the runtime context, and durable state belongs in an appropriate scoped store.

10 Trusted agents and generated code have different boundaries

The app backend and its installed agent graph are trusted deployment code. KDCube does not claim to sandbox mutually hostile app backends inside one processor. Code generated during a turn is a different subject.

The generated program does not import KDCube tool modules. It calls an execution-enabled catalog entry:

await agent_io_tools.tool_call(    fn=<available_tool_handle>,    params={...},    call_reason="Why this call is needed",    tool_id="alias.tool_name",)

In the split profile this request crosses the authenticated supervisor socket. The supervisor resolves only tools exported for that execution and applies the allowlist and runtime policy; provider credentials remain on the trusted side. An MCP tool id routes through the MCP subsystem in the supervisor; a named-service tool can continue through the Data Bus relay — the durable app-to-app message path that reaches the provider app while preserving the original request identity and consent checks. ReAct-only model tools and orchestration/job tools are not available inside generated code. This bridge is available only when the host exports an execution-enabled tool catalog: the native KDCube ReAct exec path does that; merely wrapping an isolated Python runner does not. Running the same code in a local subprocess is useful for development and crash containment, but it does not provide the split executor's credential and filesystem separation.

11 ReAct and run-to-completion agents keep their own turn semantics

The shared event lane does not force every framework to consume events in the same way.

Both use per-conversation serialization and the shared lane-finalization contract. ReAct owns a richer in-turn lifecycle; a ported LangGraph agent gets the safer default: one accepted start batch, one completed graph run, then eligible pending work. A steer applies only to the turn active when it arrives; if that turn does not consume it, the steer expires rather than becoming a later user message. The adapter must declare what it actually supports — a composer should not offer live steer or followup semantics that the agent never implemented.

12 Accounting follows integrated paths, not arbitrary spend

The hosted-agent entry binds accounting context with the app, user, request, conversation, turn, and agent identity. That context can continue through supported runtime boundaries, so participating model, embedding, web-search, and custom-call integrations can attribute usage to the same turn. An economics-enabled app can verify policy, reserve allowance, report usage, and record the final accepted usage against that reservation on integrated paths; the conversation record can persist supported cost and timing events so they survive reload.

13 What is shared, and what remains adapter-specific

The ready KDCube ReAct agent uses more of the platform immediately because its adapter is already present. A ported agent starts with a smaller integration surface, then adopts only the shared capabilities it needs. For ReAct, "already present" still does not mean one immutable global agent — each turn is constructed from two configuration roots:

config.react
  models, behavior, teaching, subagents

config.surfaces.as_consumer
  tools, skills, MCP, named services, connection identity

The runtime resolves the administrator inventory, applies the conversation's saved narrowing under cache policy, composes instructions, installs tool traits and event sources, and builds the live workflow. ANNOUNCE, the ReAct adapter's regenerated per-round runtime-state block, carries dynamic truth such as the current workspace and newly satisfied consent without rewriting the stable instruction prefix. Optional subagents are installed only when both app policy and user choice allow them.

14 A worked proof: the same host around LangGraph

The ported-langgraph-agents@2026-07-13 app is the concrete proof that the runtime is not ReAct-only. Its original agent implementations remain under solution/; the KDCube integration is concentrated under platform/ and the app entrypoint. On each turn it:

The graph remains a LangGraph graph. The added code is the host adapter that connects it to platform guarantees.

15 What the app author still owns

KDCube removes repeated runtime plumbing; it does not remove design responsibility. The app author still decides what the agent is allowed to do; which model and reasoning framework it uses; what goes into the model input; how framework-native memory is persisted; which stores own domain state and how their keys are scoped; which APIs, MCP servers, named services, and provider accounts are connected; which agent receives which tools; which calls require a user grant; where economics guards and idempotency boundaries sit; which output events and files become part of the conversation record; and how the adapter behaves on cancellation, retries, malformed model output, and provider failure.

16 The practical integration path

For an existing agent, the first settled milestone should remain small: one authenticated message runs one agent turn; progress and the answer stream through the reusable chat; the conversation reloads; a followup survives a worker restart through durable agent state; and a second user cannot see or continue the first user's state. Files, isolated execution, web tools, model selection, instruction profiles, delegated accounts, and multiple agents can then be connected independently. The full integration checklist:

For KDCube ReAct, most of the adapter already exists; construction centers on the agent descriptor, prompt, model roles, tool inventory, and optional subagents. For an existing graph, the worked LangGraph app and the settling recipe show the smaller host layer required around the original solution. The result is not "an agent hidden inside a platform." It is an agent whose reasoning remains recognizable, connected to a runtime that can identify, schedule, govern, persist, stream, account for, and extend its work through explicit boundaries.

· Read the implementation contracts

· Continue with the worked stories