> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Launch agents, inspect them, cancel work, and archive

This page covers common agent lifecycle operations in the dashboard, with the [CLI](/quickstart), and over the API. CLI examples assume you have run `omnara login` and `omnara config select`; API examples use a [bearer token](/api/authentication):

```bash theme={null}
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](/agents/configuration), or from a [profile](/agents/configuration#profiles) 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**

```bash CLI theme={null}
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."
```

```bash REST theme={null}
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."
  }'
```

```typescript SDK theme={null}
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
```

> [!NOTE]
>
> Full schema and playground: [Create agent](/api-reference/endpoints/agents/create-agent).

**Dashboard**

Select your project in the project switcher and open **Agents → Profiles**. Click
**Launch** on an existing [profile](/agents/configuration#profiles) to start an agent
with its current config. Users with launch-only access use this path.

If your role can manage project resources, click **New agent** to define a new
profile. Enter a **Name**, configure it in **Builder** or **YAML**, then click
**Create & launch agent**. In the conversation view, use the composer to send its first task.

### 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:

```json theme={null}
{
  "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.

> [!NOTE]
>
> For full schemas and playground see: [List agents](/api-reference/endpoints/agents/list-agents) and [Get agent](/api-reference/endpoints/agents/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**

```bash CLI theme={null}
npx omnara agents cancel agt_v4qtrwz3jehcyd5n6a2bfgik7m
```

```bash REST theme={null}
curl -X POST "$BASE/agents/agt_v4qtrwz3jehcyd5n6a2bfgik7m/cancel" \
  -H "Authorization: Bearer $OMNARA_TOKEN"
```

```typescript SDK theme={null}
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.

> [!NOTE]
>
> Full schema and playground: [Cancel agent](/api-reference/endpoints/agents/cancel-agent).

**Dashboard**

While the agent is working, the composer shows **Stop agent** — click it. The button disappears when the agent is idle.

## 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**

```bash CLI theme={null}
npx omnara agents archive agt_v4qtrwz3jehcyd5n6a2bfgik7m
```

```bash REST theme={null}
curl -X POST "$BASE/agents/agt_v4qtrwz3jehcyd5n6a2bfgik7m/archive" \
  -H "Authorization: Bearer $OMNARA_TOKEN"
```

```typescript SDK theme={null}
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.

> [!NOTE]
>
> Full schema and playground: [Archive agent](/api-reference/endpoints/agents/archive-agent).

**Dashboard**

On the **Agents** page's **Instances** tab, open the agent's actions menu and click **Archive**.

There is no unarchive. Launch a new agent when you need to continue with fresh work.

## Next

> **[Agent configuration](/agents/configuration)**
>
> Define an agent's model, tools, permissions, and machines

> **[Sending input](/events/sending-input)**
>
> Send messages and change direction while an agent works


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.