Package dev.agenor.core.directory

Interface AgentRegistry

All Known Subinterfaces:
AgentDirectory
All Known Implementing Classes:
CompositeAgentDirectory, InMemoryAgentDirectory, JdbcAgentRegistry
public interface AgentRegistry
Capability for registering, unregistering, and updating agents in the directory.

All backends that store agent state must implement this interface. Backends that only answer queries (e.g., a read-replica) may implement AgentDiscovery without implementing this interface.

Since:
0.20.0
See Also:

  • Method Details

    • register

      CompletableFuture<Void> register(AgentDescriptor descriptor)
      Registers an agent in the directory, making it discoverable.

      If an agent with the same ID is already registered, the implementation should update the existing entry.

      Parameters:
      descriptor - the agent descriptor, must not be null
      Returns:
      a future that completes when registration succeeds
      Throws:
      NullPointerException - if descriptor is null

    • unregister

      CompletableFuture<Void> unregister(String agentId)
      Removes an agent from the directory.

      If the agent is not registered the call is a no-op.

      Parameters:
      agentId - the unique agent identifier, must not be null
      Returns:
      a future that completes when unregistration succeeds
      Throws:
      NullPointerException - if agentId is null

    • updateStatus

      CompletableFuture<Void> updateStatus(String agentId, AgentStatus status)
      Updates the status of a registered agent.

      Implementations should also update the agent's lastSeen timestamp. If the agent is not registered the behaviour is implementation-defined (log-and-ignore is recommended for leniency).

      Parameters:
      agentId - the unique agent identifier, must not be null
      status - the new status, must not be null
      Returns:
      a future that completes when the update succeeds
      Throws:
      NullPointerException - if agentId or status is null