ReAct Agent (V2)

The ReAct V2 agent is a single autonomous loop — no separate planner, no gate. It starts in runtime.py as a ReactStateV2 with up to max_iterations=15 rounds by default. In each round the agent makes a decision (LLM call) then executes one or more tools. Planning is available as a tool the agent can call on itself — not a separate orchestration layer.

ReAct Agent V2 — Loop & Tool Integration

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.

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.

Multi-Channel Streaming

ReAct 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 — your agent can generate and run arbitrary Python code in complete isolation. The runtime has a clear two-zone model:

• Supervisor — networked, has env secrets and full runtime context. 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 env secrets, 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"

Exec Environment Variables (Inside Executed Code)

See external-exec-README.md

Supervisor vs Executor Architecture

The execution runtime uses a strict two-process model within a single container (Docker or Fargate):

• The Supervisor (PID 1) bootstraps the full runtime: loads dynamic tool modules, initializes ModelService, KB client, Redis communication, and starts a PrivilegedSupervisor listening on /tmp/supervisor.sock.
• The Executor subprocess drops privileges to UID 1001, optionally calls unshare(CLONE_NEWNET) for 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"
        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 its full runtime context via containerOverrides.environment at run_task time. Key variables include RUNTIME_GLOBALS_JSON (serialized runtime context), RUNTIME_TOOL_MODULES, EXEC_SNAPSHOT URIs for workspace restoration, and all proc-level secrets (Postgres, Redis, API keys). 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 subprocess is network-isolated. All tool calls from generated code are routed over a Unix domain socket (/tmp/supervisor.sock) to the supervisor process. 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