ReAct V3 Agent

The featured ReAct agent is v3: a single autonomous loop with no separate planner and no gate. It preserves the timeline-first runtime model while adding safe multi-action rounds when AI_REACT_AGENT_MULTI_ACTION=safe_fanout is enabled. In normal single-action operation, each round still makes a decision and executes one action: either one tool call or a final-answer action. The base round cap resolves from bundle props config.react.max_iterations / react.max_iterations, then assembly/env ai.react.max_iterations / AI_REACT_MAX_ITERATIONS, then fallback 15. Planning is available as a tool the agent can call on itself, not a separate orchestration layer.

ReAct is also not built around provider-native tool calling as the model contract. The runtime asks for its own generation shape directly, so thinking, decision JSON, raw code, and other channels do not have to be squeezed into assistant/tool/result framing.

ReAct V3 Agent — Detailed Loop & Tool Integration

What the Agent Sees Each Round

Every decision round is rendered from durable runtime state into one model-facing context. The shape is intentional: old conversation memory appears first, the active turn stays readable, and ANNOUNCE stays in the uncached tail where operational facts cannot be hidden behind stale cache.

[COMPACTED PRIOR CONVERSATION MEMORY]   # if older raw turns were compacted
PRUNED PRIOR TURNS                      # working summaries or retrieval rows
RECENT INTACT TURNS                     # newest turns rendered normally
CURRENT TURN                            # current user input, rounds, tools, files
SOURCES POOL                            # citation/source inventory
ANNOUNCE                                # uncached budget, plans, live events, workspace state

The model replies through runtime-owned channels. The primary structured channel is ReactDecisionOutV2, which carries exactly one action per channel instance: call a tool, complete, or exit. In safe fanout mode, the model may emit repeated ReactDecisionOutV2 channel instances in the same response. It must not put multiple JSON decisions into one channel block. Repeated declared channels are tolerated by the streamer: for example, a second thinking block is emitted as another thinking instance. The code channel is parsed as raw executable text, so backticks inside generated HTML, JavaScript, or Python do not hide the </channel:code> boundary.

Creating and Running the ReAct Agent

# In your workflow (BaseWorkflow subclass)
react = await self.build_react(
    scratchpad=scratchpad,
    tools_module="my_bundle.tools_descriptor",
    skills_module="my_bundle.skills_descriptor",
    knowledge_space_fn=self._search_knowledge,   # optional
    knowledge_read_fn=self._read_knowledge,      # optional
)
result = await react.run(payload)

Timeline

The timeline (timeline.py) is the single source of truth for turn context. It is persisted as artifact:conv.timeline.v1 and loaded at the start of each turn. A separate artifact:conv:sources_pool tracks all sources referenced in the conversation; the timeline payload also carries the current full source rows so react.read and exec fetch_ctx can recover fetched web content.

It is also a live event surface while a turn is running. Busy-conversation external events such as followup, steer, and the same general family of reactive inputs used by forms, wizards, or alert acknowledgements enter a shared event source for the conversation. Every such event lands on the append-only timeline first. If the event is reactive and the active React turn owns the live listener, the runtime folds it into the current turn and re-enters the loop at the next decision boundary; steer-like controls may also trigger an engineering-layer interrupt that tries to cancel the active generation or cancellable tool phase immediately. The timeline also records round start explicitly, so a reactive event that arrives while the agent is already thinking is shown inside that open round instead of looking as if it happened before the round existed. If a new reactive event lands after a visible completion attempt, the same turn can later append another assistant.completion; the latest completion keeps the stable path ar:<turn_id>.assistant.completion and earlier visible completions use numbered paths such as ar:<turn_id>.assistant.completion.1. External-event message blocks follow the same path pattern, for example ar:<turn_id>.external.followup.<message_id> or ar:<turn_id>.external.alert.<message_id>. The raw timeline remains append-only; restored conversation order is reconstructed later from truthful event start timestamps rather than from append position alone. React then re-enters with the new reactive material already on the timeline and gets a short bounded finalize phase to close the turn cleanly while preserving the progress made so far.

When context compaction actually starts or completes, the runtime emits chat.compaction on the dedicated chat_compaction transport route. Browser clients and adapters such as Telegram can append this as a short progress item while the same ReAct turn continues running.

Cache checkpoints are computed by rounds (tool call rounds + final completion). They allow LLM context caching to skip retokenizing earlier parts of long conversations. See timeline-README.md, source-pool-README.md, and react-announce-README.md.

