dragon.ai.agent.reasoning.tool_dispatcher.ToolDispatcher

class ToolDispatcher[source]

Bases: object

Drives the structured-output agentic loop for a single LLM engine.

Responsibilities:

  • Owns and manages any number of MCPServerClient connections (one per MCP server, keyed by user-supplied alias).

  • Combines local tool schemas (from ToolRegistry) with remote tool schemas (from each MCPServerClient) into a single tool list for the LLM.

  • Routes tool calls: {alias}__{tool_name} → the matching MCPServerClient; everything else → the local ToolRegistry.

Parameters

llm_engine:

An LLMProxy instance (or any object exposing a compatible .chat(messages, tools, json_schema, continue_final_message) method).

registry:

Registry of local BaseTool instances. Pass an empty ToolRegistry() if no local tools are needed.

Example

dispatcher = ToolDispatcher(llm_engine, registry)
await dispatcher.connect_mcp(url, token, alias="jupyter")
outputs = await dispatcher.chat(messages)
await dispatcher.close_mcp()
__init__(llm_engine, registry, approval_filter=None, max_tool_call_iterations: int = 20, context_manager=None) → None [source]

Methods

__init__(llm_engine, registry[, ...])

chat(prompts, **dispatch_ctx)

Run the structured-output agentic tool-calling loop.

close_mcp([alias])

Close one or all MCP connections.

connect_mcp(url, token, alias, *[, ...])

Connect to an MCP server and register it under alias.
__init__(llm_engine, registry, approval_filter=None, max_tool_call_iterations: int = 20, context_manager=None) → None [source]
async connect_mcp(url: str , token: str , alias: str , *, max_retries: int = 3, retry_delay: float = 0.5, timeout: float = 5.0) → None [source]

Connect to an MCP server and register it under alias.

Parameters:

  • url – MCP server URL.

  • token – Authentication token.

  • alias – Short unique label (e.g. "jupyter"). Used as the routing prefix: tools from this server will be named {alias}__{tool_name}.

  • max_retries – Number of connection attempts before raising ConnectionError. Defaults to 3.

  • retry_delay – Seconds to wait between retry attempts. Defaults to 0.5.

  • timeout – Per-attempt connection timeout in seconds. Defaults to 5.0.

Raises:
async close_mcp(alias: str | None = None) → None [source]

Close one or all MCP connections.

Parameters:

alias – If given, close only that connection. If None (default), close all connections.

async chat(prompts: List [Dict [str , Any ]], **dispatch_ctx) → List [List [str ]][source]

Run the structured-output agentic tool-calling loop.

Builds a combined tool list from the ToolRegistry and all connected MCPServerClient instances, then iterates up to max_tool_call_iterations times. On each iteration the LLM either requests one or more tool calls or signals a final answer. Tool calls are dispatched to the correct backend, and the results are appended to the conversation. Once the LLM signals final_answer a second, unstructured call produces the natural-language response.

Parameters

prompts:

Conversation messages in OpenAI chat format (list of message dicts).

**dispatch_ctx:

DDict context forwarded from _invoke_llm_with_tools: ddict, task_id, agent_id, dispatch_id. When hitl_queue is also present and self._approval_filter is set, the HITL approval gate is active. Per-event keys (LLM_EVENT_KEY, TOOL_EVENT_KEY, HITL_EVENT_KEY) are written to DDict in real time using these context values.

Returns

list[list[str]]

List of conversation turns added after the initial prompt.