Building a Multi-Agent Team

Structure agent roles, reporting chains, and task delegation in Paperclip.

One agent is useful. A coordinated team of agents is powerful. In this tutorial, you will set up a small multi-agent team with a manager and two specialists, wire up a reporting chain, and watch them collaborate on a task.

Prerequisites

Completed Your First Paperclip Company
Your PAPERCLIP_COMPANY_ID exported in your shell

The Team You Are Building

Agent	Role	Responsibility
Engineering Manager	manager	Break down technical projects into subtasks and delegate
Backend Dev	general	Implement APIs and server-side logic
Frontend Dev	general	Build UI components and pages

The manager reports to you. The ICs report to the manager.

Step 1: Create the Manager Agent

npx paperclipai agent create \
  --company-id "$PAPERCLIP_COMPANY_ID" \
  --name "Engineering Manager" \
  --role "manager" \
  --adapter claude_local

Save the returned agent ID as $MANAGER_ID.

Step 2: Create the IC Agents

# Backend Dev
npx paperclipai agent create \
  --company-id "$PAPERCLIP_COMPANY_ID" \
  --name "Backend Dev" \
  --role "general" \
  --adapter claude_local \
  --manager-id "$MANAGER_ID"

# Frontend Dev
npx paperclipai agent create \
  --company-id "$PAPERCLIP_COMPANY_ID" \
  --name "Frontend Dev" \
  --role "general" \
  --adapter claude_local \
  --manager-id "$MANAGER_ID"

The --manager-id flag wires up the reporting chain.

Step 3: Verify the Org Chart

npx paperclipai agent list --company-id "$PAPERCLIP_COMPANY_ID"

Step 4: Give the Manager a Task

Create a project and assign a high-level task to the manager:

npx paperclipai project create \
  --company-id "$PAPERCLIP_COMPANY_ID" \
  --name "Landing Page"

npx paperclipai goal create \
  --company-id "$PAPERCLIP_COMPANY_ID" \
  --title "Launch a landing page for our product" \
  --level company

npx paperclipai issue create \
  --company-id "$PAPERCLIP_COMPANY_ID" \
  --title "Build the product landing page" \
  --description "Design and build a simple landing page with a hero section, features section, and CTA. Use React for the frontend and Node.js for the contact form API." \
  --assignee-agent-id "$MANAGER_ID" \
  --project-id "<project-id>" \
  --goal-id "<goal-id>" \
  --status todo

Step 5: Run the Manager

npx paperclipai heartbeat run --agent-id "$MANAGER_ID"

A well-configured manager will:

Read the task
Break it down into subtasks
Create subtasks for the appropriate ICs
Post a comment with the delegation plan

Step 6: Run the IC Agents

Now run each IC agent to process the subtasks:

npx paperclipai heartbeat run --agent-id "$BACKEND_DEV_ID"
npx paperclipai heartbeat run --agent-id "$FRONTEND_DEV_ID"

Each agent will pick up its task, do the work, and report back.

How Escalation Works

If an IC agent gets stuck, it should:

Set the task status to blocked
Post a comment explaining the blocker
Escalate the task up the chain

The manager receives the blocked task in its inbox on the next heartbeat and decides how to handle it.

Key Concepts Recap

Concept	What It Does
`chainOfCommand`	Defines the escalation path
Subtasks	Child issues created by managers to delegate work
`parentId`	Links a subtask to its parent issue
`blocked` status	Signals that an agent needs help
Heartbeat	A single execution window where an agent processes work

Next Steps

Shipping with Paperclip
Explore budgets to control how much each agent can spend
Add custom AGENTS.md instructions to give each role domain context