ai-provider.setup

Attach a CloudConnection to an organisation as an AI provider configuration, validating AI-capability and persisting via data.ai-provider.persist

Attach a CloudConnection to an organisation as an AI provider configuration.

Validates that the connection exists, is active, and belongs to an AI-capable provider type, then delegates persistence to data.ai-provider.persist via engine.run_sync.

States: PENDING (initial) → COMPLETED | FAILED

Overview

Property	Value
Workflow type	Atomic
Library	App-connection
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	UUID of the organisation that will own the AI provider config
connection_uuid	uuid	Yes	—	UUID of the CloudConnection to attach as an AI provider
default_model	string	Yes	—	Default model ID (e.g. 'gpt-4o-mini', 'MiniMax-M2')
models	list	No	—	User-supplied list of model IDs (e.g. for OpenRouter); null leaves it unset
model_config	dict	No	—	Model configuration: temperature, max_tokens, etc.
agent_capacity	dict	No	—	Typed coding-session reservation with positive session_rpm and session_tpm; requires provider rate_limit_rpm and rate_limit_tpm
rate_limit_rpm	integer	No	—	Requests-per-minute rate limit; null means unlimited
rate_limit_tpm	integer	No	—	Tokens-per-minute rate limit; null means unlimited
is_default	boolean	No	—	Mark as the default AI provider for this organisation
actor	string	No	—	Authenticated caller (Cognito sub or UUID) initiating this setup

Output Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	UUID of the organisation that will own the AI provider config
connection_uuid	uuid	Yes	—	UUID of the CloudConnection to attach as an AI provider
default_model	string	Yes	—	Default model ID (e.g. 'gpt-4o-mini', 'MiniMax-M2')
models	list	No	—	User-supplied list of model IDs (e.g. for OpenRouter); null leaves it unset
model_config	dict	No	—	Model configuration: temperature, max_tokens, etc.
agent_capacity	dict	No	—	Typed coding-session reservation with positive session_rpm and session_tpm; requires provider rate_limit_rpm and rate_limit_tpm
rate_limit_rpm	integer	No	—	Requests-per-minute rate limit; null means unlimited
rate_limit_tpm	integer	No	—	Tokens-per-minute rate limit; null means unlimited
is_default	boolean	No	—	Mark as the default AI provider for this organisation
actor	string	No	—	Authenticated caller (Cognito sub or UUID) initiating this setup
ai_provider_config_uuid	uuid	No	—	UUID of the persisted AIProviderConfig row
created	boolean	No	—	True when a new AIProviderConfig row was inserted
completed_at	string	No	—	ISO-8601 timestamp of successful completion
failure_reason	string	No	—	Controlled-vocabulary failure reason
failure_type	string	No	—	Failure category
failed_action	string	No	—	Action method that raised
failed_at_state	string	No	—	State the workflow was in when it failed
failed_at	string	No	—	ISO-8601 timestamp of failure
error	string	No	—	Engine-stamped error message on the failure path
error_type	string	No	—	Engine-stamped error type on the failure path
failed_layer	string	No	—	Engine-stamped DAG layer name on the failure path
failed_step	string	No	—	Engine-stamped DAG step name on the failure path

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	AI provider setup request received; validating and persisting
completed	No	Yes	Yes	—	AI provider configuration created or updated successfully
failed	No	Yes	No	—	AI provider setup failed

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

Business Errors

Code	Message Template
CONNECTION_NOT_FOUND	CloudConnection {connection_uuid} not found for this organisation
CONNECTION_NOT_ACTIVE	CloudConnection {connection_uuid} is not active
CONNECTION_NOT_AI_PROVIDER	CloudConnection {connection_uuid} (type={connection_type}) is not an AI-capable provider
INVALID_CONFIG

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "ai-provider.setup",
  "initial_data": {
    "organization_uuid": "value",
    "connection_uuid": "value",
    "default_model": "value"
  }
}