Skip to main content
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

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

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

​
Troubleshooting

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