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

# Manage Agents

> Deploy, cancel, stop, resume, and redeploy Streamkap streaming agents — including savepoint and Kafka offset behavior, drafts, config history, and the dead-letter topic

The **Agents** tab lists every agent in the project and is where you run the agent lifecycle. Managing agents requires the `write:agents` permission; read-only users can view the list but not act on it.

## The Agents List

Each row shows the agent, its input topic, tool count, output topic, status, and config version. Expand a row for a health glance, or open the row menu for actions.

* **Search** by name, topic, or tool.
* **Filter** by status: All, Running, Deploying, Failed, Stopped, or Drafts.
* **Bulk actions** (Cancel, Redeploy, Delete) apply to selected rows.

## Statuses

| Status         | Meaning                                             |
| -------------- | --------------------------------------------------- |
| **Draft**      | Saved but not deployed                              |
| **Deploying**  | Deployment in progress                              |
| **Running**    | Processing its input topic                          |
| **Cancelling** | Cancel in progress                                  |
| **Cancelled**  | Stopped by a cancel or stop                         |
| **Failed**     | The job failed — open the detail page for the error |

Cancelled and stopped agents both show the **Cancelled** status and appear under the **Stopped** filter. While an agent is Deploying or Cancelling, state-change actions are disabled until it settles.

## Lifecycle Actions

Cancel and stop differ in whether they keep a **savepoint**, which determines where processing resumes on the Kafka topic.

| Action                      | Available when     | Effect                                                                                                                                                                  |
| --------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Deploy**                  | Draft              | Deploys the agent for the first time.                                                                                                                                   |
| **Cancel (with savepoint)** | Running            | Stops gracefully and writes a savepoint, preserving the topic position.                                                                                                 |
| **Stop (no savepoint)**     | Running            | Stops immediately without a savepoint.                                                                                                                                  |
| **Resume from savepoint**   | Cancelled / Failed | Redeploys from the savepoint, continuing from the last processed offset. Only available when a savepoint exists: after **Cancel (with savepoint)**, not after **Stop**. |
| **Redeploy from earliest**  | Cancelled / Failed | Redeploys without a savepoint, reprocessing the topic from the earliest offset.                                                                                         |
| **Edit & Redeploy**         | Any deployed agent | Saves changes and redeploys. See the warning below.                                                                                                                     |
| **Delete**                  | Any                | Permanently removes the agent (requires typing a confirmation).                                                                                                         |

<Warning>
  **Editing and redeploying resets Kafka offsets.** Saving a change cancels the running job and redeploys without a savepoint, so the agent reprocesses from the earliest offset of its input topic. To preserve the position, **Cancel (with savepoint)** first, then **Resume from savepoint**.
</Warning>

<Note>
  Some secrets — such as the LLM key or an MCP token — come back **masked** when you edit an agent and don't round-trip. Leave a masked field blank to keep the stored value, or type a new value to replace it. Deploy is blocked if a required secret was cleared and not re-entered.
</Note>

## Drafts

Saving a draft (from the wizard) stores the configuration without deploying. Drafts show a **Draft** status and can be deployed from the list or the detail page once ready.

## Duplicate

Use **Duplicate** to clone an agent's configuration into a new one (its name is suffixed with `-copy`). The clone opens in the wizard pre-filled, so you can adjust and deploy it separately.

## Config History & Rollback

Every successful save is versioned (up to 50 versions per agent). From the agent detail or edit header, open **History** to view a past version and **roll back** to it with a note. A rollback creates a new version rather than overwriting history.

## Dead-Letter Topic

Records an agent can't process are routed to its dead-letter topic, `dlq.<output-topic>`. Records land there on output-schema mismatch, unparseable model output, tool errors, or exhausted LLM retries, with an error header describing why.

<Warning>
  Streamkap does not consume the dead-letter topic for you. **Set up your own Kafka consumer on `dlq.<output-topic>`** to catch failed records — otherwise failures can go unnoticed. See [DLQ Operations](/dlq-operations).
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="An agent went straight to Failed after deploy">
    Open the agent detail page for the error message. Common causes are an unavailable input topic, an unreachable tool endpoint, or an LLM connection whose key no longer works. Fix the configuration and redeploy.
  </Accordion>

  <Accordion title="Records are disappearing / output is empty">
    Check the dead-letter topic (`dlq.<output-topic>`). Records that fail output-schema validation or a tool call are routed there rather than to the output topic. Loosen or correct the output schema, or fix the failing tool.
  </Accordion>

  <Accordion title="Deploy is blocked on a masked secret">
    Editing masks stored secrets. If you cleared a required field (for example the LLM key), re-enter it before deploying, or leave it blank to keep the stored value.
  </Accordion>

  <Accordion title="Two agents can't share an output topic">
    An output topic can be written by only one agent. If you see a conflict, change the output topic on Step 4 of the wizard.
  </Accordion>
</AccordionGroup>

## Related

* [Build an Agent](/streaming-agents-build) — the deploy wizard
* [Agent Observability](/streaming-agents-observability) — traces, tool calls, and logs
* [DLQ Operations](/dlq-operations) — working with dead-letter topics