Skip to main content
Glama
Sign In

Omnara

by com.omnara
OverviewDiscussions(1)Admin

Launch agent

agents_launch

Launch from a pinned config, optionally adding agent-local integration tools, subscriptions and interaction handlers and admitting an attributed initial text input in the same transaction. Adding integration capabilities requires project management permission; launching an existing config requires agent operate permission. Reusing an idempotency key returns the current agent even if the retry body differs. The retry body is not applied and integration references are not resolved again.

Input Schema

NameRequiredDescriptionDefault
nameNoOptional agent name. Omit to inherit the profile name when present; send an empty string to leave the agent unnamed.
orgIDYesOrganization ID (org_...).
toolsNoAdditional integration tool entries (int__<integration-name>__<operation>) and optional list_interaction_handlers or set_interaction_handler tools for this agent. Other tool names are not accepted here. Existing config entries win unchanged. Requires project management permission. The derived config is created atomically with the agent and initial input; the profile is unchanged.
configNoAgent config ID (acfg_...).
messageNoOptional initial text message. Mutually exclusive with initial_input.
profileNo
projectIDYesProject ID (proj_...).
config_sourceNoAn agent config to compile. The source, YAML or JSON, as text or as a JSON object, is stored exactly as sent, so comments and formatting survive. Configs whose sources compile to the same definition share it, however their sources are formatted.
initial_inputNoInitial queued text input, committed atomically with the agent and any derived config. Mutually exclusive with message. Initial inline media is not supported; upload it through the agent input endpoint after launch.
subscriptionsNoIntegration-owned conversation subscriptions attached atomically with launch and initial input. Requires project management permission. Subscriptions alone preserve the pinned config. Launch replay never adds or restores subscriptions.
interaction_handlersNoAdditional integration interaction handlers, keyed by immutable integration name with empty object values. Slack and Discord handlers require an assigned conversation and accept empty runtime args. Adding a handler does not assign a conversation. Existing entries win unchanged. Requires project management permission.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / $defs / AgentConfigDefinitionGitCredentials / properties / read_only / description
      Previous value: -"Prevents pushing, even if the integration allows it."New value: +"Prevents pushing and opening or approving pull requests, even if the integration allows it."
  2. Changed2 schema fields changed
    • addedInput schema / properties / initial_input / properties / actor / description
      Added value: +"Optional external actor for API key authentication. User-authenticated requests must omit this field. Without it, the authenticated user or API key is the actor."
    • changedInput schema / properties / name / description
      Previous value: -"Agent name. Empty means the agent is unnamed; non-empty values use the ResourceName policy."New value: +"Optional agent name. Omit to inherit the profile name when present; send an empty string to leave the agent unnamed."
  3. Changed3 schema fields changed
    • removedInput schema / $defs / AgentConfigDefinition / properties / event_webhook
      Removed value: -{
-  "$ref": "#/$defs/AgentConfigDefinitionEventWebhook"
-}
    • removedInput schema / $defs / AgentConfigDefinitionEventWebhook
      Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "events": {
-      "items": {
-        "enum": [
-          "agent_input",
-          "model_output",
-          "tool_result",
-          "context_checkpoint",
-          "tool_call_update"
-        ]
-      },
-      "minItems": 1,
-      "type": "array",
-      "uniqueItems": true
-    },
-    "signing_secret_id": {
-      "minLength": 1,
-      "type": "string"
-    },
-    "url": {
-      "minLength": 1,
-      "type": "string"
-    }
-  },
-  "required": [
-    "url",
-    "events"
-  ],
-  "type": "object",
-  "x-go-type": "json.RawMessage"
-}
    • changedInput schema / properties / config_source / description
      Previous value: -"An agent config to compile. YAML sources are stored verbatim, so comments and formatting survive; JSON sources, as text or as an object, are stored canonicalized, so the same JSON definition always maps to the same config."New value: +"An agent config to compile. The source, YAML or JSON, as text or as a JSON object, is stored exactly as sent, so comments and formatting survive. Configs whose sources compile to the same definition share it, however their sources are formatted."
  4. Changed2 schema fields changed
    • addedInput schema / $defs / AgentConfigDefinitionGitCredentials / properties / read_only
      Added value: +{
+  "description": "Prevents pushing, even if the integration allows it.",
+  "type": "boolean"
+}
    • addedInput schema / $defs / AgentConfigDefinitionGitCredentials / properties / repository_ids
      Added value: +{
+  "description": "GitHub repository IDs the credentials can access. Defaults to every repository the installation can access.",
+  "items": {
+    "minimum": 1,
+    "type": "integer"
+  },
+  "maxItems": 500,
+  "minItems": 1,
+  "type": "array",
+  "uniqueItems": true
+}
  5. Changed4 schema fields changed
    • addedInput schema / properties / config / description
      Added value: +"Agent config ID (acfg_...)."
    • addedInput schema / properties / config_source / properties / source_format / description
      Added value: +"Format of source: yaml or json."
    • addedInput schema / properties / orgID / description
      Added value: +"Organization ID (org_...)."
    • addedInput schema / properties / projectID / description
      Added value: +"Project ID (proj_...)."
  6. Changed6 schema fields changed
    • addedInput schema / $defs / AgentConfigDefinitionModel / properties / context_window_tokens / description
      Added value: +"Context budget for input and output tokens. Triggers compaction when estimated input exceeds the remaining budget after output and safety reserves. The turn fails if compaction cannot make it fit."
    • addedInput schema / $defs / AgentConfigDefinitionModel / properties / context_window_tokens / maximum
      Added value: +2147483647
    • changedInput schema / $defs / AgentConfigDefinitionModel / properties / context_window_tokens / minimum
      Previous value: -1New value: +2
    • addedInput schema / $defs / AgentConfigDefinitionSubagentModel / properties / context_window_tokens / description
      Added value: +"Context budget for input and output tokens. Triggers compaction when estimated input exceeds the remaining budget after output and safety reserves. The turn fails if compaction cannot make it fit."
    • addedInput schema / $defs / AgentConfigDefinitionSubagentModel / properties / context_window_tokens / maximum
      Added value: +2147483647
    • changedInput schema / $defs / AgentConfigDefinitionSubagentModel / properties / context_window_tokens / minimum
      Previous value: -1New value: +2
  7. Changed37 schema fields changed
    • addedInput schema / $defs / AgentConfigDefinition
      Added value: +{
+  "additionalProperties": false,
+  "description": "An agent config as a JSON object. This schema is the source of truth for agent configs: the server compiles YAML and JSON configs against it.",
+  "properties": {
+    "event_webhook": {
+      "$ref": "#/$defs/AgentConfigDefinitionEventWebhook"
+    },
+    "git_credentials": {
+      "$ref": "#/$defs/AgentConfigDefinitionGitCredentials"
+    },
+    "instruction": {
+      "minLength": 1,
+      "pattern": "\\S",
+      "type": "string"
+    },
+    "interaction_handlers": {
+      "$ref": "#/$defs/AgentConfigDefinitionInteractionHandlers"
+    },
+    "machine_sources": {
+      "$ref": "#/$defs/AgentConfigDefinitionMachineSources"
+    },
+    "max_depth": {
+      "maximum": 8,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "max_subagents": {
+      "maximum": 2147483647,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "mcp": {
+      "$ref": "#/$defs/AgentConfigDefinitionMCPServers"
+    },
+    "memory_stores": {
+      "$ref": "#/$defs/AgentConfigDefinitionMemoryStores"
+    },
+    "model": {
+      "$ref": "#/$defs/AgentConfigDefinitionModel"
+    },
+    "skills": {
+      "$ref": "#/$defs/AgentConfigDefinitionSkills"
+    },
+    "subagents": {
+      "$ref": "#/$defs/AgentConfigDefinitionSubagents"
+    },
+    "tools": {
+      "$ref": "#/$defs/AgentConfigDefinitionTools"
+    },
+    "version": {
+      "enum": [
+        "v1"
+      ]
+    }
+  },
+  "required": [
+    "instruction",
+    "model"
+  ],
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionEventWebhook
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "events": {
+      "items": {
+        "enum": [
+          "agent_input",
+          "model_output",
+          "tool_result",
+          "context_checkpoint",
+          "tool_call_update"
+        ]
+      },
+      "minItems": 1,
+      "type": "array",
+      "uniqueItems": true
+    },
+    "signing_secret_id": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "url": {
+      "minLength": 1,
+      "type": "string"
+    }
+  },
+  "required": [
+    "url",
+    "events"
+  ],
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionGitCredentials
      Added value: +{
+  "additionalProperties": false,
+  "description": "Integration whose git credentials the agent's machines use.",
+  "properties": {
+    "integration": {
+      "pattern": "^[a-zA-Z][a-zA-Z0-9-]{0,31}$",
+      "type": "string"
+    }
+  },
+  "required": [
+    "integration"
+  ],
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionInteractionHandler
      Added value: +{
+  "additionalProperties": false,
+  "description": "Enables an integration's interaction handler. Takes no settings.",
+  "type": "object",
+  "x-go-type": "agentconfig.AgentConfigIntegrationCapabilitySource",
+  "x-go-type-import": {
+    "path": "github.com/omnara-ai/omnara/internal/agentconfig"
+  }
+}
    • addedInput schema / $defs / AgentConfigDefinitionInteractionHandlers
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "$ref": "#/$defs/AgentConfigDefinitionInteractionHandler"
+      },
+      "propertyNames": {
+        "pattern": "^[a-zA-Z][a-zA-Z0-9-]{0,31}$",
+        "type": "string"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Interaction handlers keyed by integration name.",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionMCPAuth
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "region": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "secret_id": {
+      "minLength": 1,
+      "pattern": "^sec_[a-z2-7]{26}$",
+      "type": "string"
+    },
+    "service": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "type": {
+      "enum": [
+        "bearer",
+        "oauth",
+        "sigv4"
+      ]
+    }
+  },
+  "required": [
+    "type",
+    "secret_id"
+  ],
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionMCPServer
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "auth": {
+      "$ref": "#/$defs/AgentConfigDefinitionMCPAuth"
+    },
+    "default_enabled": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "deferred": {
+      "type": "boolean"
+    },
+    "permission": {
+      "$ref": "#/$defs/AgentConfigDefinitionToolPermission"
+    },
+    "tools": {
+      "additionalProperties": {
+        "$ref": "#/$defs/AgentConfigDefinitionMCPTool"
+      },
+      "propertyNames": {
+        "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$",
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "url": {
+      "minLength": 1,
+      "type": "string"
+    }
+  },
+  "required": [
+    "url"
+  ],
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionMCPServers
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "$ref": "#/$defs/AgentConfigDefinitionMCPServer"
+      },
+      "propertyNames": {
+        "pattern": "^[a-zA-Z][a-zA-Z0-9-]{0,31}$",
+        "type": "string"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionMCPTool
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "deferred": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "enabled": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "permission": {
+      "$ref": "#/$defs/AgentConfigDefinitionToolPermission"
+    }
+  },
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionMachineSource
      Added value: +{
+  "additionalProperties": false,
+  "oneOf": [
+    {
+      "required": [
+        "machine_name"
+      ],
+      "type": "object"
+    },
+    {
+      "required": [
+        "machine_pool_name"
+      ],
+      "type": "object"
+    }
+  ],
+  "properties": {
+    "cwd": {
+      "maxLength": 4096,
+      "type": "string"
+    },
+    "delete_after_idle_minutes": {
+      "anyOf": [
+        {
+          "const": 0
+        },
+        {
+          "maximum": 2147483647,
+          "minimum": 5,
+          "type": "integer"
+        }
+      ]
+    },
+    "description": {
+      "maxLength": 4096,
+      "type": "string"
+    },
+    "env_overlay": {
+      "anyOf": [
+        {
+          "additionalProperties": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "propertyNames": {
+            "$ref": "#/$defs/EnvironmentVariableName"
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "initial_num_machines": {
+      "minimum": 0,
+      "type": "integer"
+    },
+    "machine_cpu": {
+      "maximum": 2147483647,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "machine_memory_mb": {
+      "maximum": 2147483647,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "machine_name": {
+      "$ref": "#/$defs/ResourceNameReference"
+    },
+    "machine_pool_name": {
+      "$ref": "#/$defs/ResourceNameReference"
+    },
+    "machine_provider_options_overlay": {
+      "anyOf": [
+        {
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "max_machines": {
+      "minimum": 0,
+      "type": "integer"
+    },
+    "secret_env_overlay": {
+      "anyOf": [
+        {
+          "additionalProperties": {
+            "anyOf": [
+              {
+                "pattern": "^sec_[a-z2-7]{26}$",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "propertyNames": {
+            "$ref": "#/$defs/EnvironmentVariableName"
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionMachineSources
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "$ref": "#/$defs/AgentConfigDefinitionMachineSource"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionMemoryStore
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "access": {
+      "enum": [
+        "read",
+        "read_write"
+      ],
+      "type": "string"
+    },
+    "name": {
+      "$ref": "#/$defs/MemoryStoreName"
+    }
+  },
+  "required": [
+    "name",
+    "access"
+  ],
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionMemoryStores
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "$ref": "#/$defs/AgentConfigDefinitionMemoryStore"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionModel
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "cache_retention": {
+      "enum": [
+        "none",
+        "short",
+        "long"
+      ]
+    },
+    "context_window_tokens": {
+      "minimum": 1,
+      "type": "integer"
+    },
+    "default_max_output_tokens": {
+      "minimum": 1,
+      "type": "integer"
+    },
+    "name": {
+      "$ref": "#/$defs/ResourceNameReference"
+    },
+    "provider_config": {
+      "$ref": "#/$defs/ResourceNameReference"
+    },
+    "reasoning": {
+      "additionalProperties": false,
+      "properties": {
+        "effort": {
+          "minLength": 1,
+          "pattern": "\\S",
+          "type": "string"
+        }
+      },
+      "required": [
+        "effort"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "provider_config",
+    "name"
+  ],
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionSkills
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "pattern": "^skl_[a-z2-7]{26}$",
+        "type": "string"
+      },
+      "type": "array",
+      "uniqueItems": true
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionSubagent
      Added value: +{
+  "additionalProperties": false,
+  "else": {
+    "not": {
+      "required": [
+        "profile"
+      ],
+      "type": "object"
+    }
+  },
+  "if": {
+    "properties": {
+      "type": {
+        "const": "profile"
+      }
+    },
+    "required": [
+      "type"
+    ],
+    "type": "object"
+  },
+  "properties": {
+    "archive_after_idle_minutes": {
+      "maximum": 2147483647,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "description": {
+      "type": "string"
+    },
+    "instruction": {
+      "$ref": "#/$defs/AgentConfigDefinitionSubagentInstruction"
+    },
+    "max_instances": {
+      "maximum": 2147483647,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "model": {
+      "$ref": "#/$defs/AgentConfigDefinitionSubagentModel"
+    },
+    "profile": {
+      "$ref": "#/$defs/ResourceNameReference"
+    },
+    "type": {
+      "enum": [
+        "profile",
+        "self"
+      ]
+    }
+  },
+  "required": [
+    "type"
+  ],
+  "then": {
+    "required": [
+      "profile"
+    ]
+  },
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionSubagentInstruction
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "append": {
+      "type": "string"
+    }
+  },
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionSubagentModel
      Added value: +{
+  "additionalProperties": false,
+  "dependentRequired": {
+    "name": [
+      "provider_config"
+    ],
+    "provider_config": [
+      "name"
+    ]
+  },
+  "properties": {
+    "cache_retention": {
+      "enum": [
+        "none",
+        "short",
+        "long"
+      ]
+    },
+    "context_window_tokens": {
+      "minimum": 1,
+      "type": "integer"
+    },
+    "default_max_output_tokens": {
+      "minimum": 1,
+      "type": "integer"
+    },
+    "name": {
+      "$ref": "#/$defs/ResourceNameReference"
+    },
+    "provider_config": {
+      "$ref": "#/$defs/ResourceNameReference"
+    },
+    "reasoning": {
+      "additionalProperties": false,
+      "properties": {
+        "effort": {
+          "minLength": 1,
+          "pattern": "\\S",
+          "type": "string"
+        }
+      },
+      "required": [
+        "effort"
+      ],
+      "type": "object"
+    }
+  },
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionSubagents
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "$ref": "#/$defs/AgentConfigDefinitionSubagent"
+      },
+      "propertyNames": {
+        "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
+        "type": "string"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionTool
      Added value: +{
+  "additionalProperties": false,
+  "else": {
+    "not": {
+      "anyOf": [
+        {
+          "required": [
+            "description"
+          ],
+          "type": "object"
+        },
+        {
+          "required": [
+            "input_schema"
+          ],
+          "type": "object"
+        }
+      ]
+    }
+  },
+  "if": {
+    "properties": {
+      "type": {
+        "const": "custom"
+      }
+    },
+    "required": [
+      "type"
+    ],
+    "type": "object"
+  },
+  "properties": {
+    "deferred": {
+      "type": "boolean"
+    },
+    "description": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "enabled": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "input_schema": {
+      "$ref": "#/$defs/AgentConfigDefinitionToolInputSchema"
+    },
+    "permission": {
+      "$ref": "#/$defs/AgentConfigDefinitionToolPermission"
+    },
+    "type": {
+      "enum": [
+        "built_in",
+        "custom"
+      ]
+    }
+  },
+  "then": {
+    "required": [
+      "description",
+      "input_schema"
+    ]
+  },
+  "type": "object",
+  "x-go-type": "agentconfig.AgentConfigToolSource",
+  "x-go-type-import": {
+    "path": "github.com/omnara-ai/omnara/internal/agentconfig"
+  }
+}
    • addedInput schema / $defs / AgentConfigDefinitionToolInputSchema
      Added value: +{
+  "additionalProperties": true,
+  "description": "A JSON Schema for the tool's input. Keywords beyond those listed, such as additionalProperties or description, are allowed.",
+  "properties": {
+    "properties": {
+      "additionalProperties": {
+        "type": "object"
+      },
+      "type": "object"
+    },
+    "required": {
+      "items": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "type": {
+      "const": "object"
+    }
+  },
+  "required": [
+    "type"
+  ],
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionToolPermission
      Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "mode": {
+      "minLength": 1,
+      "pattern": "\\S",
+      "type": "string"
+    },
+    "parameters": {
+      "type": "object"
+    }
+  },
+  "required": [
+    "mode"
+  ],
+  "type": "object",
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigDefinitionTools
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "$ref": "#/$defs/AgentConfigDefinitionTool"
+      },
+      "propertyNames": {
+        "allOf": [
+          {
+            "anyOf": [
+              {
+                "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$",
+                "type": "string"
+              },
+              {
+                "maxLength": 64,
+                "pattern": "^int__[a-zA-Z][a-zA-Z0-9-]{0,31}__[a-zA-Z][a-zA-Z0-9_-]*$",
+                "type": "string"
+              }
+            ]
+          },
+          {
+            "not": {
+              "pattern": "^mcp__",
+              "type": "string"
+            }
+          }
+        ]
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "x-go-type": "json.RawMessage"
+}
    • addedInput schema / $defs / AgentConfigSourceInput
      Added value: +{
+  "anyOf": [
+    {
+      "minLength": 1,
+      "type": "string"
+    },
+    {
+      "$ref": "#/$defs/AgentConfigDefinition"
+    }
+  ],
+  "description": "Agent config source as YAML or JSON text, or, with source_format json, as a JSON object.",
+  "x-go-type": "json.RawMessage"
+}
    • removedInput schema / $defs / ConfigAgentToolInputSchema
      Removed value: -{
-  "properties": {
-    "properties": {
-      "additionalProperties": {
-        "type": "object"
-      },
-      "type": "object"
-    },
-    "required": {
-      "items": {
-        "minLength": 1,
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "type": {
-      "const": "object"
-    }
-  },
-  "required": [
-    "type"
-  ],
-  "type": "object"
-}
    • removedInput schema / $defs / ConfigIntegrationCapabilitySource
      Removed value: -{
-  "additionalProperties": false,
-  "type": "object",
-  "x-go-type": "agentconfig.AgentConfigIntegrationCapabilitySource",
-  "x-go-type-import": {
-    "path": "github.com/omnara-ai/omnara/internal/agentconfig"
-  }
-}
    • removedInput schema / $defs / ConfigToolPermissionSelection
      Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "mode": {
-      "minLength": 1,
-      "pattern": "\\S",
-      "type": "string"
-    },
-    "parameters": {
-      "type": "object"
-    }
-  },
-  "required": [
-    "mode"
-  ],
-  "type": "object"
-}
    • removedInput schema / $defs / ConfigToolSource
      Removed value: -{
-  "additionalProperties": false,
-  "else": {
-    "not": {
-      "anyOf": [
-        {
-          "required": [
-            "description"
-          ],
-          "type": "object"
-        },
-        {
-          "required": [
-            "input_schema"
-          ],
-          "type": "object"
-        }
-      ]
-    }
-  },
-  "if": {
-    "properties": {
-      "type": {
-        "const": "custom"
-      }
-    },
-    "required": [
-      "type"
-    ],
-    "type": "object"
-  },
-  "properties": {
-    "deferred": {
-      "type": "boolean"
-    },
-    "description": {
-      "minLength": 1,
-      "type": "string"
-    },
-    "enabled": {
-      "anyOf": [
-        {
-          "type": "boolean"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
-    "input_schema": {
-      "$ref": "#/$defs/ConfigAgentToolInputSchema"
-    },
-    "permission": {
-      "$ref": "#/$defs/ConfigToolPermissionSelection"
-    },
-    "type": {
-      "enum": [
-        "built_in",
-        "custom"
-      ]
-    }
-  },
-  "then": {
-    "required": [
-      "description",
-      "input_schema"
-    ]
-  },
-  "type": "object",
-  "x-go-type": "agentconfig.AgentConfigToolSource",
-  "x-go-type-import": {
-    "path": "github.com/omnara-ai/omnara/internal/agentconfig"
-  }
-}
    • addedInput schema / $defs / EnvironmentVariableName
      Added value: +{
+  "minLength": 1,
+  "pattern": "^[^=\\x00]+$",
+  "type": "string"
+}
    • addedInput schema / $defs / MemoryStoreName
      Added value: +{
+  "description": "Machine-readable memory store identifier consisting of lowercase ASCII segments separated by single hyphens.",
+  "maxLength": 64,
+  "minLength": 1,
+  "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+  "type": "string"
+}
    • addedInput schema / $defs / ResourceNameReference
      Added value: +{
+  "description": "Name of an existing resource, resolved when the config is compiled.",
+  "maxLength": 64,
+  "minLength": 1,
+  "pattern": "^\\S(?:.*\\S)?$",
+  "type": "string"
+}
    • addedInput schema / anyOf
      Added value: +[
+  {
+    "required": [
+      "profile"
+    ]
+  },
+  {
+    "required": [
+      "config"
+    ]
+  },
+  {
+    "required": [
+      "config_source"
+    ]
+  }
+]
    • addedInput schema / not
      Added value: +{
+  "required": [
+    "config",
+    "config_source"
+  ]
+}
    • addedInput schema / properties / config_source
      Added value: +{
+  "additionalProperties": false,
+  "description": "An agent config to compile. YAML sources are stored verbatim, so comments and formatting survive; JSON sources, as text or as an object, are stored canonicalized, so the same JSON definition always maps to the same config.",
+  "properties": {
+    "source": {
+      "$ref": "#/$defs/AgentConfigSourceInput"
+    },
+    "source_format": {
+      "enum": [
+        "yaml",
+        "json"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "source",
+    "source_format"
+  ],
+  "type": "object"
+}
    • changedInput schema / properties / interaction_handlers / additionalProperties / $ref
      Previous value: -"#/$defs/ConfigIntegrationCapabilitySource"New value: +"#/$defs/AgentConfigDefinitionInteractionHandler"
    • changedInput schema / properties / tools / additionalProperties / $ref
      Previous value: -"#/$defs/ConfigToolSource"New value: +"#/$defs/AgentConfigDefinitionTool"
    • changedInput schema / required
      Previous value: -[
-  "config",
-  "orgID",
-  "projectID"
-]New value: +[
+  "orgID",
+  "projectID"
+]
  8. First observed

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly=false, destructive=false, openWorld=true, so the safety profile is covered; the description adds genuinely new behavior: atomic commit of agent plus derived config plus initial input, the permission gates, and the idempotency-key replay rule that a differing retry body is ignored and integration references are not re-resolved. These are non-obvious semantics an agent cannot get from the schema. Slight tension exists with idempotentHint=false, which reads as implying repeated calls re-execute, though the keyed-retry behavior explains the refinement rather than contradicting the write nature of the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with the core action and the optional add-ons, then permissions, then retry semantics; nothing is padded. The first sentence is a long noun-piled construction ('admitting an attributed initial text input in the same transaction') that takes effort to parse, which costs a point, but overall it is dense rather than wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, deeply nested creation tool with no output schema, the description covers the transactional and permission dimensions well but omits the launch-mode selection (profile vs config vs config_source) and says nothing about what a successful launch yields beyond the retry case. The schema carries most of the parameter burden at 91% coverage, so the definition is workable but not fully self-sufficient for a complex create call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 91%, so the parameters are already well documented at 91% and the baseline of 3 applies. The description reinforces the composite semantics ('in the same transaction', 'attributed initial text input') but adds little syntax or constraint detail beyond what the schema already states about tools, subscriptions, interaction_handlers, message versus initial_input, and name inheritance. It also references an idempotency key that does not appear among the 11 declared parameters, leaving that mechanism's location unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence uses a specific verb (launch) and resource (agent) and enumerates what can be bundled into the launch (agent-local integration tools, subscriptions, interaction handlers, initial text input). It is clearly differentiated from siblings like agents_update or agents_input because it is the creation path. It loses a point for saying only 'from a pinned config' when the schema also permits launching via 'profile' or 'config_source', leaving the three launch modes undifferentiated in prose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives permission context (project management permission for integration capabilities, agent operate permission for launching an existing config) which helps an agent predict failures, and it implicitly signals this is the create path rather than an update. However, there is no explicit when-to-use versus when-not-to-use guidance, no mention of when to prefer launching from a profile versus a config versus inline source, and no pointer to any sibling for related follow-up work.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Omnara toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources