Skip to main content
Each genai.model of a flow runs the model its model port names. A run can name another for that run alone, with an entry in its input_data: an entry addresses one provider by its alias, and an entry with the alias * addresses every provider no entry names. The flow stays as it is, and a run that names no model runs the models the flow names. Which model one provider runs:

The entry

A run’s input_data entry is {"alias", "type", "value"}, type being optional. For a genai.model, the value is an object holding the model’s id, as <vendor>/<model>, and optional settings, any of the provider’s setting ports:
  • type is optional on any entry and names the component type the entry is for. Given, the entry reaches only components of that type, and its alias must name one. Left out, the entry reaches the data component or the genai.model holding its alias, since the two share one alias namespace. The types that take a run’s input are data.message, data.messages and genai.model.
  • * needs a type, is accepted only for genai.model, once per run, and reaches every genai.model that no entry names by its alias.
The first entry above runs anthropic/claude-sonnet-5-5 on the provider whose alias is writer, with its output capped at 800 tokens; the second runs gemini/gemini-3.1-flash-lite on every other provider of the flow that can run it.

Which model a provider runs

A genai.model runs the model of the entry naming its alias, else the model of the * entry, else the model of its own model port. It can run a model when:
  • its vendors has an entry for the model’s vendor;
  • its allowed_models is empty or matches the model;
  • the catalog does not show the model lacking a capability the provider’s components need, such as chat for genai.chat (The catalog). A model the catalog does not list is not checked for capabilities.
A model named by alias that its provider cannot run is refused when the run is created, with invalid_model: the run never starts. A * model that a provider cannot run passes that provider by: that provider keeps its own model, with a warning, and the providers that can run the * model run it. The run is refused for a * model only when no provider left to it can run that model, or for the model’s own problems, below. A model id that is not <vendor>/<model>, or whose vendor is not openai, anthropic or gemini, is refused whether an entry names it by alias or through *.

Settings for one run

An entry’s settings holds any of the provider’s nine settings. Each setting it gives replaces the provider’s for this run, and the provider’s other settings stay. They are checked by the rules the provider’s ports follow, so a value out of range, or a field that is not a setting, refuses the run with invalid_input_data. A setting the vendor or the model does not accept is left out of the call, as the provider’s own would be, and the provider posts one warning naming each setting left out and why. For a model the catalog does not list, only a setting its vendor has no field for is left out.

From each surface

  • REST. Create Execution takes the entries in its input_data. A refusal is a 400 holding every problem of its kind in problems.
  • The SDK. execute() takes model=, <vendor>/<model> or {"id", "settings"}, sent as the * entry, and models=, a provider’s alias to a model, one entry each (Workflow). A refusal raises CommandError with the refusal’s error and message; the SDK does not expose problems.
  • The CLI. blobhub workflow execute --model <vendor>/<model> sends the * entry, and --model <alias>=<vendor>/<model> one provider’s entry; the option repeats and takes no settings (execute). A malformed --model fails before any request with MODEL_SELECTION_INVALID, and a refusal fails with API_COMMAND_FAILED.
  • The web. The debugger’s New Execution button opens the Create a New Execution dialog, whose Input Data field takes the entries as JSON. A refusal shows as Failed to create execution: <message>.
  • A schedule. A workflow target’s input_data takes the same entries, and a fire whose run is refused is recorded as invocation_error with result.error invocation_failed (Execution History).
  • A listener. A workflow target’s input_data takes the same entries, checked for their shape only when the listener is saved; a run they cannot start ends the batch as invocation_error (Listeners).

When a run is refused

create_execution answers 400 and lists every problem of one kind in the run rather than the first: message joins the problems’ messages with ; , and problems holds [{"index", "alias", "message"}], index being the entry’s position in input_data. Nothing is written: no execution, no snapshot, no event, and nothing counts against a limit. The request’s shape is checked first, as for every command, with invalid_request_body: a type must be a non-empty string, and an alias * or a valid alias (Create Execution). For a flow with two providers, writer, whose vendors lists only openai and whose allowed_models is empty, and judge, whose vendors lists openai and gemini and whose allowed_models is openai/*, this input is refused twice over: writer cannot run the Anthropic model named for it, and judge, the one provider left to *, cannot run the * model.
error is the code of the table below that the problems come from. The model is checked only once every entry is addressed, so a run with problems of both kinds is refused with invalid_input_data alone. invalid_input_data: an entry addresses nothing it can reach. invalid_model: the model cannot run where the entry sends it. A * left with no provider, because an entry names every genai.model by its alias, is unused: the checks that depend on a provider (credential, allowed_models, capability) are skipped and nothing is reported for them. It is refused for its own problems all the same: an id that is not <vendor>/<model>, an unknown vendor, a setting out of range.

Not checked when the run is created

Creation reads the definition only when an entry has a type, the alias * or an object value. These are not checked there:
  • An entry without type whose alias no component holds is ignored, since a template may still read it.
  • An entry without type whose value is not an object and whose alias a genai.model holds passes creation when no other entry makes creation read the definition. The run then ends with flow.error, listing the problems.
  • Whether a data value’s type suits its data component.
  • The definition itself: Prepare runs check_definition, and a failing definition ends the run with flow.error Workflow definition check failed, the provider’s own errors among its events.
  • Whether the vendor’s credential exists, and whether the vendor serves the model: both are found at the call, as for the model a flow names itself, since a credential can be deleted between creation and the call (When the call fails).

Warnings while it runs

Each genai.model posts these as processor.warning events on its node when it runs: the adapter’s after its call, the others before it. They show wherever events are shown: the debugger, blobhub workflow execute --watch and the SDK’s events. An unknown model in the model port is not warned about at run time: check_definition warns when the flow is saved.

Which model ran

A provider posts one processor.output event per call, and its attributes.model names the model it ran, as {"id", "chosen_by"}. chosen_by is alias for an entry naming the provider’s alias, * for the * entry, and flow for the provider’s own model port, a * that passed it by included:
The model sits in the event’s attributes, so an event listing returns it whether or not the session keeps the events’ data (tracing.log_data); the call’s request, response and usage are in data. List Execution Events returns it, and the filter {"types": ["processor.output"]} keeps only these events; the SDK’s run.events() returns it too, and the debugger’s Event Details shows it.

Templates do not choose the model

A run’s model entry stays in the execution’s input_data like any input, so a templated session alias can read it as {{ execution.input_data.<alias>.id }}. A template never chooses the model: a provider runs the model of the entry whose alias matches its alias port, or of *. A * entry is no one component’s input, and no template sees it.