Flow

Flow

Proxy object for executing a single flow. Obtained via noukai.flow(slug).

Methods

async execute(options) -> ExecuteResult | PausedResult

Execute the flow to completion and return the result.

Parameters:

• message (string, optional): User message — the flow's primary input. Can be omitted if parameters contains all required inputs.
• parameters (object, optional): Flat object of flow-level initial inputs (not nested by block). Default: {}
• blockOverrides (object, optional): Per-step config overrides, format { "step_id": { "field": value } }. Default: {}
• attachments (array, optional): Up to 10 media attachments (HTTPS URLs). Default: []
• tools (array, optional): OpenAI-format tool definitions. Max 64. Default: []
• toolChoice (string or object, optional): "auto" | "none" | "required" | { type: "function", function: { name: ... } }. Default: undefined
• toolHandler (function, optional): Async function (toolCalls) => toolResults for auto-resume. Default: undefined
• maxToolRounds (number, optional): Safety bound on tool-handler loop. Defaults to 10. Throws if exceeded.
• trace (boolean, optional): Capture full input/output snapshots in trace. Timing/tokens recorded either way. Default: false
• version (string or number, optional): "draft" (default), "production", or a published version number. Default: "draft"
• timeout (number, optional): Request timeout in milliseconds. Default: undefined
• signal (AbortSignal, optional): Abort signal for cancellation. Default: undefined

Returns:

• ExecuteResult on successful completion
• PausedResult if the flow pauses for tool calls and no toolHandler is provided

Throws:

• FlowNotFoundError: Flow does not exist
• InsufficientCreditsError: Account balance insufficient
• FlowExecutionError: Server-side execution failure
• ValueError: Invalid version value

Examples:

Basic execution:

const result = await flow.execute({
  message: "The cat sat on the mat."
});
console.log(result.output);

With parameters and version:

const result = await flow.execute({
  message: "Grade this essay",
  parameters: {
    targetGrade: "college",
    locale: "en-US"
  },
  version: "production"
});
console.log(result.status);  // "completed" | "failed"

With tools and auto-resume:

const result = await flow.execute({
  message: "hello",
  tools: [...],
  toolHandler: async (toolCalls) => {
    // Process tool calls and return results
    return [{ toolCallId: "...", content: "..." }];
  }
});

steps(options) -> AsyncIterable<StepCompleted>

Stream completed steps as they finish during execution.

Yields: StepCompleted events with step output and timing

Example:

for await (const step of flow.steps({
  message: "The cat sat on the mat."
})) {
  console.log(`${step.stepId}: ${step.durationMs}ms`);
}

events(options) -> AsyncIterable<StreamEvent>

Stream all execution events in real-time.

Yields: StreamEvent — discriminated union of RunStarted, StepStarted, StepInput, StepOutput, StepCompleted, StepFailed, StepPaused, ToolCallsRequired, FlowCompleted. Switch on event.type for full TypeScript narrowing.

Example:

for await (const event of flow.events({
  message: "hello"
})) {
  if (event.type === "step_completed") {
    console.log(`Step ${event.stepId} took ${event.durationMs}ms`);
  } else if (event.type === "flow_completed") {
    console.log(`Result: ${JSON.stringify(event.result)}`);
  }
}

run(executionId) -> Run

Get a proxy to inspect a previous execution.

Parameters:

• executionId (string): Execution ID from a previous execute() result

Returns: Run proxy for tracing and inspection

Example:

const result = await flow.execute({ message: "hello" });
const trace = await flow.run(result.executionId).trace();
const totalCost = trace.steps.reduce(
  (sum, s) => sum + (s.costUsd ? parseFloat(s.costUsd) : 0),
  0
);
console.log(`Total cost: $${totalCost.toFixed(6)}`);

async executeAsync(options) -> Job

Submit the flow to the server queue for asynchronous execution (long-running flows). Returns immediately with a Job handle.

Accepts same parameters as execute() except toolHandler, maxToolRounds, and attachments are not supported.

Returns: Job with executionId available immediately

Example:

const job = await flow.executeAsync({
  message: "Long-running input"
});
// job.executionId available immediately; flow runs server-side
 
const status = await job.wait({ timeoutMs: 300_000 });
console.log(status.status);  // "completed" | "failed"

Streaming Parameters

Both steps() and events() accept the same parameters as execute():

for await (const event of flow.events({
  message: "input text",
  parameters: { locale: "en-US" },
  blockOverrides: { essay_grader: { rubric: "college" } },
  tools: [...],
  toolHandler: async (toolCalls) => [...],
  version: "draft"
})) {
  // ...
}

Version Values

The version parameter accepts:

Strings other than "draft" and "production" (e.g., "main", "dev") throw ValueError.

Examples:

await flow.execute({ message: "test", version: "draft" });    // In-progress draft
await flow.execute({ message: "test", version: 5 });          // Version 5 (if published)
// await flow.execute({ message: "test", version: "main" });  // ERROR: ValueError