# ManagedInteractionCreateRequest

Creates a managed interaction: a manager agent and the agents it can hand work to.

**Kind:** an object, used in requests.

## Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `managerAgent` | [`InteractionAgentBindingInput`](https://docs.maitento.com/reference/types/interaction-agent-binding.md#in-a-request) | yes | The manager: the agent that runs the conversation and dispatches work to the others. Constraints: required (empty or whitespace-only strings are rejected). |
| `agents` | [`ManagedInteractionAgentBindingInput`](https://docs.maitento.com/reference/types/managed-interaction-agent-binding.md#in-a-request)`[]` | yes | The agents the manager can dispatch to, each with what it sees when it is dispatched to. Constraints: minLength: 1, required (empty or whitespace-only strings are rejected). |
| `humanSettings` | [`RoundRobinInteractionHumanSettingsInput`](https://docs.maitento.com/reference/types/round-robin-interaction-human-settings.md#in-a-request)`\| null` |  | Whether a person talks with the manager, and who speaks first. Null: no one does. |
| `maxDispatches` | `integer \| null` |  | The most dispatches one run may make, 1 to 200. Null: 30. Constraints: range: 1..200. |
| `name` | `string` | yes | The interaction's name, unique within its namespace. Constraints: maxLength: 150, required (empty or whitespace-only strings are rejected). |
| `prompt` | `string` | yes | What the agents are asked to do. A run's inputs are filled in wherever it says `%%name%%`. Constraints: minLength: 3, required (empty or whitespace-only strings are rejected). |
| `solutionSchema` | `string \| null` |  | The JSON Schema the answer must match, as JSON text: the run's output is then JSON of that shape. Null: the output is free text. |
| `systemPromptMode` | [`InteractionSystemPromptMode`](https://docs.maitento.com/reference/types/interaction-system-prompt-mode.md) | yes | How `systemPrompts` combine with the instructions Maitento gives every agent. Constraints: required (empty or whitespace-only strings are rejected). |
| `systemPrompts` | `string[]` | yes | Extra system instructions for every agent in the interaction. Constraints: required (empty or whitespace-only strings are rejected). |
| `durationWarningToAi` | `timespan \| null` |  | How long into a run the agents are told that time is running short. Null: they are not told. |
| `durationAutoTermination` | `timespan \| null` |  | The longest a run may take. The run stops with an error when it is reached; time spent waiting for a person does not count. Null: no limit. |
| `contextSettings` | [`InteractionContextSettingsInput`](https://docs.maitento.com/reference/types/interaction-context-settings.md#in-a-request)`\| null` |  | How the conversation is kept within the model's context window, and how many rounds of tool calls an agent may make in one turn. Null: the defaults. |
| `swarm` | [`InteractionSwarmSettingsInput`](https://docs.maitento.com/reference/types/interaction-swarm-settings.md#in-a-request)`\| null` |  | The sub-interactions its participants may start. Null: none. |
| `credentialStack` | `string \| null` |  | The credential stack its runs use, by id or name, when their start doesn't name one. Null: the namespace's default stack, then your tenant's. A stack that doesn't exist when a run starts refuses the run. |
| `externalOperationsOpenApi` | [`OpenApiExternalOperationBindingInput`](https://docs.maitento.com/reference/types/open-api-external-operation-binding.md#in-a-request)`[]` | yes | Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools. Constraints: required (empty or whitespace-only strings are rejected). |
| `externalOperationsMcp` | [`McpExternalOperationBindingInput`](https://docs.maitento.com/reference/types/mcp-external-operation-binding.md#in-a-request)`[]` | yes | Tools from MCP connectors that every agent in the interaction can call, as well as its own tools. Constraints: required (empty or whitespace-only strings are rejected). |
| `inputsConnectorAuthenticationSecret` | [`ConnectorAuthenticationSecretInputInput`](https://docs.maitento.com/reference/types/connector-authentication-secret-input.md#in-a-request)`[]` | yes | Run inputs that choose the secret a tool sends with its calls. Constraints: required (empty or whitespace-only strings are rejected). |
| `inputsConnectorBinding` | [`ConnectorBindingInputInput`](https://docs.maitento.com/reference/types/connector-binding-input.md#in-a-request)`[]` | yes | Run inputs whose values go straight into a tool's calls, so the model never sees or chooses them. Constraints: required (empty or whitespace-only strings are rejected). |
| `inputsPrompt` | [`PromptInputInput`](https://docs.maitento.com/reference/types/prompt-input.md#in-a-request)`[]` | yes | The inputs a run is started with, which the prompt uses as `%%name%%`. Constraints: required (empty or whitespace-only strings are rejected). |
| `loom` | [`LoomConfigurationInput`](https://docs.maitento.com/reference/types/loom-configuration.md#in-a-request)`\| null` |  | Long-term memory for the interaction's agents. Null: no memory. |

## Example

```json
{
  "managerAgent": {
    "name": "...",
    "agent": {
      "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "version": 0
    },
    "externalOperationsMcp": [
      {}
    ],
    "externalOperationsOpenApi": [
      {}
    ],
    "loomId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "webAccess": {
      "search": false,
      "fetch": false
    }
  },
  "agents": [
    {
      "mode": "OneTime",
      "name": "...",
      "agent": {},
      "externalOperationsMcp": [],
      "externalOperationsOpenApi": [],
      "loomId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "webAccess": {}
    }
  ],
  "humanSettings": {
    "chatMode": "Excluded",
    "includeInVotes": false,
    "includeInSolutions": false
  },
  "maxDispatches": 0,
  "name": "...",
  "prompt": "...",
  "solutionSchema": "...",
  "systemPromptMode": "AppendToDefault",
  "systemPrompts": [
    "..."
  ],
  "durationWarningToAi": "00:05:00",
  "durationAutoTermination": "00:05:00",
  "contextSettings": {
    "mode": "None",
    "targetUtilization": 0,
    "toolResultTrimmingMode": "Never",
    "toolResultTrimmingMaxCycles": 0,
    "toolResultTrimmingStyle": "Placeholder",
    "toolResultTrimmingReplacement": "...",
    "compactionType": "SameAgent",
    "lowWaterUtilization": 0,
    "compactAtUtilization": 0,
    "compactKeepRecentTokens": 0,
    "compactTargetTokens": 0,
    "maxToolCallLoops": 0,
    "responseMaxTokens": 0,
    "compactMaxTokens": 0
  },
  "swarm": {
    "interactions": [
      "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
    ],
    "participants": [
      "..."
    ],
    "maxDepth": 0,
    "maxConcurrent": 0,
    "maxTotal": 0
  },
  "credentialStack": "...",
  "externalOperationsOpenApi": [
    {
      "pathBindings": [],
      "queryBindings": [],
      "name": "...",
      "externalOperationId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "externalOperationVersion": 0,
      "requestBindings": [],
      "authenticationHeader": {},
      "promptGuidance": "...",
      "isTerminal": false
    }
  ],
  "externalOperationsMcp": [
    {
      "name": "...",
      "externalOperationId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "externalOperationVersion": 0,
      "requestBindings": [],
      "authenticationHeader": {},
      "promptGuidance": "...",
      "isTerminal": false
    }
  ],
  "inputsConnectorAuthenticationSecret": [
    {
      "externalOperationId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "agentId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "defaultSecretId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "headerName": "...",
      "name": "...",
      "description": "...",
      "isRequired": false
    }
  ],
  "inputsConnectorBinding": [
    {
      "externalOperationId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "agentId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "target": "...",
      "defaultValue": "...",
      "type": "Request",
      "name": "...",
      "description": "...",
      "isRequired": false
    }
  ],
  "inputsPrompt": [
    {
      "dataType": "String",
      "name": "...",
      "description": "...",
      "isRequired": false
    }
  ],
  "loom": {
    "enabled": false,
    "scope": "Process",
    "scopeInput": "...",
    "shared": false,
    "recall": "Off",
    "weave": "Manual",
    "tapestryTokens": 0,
    "subjectInputs": [
      "..."
    ],
    "nightWeaving": false,
    "quietMinutes": 0,
    "weaverModel": "...",
    "vetModel": "...",
    "vetRecall": false,
    "seedFromLoomId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "readFromLoomIds": [
      "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
    ]
  }
}
```

## Where it's used

- [`interactions.createManaged`](https://docs.maitento.com/reference/api/interactions.md) (`POST /namespaces/{namespaceName}/interactions/managed`)