RFC: Actions as reusable finite agent orchestration

[FredKSchott]

Summary

Introduce actions as Flue’s reusable primitive for finite, top-to-bottom agent orchestration.

An action receives an input and an invocation-scoped harness, performs finite work, and returns an output. The same action can be:

• exposed to an agent’s model as a tool;
• exported from a workflow module and run through the CLI;
• exposed as a finite hosted workflow when paired with an explicit agent and route.

This separates reusable behavior from the two execution models that consume it:

• Agents are persistent, message-driven actors.
• Workflows are finite execution envelopes with payloads, run lifecycle, and results.
• Actions are the composable behavior shared by both.

Motivation

Today, workflows initialize agents themselves:

export async function run(ctx) {
  const harness = await ctx.init(agent);
  // ...
}

This has caused createAgent() initialization to receive a potentially undefined payload:

• under a workflow, payload is defined;
• for an addressable agent, payload is always undefined.

The type suggests that agent initialization may happen for every message and encourages users to build agent behavior around workflow invocation data. That is not how addressable agents work.

Simply removing payload and moving createAgent() inline does not address the deeper problem. It further couples workflow behavior to harness creation and makes that behavior difficult for an existing agent to reuse.

The reusable part is not the workflow execution envelope or the agent definition. It is the finite procedure that operates through a harness.

Proposed model

Action

An action is finite orchestration over a provided harness:

// src/actions/review.ts
export const review = defineAction({
  input: ReviewInputSchema,
  output: ReviewOutputSchema,

  async run({ harness, input }) {
    // finite, top-to-bottom orchestration
  },
});

input and output schemas are optional. Valibot schemas would be supported through the schema interface Flue adopts.

An action:

• does not create an agent;
• does not choose a sandbox;
• does not own workflow admission or persistence;
• does not receive workflow-specific context;
• can use the supplied harness to access sessions, shell, filesystem, skills, and other capabilities;
• returns a finite result.

Agent

An agent may expose actions to its model:

import { review } from "../actions/review";

export default createAgent(() => ({
  actions: [review],
  // ...
}));

actions should be a first-class field rather than requiring:

tools: [review]
tools: [review.asTool()]

Flue adapts each action into a model-callable tool internally. This preserves the semantic distinction between ordinary tools and finite orchestration without exposing conversion plumbing.

When the model invokes an action, Flue supplies a scoped view of the calling agent’s harness.

Workflow

A workflow module binds an action to Flue’s finite run lifecycle:

// src/workflows/review.ts
import { review } from "../actions/review";

export const action = review;

An action may also be defined inline:

// src/workflows/review.ts
export const action = defineAction({
  input: ReviewInputSchema,
  output: ReviewOutputSchema,

  async run({ harness, input }) {
    // ...
  },
});

The workflow remains the top-level runnable artifact. Users should not need to create a separate agent merely to run a local workflow.

A separate defineWorkflow() wrapper does not appear necessary initially. The workflow module itself is the execution binding. We can introduce a wrapper later if the envelope gains enough configuration to justify one.

Harness and session semantics

Every action invocation receives an invocation-scoped harness.

When an agent calls an action:

• the action inherits the calling agent’s configuration and capabilities;
• it shares the calling agent’s sandbox and filesystem;
• it does not reenter the session currently waiting for the tool result;
• its default session resolves to a fresh invocation-owned session;
• named sessions are also isolated within the action invocation;
• the action may create additional sessions or delegated tasks;
• the action’s return value becomes the tool result delivered to the parent session.

Conceptually, "default" is an alias for the unnamed session belonging to the current execution scope. It is not a globally shared session literally named "default".

This follows the same general principle as delegation: share the working environment, but isolate conversation state.

CLI execution

Running a workflow locally should require only the workflow:

flue run review

The CLI supplies a built-in ephemeral local agent policy:

• Node runtime;
• local sandbox rooted in the current project;
• project model/provider defaults;
• instructions and skills discovered from the filesystem;
• no separately authored agent required.

This makes workflows well suited to repository automation and CI: finite jobs that begin, run to completion, return a result, and can be restarted if necessary.

An advanced --agent option could be considered later, but it should not be required or presented as the normal workflow model.

Custom workflow agent

A workflow may optionally export an agent when its execution requires behavior beyond the default local runner:

