Unions

Unions describe payloads that can take one of several typed shapes. In Flow AI they are most often used for plan action schemas, where each action has a discriminator such as kind and a variant-specific payload.

Use TaggedUnion(...) when a plan, event, or other schema accepts multiple Pydantic model variants. It returns a Pydantic discriminated union over the kind field by default, validates that every variant has a unique discriminator value, and exports a schema the runtime can use for validation.

For plan-action examples, see Plans concept.

TaggedUnion

TaggedUnion(*models: 'type[BaseModel]', discriminator: 'str' = 'kind') -> 'Any'

Parameter	Type	Default
models	type[BaseModel]	required
discriminator	str	'kind'

Returns: Any

Create a Pydantic discriminated union over discriminator.

Models may use either Pydantic's native Literal[...] discriminator field or the public Harness shorthand kind: str = "some_kind".

Python type checkers cannot infer a precise alias from a runtime function call, so the return annotation is intentionally Any. Runtime validation and JSON schema generation still use Pydantic's discriminated union.