createFlow
Custom flow with a user-provided executor function for bespoke orchestration.
createFlow creates a flow with a custom executor function. Use it when the built-in sequential, cycle, and broadcast patterns don't fit your orchestration needs — for example, conditional branching, dynamic step selection, or partial execution.
import { createAgent, createFlow } from "@comma-agents/core";
const classifier = createAgent({
name: "classifier",
model: "openai/gpt-4o",
systemPrompt: "Classify the input as 'technical' or 'creative'. Reply with only the category.",
});
const technicalWriter = createAgent({
name: "technical-writer",
model: "openai/gpt-4o",
systemPrompt: "Write a detailed technical explanation.",
});
const creativeWriter = createAgent({
name: "creative-writer",
model: "openai/gpt-4o",
systemPrompt: "Write a creative, engaging piece.",
});
const flow = createFlow({
name: "routed-writing",
steps: [classifier, technicalWriter, creativeWriter],
execute: async (steps, message, flowContext) => {
const classification = await flowContext.runStep(steps[0]!, message);
if (classification.text.includes("technical")) {
const result = await flowContext.runStep(steps[1]!, message);
return result.text;
} else {
const result = await flowContext.runStep(steps[2]!, message);
return result.text;
}
},
});
const result = await flow.call("Explain monads");
console.log(result.text);CustomFlowConfig
Prop
Type
FlowExecutor
The execute function receives the step list, the input message, and a context object. Call flowContext.runStep() to execute steps — this tracks results for aggregation into the FlowResult and fires beforeStep/afterStep hooks.
Prop
Type
The executor must return the final output text as a string. The context also exposes flowContext.results for inspecting collected step results mid-flow.
buildFlowAgent
buildFlowAgent builds a flow from a config, typed name, and executor function. Use it to create reusable flow factories with custom orchestration logic:
import { createAgent, buildFlowAgent } from "@comma-agents/core";
import type { FlowHooks } from "@comma-agents/core";
function createMyCustomFlow(config) {
return buildFlowAgent(
config,
"my-custom",
{},
async (steps, message, flowContext) => {
// your orchestration logic
let output = message;
for (const step of steps) {
const result = await flowContext.runStep(step, output);
output = result.text;
}
return output;
},
);
}Declarative Custom Flow Types
Use defineFlowType and registerFlow when JSON or YAML strategies need to reference a reusable custom implementation by name. The configuration schema validates the flow's config object before the factory runs.
import {
createFlow,
defineFlowType,
registerFlow,
} from "@comma-agents/core";
import { z } from "zod";
registerFlow(
"first-match",
defineFlowType({
configSchema: z.object({ marker: z.string() }).strict(),
create: ({ name, steps, config }) =>
createFlow({
name,
steps,
execute: async (availableSteps, message, flowContext) => {
for (const step of availableSteps) {
const result = await flowContext.runStep(step, message);
if (result.text.includes(config.marker)) return result.text;
}
return message;
},
}),
}),
);After registration, strategy and standalone flow files can use the registered name as type:
name: Routed Review
type: first-match
steps:
- agent: reviewer-a
- agent: reviewer-b
config:
marker: APPROVEDKeep implementation-specific fields inside config. Common fields remain name, type, description, and steps. An unknown flow type or invalid configuration fails when the flow is loaded.
FlowTypeDefinition
The schema and factory used to register a declarative custom flow type.
Prop
Type
FlowTypeContext
The resolved steps, validated configuration, and agent resolver passed to the custom factory.
Prop
Type