Module: Conductor Agent

class diskurs.conductor_agent.ConductorAgent

Bases: BaseAgent[ConductorPrompt], ConductorAgent

__init__(name, prompt, llm_client, topics, locked_fields, finalizer_name=None, supervisor=None, can_finalize_name=None, dispatcher=None, max_trials=5, max_dispatches=50, rules=None, fallback_to_llm=True, tools=None, tool_executor=None, init_prompt_arguments_with_longterm_memory=True)
Parameters:

  • name (str)

  • prompt (ConductorPrompt)

  • llm_client (LLMClient)

  • topics (list[str])

  • locked_fields (dict[str, Any] | None)

  • finalizer_name (str | None)

  • supervisor (str | None)

  • can_finalize_name (str | None)

  • dispatcher (ConversationDispatcher | None)

  • max_trials (int)

  • max_dispatches (int)

  • rules (List[RoutingRule] | None)

  • fallback_to_llm (bool)

  • tools (list[Any] | None)

  • tool_executor (Any | None)

  • init_prompt_arguments_with_longterm_memory (bool)

async add_routing_message_to_chat(conversation, next_agent)

Adds a routing message to the conversation chat history.

This method updates the prompt_argument with the next agent and adds a JSON message to the conversation history to ensure consistency. This creates a clear record of routing decisions in the conversation history.

Parameters:

  • conversation – The conversation to update

  • next_agent – The name of the next agent to route to

Returns:

The updated conversation with routing information

async can_finalize(conversation)

Determines if the conversation is ready to be finalized.

This method checks if the conversation has reached a state where it can be considered complete. It either: 1. Delegates the decision to another agent specified by can_finalize_name,

which should return a prompt_argument with a can_finalize property, or

  1. Uses the prompt’s own can_finalize method on the longterm memory

If we are using a function i.e. heuristics, this method evaluates the long-term memory of the conversation to decide whether it can be finalized.

If we are using an LLM i.e. agent based can_finalize, this method evaluates the chat history of the conversation to decide whether it can be finalized. This allows for free-form questions as observed in open chat.

Parameters:

conversation (Conversation) – The conversation to check for finalization

Returns:

True if the conversation can be finalized, False otherwise

Return type:

bool

can_finalize_name: str | None
async compute_tool_response(response)

Executes the tool calls in the response and returns the tool responses.

Parameters:

response (Conversation) – The conversation object containing the tool calls to execute.

Returns:

One or more ChatMessage objects containing the tool responses.

Return type:

list[ChatMessage]

classmethod create(name, **kwargs)
Parameters:

name (str)

Return type:

Self

evaluate_rules(conversation)

Evaluates all routing rules against the current conversation.

This method iterates through the configured routing rules and executes their condition functions against the provided conversation. It returns the target agent of the first rule that matches, or None if no rules match.

Exceptions in rule evaluation are caught and logged to prevent rule failures from crashing the routing process.

Parameters:

conversation (Conversation) – The conversation to evaluate against the rules.

Returns:

The name of the target agent if a rule matches, None otherwise.

Return type:

str | None

fail(conversation)

Handles conversation failure cases.

This method is called when a conversation cannot be successfully completed, such as when maximum dispatch attempts are exceeded or other failure conditions are met. It generates an appropriate failure response.

Parameters:

conversation (Conversation) – The conversation that has failed

Returns:

A dictionary containing the failure response data

Return type:

dict[str, Any]

async finalize(conversation)

Finalizes the conversation based on current routing configuration.

This method handles the finalization process for a conversation based on the agent’s configuration:

  1. If a supervisor is configured, routes the conversation to that agent

  2. If a finalizer_name is configured, publishes the conversation to that finalizer

  3. Otherwise, sets the final_result directly using the prompt’s finalize method

The method ensures that every conversation is properly concluded and that the appropriate finalization logic is applied.

Parameters:

conversation (Conversation) – The conversation to finalize

Return type:

None

finalizer_name: str | None
async generate_validated_response(conversation, message_type=MessageType.CONVERSATION)

Generates a validated response for the given conversation.

This method attempts to generate a valid response for the conversation by interacting with the LLM client and validating the response. It performs multiple trials if necessary, and handles tool calls and corrective messages.

Parameters:

  • conversation (Conversation) – The conversation object to generate a response for.

  • message_type (MessageType) – The type of message to render the user prompt as, defaults to MessageType.CONVERSATION.

Returns:

The updated conversation object with the validated response.

Return type:

Conversation

async handle_tool_call(conversation, response)

This method handles a tool call by executing the tool and updating the conversation with the tool response.

Parameters:

  • conversation – The conversation object to add the result to.

  • response – The response object containing the tool call to handle.

Returns:

The updated conversation object with the tool response.

async invoke(conversation, message_type=MessageType.CONVERSATION, reset_prompt=True)

Run the agent on a conversation.

This method processes the given conversation by invoking the agent’s logic. It takes a Conversation object representing the conversation and returns an updated Conversation object after processing.

Parameters:

  • conversation (Conversation) – The current state of the conversation, represented as a Conversation object

  • message_type – The type of message to use when rendering templates and processing the conversation

  • init_prompt – Whether to initialize the prompt before processing the conversation

Returns:

An updated Conversation object with the processed state.

Return type:

Conversation

name: str
async process_conversation(conversation)

Receives a conversation from the dispatcher, i.e. message bus, processes it and finally publishes a deep copy of the resulting conversation back to the dispatcher.

Parameters:

conversation (Conversation) – The conversation object to process.

Return type:

None

prompt: ConductorPrompt
register_dispatcher(dispatcher)

Register a dispatcher with the agent.

Parameters:

dispatcher (ConversationDispatcher) – The dispatcher to register

Return type:

None

register_tools(tools)

Register tools with the agent.

Parameters:

tools (list[Callable] | Callable) – A list of callables or a single callable to register as tools

Return type:

None

return_fail_validation_message(response)

Returns a fail validation message when max trials are exhausted.

Parameters:

response – The conversation to add the fail message to

Returns:

The updated conversation with the fail message

supervisor: str | None
property topics: list[str]
diskurs.conductor_agent.validate_finalization(finalizer_name, prompt, supervisor)