// src/workflows/review.ts
import { review } from "../actions/review";

export const agent = createAgent(() => ({
  model: "provider/model",
  skills: [/* ... */],
  tools: [/* ... */],
}));

export const action = review;

This agent configures the harness used by the finite workflow runner. It is not an addressable, persistent agent merely because it appears in a workflow module.

createAgent() should no longer receive workflow payload. Flue initializes the harness first and passes validated workflow payload to the action as input.

Hosted workflows

A workflow without an exported route remains available to local tooling but is not included as a hosted endpoint.

A routed workflow must export an explicit agent:

export const route = {
  // middleware and route configuration
};

export const agent = createAgent(() => ({
  // explicit hosted execution policy
}));

export const action = review;

Deployment should fail when a workflow exports a route without exporting an agent.

This keeps local execution convenient while avoiding an ambiguous hosted default. A hosted runtime has no natural equivalent of the CLI’s current filesystem, local sandbox, or inherited project environment.

The existing workflow route remains valuable for deterministic finite work initiated by webhooks, schedules, CI systems, or background jobs. A caller should not be forced to prompt a persistent agent and hope that its model chooses to invoke the action.

Execution model

The resulting concepts are:

Concept	Purpose	Lifetime
Action	Reusable finite orchestration	One invocation
Agent	Persistent message-driven actor	Indefinite
Workflow	Finite run envelope binding an action to execution policy	One run
Harness	Agent policy bound to runtime resources	Execution-scoped
Session	Conversation state within a harness scope	Named or invocation-default

The distinction is who controls execution:

• An agent receives messages and lets its model decide what to do.
• A workflow deterministically invokes its exported action.
• An action contains the reusable procedure both execution models can run.

API sketch

interface ActionDefinition<TInput, TOutput> {
  input?: Schema<TInput>;
  output?: Schema<TOutput>;
  run(context: {
    harness: FlueHarness;
    input: TInput;
  }): TOutput | Promise<TOutput>;
}

declare function defineAction<TInput = unknown, TOutput = unknown>(
  definition: ActionDefinition<TInput, TOutput>,
): ActionDefinition<TInput, TOutput>;

Agent configuration gains:

interface AgentRuntimeConfig {
  actions?: ActionDefinition<any, any>[];
}

A workflow module exports:

export const action: ActionDefinition<any, any>;
export const agent?: CreatedAgent;
export const route?: WorkflowRoute;

Relationship to dynamic workflow systems

Claude Code’s dynamic workflows offer useful prior art: orchestration lives in executable code while individual prompts run as delegated worker sessions. The parent conversation does not become the workflow’s mutable session.

Flue does not need dynamically generated workflows to adopt the same useful boundary:

• orchestration is finite code;
• each model interaction can run in an isolated session;
• the working environment may be shared;
• the completed result returns to the caller.

Breaking changes and migration

Remove payload from createAgent()

Before:

const agent = createAgent(({ payload }) => ({
  instructions: `Review ${payload.repository}`,
}));

After:

const review = defineAction({
  input: ReviewInputSchema,

  async run({ harness, input }) {
    return harness.session().prompt(`Review ${input.repository}`);
  },
});

Agent definitions become independent of per-invocation workflow data.

Replace workflow-owned initialization

Before:

export async function run(ctx) {
  const harness = await ctx.init(agent);
  return harness.session().prompt(/* ... */);
}

After:

export { agent };
export const action = defineAction({
  async run({ harness, input }) {
    return harness.session().prompt(/* ... */);
  },
});

For ordinary local workflows, the exported agent can be omitted.

Goals

• Remove workflow payload from createAgent().
• Make finite orchestration reusable by workflows and agents.
• Keep workflows complete and directly runnable.
• Preserve the distinct mental models of persistent agents and finite runs.
• Make local repository automation and CI the default workflow experience.
• Isolate action conversation state while sharing the caller’s sandbox.
• Require explicit execution policy for hosted workflow routes.
• Keep action-to-tool adaptation framework-owned.

Non-goals

• Dynamically generating action source code at runtime.
• Allowing an action tool to reenter its parent’s active session.
• Guaranteeing that every action is compatible with every agent.
• Statically validating that an agent provides every skill or tool an action expects.
• Making hosted workflows inherit an arbitrary caller-selected agent through query parameters.
• Strengthening workflow durability as part of this RFC.

