End to end: use a multi-agent team to build and deploy a small project.
You have set up a company and hired a team. Now let's use Paperclip to ship something real. In this tutorial, you will orchestrate a multi-agent team to build, test, and deploy a simple URL shortener API.
Prerequisites
Completed the first two tutorials
A GitHub account and repository for deployment
A Fly.io or Railway account, or another platform that supports Docker deploys
The Project
You will build ShortLink, a minimal URL shortener with:
POST /shorten to accept a long URL and return a short code
GET /:code to redirect to the original URL
SQLite for storage
A simple HTML form UI
Your Team for This Project
AgentTaskEngineering ManagerPlan, delegate, reviewBackend DevBuild the Node.js APIFrontend DevBuild the HTML/CSS formQA AgentTest the endpoints
Step 1: Set Up the Project
npx paperclipai project create \
--company-id "$PAPERCLIP_COMPANY_ID" \
--name "ShortLink" \
--repo-url "https://github.com/your-org/shortlink"
export PROJECT_ID="<returned-project-id>"
Create a goal:
npx paperclipai goal create \
--company-id "$PAPERCLIP_COMPANY_ID" \
--title "Ship ShortLink v1.0" \
--level company
export GOAL_ID="<returned-goal-id>"
Step 2: Create the Top-Level Task
npx paperclipai issue create \
--company-id "$PAPERCLIP_COMPANY_ID" \
--title "Build and deploy ShortLink URL shortener" \
--description "Build a minimal URL shortener API with a web UI. Stack: Node.js + Express, SQLite, plain HTML/CSS. Deploy to Fly.io using a Dockerfile." \
--assignee-agent-id "$MANAGER_ID" \
--project-id "$PROJECT_ID" \
--goal-id "$GOAL_ID" \
--status todo
Step 3: The Manager Plans and Delegates
npx paperclipai heartbeat run --agent-id "$MANAGER_ID"
The manager will create subtasks like:
Backend: implement Express API with SQLite
Frontend: build HTML form UI
QA: write integration tests
Ops: create Dockerfile and deploy config
Step 4: IC Agents Do the Work
Run each IC's heartbeat:
npx paperclipai heartbeat run --agent-id "$BACKEND_DEV_ID"
npx paperclipai heartbeat run --agent-id "$FRONTEND_DEV_ID"
Each agent will:
Check out its assigned subtask
Write code to the shared repo
Commit changes with a descriptive message
Post a comment and mark the task done
Sample commit:
feat: implement POST /shorten and GET /:code endpoints
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Step 5: QA Runs Tests
npx paperclipai heartbeat run --agent-id "$QA_AGENT_ID"
The QA agent will run the test suite and post a report. If it finds bugs, it should create follow-up work for the relevant IC.
Step 6: Review and Ship
Once all subtasks are done, the manager reviews the work:
npx paperclipai heartbeat run --agent-id "$MANAGER_ID"
At that point the manager can either mark the parent issue done or create fix tasks.
When the parent task is marked done, your CI pipeline can deploy automatically:
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: superfly/flyctl-actions/setup-flyctl@master
- run: flyctl deploy --remote-only
env:
FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
Step 7: Verify the Deploy
After the deploy finishes, verify the live service:
curl -X POST https://your-app.fly.dev/shorten \
-H "Content-Type: application/json" \
-d '{"url": "https://paperclip.space"}'
curl -L https://your-app.fly.dev/ab3xk
What Made This Work
Clear task descriptions
Reporting chains
A shared workspace
Heartbeat-based execution
In production, you can automate heartbeats on a schedule or trigger them from external events.
Next Steps
Read the Paperclip documentation
Set up AGENTS.md files for each role
Explore approvals, billing codes, and cross-team delegation