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

<Tabs>
  <Tab title="API">
    <CodeGroup>
      ```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."
      ```

      ```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
      ```
    </CodeGroup>

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

  <Tab title="Dashboard">
    In your project, open **Agents** and click **New agent**. If your role can manage project resources, choose how to define the agent:

    * **From profile** — pick an existing [profile](/agents/configuration#profiles); the launch uses its current config.
    * **Builder** — a form for instruction, model, machine sources, tools, skills, and MCP servers, with a live YAML preview.
    * **YAML** — paste or write the config directly in the editor.

    Users with launch-only access can select **From profile** but cannot create a config with the Builder or YAML editor.

    Give the agent a **Name**, then click **Create & launch agent**. In the conversation view, use the composer to send its first task.
  </Tab>
</Tabs>

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

<Info>
  For full schemas and playground see: [List agents](/api-reference/endpoints/agents/list-agents) and [Get agent](/api-reference/endpoints/agents/get-agent).
</Info>

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

<Tabs>
  <Tab title="API">
    <CodeGroup>
      ```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' },
      })
      ```
    </CodeGroup>

    The response includes `affected: true` when work was canceled. `affected: false` means the agent was already idle, so the request is safe to repeat.

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

  <Tab title="Dashboard">
    While the agent is working, the composer shows **Stop agent** — click it. The button disappears when the agent is idle.
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="API">
    <CodeGroup>
      ```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' },
      })
      ```
    </CodeGroup>

    The response returns the agent with `state: "archived"`. Repeating the request is safe.

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

  <Tab title="Dashboard">
    On the **Agents** page, open the row's actions and click **Archive**.
  </Tab>
</Tabs>

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

## Next

<CardGroup cols={2}>
  <Card title="Agent configuration" icon="file-code" href="/agents/configuration">
    Define an agent's model, tools, permissions, and machines
  </Card>

  <Card title="Sending input" icon="paper-plane" href="/events/sending-input">
    Send messages and change direction while an agent works
  </Card>
</CardGroup>