Open questions

1. Should action schemas use the existing result-schema abstraction, Standard Schema, or explicitly expose Valibot types?
2. Should filesystem-discovered instructions and skills apply only to the CLI’s default runner, or also augment explicitly exported workflow agents?
3. Should actions have explicit metadata such as name and description, or should these default from the exported symbol/module and schema descriptions?
4. Should an action invocation’s named sessions remain inaccessible after completion, or be inspectable through workflow run APIs?
5. Should flue run --agent be included initially as an advanced feature or deferred until a concrete use case appears?
6. What should happen when two actions exposed by an agent resolve to the same model-facing tool name?

[FredKSchott]

Implementation note: use Actions to delete the old workflow orchestration model

The largest opportunity in this RFC is not adding Actions alongside the existing workflow API. It is deleting the old workflow-owned orchestration model once Actions exist.

The implementation should treat this cleanup as part of the RFC rather than layering Actions over run(ctx) and ctx.init().

High-confidence cleanup

Remove workflow payload from createAgent() entirely

Delete the payload generic from createAgent(), CreatedAgent, and AgentCreateContext, along with the bivariance workaround it requires today.

Agent initialization should receive only agent-lifetime information such as id and env. Per-invocation data belongs exclusively to:

action.run({ harness, input })

This also removes the two current initialization paths where workflows pass a payload but addressable agent submissions explicitly pass undefined.

Remove public ctx.init()

Workflow code should no longer create harnesses. The workflow runner should resolve the exported agent or local default policy, create exactly one invocation-scoped harness, and then execute the action.

This allows us to remove:

• FlueContext.init();
• AgentHarnessOptions from workflow authoring;
• user-selected workflow harness names;
• duplicate harness-name tracking and retry cleanup;
• per-init() tool, skill, and subagent augmentation.

Capability composition should live in the runner's agent policy rather than in a second workflow-only composition system.

Replace run(ctx) with export const action

We should not retain both contracts long-term. A workflow module should normalize to one definition:

{
  action,
  agent?,
  route?,
}

That lets us delete WorkflowHandler, raw handler/context plumbing, and direct calls to arbitrary workflow handlers. A workflow becomes the finite execution envelope around an Action rather than another place to author orchestration behavior.

Make FlueContext an internal execution context

The runtime still needs an internal object containing run/instance identity, requests, environment bindings, stores, event emission, recovery state, and harness construction.

Actions should not receive that object. Their public context should remain:

{
  harness,
  input,
}

Otherwise ActionContext will become the old FlueContext under a new name.

Existing workflow access needs an explicit policy:

• req belongs in route middleware;
• workflow/run identity belongs to the execution envelope;
• platform bindings should generally be represented by agent capabilities or tools;
• structured logging may deserve an execution-neutral service exposed through the harness.

Rename workflow payload to input

This is the right breaking-change window to establish one vocabulary across Actions and Workflows:

• CLI --payload → --input;
• SDK workflow options payload → input;
• run records payload → input;
• run_start.payload → run_start.input;
• docs, errors, and OpenAPI likewise.

Keeping payload at the workflow boundary and input inside the action would create unnecessary translation and ambiguity.

Introduce execution scopes

Actions make the current literal "default" harness/session identity inadequate. We should introduce an internal execution scope model:

root agent/workflow scope
├── action scope
│   ├── default session
│   └── named sessions
└── task scope

The important semantics are:

• "default" is only a public alias for the unnamed session in the current scope;
• a model-invoked Action receives a fresh child scope;
• all Action sessions, including named sessions, are isolated from the parent scope;
• the Action inherits the parent sandbox, filesystem, configuration, and capabilities;
• the active parent session is never reentered;
• returning from the Action supplies the parent tool result.

Session storage identity should eventually be based on owner plus execution scope plus local session name, rather than literal default harness/session names.

There is migration risk because current session keys persist [instanceId, harness, session]. A staged implementation could initially map the stable agent root scope to the legacy "default" slot while using real scope IDs for new Action scopes.

Share internal scope machinery with delegated tasks

session.task() already implements much of what Actions need:

• a fresh child identity;
• isolated conversation state;
• inherited sandbox environment;
• optional scoped cwd;
• cancellation propagation;
• parent/child event correlation;
• returning a result to the parent.

