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. Send at least one of profile, config (an existing config ID), or config_source (a config to compile and save during the launch, with the same source and source_format fields as creating a config), and not both config and config_source:

profile alone runs the profile’s current config.
config or config_source alone runs that config.
profile with config or config_source attributes the agent to the profile but runs the given config, which need not be one of the profile’s versions.

The CLI takes --profile, and --config, --file, or --source for the config.

API
Dashboard

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

# or run a profile's current config:
npx omnara agents launch \
  --profile aprf_3jehcyd5n6a2bfgik7mv4qtrwz \
  --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.

Attach integrations and an initial input atomically

The create-agent API accepts tools and interaction_handlers alongside profile, config, or config_source. They extend the config the launch would otherwise run, and the result is saved as a new 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. 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:

{
  "config": "acfg_mv4qtrwz3jehcyd5n6a2bfgik7",
  "subscriptions": [{
    "integration_id": "YOUR_GITHUB_INTEGRATION_ID",
    "conversation": {"repository_id": 123456, "pull_request": 42}
  }],
  "initial_input": {
    "content_blocks": [{"type": "text", "text": "Track updates to pull request 42."}],
    "actor": {"provider_tenant_id": "review-service", "provider_user_id": "customer-7"}
  }
}

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.

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

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

Examples

Inputs & events

Tools

Machines

Organization

Integrations

Agents

Launch an agent

Attach integrations and an initial input atomically

Find agents

Stop current work

Archive an agent

Next

Agent configuration

Sending input

​Launch an agent

​Attach integrations and an initial input atomically

​Find agents

​Stop current work

​Archive an agent

​Next

Agent configuration

Sending input

Launch an agent

Attach integrations and an initial input atomically

Find agents

Stop current work

Archive an agent

Next