Running agent workflows

This guide is non-normative. It describes application practice and adds no language mechanism. Tools owns typed calls, history owns continuity, and execution owns runtime commands.

The authoring application combines repository review, research and synthesis, and model-written Flow. Its program sequences typed observations; its Python host supplies application services and evidence checks. The adjacent SDK application demonstrates a separate bounded observation through an application-owned SDK session.

Give an existing agent Flow tools

An existing agent can author Flow files and call the native MCP server's check, run, history and replay operations. Start with the maintained CSV application's MCP launcher, which copies a private editable controller and prepares its generated Tool types and host arguments. It prints the program path and server command. The agent writes the controller; its application supplies the CSV implementation through the copied flow.toml.

The launcher prepares a local application, not a model session. Choose an agent client and configure that server for the intended application. For Codex, the official MCP configuration guide describes server commands and tool approval settings. These settings belong to the client around Flow; a noninteractive client that requires approval can stop before sending a call to Flow. The launcher does not change account settings or start a model.

Use the printed command from either Zed's or VS Code's integrated terminal when checking setup. Their stock Flow Run tasks do not prepare this application's MCP session. Inspect the returned diagnostics, recorded facts and saved artifacts before interpreting the agent's final message as evidence. The bounded MCP study provides a separate authoring experiment and independent checks; it is not a general agent harness or a claim that an agent will choose Flow voluntarily.

Start with scripted services

From the repository root, build the CLI and run a repair scenario:

cargo build -p flow-cli --locked
python3 examples/agent-workflow/authoring/run.py start --task author --goal ten --scenario repair

scripted is the default mode: deterministic responses, no credentials and no external requests. A real compiler rejects the first submitted program; the scripted service receives its diagnostics and supplies a corrected program. The program then runs through std@v1/runner in a separate history. The default launcher pauses on an ordinary final confirmation Tool call.

For first-party authoring, select start --task author --mode codex with an already logged-in Codex CLI. Flow still owns the check/repair/run sequence; the application records bounded model invocations. This backend supports authoring only, with no API-key fallback or citation interface for research.

For Responses API execution, explicitly select start --mode model. OPENAI_API_KEY supplies the credential; FLOW_MODEL selects a model and defaults to gpt-4.1-mini; FLOW_API_URL selects a compatible Responses endpoint and receives the credential. The launcher rejects endpoint userinfo, queries and fragments before creating artifacts. API configuration is captured only for this backend. The host makes structured output requests and uses web-search citation annotations to discover URLs. There is no automatic service retry. Model availability and response quality are properties of the chosen service.

The application owns model loops, credentials, filesystem and network access, request limits, cancellation, bindings and storage. A model prompt asks for a program without Tool declarations; that request is an application instruction, and does not define a separate class of Flow functions or prove isolation. Nested bindings and module resolution belong to the embedding host.

Fixed revision review

python3 examples/agent-workflow/authoring/run.py start --task review --mode model --repo /path/to/repository --base HEAD~1 --head HEAD

The host resolves both revisions to commits, then reads their diff, changed files and root AGENTS.md and CONTRIBUTING.md at the reviewed revision. Working files are not evidence for that review. Two lenses run concurrently; a failed lens remains visible alongside the successful lens. Findings are deduplicated and retained only when a nonempty short quote occurs on the stated changed line. These checks establish location provenance; a person still assesses whether the diagnosis is correct.

The example refuses more than 20 changed files, more than 160,000 context characters, or more than 12,000 characters in either instruction file. The report stays local. Scripted review uses a seeded calc.py finding from the tests; selecting an unrelated revision causes that finding to be rejected.

Search, fetch and cited claims

python3 examples/agent-workflow/authoring/run.py start --task research --scenario review --question alpha --max-searches 2

The program caps planner queries, with at most two concurrent searches and three fetched URLs per search. In model mode, URLs originate in service citation annotations. The HTTP host follows at most five redirects, checks public destinations before connecting, limits each body to 1,000,000 bytes and extracted text to 24,000 characters, and removes script and style content. Those restrictions belong to this application.

