Skip to main content

​
What is FlowState?

FlowState is the central state object that flows through the entire execution lifecycle of an agent. It contains all the information about the current execution: conversation history, tool calls, configuration, storage access, and more. FlowState is available in tool handlers and hooks, providing a complete view of the execution context and utilities to modify it.

​
FlowState Interface

interface FlowState {
  // Identity
  threadId: string;              // Unique thread identifier
  flowId: string;                // Unique flow execution identifier

  // Thread reference
  thread: {
    instance: ThreadInstance;    // DurableObject instance
    metadata: ThreadMetadata;    // Thread metadata
  };

  // Configuration
  agentConfig: Agent;            // Complete agent configuration
  currentSide: "a" | "b";        // Current executing side

  // Execution tracking
  turnCount: number;             // Current turn number
  stopped: boolean;              // Whether execution should stop
  stoppedBy?: "a" | "b";         // Which side triggered stop

  // Message context
  messageHistory: Message[];     // Full conversation history

  // Tool execution queue
  sequence: {
    queue: ToolCall[];           // Pending tool calls
    isHandling: boolean;         // Currently processing queue
  };

  // Storage & environment
  storage: DurableObjectStorage; // DurableObject SQLite storage
  env: ThreadEnv;                // Cloudflare environment bindings

  // Runtime context
  context: Record<string, unknown>; // Arbitrary state data

  // Hierarchical tracking (for sub-prompts)
  rootState?: FlowState;         // Reference to root FlowState
  isChildPrompt?: boolean;       // Is this a sub-prompt execution?
}

​
Accessing FlowState

FlowState is passed as the first argument to tool handlers and hooks:
  • In Tools
  • In Hooks
import { defineTool } from "@standardagents/builder";
import { z } from "zod";

export default defineTool(
  "Example tool",
  z.object({ input: z.string() }),
  async (flow, args) => {
    // Access FlowState properties
    console.log("Thread ID:", flow.threadId);
    console.log("Turn count:", flow.turnCount);
    console.log("Message count:", flow.messageHistory.length);

    return {
      status: "success",
      result: "Done",
    };
  }
);

​
Key Properties

​
Identity

PropertyTypeDescription
threadIdstringUnique identifier for the conversation thread
flowIdstringUnique identifier for this specific execution flow

​
Configuration

PropertyTypeDescription
agentConfigAgentComplete agent configuration object
currentSide"a" | "b"Which side is currently executing

​
Execution State

PropertyTypeDescription
turnCountnumberCurrent turn number
stoppedbooleanWhether execution has been stopped
stoppedBy"a" | "b" | undefinedWhich side triggered the stop
messageHistoryMessage[]Full conversation history

​
Tool Queue

PropertyTypeDescription
sequence.queueToolCall[]Pending tool calls to execute
sequence.isHandlingbooleanWhether currently processing the queue

​
Environment

PropertyTypeDescription
storageDurableObjectStorageAccess to DurableObject SQLite storage
envThreadEnvCloudflare environment bindings
contextRecord<string, unknown>Arbitrary runtime state data

​
Sub-Prompt Tracking

PropertyTypeDescription
rootStateFlowState | undefinedReference to root FlowState (in sub-prompts)
isChildPromptboolean | undefinedWhether this is a sub-prompt execution

​
Common Types

​
Message

interface Message {
  id: string;
  role: "system" | "user" | "assistant" | "tool";
  content: string | null;
  name?: string | null;
  tool_calls?: string | null;
  tool_call_id?: string | null;
  log_id?: string | null;
  created_at: number;
  status?: "pending" | "completed" | "failed";
  silent?: boolean;
  depth?: number;
}

​
ToolCall

interface ToolCall {
  id: string;
  type: "function";
  function: {
    name: string;
    arguments: string; // JSON string
  };
}

​
Next Steps

Utilities

Functions to manipulate FlowState

Tools

Create tools that use FlowState

Hooks

Use FlowState in lifecycle hooks

React Integration

Connect frontend to backend events