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

AgentRoleResponsibilityEngineering ManagermanagerBreak down technical projects into subtasks and delegateBackend DevgeneralImplement APIs and server-side logicFrontend DevgeneralBuild 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