Plans

Plans are typed, reviewable containers for the actions an agent intends to take. In a planner/executor flow, a planner creates and stores a plan, the runtime validates it against the plan schema and approval policy, and an executor later loads and executes the approved actions.

Use define_plan(...) to declare the action payload schema shared by planner and executor agents. It accepts JSON Schema, Pydantic models, or a {name: type} shorthand and produces a frozen PlanSpec.

Plan schemas are normalized by normalize_schema(...), the same helper used by tools and references.

For the full lifecycle and execution model, see the Plans concept and Action dispatcher references.

define_plan

define_plan(name: 'str', schema: 'Any', display_aliases: 'Mapping[str, str] | Iterable[PlanDisplayAlias | Mapping[str, str]]' = ()) -> 'PlanSpec'

Parameter	Type	Default
name	str	required
schema	Any	required
display_aliases	Mapping[str, str] | Iterable[PlanDisplayAlias | Mapping[str, str]]	()

Returns: PlanSpec

Create a validated Flow AI plan spec.

Args: name: Unique plan name within the runtime spec. schema: Action schema for plan items: a JSON Schema mapping, a Pydantic model class, a simple type map, or any type hint Pydantic can export. display_aliases: Display names for fixed plan lifecycle statuses, either a {status: alias} mapping or an iterable of PlanDisplayAlias / mappings. Statuses are limited to draft, approved, executing, executed, and failed.

Returns: A frozen, validated PlanSpec.

Raises: ValueError: If a display alias names an unsupported status. TypeError: If the schema input cannot be normalized to JSON Schema.

PlanSpec

PlanSpec(*, name: str, schema: dict[str, typing.Any], displayAliases: list[PlanDisplayAlias] = <factory>) -> None

Parameter	Type	Default
name	str	required
schema	dict[str, Any]	required
displayAliases	list[flowai_harness.plans.PlanDisplayAlias]	<factory>

Returns: None

Plan declaration compiled by flowai-runtime to Plan<HarnessAction>.

PlanDisplayAlias

PlanDisplayAlias(*, status: Literal['draft', 'approved', 'executing', 'executed', 'failed'], alias: str) -> None

Parameter	Type	Default
status	Literal['draft', 'approved', 'executing', 'executed', 'failed']	required
alias	str	required

Returns: None

Display alias for one fixed Flow AI plan lifecycle status.