Skip to content

Coordinate Agents

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

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 to understand how lifecycle, invalidation, revocation, and audit messages move.