---
template: "page.peb"
title: "Dispatch Agent Skill"
description: "Configure an Agent Router to fork work to a named specialist Agent in a separate background Dialogue."
displayName: "Dispatch Agent Skill"
category: "skills"
contentType: "reference"
audience: "admin"
tags: "skills,dispatch-agent,agent-router,background,openai-responses,salesforce,mermaid"
section: "skills"
seoTitle: "Dispatch Agent Skill"
seoDescription: "Route Salesforce Agent work to named background specialists using auditable prose or Mermaid rules."
---

# 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

| Ownership | Properties |
| --- | --- |
| Agent supplies | Required `routeId`, `agentName`, and `userMessage`; no additional properties. |
| Server derives | Org/user, parent lineage/tool call, record/file IDs, room/member, IP/anonymous/memory context, target/settings, child/idempotency, OpenAI response, and SQS acknowledgement. |

`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

```mermaid
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.