---
title: "Manage Agents and Delegation"
url: "https://docs.caracal.run/runtime-console/agents/"
markdown_url: "https://docs.caracal.run/markdown/runtime-console/agents.md"
description: "Inspect and manage agent sessions and delegation edges through the Console."
page_type: "reference"
concepts: []
requires: []
---

# Manage Agents and Delegation

Canonical URL: https://docs.caracal.run/runtime-console/agents/
Markdown URL: https://docs.caracal.run/markdown/runtime-console/agents.md
Description: Inspect and manage agent sessions and delegation edges through the Console.
Page type: reference
Concepts: none
Requires: none

---

Agent sessions and delegation operations are Console workflows backed by the Coordinator. They are not top-level runtime CLI commands.

## Requirements

| Input | Purpose |
| --- | --- |
| Coordinator endpoint | Automatic for local dev/stable; explicit only for cloud/custom deployments. |
| `CARACAL_COORDINATOR_TOKEN` or `CARACAL_COORDINATOR_TOKEN_FILE` | Coordinator authority for agent and delegation views. |
| Selected zone | Scope for agent session and delegation queries. |

For the default local stack, Console prefers the Coordinator token generated by `caracal up` so a purge/up cycle does not leave an old exported token in use.

## Agent Sessions

Open `agent session` with `r` to list agent sessions, inspect a session tree, suspend an active subtree, resume a suspended subtree, or terminate a session. Tree views show parent-child relationships so operators can understand inherited authority.

## Delegation

Open `delegation` with `g` to inspect active, inbound, and outbound delegation edges. Detail views show source and target sessions, resources, scope bounds, expiry, and traversal state.

Revoking a delegation edge ends the delegated authority immediately. Review outbound edges before terminating an agent session so dependent work can be stopped cleanly.

## Audit Correlation

Agent session IDs and delegation edge IDs appear in audit events. Use `audit` request tracing or `request trace` when you need the policy decision and diagnostic payload behind an allow or deny.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Agent session views are empty | Confirm the selected zone and that workloads are creating agent sessions through an SDK. |
| Coordinator token missing | Run `caracal up` locally or set `CARACAL_COORDINATOR_TOKEN_FILE` for a remote Coordinator. |
| Delegation revocation appears delayed | Confirm resource servers consume revocation state and reject revoked delegation anchors. |