AI Agent & Automation Workflows

Orientation for an agent that is new to Boardwalk: what the platform is and how it fits together, before driving the CLI or writing a workflow. Boardwalk runs agent workflows, which are TypeScript or Python programs (not YAML, a GUI, or a chatbot) that call models on a schedule, webhook, or on demand. Use when a user mentions Boardwalk and the agent lacks the mental model. Points to boardwalk-use-cli (scaffold, run, ship) and write-good-loops (iterating loops).

Use when a user wants to install, configure, authenticate against, or drive the first-party Boardwalk CLI, the boardwalk command for authoring, validating, running, shipping, and operating agent workflows. A workflow is a package: a TypeScript or Python run function plus a workflow.jsonc deployment descriptor, calling agent(prompt) and durable primitives (secrets, sleep, phases, artifacts, workflows.call, humanInput) and returning the run's output. Covers install, scaffolding (init, incl. --python), validation (check), building the artifact (build), OAuth login, deploy (deterministic org resolution), triggering and cancelling runs, inspecting runs and usage, human-in-the-loop inputs (inputs/respond), managing workflows, secrets, environments, variables, persistent workspaces, and inference providers, the managed model catalog (models), webhook URLs (header-based, secret never in the URL), self-hosted runners (runner), and project linking.

Use when a Boardwalk workflow needs to give an agent() more than a prompt: reusable skills, inline tools, MCP servers, persistent memory, or a human-input gate. Covers the per-call agent() capabilities (skills, tools, mcp, memory, cwd, humanInput, and builtins scoping), short-lived credentials via auth.idToken/auth.apiToken, and the workflow package that bundles a skills/ folder and other assets. A skill is a skills/ /SKILL.md the leaf loads on demand through the built-in skill tool (progressive disclosure), anchored to the code-review example. Pairs with boardwalk-use-cli to scaffold, build, and deploy the package.

Use when a user wants to build an agent LOOP in Boardwalk, a workflow that iterates until a goal is reached rather than running once. Covers find/fix/verify loops, poll-until-healthy, drain-a-queue, and run-on-a-schedule maintainers. Teaches the core loop shape (plain control flow over agent()), the layered exits every loop needs (a verifier, a hard iteration cap, a budget plus usage.get() self-governing, no-progress detection), choosing the topology (one long run with while+sleep vs a recurring cron trigger of many short runs vs workflows.schedule for runtime-computed cadences), splitting the maker from the checker for verification, carrying durable state across runs, and never paying for idle wait. Pairs with boardwalk-use-cli for scaffolding, validating (boardwalk check), and running the loop.

Use when authoring or improving a Boardwalk workflow program to make it correct, cheap, and legible, not just working. Covers the shape of a workflow (the run function plus the workflow.jsonc descriptor, growing into a package), typed input and output (native types drive the run form and the output contract), the SDK primitives (agent, phase, sleep, workflows.call, parallel), making a run legible with phases and console.log, writing efficient workflows (match the model per agent() call, scope tools and output, prompt caching, parallelism, don't pay to wait, budget and reuse guardrails), and surviving crashes and restarts. For iterating loops see write-good-loops; for giving an agent() skills/tools/MCP/memory see equip-agents; for running and deploying see boardwalk-use-cli.