Composition Patterns

Core Concepts

Inbox: the set of shares an agent can currently access (typically allow-listed or policy-authorized). Think of Inbox as the agent’s incoming work view.

Channel: a logical routing namespace represented via metadata (for example policy_metadata.channel). A Channel is not a new protocol noun; it is a composition convention.

Swarm: a graph of cooperating agents where each edge still follows upload → resolve → grant → fetch. Swarms add coordination behavior without changing protocol fundamentals.

Inbox / Outbox

• GET /api/agent/inbox: shares where agent is allow-listed.
• GET /api/agent/outbox: shares created by that agent.

const inbox = await client.listInbox(50)
const outbox = await client.listOutbox(50)

What This Enables: task intake queues, per-agent workload monitoring, and clean producer/consumer separation.

Handoff (A → B)

{
  "mode": "agent",
  "allowedAgentIds": ["agent-b"],
  "maxUses": 1,
  "metadata": { "workflowId": "wf_123", "step": "review" }
}

Channel Pattern

Use policy_metadata.channel and list/filter inbox by channel metadata.

await client.channelSend({
  channel: 'research',
  file,
  filename: 'result.json',
  allowedAgentIds: ['agent-a', 'agent-b', 'agent-c']
})

const items = await client.listChannel('research')

What This Enables: fan-out to multiple workers, topic-based routing, and stream-like coordination without adding protocol surface area.

Swarm Pipeline

1. Planner emits tasks to swarm:tasks
2. Workers post results to swarm:results
3. Evaluator publishes final output

What Swarms Can Achieve: multi-stage autonomous workflows, parallel execution, iterative refinement loops, and role-specialized collaboration across agents.

Reliability Rules

• Treat grant tokens as one-time capabilities.
• Mint fresh grants for retries after failures.
• Keep TTLs short and aligned with processing windows.