Director

The Director is GNETiX's core orchestration service. It receives messages from all supported platforms, determines what actions to take using an LLM, dispatches tool calls to on-prem agents, and synthesizes a response for the user.

How It Works

Each incoming message triggers the following pipeline:

1. Gather MCP Capabilities

The Director loads all MCP tool definitions, resources, prompts, and resource templates from the database for the agents associated with the current conversation. These capabilities were persisted during agent discovery (when an agent connects and reports its MCP servers).

Tool definitions are converted to the OpenAI function-calling format and passed to the LLM as available tools.

2. Build the System Prompt

The system prompt is assembled from multiple sources:

• Base identity -- the Director's core instructions for how to behave
• Soul content -- organization-specific personality and context configured by admins
• Custom system prompt -- optional per-org override set in the LLM configuration tab
• Resource context -- static resources from MCP servers (documentation, reference data) injected as additional context
• Prompt templates -- MCP prompt definitions that provide structured interaction patterns
• Topic hints -- extracted from MCP server metadata to help the LLM understand its domain

3. Run the LLM Tool-Call Loop

The Director calls the LLM via LiteLLM using the organization's configured provider and API key. The loop runs for up to 10 iterations:

while iterations < 10:
    response = LLM(messages + tool_results)

    if response has tool_calls:
        dispatch each tool call to the owning agent via relay
        collect results
        append tool results to messages
        continue

    if response has text content:
        return text as final answer

Each tool call is dispatched to the specific agent that owns that tool, determined by the tool-to-agent mapping built during capability gathering.

4. Dispatch Tool Calls via Relay

Tool calls are sent to on-prem agents through the WebSocket relay. The relay maintains persistent connections to all registered agents. The Director sends a JSON-RPC request with the tool name and arguments, and the agent executes it against the appropriate MCP server.

5. Synthesize Response

Once the LLM produces a text response (or the iteration limit is reached), the Director returns the final answer to the calling connector, which delivers it to the user.

Extended Thinking

When enabled for an organization, the Director activates Claude's extended thinking capability. This gives the model a dedicated reasoning budget (5,000 tokens) before it produces its visible response, improving performance on complex multi-step problems.

Extended thinking can be toggled per-organization in the Org Settings > LLM tab.

Guardrails

The Director enforces guardrail policies at two points in the pipeline:

• Input guardrails -- checked before any LLM call. If the user's message violates the policy, the Director returns a rejection message without consuming LLM tokens.
• Output guardrails -- checked after the LLM produces its final response. If the response violates the policy, it is replaced with a safe fallback.

Guardrail policies are configured per-organization and support topic restrictions, content filtering, and custom rules.

RBAC and Tool Access

The Director respects role-based access control when building the tool set:

• Server-level access -- users can be granted or denied access to entire MCP servers
• Tool-level filtering -- only tools the current user is permitted to use are included in the LLM context

This ensures that even if an agent has many tools registered, each user only sees and can invoke the tools appropriate to their role.

Trace Emission

Every step of the Director pipeline emits trace events to the Pipeline Monitor. These events include:

Traces are streamed in real-time via WebSocket to the frontend Pipeline Monitor, giving operators full visibility into every message flowing through the system.