omnara

Official

Overview Schema Source Related Servers Discussions Admin

Launch agent

agents_launch

Launch a durable Omnara agent from a pinned config or profile, atomically attaching integration tools, subscriptions, interaction handlers, and an initial text message in one call.

Instructions

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

Name	Required	Description
`name`	No	Agent name. Empty means the agent is unnamed; non-empty values use the ResourceName policy.
`orgID`	Yes	Organization ID (org_...).
`tools`	No	Additional 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.
`config`	No	Agent config ID (acfg_...).
`message`	No	Optional initial text message. Mutually exclusive with initial_input.
`profile`	No
`projectID`	Yes	Project ID (proj_...).
`config_source`	No	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.
`initial_input`	No	Initial 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.
`subscriptions`	No	Integration-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_handlers`	No	Additional 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.

Changed3 schema fields changedv0.1.4Oct 29, 2026

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."

Changed2 schema fields changedv0.1.2Oct 23, 2026

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
+}

Changed4 schema fields changedv0.1.1Oct 17, 2026
- 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_...)."
```
First observedOct 15, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Beyond the annotations (readOnly=false, openWorld=true, destructive=false), the description adds meaningful behavior: permissions required for the integration additions, atomic transaction semantics for the derived config and initial input, and precise idempotency-key/retry behavior ('retry body is not applied and integration references are not resolved again'). It omits the profile-launch path's behavior and doesn't characterize the response, but the core behavioral traits are disclosed.

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 main action and the optional additions. The phrasing is dense ('admitting an attributed initial text input in the same transaction') but every sentence carries useful information and there is no filler.

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

Completeness4/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 mutation with no output schema, the description covers the important non-schema facts: permissions, atomicity, idempotency-key retry semantics, and what gets added. The main gap is that launching from a profile is not mentioned, which leaves one of the three mutually exclusive launch modes unexplained.

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 schema already documents most parameters; the description adds permission context for tools/subscriptions/interaction_handlers and confirms initial_input is attributed and transactional. It does not resolve the key ambiguity of config vs. config_source vs. profile, leaving the most important parameter choice to the schema alone.

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?

It names a specific verb and resource (launch an agent) and enumerates the optional additions (tools, subscriptions, handlers, initial input) in one transaction. It does not clearly distinguish the three launch paths the schema allows (config, config_source, profile) — the opening line says 'from a pinned config,' which undersells the profile-based launch the schema permits — and it names no sibling.

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 useful prerequisites: 'Adding integration capabilities requires project management permission; launching an existing config requires agent operate permission.' However, there is no explicit when-to-use vs alternatives guidance (e.g., when to launch from a profile instead of a config, or how this differs from configs_create/profiles_create), so the usage context is only implied.

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

Deploy Server

Launch agent

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools