---
title: "Coordinate Agents"
url: "https://docs.caracal.run/architecture/delegation-flow/"
markdown_url: "https://docs.caracal.run/markdown/architecture/delegation-flow.md"
description: "How agent sessions, delegation edges, and invocation lifecycle move through Coordinator."
page_type: "architecture"
concepts: []
requires: []
---

# Coordinate Agents

Canonical URL: https://docs.caracal.run/architecture/delegation-flow/
Markdown URL: https://docs.caracal.run/markdown/architecture/delegation-flow.md
Description: How agent sessions, delegation edges, and invocation lifecycle move through Coordinator.
Page type: architecture
Concepts: none
Requires: none

---

Coordinator owns agent runtime state. It records agent sessions, service leases, invocation lifecycle, and delegation edges that STS later uses to validate delegated exchanges.

## Flow

```mermaid
sequenceDiagram
  participant SDK as Agent SDK
  participant Coord as Coordinator
  participant PG as Postgres
  participant Redis as Redis Streams
  participant STS
  SDK->>Coord: create or update agent session
  Coord->>PG: persist session and leases
  Coord->>Redis: publish caracal.agents.lifecycle
  SDK->>Coord: create delegation edge
  Coord->>PG: persist edge and graph epoch
  Coord->>Redis: publish delegation invalidation
  SDK->>STS: exchange with agent_session_id/delegation_edge_id
  STS->>PG: validate session, edge, constraints, and graph state
```

## Coordinator State

| State | Purpose |
| --- | --- |
| `agent_sessions` | Agent session tree, parent-child relationships, status, leases, and root subject session. |
| `agent_services` | Service agents and heartbeat health. |
| `delegation_edges` | Source/target sessions, resource/scope bounds, expiry, constraints, and status. |
| `agent_invocations` | Invocation lifecycle and deadline tracking. |
| `delegation_graph_epochs` | Graph invalidation and traversal consistency. |
| `caracal_outbox` | Durable event publication for Coordinator-produced topics. |

## Event Topics

| Topic | Meaning |
| --- | --- |
| `caracal.agents.lifecycle` | Agent session lifecycle. |
| `caracal.invocations.lifecycle` | Invocation lifecycle. |
| `caracal.delegations.invalidate` | Delegation graph invalidation. |
| `caracal.sessions.revoke` | Session, agent, and delegation revocation propagation. |

## Operator Boundaries

Human operators use Console `agent session` and `delegation` views. Automation uses Coordinator API/Admin SDK surfaces. Top-level `caracal` runtime commands do not manage agent sessions or delegation.

## Next Step

Use [Propagate Events](/architecture/event-streams/) to understand how lifecycle, invalidation, revocation, and audit messages move.

## Related Pages

- [Coordinate Agent State](/services/coordinator/)
- [Agent Delegation](/concepts/delegation/)
- [Manage Agents and Delegation](/runtime-console/agents/)