InteractionProcessStartRequest

Starts a run of an interaction: its inputs, and anything this run does differently from the definition.

Kind: an object, used in requests.

Fields

Field	Type	Required	Description
inputs	NameValuePair[]	yes	The run’s inputs, by name. Every required input must be given. Constraints: required (empty or whitespace-only strings are rejected).
loomMappings	LoomMappingRequest[] | null		The loom particular agents wake up with in this run, in place of the one the interaction would choose.
loomGifts	LoomStartGiftRequest[] | null		Threads to hand to agents as they start, so they wake up knowing them, and knowing they were told.
aiModelOverrides	AiModelOverrideRequestInput[] | null		Agents to run on a different model in this run.
responseJsonSchema	string | null		A JSON Schema the run’s answer must match, in place of the interaction’s own. Must be a valid JSON Schema.
disabledTools	string[] | null		The names of tools this run’s agents are not given.
credentials	InteractionProcessCredentialRequest[] | null		Model provider keys of yours for this run. Calls use these first, then your tenant’s model keys.
allowMaitentoFallback	boolean | null		Whether an agent may fall back to Maitento’s own key once your keys for its provider are used up or have failed (and only when your tenant allows it). Null or false: it may not, and the turn fails instead.
credentialStack	string | null		The credential stack the run uses, by id or name. Its credentials serve every model call, in the stack’s order, and Maitento’s own keys are never used. Leave it out to use the interaction’s own stack, then the namespace’s default, then your tenant’s. Can’t be combined with credentials.
durationAutoTerminationOverride	timespan | null		The longest this run may take, in place of the interaction’s own limit. Null: the interaction’s.
durationWarningOverride	timespan | null		How long into this run the agents are told that time is running short, in place of the interaction’s own setting. Null: the interaction’s.
swarmLimits	InteractionSwarmLimitsRequestInput| null		Narrows how far the sub-interactions this run’s participants start may spread: each limit given becomes the lesser of it and the definition’s, and each left out is not narrowed. It can never widen them. Null: the definition’s limits.
webDownloadPartitionId	uuid | null		The temporary knowledge base (partition) the run’s web fetches are kept in. Null: the namespace’s default, then the tenant’s. A run whose agents may fetch, with none of the three, is refused (api:web:download-partition-required). Runs it starts use it too.
webAccessOverrides	WebAccessOverrideInput[] | null		Per-agent overrides of the agents’ web tools for this run.

Example

{
  "inputs": [
    {
      "name": "...",
      "value": "..."
    }
  ],
  "loomMappings": [
    {
      "agentName": "...",
      "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "namespaceId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "name": "...",
      "namespaceName": "..."
    }
  ],
  "loomGifts": [
    {
      "agentName": "...",
      "fromLoomId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "threadIds": [],
      "note": "...",
      "givenBy": "..."
    }
  ],
  "aiModelOverrides": [
    {
      "agentName": "...",
      "modelName": "...",
      "customModel": {},
      "purpose": "Agent"
    }
  ],
  "responseJsonSchema": "...",
  "disabledTools": [
    "..."
  ],
  "credentials": [
    {
      "provider": "...",
      "apiKey": "...",
      "baseUrl": "...",
      "modelNameOverrides": {
        "key": "..."
      },
      "credentialId": "...",
      "isOwnLicense": false,
      "priority": 0
    }
  ],
  "allowMaitentoFallback": false,
  "credentialStack": "...",
  "durationAutoTerminationOverride": "00:05:00",
  "durationWarningOverride": "00:05:00",
  "swarmLimits": {
    "maxDepth": 0,
    "maxConcurrent": 0,
    "maxTotal": 0
  },
  "webDownloadPartitionId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "webAccessOverrides": [
    {
      "agentName": "...",
      "search": false,
      "fetch": false
    }
  ]
}

Where it’s used

• interactions.start (PUT /interactions/processes/by-id/{id}/start)
• interactions.start (PUT /namespaces/{namespaceName}/interactions/by-name/{name}/start)