> ## Documentation Index > Fetch the complete documentation index at: https://docs.komodor.com/llms.txt > Use this file to discover all available pages before exploring further. # Manage a deployed agent > Operate a live agent — enable and disable it, edit its configuration, manage its token and labels, archive it, and read its activity. Once an agent is registered it becomes something you operate rather than something you build. The Komodor Agentic Operation Platform (KAOP) keeps every lever for a live agent in one place: whether its triggers fire, what it is configured to do, which secrets and roles it holds, and the full record of what it has done. This page covers each of those, and where to find them. ## Where an agent lives **Fleet** is the agent list. Opening an agent gives you its detail view, which is both the control panel and the evidence view for that agent. | Surface | What it is for | | ---------------------- | ---------------------------------------------------------------------------------------------------- | | **Fleet** | Every agent, its online state, and its recent behavior | | An agent's detail view | Configuration, permissions, secrets, replicas, versions, and run history for one agent | | **Settings → Agents** | The account-wide table — every registered agent, its roles, its worker token, and its replica counts | ## Enable and disable A newly registered agent is **enabled**. Disabling it is the switch you reach for when an agent is misbehaving and you want it to stop acting on its own without tearing anything down. From the agent's page, or `PATCH /api/v1/agents/{agent_id}/disable`. Its triggers no longer fire. The agent still runs when you invoke it manually and still answers in chat, so you can keep testing it while it is disabled. From the same place, or `PATCH /api/v1/agents/{agent_id}/enable`. A disabled agent stays disabled. Restarting its worker does not re-enable it — a heartbeat never overrides the decision you made, which is what stops a pod restart from quietly resuming scheduled work you had stopped on purpose. ## Edit it Editing reopens the same wizard steps you configured at create time, prefilled from the agent's current state, so you change configuration in the surface that already knows its shape. | Step | What you change | | --------------------------------- | -------------------------------------------------------- | | **Agent card** | Name and description | | **Agent instructions** | The agent's instructions and its advertised capabilities | | **Model** | The model and the credential it authenticates with | | **Integrations** | Which connected systems the agent may reach | | **MCP tools** | MCP servers and attached skills | | **Triggers** | Its schedules | | **Where it runs** and **Scaling** | Replica settings, for an agent you host yourself | How the edit lands depends on where the agent runs. For an agent Komodor hosts, the final step saves a named version and the agent redeploys. For an agent you run yourself, the final step generates the update command to apply on your side — configuration changes that live in your deployment do not take effect until you apply it. An agent deployed from the catalog offers no **Edit** at all — its behavior is sealed to the version you deployed, so the console does not present a control that would imply otherwise. What you still control is its connections and credentials, its triggers, its labels, its permissions, and — for an orchestrator — which specialists it may delegate to. See [Use specialized agents](/manage-your-agents/build/use-specialized-agents). ## Manage its permissions and secrets Two things define an agent's reach, and both are edited from the agent's detail view, where every change takes effect immediately: * **Permissions** — the roles the agent holds, which decide which platform APIs it may call. Every agent holds the standard agent role unless you narrow it. Narrowing an agent removes API access; it does not stop the agent running. * **Secrets** — which stored credentials the agent receives. Add or remove a binding per credential. See [Credentials & secrets](/manage-your-agents/build/credentials-secrets) and [Agent identity](/security-and-governance/identity-and-access/agent-identity). ## Manage its worker token A worker authenticates with a revocable token bound to its agent. The value is shown only once, when it is generated or rotated. | Action | Effect | | ------------ | --------------------------------------------------------------- | | **Generate** | Mint a token for an agent that has none | | **Rotate** | Issue a fresh token; the previous one stops working immediately | | **Revoke** | Cut the worker off entirely | You manage tokens from **Settings → Agents** or from the agent's panel in Fleet. Via the API, `POST /api/v1/agents/worker-token` creates or rotates one, `GET /api/v1/agents/{agent_id}/token` returns its status without ever returning the value, and `DELETE /api/v1/agents/{agent_id}/token` revokes it. Rotating a token stops the running worker's next call. Plan to restart the worker with the new value as part of the same change. ## Label it Labels are key/value metadata used to group and filter the fleet, and to select agents when granting roles. Manage them on the agent's **Metadata** tab, or through `PATCH /api/v1/agents/{agent_id}/labels`. Keys and values follow a Kubernetes-like syntax: 1–63 characters each, letters, digits, `.`, `_` and `-` only, starting and ending with a letter or digit. `team: sre`, `tier: production` and `category: incident-response` are all valid. A label you set that breaks those rules is rejected with a stated reason. A label a worker advertises in its own agent card that breaks them is dropped, rather than failing the worker's heartbeat — so a bad label never takes an agent offline. ## Read its activity An agent's detail view is where you find out what it has actually been doing. | Tab | What it shows | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Run history** | Every run, filterable by status. Open one for its full evidence trail | | **Run activity** | The agent's behavior over time — successful runs against errors, grouped by day or by version, with cost, average latency, error rate, and queue depth | | **Instances** | Each replica: whether it is busy or idle, its current run, its last heartbeat, and the cluster, namespace, and pod it runs in | | **Versions** | Each persisted generation of the agent's configuration, with the recorded difference between them | | **Skills & tools** | The skills attached to it, split into declared and discovered, plus the tools it advertises | | **Metadata** | Its labels and identifying detail | | **Permissions** | The roles it holds and the secrets it may receive | Two numbers on the **Instances** tab are worth knowing how to read. **Queued** is how many runs are waiting for a free worker, and **Oldest queued** is how long the longest-waiting one has been there. A rising pair means the agent is saturated — add replicas, or reduce what is starting runs. The instance list accumulates a row per worker process, so a long-lived agent has many offline entries from past restarts. Read the instance counts rather than the length of the list when you want to know how many replicas an agent actually has. For the evidence inside a single run, see [Runs & evidence](/manage-your-agents/run/runs-evidence). For fleet-wide behavior, see [Fleet health](/manage-your-agents/optimize/fleet-health). ## Exercise it by hand Two controls on the agent are for checking it rather than changing it: * **Run agent** invokes it once, now, with input you supply. The dialog offers a free-text **Prompt** or a structured **JSON input**, and opens in whichever suits the agent — an agent that declares an input schema opens in JSON mode with the fields prefilled, and lets you view the schema it expects. * The **self-check** asks the control plane to put a question to the worker and wait for its answer. A worker that is offline or unresponsive still resolves, as a failure with a reason, so this is the fastest way to separate "the agent is broken" from "the worker is not there". Both work while an agent is disabled, which is what makes disable-then-test a safe way to investigate a misbehaving agent. ## Archive it, then delete it Decommissioning is deliberately two steps. ### Archive Archiving retires an agent without destroying what it did. Its history stays readable, and the slot it occupied is freed — a workspace holds up to 60 active agents, and archived ones do not count toward that. Archive with `PATCH /api/v1/agents/{agent_id}/archive`, and unarchive to bring it back. Archiving is a control-plane state, not a shutdown. An agent you run yourself keeps running and keeps heartbeating until you stop its worker — stop it as part of the same change. ### Delete Delete is permanent, and it is only offered on an agent that is **already archived**. It removes the agent's record and revokes its worker token. For an agent you host yourself the worker must also be **offline** first; while it is still reporting in, the control offers no delete and says why. Recreating an agent under a name that already exists reuses the same agent rather than making a second one — it rotates the token and redeploys. That is how you re-provision an agent without consuming another slot, and it is usually what you want instead of delete-then-create. ## Next steps How to read what an agent did on a single run. The same questions asked across every agent at once. Change what starts a live agent. What the agent is costing you. ## Related topics - [Fleet health](/manage-your-agents/optimize/fleet-health.md) - [Deploy an agent](/manage-your-agents/build/deploy-an-agent.md) - [Skills](/manage-your-agents/build/skills.md) - [Integration groups](/manage-your-agents/build/integration-groups.md) - [Triggers & schedules](/manage-your-agents/build/triggers-schedules.md)