Fetch failures remain missing evidence. With no retrieved sources, the program returns failed evidence without synthesis. Retained claims reference a fetched URL and a nonempty quote of at most 25 words, with whitespace normalized. Rejected citations and synthesis limitations remain visible. Quote validation establishes provenance, and does not prove truth or entailment. A completed brief with no retained claims still lacks supporting evidence.

Checked model-written programs

python3 examples/agent-workflow/authoring/run.py start --task author --mode codex --goal 'Sum a List<Int> input' --max-repairs 2 --max-requests 3

The model supplies source and a JSON input object. The program feeds actual compiler diagnostics into bounded repairs, then calls std@v1/runner to run accepted source. Repair exhaustion retains source and diagnostics. A nested fault returns as outer data. A pending inner Tool causes the outer answer_pending Tool to wait for an encoded outcome, which is supplied to runner.resume.

The scripted repair, unrepaired, fault and nested scenarios demonstrate these paths without service calls. For example, a deterministic submitted program can be written as:

pub flow main() -> Int = [2, 3, 5].fold(0, flow(sum, n) = sum + n)

Fresh resume and replay

A paused launcher prints its absolute application directory and native pending call IDs, then exits with code 3. Continue from a new process:

python3 examples/agent-workflow/authoring/run.py resume APPLICATION_DIR --call CALL_ID --reply '{"Ok":true}'
python3 examples/agent-workflow/authoring/run.py history APPLICATION_DIR
python3 examples/agent-workflow/authoring/run.py replay APPLICATION_DIR

For an inner Text reply, wrap its encoded outcome in the outer reply:

python3 examples/agent-workflow/authoring/run.py resume APPLICATION_DIR --call CALL_ID --reply '{"Ok":"{\"Ok\":\"yes\"}"}'

Choose start --automatic to complete final confirmation immediately, or start --pause DECLARATION to leave another Tool pending. Confirmation is ordinary application input. Each start creates a fresh application directory below target/agent-authoring, or start --runs PARENT. Sources, generated interfaces, provider settings and executable dependencies are frozen for continuation. Resume accepts no provider or scenario override; dependency or configuration drift refuses further dispatch. Histories may contain prompts, source and replies.

Responses API requests have a 60-second elapsed deadline; Codex invocations have the shared adapter's 90-second deadline. Source requests have 20 seconds including DNS, redirects and body reads. Cancellation checks before and after dispatch do not prove a service stopped. Connection loss after dispatch becomes Unknown. For an interrupted run use resume APPLICATION_DIR without a reply. The application cleans up registered model processes and retains unknown outcomes without automatic redispatch. Registration failure after launch also kills and reaps the created process and retains uncertainty. These tested paths do not establish that every external request stopped. Replay supplies no dispatcher and requires no credential.

Local verification

FLOW_STD=$PWD/std FLOW_OFFLINE=1 target/debug/flow check examples/agent-workflow/authoring/main.flow
FLOW_STD=$PWD/std FLOW_OFFLINE=1 target/debug/flow test examples/agent-workflow/authoring/test.flow
python3 -m unittest discover -s examples/agent-workflow/authoring/tests

These scenarios exercise compiler repair, nested faults, typed pending replies, new-process resume, replay, rejected changed-line quotes, deduplication, partial reviewer failure, malformed model values, missing sources, rejected citations, interruption and local HTTP deadline behavior. They use the real Flow binary and generated Tool protocol with scripted services. Model-backed outcomes require separate inspection of their original histories.

Discovering stored runs after a lost response

A client can inspect its configured run directory with flow runs --runs DIR --limit 50 -o json, or the native MCP runs tool with { "limit": 50 }. Follow nextAfter with --after ID or the tool's after argument. Read the stored-run discovery contract for ordering, bounds, record states and their limits. Inspect an explicit ID before deciding how to continue the application.

Choose an explicit ID for history and replay. Listing does not select the newest run, resend a call, resume a program, or correlate two identical requests. An application that uses a private directory per invocation can recover an ID only when inspection leaves one unambiguous accepted candidate; multiple candidates require an explicit choice. This is application practice, not an execution guarantee.