Agents

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:

export OMNARA_API="https://api.omnara.com/v1"
export BASE="$OMNARA_API/orgs/$ORG/projects/$PROJ"

Launch an agent

Create an agent from a config, or from a profile if you want the launch tied to a named template.

API
Dashboard

npx omnara agents launch \
  --config acfg_mv4qtrwz3jehcyd5n6a2bfgik7 \
  --name "Weekly report agent" \
  --message "Draft release notes for the changes merged this week."

curl "$BASE/agents" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-weekly-report-2026-08-03" \
  -d '{
    "config": "acfg_mv4qtrwz3jehcyd5n6a2bfgik7",
    "name": "Weekly report agent",
    "message": "Draft release notes for the changes merged this week."
  }'

const launched = await sdk.createAgent({
  client,
  path: { orgID, projectID },
  headers: { 'Idempotency-Key': 'launch-weekly-report-2026-08-03' },
  body: {
    config: 'acfg_mv4qtrwz3jehcyd5n6a2bfgik7',
    name: 'Weekly report agent',
    message: 'Draft release notes for the changes merged this week.',
  },
})
const agentID = launched.data.agent.id

Full schema and playground: Create agent.

Find agents

The project’s Agents page lists active agents; 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}. 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.

API
Dashboard

npx omnara agents cancel agt_v4qtrwz3jehcyd5n6a2bfgik7m

curl -X POST "$BASE/agents/agt_v4qtrwz3jehcyd5n6a2bfgik7m/cancel" \
  -H "Authorization: Bearer $OMNARA_TOKEN"

const canceled = await sdk.cancelAgent({
  client,
  path: { orgID, projectID, agentID: 'agt_v4qtrwz3jehcyd5n6a2bfgik7m' },
})

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

API
Dashboard

npx omnara agents archive agt_v4qtrwz3jehcyd5n6a2bfgik7m

curl -X POST "$BASE/agents/agt_v4qtrwz3jehcyd5n6a2bfgik7m/archive" \
  -H "Authorization: Bearer $OMNARA_TOKEN"

const archived = await sdk.archiveAgent({
  client,
  path: { orgID, projectID, agentID: 'agt_v4qtrwz3jehcyd5n6a2bfgik7m' },
})

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.

Agent configuration

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

Sending input

Send messages and change direction while an agent works

Get started

Inputs & events

Tools

Machines

Organization

Integrations

Examples

Agents

Launch an agent

Find agents

Stop current work

Archive an agent

Next

Agent configuration

Sending input

​Launch an agent

​Find agents

​Stop current work

​Archive an agent

​Next

Agent configuration

Sending input

Launch an agent

Find agents

Stop current work

Archive an agent

Next