Squad collaboration

PrimePilot squads can work together in two ways: inside one squad (same team, one workflow) and across squads (one team handing work to another).

Like teams in an organization

In a company, work often moves between departments:

Front office reads an inbound email, recognizes a job application, and opens a case for recruiting with the thread and attachments attached.
Recruiting picks it up later in their own queue; they do not need the front office to stay on the same call.

PrimePilot mirrors that:

Real world	PrimePilot
Same department finishing a task together	Intra-squad collaboration (orchestrator + squad-scoped memory)
Handoff to another department	Inter-squad collaboration (inter-squad messages)

Squads remain the unit of deployment. Each has its own agents, orchestrator, listeners, and domains. Collaboration connects squads without merging them into one mega-squad.

Intra-squad collaboration (within one squad)

When every agent that should participate is in the same squad, use the squad orchestrator and agent memory scoped to that squad.

Orchestrators

The orchestrator decides how agents share a single squad run, for example running agents in order, or using a shared blackboard so each agent contributes when it has something to add. See What are Orchestrators? and Orchestrator Types.

Typical intra-squad patterns:

Sequential flow: early agents classify or enrich; later agents act (for example draft a reply).
Blackboard: agents read and update shared run context until the work is done.
Passthrough: one primary agent per turn, with optional manual or automatic agent switching in chat.

Squad-scoped agent memory

Agents persist leads, drafts, reports, and pipeline state as memory rows tied to the squad. Other agents in the same squad (or the same squad on a later listener or scheduled run) read that data. See Agent Memory.

Rule of thumb: If the next agent lives in the same squad, do not use inter-squad messages; use orchestration and squad memory instead.

Inter-squad collaboration (between squads)

When another squad should own the next phase, a source-squad agent creates an inter-squad message. That message is a durable handoff in the tenant queue, not a chat transcript pasted into the next squad.

How it behaves

Create: An agent in squad A decides squad B should take over (for example email triage → interview scheduling squad). It writes an inter-squad message with a short summary, destination (target squad, optional target agent slot), and references to existing agent memory rows (by id), not full email bodies in the handoff itself.
Decouple: After the message is created, squad A does not read it again. The source agent may continue its run (reply, label, archive) or stop; that is up to the agent logic.
Dispatch: A background scheduler (listener worker or
```
APP_ROLE=all
```
) polls pending messages about every 30 seconds, runs the target squad, then marks each message complete or failed. Backend env:
```
INTER_SQUAD_DISPATCH_ENABLED
```
,
```
INTER_SQUAD_DISPATCH_INTERVAL_SECONDS
```
,
```
INTER_SQUAD_DISPATCH_BATCH_SIZE
```
.
Consume: Agents in squad B load the referenced memory rows and continue the workflow under their own orchestrator and listeners.

Example: job application

Email Response squad classifies mail as a job application and saves structured data in squad-scoped memory (contact, email content, extracted fields).
The agent creates an inter-squad message with summary
```
process_job_application
```
, target squad set to Recruiting / Interview, and references pointing at those memory rows.
The Interview squad runs on its own trigger (dispatcher), loads the references, and schedules or drafts next steps.

This matches “support routed the case to HR” without coupling both squads into one long execution.

Message contents (conceptual)

Each inter-squad message stores:

summary: Short label for logs and for the target run (for example
```
process_job_application
```
).
priority: Hint for ordering (for example
```
normal
```
).
source: Which squad, chat, and agent created the handoff (audit only).
destination: Target squad and optionally a specific agent instance on that squad.
references: List of agent memory ids the target squad should load.

Operational state (pending, in progress, finished) is tracked on the memory record itself (processing and active flags), not duplicated inside the JSON payload.

Email Response (Express)

On the Intent actions tab, each classified intent can optionally select a Handover squad and Handover agent. When an inbound email matches that intent, the Email Response agent saves an email memory row, creates an inter-squad message referencing it, and skips labeling and reply for that message. Choose this squad plus another agent on the squad to route to a specialist without a separate express solution. Leave handover as None to keep the normal pipeline.

When to use inter-squad messages

Use inter-squad messages when:

Responsibility should move to a different squad with its own deployment, domains, or workspace.
The source squad should finish independently after routing.
You want a clear audit trail of cross-squad handoffs per tenant.

Do not use them for agents that already share one squad. Orchestration and squad-scoped memory are simpler and faster for that case.

Choosing the right approach

All agents involved are in one squad?
  → Orchestrator + squad-scoped agent memory

Another squad must own the next phase?
  → Inter-squad message → target squad run