How to Configure Dispatch Rules

🚦 Dispatch

The dispatch provider is a pre-processing interceptor. Before the main agent loop runs, dispatch rules are evaluated in order. The first matching rule short-circuits the normal flow and produces its own response — no LLM call happens.

List and Enable Dispatch Rules

za agents capabilities dispatch-rules list
za agents capabilities dispatch-rules configure <source-name>

Configure Provider Settings

za agents capabilities dispatch-rules settings

Provider Configuration

Setting	Type	Default	Description
enabled	bool	true	Enable dispatch rule evaluation

How Dispatch Works

When a user sends a message, before the agent enters its LLM loop:

1. Each active dispatch rule checks if it matches the current conversation context (documents, filters, tags, custom context).
2. The first matching rule wins — it produces a response directly (as a streaming async generator), bypassing the LLM entirely.
3. If no rule matches, the normal agent flow proceeds.

This is useful for:

• Fast deterministic responses to common patterns (e.g., greetings, help commands)
• Context-driven routing (e.g., if a specific document type is selected, return a pre-built analysis)
• Guard rails that block certain request patterns before they reach the LLM

Writing Custom Dispatch Rules

The SDK ships with no built-in dispatch rules — this is a pure extension point. To create a dispatch rule, subclass DispatchRule:

from zav.agents_sdk.adapters.dispatch.dispatch_rule import DispatchRule
from zav.agents_sdk.domain.chat_message import ChatMessage, ChatMessageSender
from zav.agents_sdk.domain.conversation_context import ConversationContext


class GreetingDispatchRule(DispatchRule):
    source_name = "greeting_handler"
    enabled: bool = True

    def matches(self, conversation_context: ConversationContext) -> bool:
        # Check the last user message
        return False  # your matching logic here

    async def execute(self, conversation, conversation_context, emit):
        yield ChatMessage(
            sender=ChatMessageSender.BOT,
            content="Hello! How can I help you today?",
        )

Register the rule's factory with AgentDependencyRegistry so the CLI and runtime can discover it automatically.