Pruning, Compaction, and Recovery

TTL pruning and hard compaction do different jobs. TTL pruning keeps the cache useful by replacing older visible blocks with compact recovery rows. Hard compaction is the context-window safety valve: it summarizes an older range into su:<turn_id>.conv.range.summary and removes the compacted raw blocks from the visible stream. Neither process deletes artifacts, tool logs, turn logs, or source rows. The visible text becomes a map; logical paths remain the handles for exact recovery. Compaction lifecycle is visible to clients through chat_compaction stream events.

Multi-Channel Streaming

Built-In React Tool Surface

The built-in react.* tools are control-plane tools for the loop itself. Bundle tools, MCP tools, web/email tools, and isolated exec tools sit beside them, but these are the primitives the agent uses to manage memory, files, plans, and context size.

Large initial tool results are prompt-capped before the next decision round: the full tc: result remains stored, while the model sees a bounded preview with size metadata, a depth-limited shape, and recovery instructions for react.read or exec ctx_tools.fetch_ctx.

Visible read limits are unit-specific and apply per requested path: text previews use text-character and token caps; all payloads use a raw byte cap. Unsupported binaries remain metadata-only and should be inspected through exec or related text/source refs.

ReAct V3 Agent Documentation

Full docs live in docs/sdk/agents/react/. Key files:

Plan Tracking

Plans are a first-class timeline concept, not a separate orchestration layer. The agent creates and manages plans through the react.plan tool, and every plan is persisted as an append-only sequence of react.plan snapshot blocks in the timeline.

PlanSnapshot Structure

Each plan snapshot is stored as a timeline block of type react.plan with a stable plan_id and ordered steps. Key fields:

The react.plan Tool

The agent manages plans through four lifecycle modes:

Plan Block in Timeline

Plans appear in the timeline as react.plan blocks with a stable reread handle:

# Stable latest-snapshot alias for any plan lineage
ar:plan.latest:<plan_id>

# Model creates a plan
react.plan(mode="new", steps=["collect metrics", "compare trends", "draft answer"])

# ANNOUNCE shows open plans with step markers
# [OPEN PLANS]
#   plan_id=plan_alpha (current)
#     □ [1] collect metrics
#     □ [2] compare trends
#     □ [3] draft answer

Step Statuses

The agent reports step progress via notes using status markers. The runtime parses these markers and updates the plan snapshot automatically.

Multi-Round Plan Tracking

Plans survive across rounds and turns through the following mechanisms:

• ANNOUNCE lists the last 4 open plans each round, marking the current one explicitly with (current).
• The stable alias ar:plan.latest:<plan_id> always resolves to the newest snapshot for a lineage, regardless of which turn last updated it.
• On a new turn, the runtime rehydrates only the current open plan automatically. Older plans must be inspected explicitly via react.read if they become relevant again.
• When history is compacted, older plans appear in a react.plan.history block with step skeletons, statuses, and stable snapshot_refs for recovery.

A plan lineage is considered open only if its latest snapshot is not closed, superseded, or complete. Only the plan tagged (current) in ANNOUNCE may receive step acknowledgements.

See plan-README.md

Isolated Execution Runtime

The platform provides a sandboxed code execution runtime: the agent can generate Python programs, execute them under policy, and receive a normalized result envelope. The runtime has two logical zones. Docker can run those zones in the default split topology with sibling supervisor and executor containers, or in the legacy combined container strategy. Fargate runs the same logical contract in a remote ECS task.

• Supervisor — networked, has full runtime context, and resolves settings/secrets through the descriptor-backed provider. All bundle tools from tools_descriptor.py execute here, including MCP tools, bundle-local tools, and custom SDK tools. The ChatCommunicator is also available to tool code, streaming events via Redis Pub/Sub to the client SSE.
• Executor — completely isolated: no network, no descriptor payloads, no provider secret material, separate Linux namespace (UID 1001). Runs LLM-generated code. All tool calls are proxied to the Supervisor over a Unix socket. Can only write to /workspace/work and /workspace/out.

Two execution backends are practical:

execution:
  runtime:
    mode: "docker"
    enabled: true  # default

execution:
  runtime:
    mode: "fargate"
    cluster: "arn:aws:ecs:..."
    task_definition: "exec-task"

Executor Environment Variables (Generated Code)

