Package dev.agenor.core.dialogue

Interface ConversationManager

All Known Implementing Classes:
DefaultConversationManager
public interface ConversationManager
Manages dialogue conversations for an agent.

Provides high-level methods for initiating common interaction patterns and tracking ongoing conversations.

Since:
0.5.0

  • Method Details

    • request

      CompletableFuture<DialogueMessage> request(String targetAgentId, Object content, Duration timeout)
      Sends a request to another agent and waits for response.
      Parameters:
      targetAgentId - the agent to request from
      content - the request content
      timeout - maximum time to wait
      Returns:
      future containing the response

    • query

      CompletableFuture<DialogueMessage> query(String targetAgentId, Object query, Duration timeout)
      Sends a query to another agent and waits for information.
      Parameters:
      targetAgentId - the agent to query
      query - the query content
      timeout - maximum time to wait
      Returns:
      future containing the response

    • callForProposals

      CompletableFuture<List<DialogueMessage>> callForProposals(List<String> participants, Object taskSpec, Duration deadline)
      Initiates a call for proposals to multiple agents.
      Parameters:
      participants - list of agent IDs to send CFP to
      taskSpec - the task specification
      deadline - time limit for proposals
      Returns:
      future containing all received proposals

    • handleIncoming

      void handleIncoming(DialogueMessage message)
      Handles an incoming dialogue message.
      Parameters:
      message - the incoming message

    • reply

      CompletableFuture<Void> reply(DialogueMessage original, Performative performative, Object content)
      Sends a reply to a received message.
      Parameters:
      original - the message being replied to
      performative - the reply performative
      content - the reply content
      Returns:
      future completing when sent

    • getConversation

      Optional<Conversation> getConversation(String conversationId)
      Gets a conversation by ID.
      Parameters:
      conversationId - the conversation ID
      Returns:
      the conversation if found

    • getActiveConversations

      List<Conversation> getActiveConversations()
      Gets all active (non-terminal) conversations.
      Returns:
      list of active conversations

    • getConversationsWith

      List<Conversation> getConversationsWith(String agentId)
      Gets all conversations with a specific agent.
      Parameters:
      agentId - the agent ID
      Returns:
      list of conversations with that agent

    • cancel

      void cancel(String conversationId)
      Cancels an ongoing conversation.
      Parameters:
      conversationId - the conversation to cancel

    • getCommitmentTracker

      CommitmentTracker getCommitmentTracker()
      Returns the commitment tracker backing this manager.

      Commitments are created and advanced as a side effect of the messages flowing through a conversation, so the tracker is part of a manager's contract rather than an implementation detail: a caller holding only this interface must still be able to observe the promises its agent has made.

      Returns:
      the commitment tracker, never null
      Since:
      0.26.0

    • cleanup

      default int cleanup(Duration olderThan)
      Removes conversations that have reached a terminal state and have been inactive for longer than the given duration.

      Conversation state is retained after a dialogue ends so that it can still be inspected; without a periodic sweep the retained state grows for the whole lifetime of the agent. Implementations that do not accumulate state in memory (for example a store-backed manager with its own expiry) may leave this as the default no-op.

      Parameters:
      olderThan - retention window measured from the conversation's last activity; Duration.ZERO removes every terminated conversation
      Returns:
      the number of conversations removed
      Since:
      0.26.0

    • onMessage

      void onMessage(String conversationId, Consumer<DialogueMessage> handler)
      Registers a handler invoked for every message received in a specific conversation, including intermediate replies (e.g. AGREE) that do not resolve the future returned by request(String, Object, Duration).
      Parameters:
      conversationId - the conversation to observe
      handler - callback invoked for each incoming message in that conversation