using-workflows_skill

Overview

This skill shows how to create and run durable TypeScript workflows with step-level checkpoints, streaming UI message chunks, and agent execution. It explains folder structure, starting and resuming runs, persisting results, and safe logging patterns for production-ready full‑stack AI apps. The content focuses on practical patterns for streaming chat, durable steps, and reconnectable runs.

How this skill works

Workflows are defined with a "use workflow" directive and orchestrate step functions ("use step") that act as durable checkpoints. Streams are framed by explicit startStream and finishStream steps so clients can parse UIMessageChunk sequences. Agents run inside workflows with a writable stream from getWritable(), and results are validated and persisted via step functions for safe resumption.

When to use it

• Building chat apps that stream assistant responses to clients in real time.
• Running long-running or resumable multi-step AI processes that need durability.
• Coordinating agent-driven decision flows with persistent checkpoints.
• Needing reconnectable runs so clients can resume in-progress streams.
• Persisting structured agent outputs to your application database reliably.

Best practices

• Organize each workflow in src/workflows/<name>/ with shared steps and types for clarity.
• Wrap any external I/O or logging in "use step" functions so they run in the workflow runtime safely.
• Always call startStream(messageId) before agent.run() and finishStream() after to frame the stream.
• Use getWorkflowMetadata() to store runId with created records so runs can be resumed.
• Validate agent output (e.g., assertChatAgentParts) before persisting to prevent schema drift.

Example use cases

• A realtime chat assistant that streams partial messages to clients and stores final parts in the DB.
• A multi-step form assistant that checkpoints progress so users can resume later.
• An agent orchestration that runs tools sequentially and persists each tool result as a step.
• Reconnect logic for mobile clients that lost connection: fetch run via getRun(runId) and replay stream.