Manage Agents
Manage the lifecycle of Streamkap streaming agents: deploy, cancel with a savepoint, stop, resume, redeploy, plus drafts, config history, and rollback.
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). |
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.
Troubleshooting
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.
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.
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.
Related
- Build an Agent — the deploy wizard
- Agent Observability — traces, tool calls, and logs
- DLQ Operations — working with dead-letter topics