Actions and Tasks should remain distinct public concepts, but they can share one internal child-scope executor.

• A Task delegates one prompt to a child agent session.
• An Action executes finite TypeScript orchestration over a child-scoped harness.

This should also consolidate duplicated agent-policy assembly between root harness initialization and task session initialization.

Make sandbox ownership explicit

Today sandbox construction happens while initializing a created agent, making resource lifetime ambiguous. Actions suggest a clearer invariant:

The root runner acquires policy and resources once; Action and Task scopes borrow them.

Conceptually:

agent/workflow runner
└── resource lease
    ├── root harness scope
    ├── action child scopes
    └── task child scopes

Only the root owner may dispose of the sandbox. Child scopes close their sessions but never destroy shared resources.

This prevents an Action from accidentally creating a second sandbox and gives us one future location for optional sandbox cleanup/disposal.

Use one first-class Action executor

Actions should not be implemented as ordinary custom tools or as ctx.init() under another name.

One internal executor should serve both entry points:

• top-level workflow execution;
• model-triggered Action execution.

It should own:

• input validation;
• child scope creation;
• cancellation;
• Action lifecycle correlation;
• output validation;
• cleanup;
• adapting errors to either workflow failures or tool errors.

The framework-owned Action-to-tool adapter must preserve the launching tool-call ID. Actions should remain a first-class actions capability rather than being accepted through tools or requiring .asTool().

Consolidate workflow discovery and generated runtime state

Current discovery maintains separate local and hosted workflow handler maps even though they contain the same behavior and differ only in exposure.

Replace them with one registry:

workflows[name] = {
  action,
  agent,
  route,
};

Then:

• CLI can run every workflow;
• HTTP exposes only workflows with route;
• normalization rejects route without agent;
• route middleware remains attached to the owning workflow and continues protecting run reads;
• manifests derive from the same definition;
• Node and Cloudflare adapters execute the same normalized workflow definition.

The generated module-normalization source string can also become a typed internal function, making the new module contract easier to validate and test.

Additional cleanup worth including

• Add actions consistently to both AgentRuntimeConfig and Agent Profiles.
• Require stable Action metadata such as name and description; do not infer model-facing names through several symbol/module fallbacks.
• Validate name collisions across built-in tools, custom tools, Actions, and sandbox-provided tools in one place.
• Remove public workflow-selectable harness names and likely public harness.name unless another concrete use remains.
• Consider renaming SDK workflows.invoke() to workflows.run() so Actions are invoked/executed while Workflows are run.
• Remove the apparently unused top-level AgentRuntimeConfig.description; module descriptions, profile descriptions, and Action descriptions have clearer roles.
• Keep Workflow Runs, run IDs, workflow SDK APIs, and React workflow APIs. An Action called by an agent is finite, but it is not a Workflow Run.
• Avoid adding flue run --agent initially; an exported workflow agent already supplies custom runner policy, and no concrete override precedence model exists yet.

Compatibility branches to avoid

Because this cleanup is the primary value of the RFC, we should avoid preserving these indefinitely:

• workflow modules supporting either run or action;
• payload aliasing input;
• ctx.init() beside runner-created harnesses;
• Actions accepted in both tools and actions;
• public action.asTool() conversion;
• hosted workflows silently receiving a default agent policy;
• calling model-invoked Action executions Workflow Runs.

A direct pre-1.0 migration with clear build errors is preferable to retaining the concepts this RFC is intended to separate.

Recommended implementation sequence

1. Define Action metadata, schemas, and invocation semantics.
2. Implement invocation-scoped harness/session identity and one Action executor.
3. Add Actions to agent configs and profiles.
4. Normalize workflow modules as { action, agent?, route? } and enforce route => agent.
5. Move workflow harness creation into the runner.
6. Remove ctx.init(), named workflow harnesses, and AgentHarnessOptions.
7. Remove workflow payload from createAgent() and split the public Action context from the internal execution context.
8. Rename public workflow payload terminology to input.
9. Consolidate local/hosted workflow registries and generated normalization.
10. Rewrite docs, examples, and blueprints around the three concepts.
11. Stage session-storage identity migration and explicit sandbox disposal separately where required.

The target invariant should be:

Agents define persistent behavior and policy. Workflows define finite admission and lifecycle. Actions define reusable behavior. Runners own harnesses and resources; Actions only borrow scoped access to them.

