Skip to main content
This page covers common agent lifecycle operations in the dashboard, with the CLI, and over the API. CLI examples assume you have run omnara login and omnara config select; API examples use a bearer token:

​
Launch an agent

Create an agent from a config, or from a profile if you want the launch tied to a named template.
Full schema and playground: Create agent.

​
Attach integrations and an initial input atomically

The create-agent API accepts tools and interaction_handlers alongside the pinned config. They use the same names and capability selections as ordinary config authoring. Derivation adds missing entries and preserves existing entries as a whole, including explicit disabled tools. The base’s pinned model and other identities are retained. When profile is supplied, the base config must be its current config or a historical version of that profile. The separate subscriptions array attaches integration-owned conversations to the new agent, using integration_id and conversation. The integration determines which activity is forwarded. Subscriptions alone leave the pinned config unchanged. Ordinary API attachments do not establish sending context. The shipped integration tools require context assigned by a provider or scheduled launch. Their interaction handlers use that same assigned conversation. Adding tools, handlers or subscriptions requires project management permission; operating an existing config requires only agent operate permission. Use initial_input instead of message to supply text blocks with an attributed actor. This example subscribes a new agent to events from one PR without changing its config:
User-authenticated requests omit actor; API keys may supply an external actor. Initial input supports queued text blocks; send inline media through the agent input endpoint after launch. The agent, subscriptions, initial input and any derived config commit together. A failure leaves none of those writes. The profile stays unchanged. Supply an Idempotency-Key to make retries safe: the first success returns 201 with the launch envelope, and reusing the key within the project returns 200 with only the current agent. The retry body is not applied, even if it has changed or an integration reference has since been deleted.

​
Find agents

The project’s Agents page opens on Profiles; switch to the Instances tab to list active agents, and click one to open its conversation. omnara agents list and the API return active agents newest first; fetch one by ID with omnara agents get {agent-id}. Both responses include each agent’s activity, whose state is running, waiting_on_interaction, idle, or archived. Archived agents are omitted from the list but remain retrievable by ID.
For full schemas and playground see: List agents and Get agent.

​
Stop current work

Stopping cancels the agent’s current turn, pending tool calls, and open interactions. The agent and its conversation remain available; the next input starts a new turn.
The response includes affected: true when work was canceled. affected: false means the agent was already idle, so the request is safe to repeat.
Full schema and playground: Cancel agent.

​
Archive an agent

Archiving retires an agent. It deletes its integration subscriptions, stops current work, drops queued inputs, releases machine bindings, and deletes pooled machines created for the agent. The agent leaves active listings, but its event history remains available by ID. Machines you connected yourself, configs, and profiles are not deleted.
The response returns the agent with state: "archived". Repeating the request is safe.
Full schema and playground: Archive agent.
There is no unarchive. Launch a new agent when you need to continue with fresh work.

​
Next

Agent configuration

Define an agent’s model, tools, permissions, and machines

Sending input

Send messages and change direction while an agent works