model (<vendor>/<model>), a vendors list holding
one credential per vendor, and the sampling settings shared by every vendor. genai.chat and genai.agent.basic
reach it through their model ports. The vendors are openai, anthropic and gemini.
A call picks its model first, then takes the credential and endpoint from that model’s vendor entry, and calls that
vendor’s API:
Ports
The ports below are data inputs, which the editor shows in three groups, Model, Vendors and Settings. Agenai.model has no flow ports: it is connected to the model port of each component it serves.
vendors is keyed by vendor, so no two entries name the same vendor. Each entry’s fields, by their labels in the
editor:
Stored in a definition, the port holds a
list value whose items are plain data, a credential by its alias:
Model ids
A model id is<vendor>/<model>, split at the first /: anthropic/claude-sonnet-5-5 is the model
claude-sonnet-5-5 of the vendor anthropic. The vendor names the API that is called, not the model’s maker, so a
model on a server speaking OpenAI’s API is an openai id however it was made. The vendors are openai, anthropic
and gemini. An id without a vendor and a model, or with another vendor, is an error in the model port, and a run
naming one is refused.
The catalog
The catalog lists the models BlobHub knows, with what each can do, the settings it accepts, its context window and its maximum output, in tokens. It is served with the workflow manifest, so the editor’s model picker offers the same models.- A model the catalog does not list is accepted.
check_definitionwarns about one in themodelport, and a run naming one posts a warning on the provider’s node,anthropic/x is not in the catalog: its capabilities were not checked and every setting is sent. Its capabilities are not checked, and every setting its vendor has is sent. - A component’s model port names the capability its model needs:
chat, forgenai.chatand for each of the basic agent’s five model ports. A catalog model without it is an error in themodelport, and a run naming one for that provider by its alias is refused; through*that provider keeps its own model, with a warning, unless no provider left to*can run it, which refuses the run. - The catalog changes only with a platform release.
Settings
The nine settings aremax_output_tokens, temperature, top_p, top_k, stop_sequences, seed,
frequency_penalty, presence_penalty and reasoning_effort. A value goes to the vendor unchanged, and a setting left
unset is not sent, so the vendor’s own default applies, except that an Anthropic call with no max_output_tokens sends
16,000, the API requiring a value. The editor seeds a setting with a default, but only a value the definition stores is
sent. Each setting a run gives replaces the provider’s for that run; the others stay. A run’s settings are checked
against the same ranges, so an out-of-range value refuses the run (invalid_input_data).
Each setting becomes a field of the vendor’s own API:
A setting the vendor has no field for, or that the catalog model does not accept, is left out of the call, and the
provider posts one warning naming each setting left out and why:
vendor_settings holds extra request fields per vendor. Only the selected vendor’s block is sent, as the SDK’s extra
body (extra_body for OpenAI and Anthropic, http_options.extra_body in Gemini’s config), so a field the SDK does
not know still reaches the API.
Vendors and credentials
vendors holds one entry per vendor the provider may call. An entry’s credential is the alias of an api_key
credential, resolved against whoever started the run, as every credential is
(How a run uses one). The provider loads only the credential of the selected
model’s vendor, so a vendor it does not call needs no credential where it runs: a provider listing three vendors runs
where only one of those credentials exists, as long as the model it runs is that vendor’s.
A credential’s type says how a service authenticates, not which service it is, so any api_key credential fits any
entry. A key in the wrong entry fails at the first call with the vendor’s own error.
base_url, the Endpoint, points that vendor’s calls at another server speaking the same API, such as an
OpenAI-compatible one. A model served there is usually not in the catalog, and is treated as any unknown model.
allowed_models holds the models a run may name: exact ids, or <vendor>/* for every model of a vendor. Empty allows
every model.
Checks
check_definition reports these on the component. Prepare runs it before every run, and a definition that fails it
ends the run with flow.error Workflow definition check failed.
Errors:
modelis not<vendor>/<model>, or names an unknown vendor.vendorshas no entry for the vendor of themodelport’s model.- A
vendorsentry without a vendor or a credential, an unknown vendor, or two entries for one vendor: alistorobjectport whose value does not fit its shape is an error, as on every component. - A
base_urlthat does not start withhttp://orhttps://. - An
allowed_modelsentry that is neither an id nor<vendor>/*. - An
aliasthat anothergenai.modelor adatacomponent of the definition also holds. - A catalog model in the
modelport that lacks a capability a consuming port declares.
- The
modelport’s model is not in the catalog. - An exact id in
allowed_modelslacks a capability the consumers need. vendor_settingsnames an unknown vendor.- A setting port holds a value that the
modelport’s catalog model does not accept:<setting> is not sent to <id>: it does not accept it. - An
allowed_modelsentry’s vendor has novendorsentry:Allowed model <entry> has no vendors entry for <vendor>: a run naming it is refused with invalid_model.
When the call fails
A failed call posts aprocessor.error event, and the component the provider serves takes its failure route. A
call fails when:
- the vendor’s credential alias names no credential where the run runs:
"<alias>" credential alias not found; - the vendor answers with an error, such as for an unknown model or a value it refuses: its own text reaches the event unchanged;
- the call times out, or cannot connect after its one retry;
- Anthropic stops the answer as a refusal:
refusal: <category>, orrefusalalone when the vendor gives no category; - Gemini blocks the prompt:
refusal: <reason>, orno_candidateswhen the reply has no candidate and no reason.
SAFETY, arrive as an empty or partial message on success.
A call is retried once, on a 502 or 503, or on a connection refused before the request was sent. It is never retried
on a timeout or on a connection broken after the request was sent, which could bill the call twice.
With logic.code
A genai.model has no credential port: its credentials sit inside its vendors list. Wired to a
logic.code, it hands the code no credential, and
get_provider_credential finds none on it. Code that calls a vendor itself gets the key from a
logic.generic_provider holding the credential.
Choosing the model per run
A run can name the model eachgenai.model calls, and replace the settings it gives for that run (the others stay),
with an input_data entry of type genai.model that addresses one provider by its alias, or every provider no entry
names by alias, by *. Choosing a Model per Run covers the entry,
what refuses it, and the SDK’s and the CLI’s options for it.
Moving from the per-vendor chat providers
genai.model replaced the three per-vendor chat providers, genai.chat.openai, genai.chat.anthropic and
genai.chat.gemini, and the platform’s migration rewrote the stored definitions and credentials that used them:
- Each per-vendor provider became a
genai.modelwith the model<vendor>/<model>, avendorsentry holding its credential alias and, when it was not the vendor’s own, its endpoint, and its stored settings. A migrated flow sends what it sent before: Anthropic’s implicitmax_tokensof 1024 was written out, and an Anthropic provider’s temperature was halved, as the old provider did on every call. - A setting stored on a chat component overrode its provider’s for that component alone, so a provider shared by chat components that overrode different settings was copied, one per component.
response_formatandresponse_schemaheld on an OpenAI or Gemini provider moved to the chat components it served.genai.chat’schatroute becamemodel, and the basic agent’sgeneric_chat,planning_chat,tool_use_chat,tool_response_chatandresponse_chatroutes becamegeneric_model,planning_model,tool_use_model,tool_response_modelandresponse_model.providers, the per-message override, was removed from every message a definition holds. Messages stored in session objects and thread items keep it, and nothing reads it.- Credentials of the types
openai,anthropic,gemini,pinecone,firecrawlandtavilybecameapi_key.
logic.code read a per-vendor provider’s
credential, was left unchanged for a person to fix; such code is rewired to a logic.generic_provider. Execution
snapshots are history and keep the retired types, so the debugger still draws an old run’s provider under its old
name.
A local copy pulled before the migration still holds the retired types: pull it again before the next deploy.
blobhub workflow deploy uploads a changed definition before it checks it, so deploying an old copy writes the
retired types back to the revision. The check then fails with Component type `genai.chat.openai` is not supported,
and every run of the definition ends with flow.error Workflow definition check failed.
A per-message override has no successor: name the model per run instead
(Choosing a Model per Run).