[FredKSchott]

Follow-up: first-class Workflow identity and programmatic invocation

The Actions model also clarifies how workflows should be represented and triggered programmatically.

Add createWorkflow() as the finite execution binding

An Action is reusable behavior. A Workflow is a particular way to run that behavior as a finite run, optionally using an explicit agent policy.

That gives createWorkflow() a concrete purpose beyond wrapping module exports: it creates a branded, importable Workflow value that can be passed to programmatic invocation APIs.

This parallels the relationship between reusable Agent Profiles and created Agents:

• defineAction() defines reusable finite behavior;
• createWorkflow() creates one runnable finite binding;
• defineAgentProfile() defines reusable agent behavior;
• createAgent() creates one addressable/runtime-initializable agent binding.

A workflow may bind an extracted Action:

// src/workflows/review.ts
import { createWorkflow } from '@flue/runtime';
import reviewer from '../agents/reviewer.ts';
import { review } from '../actions/review.ts';

export default createWorkflow({
  action: review,
  agent: reviewer,
});

Or define a workflow-private Action inline:

// src/workflows/review.ts
import { createWorkflow } from '@flue/runtime';

export default createWorkflow({
  agent: reviewer,
  input: ReviewInputSchema,
  output: ReviewOutputSchema,

  async run({ harness, input }) {
    // finite orchestration
  },
});

The inline form should be the most common and concise authoring experience. Authors only need defineAction() when the behavior is reused by an agent or another workflow.

The two forms should be mutually exclusive at the type level:

createWorkflow({ action, agent? });

createWorkflow({
  agent?,
  input?,
  output?,
  run,
});

Keep route outside createWorkflow()

route controls transport access to a discovered workflow; it is not part of the Workflow value itself. This should match the existing agent module model, where route/channel exposure is separate from createAgent().

export default createWorkflow({
  action: review,
  agent: reviewer,
});

export const route = middleware;

This keeps the boundaries clear:

• the Workflow defines finite execution;
• the exported route controls HTTP access and middleware;
• discovery combines them for deployment.

A routed workflow still requires an explicit agent. Local CLI execution may use the built-in local runner when the Workflow omits one.

Add top-level invoke() as the Workflow counterpart to dispatch()

For the initial API, add one top-level asynchronous admission function:

import { invoke } from '@flue/runtime';
import review from './workflows/review.ts';

const { runId } = await invoke(review, {
  input: { repository: 'withastro/flue' },
});

invoke() should:

• accept an imported, discovered Workflow value;
• validate/admit its input;
• create a real Workflow Run;
• return run admission information including runId;
• detach rather than waiting for the result;
• work independently of whether the Workflow exports an HTTP route.

This intentionally pairs with the existing agent API:

const { dispatchId } = await dispatch(agent, {
  id: 'repo-42',
  input: event,
});

const { runId } = await invoke(workflow, {
  input,
});

The distinction remains small and meaningful:

• dispatch() admits work to a persistent Agent instance;
• invoke() admits one finite Workflow Run.

We should not overload dispatch() with Workflow semantics because its target identity, persistence model, and returned identifier differ. However, both APIs remain simple top-level ways to kick off background work.

Do not add waiting to the initial runtime API

The initial runtime invoke() should not support wait: 'result', return the completed Action output, or add separate start() and run() verbs.

The immediate application use case is background work from channels, schedules, and application code. Callers receive a runId and use existing run observation or SDK streaming surfaces when they need progress or results.

This keeps the initial API narrow:

invoke(workflow, { input }) -> run admission

A later project can reconsider attached waiting, streaming, cancellation, and broader naming consistency across runtime and SDK APIs once concrete use cases are established.

Updated conceptual model

Primitive	Definition	Programmatic admission
Action	Reusable finite behavior over a scoped harness	Invoked internally by an Agent or Workflow runner
Agent	Persistent, message-driven actor	dispatch(agent, { id, input })
Workflow	Branded finite binding created from an Action plus optional agent policy	invoke(workflow, { input })
Route	Separate transport/middleware exposure for a discovered Workflow	HTTP/SDK boundary

The resulting core authoring model is:

Extract an Action when behavior needs reuse. Create a Workflow when that behavior needs a finite run identity and lifecycle. Dispatch work to persistent Agents; invoke finite Workflows.