Supervisor launch env is different from generated-code env. Docker receives the exec launch payload inline as RUNTIME_GLOBALS_JSON. Fargate receives KDCUBE_EXEC_PAYLOAD_SECRET_ID, an AWS Secrets Manager secret name for temporary launch JSON; the entrypoint calls GetSecretValue, parses the JSON, and restores RUNTIME_GLOBALS_JSON, RUNTIME_TOOL_MODULES, and packaged supervisor env before bootstrap. The supervisor also receives descriptor payloads such as KDCUBE_RUNTIME_ASSEMBLY_YAML_B64, KDCUBE_RUNTIME_BUNDLES_YAML_B64, KDCUBE_RUNTIME_GATEWAY_YAML_B64, KDCUBE_RUNTIME_SECRETS_YAML_B64, and KDCUBE_RUNTIME_BUNDLES_SECRETS_YAML_B64. It materializes those descriptors before tool bootstrap so bundle tools can use normal get_settings(), get_plain(), get_secret(...), bundle props, and get_secret("b:...") bundle-secret lookups. By default descriptor payloads are full; setting execution.runtime.descriptor_payload_scope: active_bundle filters only bundles.yaml and bundles.secrets.yaml to the active caller bundle.

See external-exec-README.md

Supervisor vs Executor Architecture

The execution runtime uses a strict supervisor/executor boundary. In Docker combined, that boundary is inside one py-code-exec container. In Docker split, the supervisor and executor are sibling containers. In Fargate, the same logical contract runs inside the remote exec task.

• The Supervisor bootstraps the full runtime: loads dynamic tool modules, initializes ModelService, KB client, Redis communication, and starts a PrivilegedSupervisor listening on the supervisor socket.
• The Executor drops privileges to UID 1001, uses runtime-level network isolation, and runs the LLM-generated user_code.py.
• Every tool call from executor code (io_tools, web_tools, react_tools, etc.) is proxied over the Unix socket to the supervisor. The executor never has direct access to network, secrets, or databases.

Docker Execution Mode

# Docker profile in bundle props
execution:
  runtime:
    profiles:
      docker:
        mode: "docker"
        image: "py-code-exec:latest"
        container_strategy: "split"  # default; combined | split
        network_mode: "host"
        cpus: "1.5"
        memory: "2g"
        extra_args: ["--pids-limit", "256"]

Fargate Execution Mode

Fargate exec runs the same supervisor/executor architecture as Docker, but on a dedicated ECS Fargate task instead of a local container. This is the replacement for Docker-on-node in environments where Fargate containers cannot access the Docker daemon.

The caller (chat-proc) snapshots the workdir and outdir to S3, launches the Fargate task via ecs.run_task, polls until completion, then restores output zips back to the local workspace. From the agent's perspective, the result contract is identical to Docker mode.

Environment Variable Injection

The Fargate task receives supervisor launch state through containerOverrides.environment at run_task time. The current Fargate path stores the exec launch payload in AWS Secrets Manager under a name like kdcube/runtime/exec-payloads/<exec_id> and passes that name as KDCUBE_EXEC_PAYLOAD_SECRET_ID. The task entrypoint reads it with GetSecretValue, restores the runtime env, then proc deletes the temporary secret after the task finishes. Platform and bundle config are shipped separately as descriptor payloads (KDCUBE_RUNTIME_*_YAML_B64), not as raw provider API-key env promotion. Bundle tool module paths are rewritten from host paths to container paths (/workspace/bundles/{bundle_dir}/...).

Network Isolation & Unix Socket Communication

In both Docker and Fargate modes, the executor side is network-isolated. All tool calls from generated code are routed over a Unix domain socket to the supervisor side. In Docker split mode the socket is shared through a small socket volume. The supervisor has full access to Redis, Postgres, ModelService, S3, and external APIs. In Fargate, the supervisor connects to backing services via VPC DNS (Cloud Map private DNS or direct ElastiCache/RDS endpoints).

Error Propagation

Runtime-specific failures (ECS startup failure, Fargate timeout, snapshot restore failure) are surfaced through the same report_text / error envelope as local Docker execution. The agent sees a unified result contract regardless of backend:

# Unified result fields (both Docker and Fargate)
ok: bool          # execution succeeded
artifacts: list   # produced files
error: str        # error message if failed
report_text: str  # human-readable summary
user_out_tail: str       # last lines of user.log
runtime_err_tail: str    # last lines of runtime errors

See distributed-exec-README.md and exec-logging-error-propagation-README.md