Dispatch Agent

Add Dispatch Agent when instructions select a named specialist; the server records the route, resolves one Published same-org Agent, copies trusted context, and creates a background Dialogue.

Context and inputs

routeId identifies the instruction edge; agentName is the exact Salesforce Name; userMessage is the specialist objective. Do not add context IDs, rationale, confidence, NBA fields, or DML inputs.

The server rejects Web Chat and validates context/target eligibility, not Mermaid semantics. It requires one exact normalized Published name; inactive Published Agents remain eligible.

Background lifecycle

sequenceDiagram
    participant R as Router Agent
    participant S as Dispatch Server
    participant O as OpenAI Responses
    participant Q as SQS
    participant J as JobQueueHandler
    participant W as BackgroundAIWorker
    R->>S: routeId, agentName, userMessage
    S->>O: Create background response for persisted child
    O-->>S: backgroundResponseId, providerStatus
    S->>Q: Enqueue AI_BACKGROUND_WORKER
    Q-->>S: sqsMessageId
    S-->>R: status=queued receipt
    Q->>J: Deliver message
    J->>W: Run BackgroundAIWorker

Queued requires a child, OpenAI response ID, and SQS acknowledgement; it is not completion. Receipt persistence is retried, failures are logged, and indeterminate lineages are not automatically redispatched.

Receipt, troubleshooting, and evals

Success returns route/resolution fields, matchedBy, dispatchId, child/provider/SQS evidence, parent/tool-call lineage, and deduplicated; resolvedAgentExternalId is optional UniqueID__c audit data.

Failures add the documented stable errorCode and message, including argument, resolution, synchronization, model, depth, background-start, and SQS-acknowledgement failures.

The parent transcript records instructions, arguments, and receipt; the child records lineage and target context. Eval evidence or rationale must be logged output/content, not dispatch input.