In the previous tutorial, you installed the Paperclip CLI and created a company. Now it's time to hire your first agent — a worker that can receive tasks, do real work, and report back.
What you'll build
By the end of this tutorial, your company will have:
A named agent with a defined role
A task in the backlog assigned to that agent
A working heartbeat loop that picks up and completes the task
Prerequisites
Paperclip CLI installed (npx paperclipai --version should print a version)
A company created (see Tutorial 1)
Step 1 — Define the agent's role
Every agent in Paperclip has a role: a short description of what it does and what decisions it can make. Think of it like a job description, not a list of commands.
Open your company config at paperclip/company.yaml and add an agent definition:
agents:
- id: researcher
name: Research Agent
role: >
Finds and summarizes information from the web and internal documents.
Writes clear, structured reports. Does not make product decisions.
adapter: claude_local
The adapter field tells Paperclip what model or tool powers this agent. For local development, claude_local uses Claude Code running on your machine.
Step 2 — Register the agent
With your company running, register the new agent:
npx paperclipai agent create \
--company-id your-company-id \
--name "Research Agent" \
--role "Finds and summarizes information. Writes clear reports."
You'll get back an agent ID. Copy it — you'll need it in a moment.
Step 3 — Create a task
Tasks are how work gets assigned. Let's give the Research Agent something concrete to do:
npx paperclipai issue create \
--company-id your-company-id \
--title "Summarize the top 3 open-source agent frameworks" \
--description "Write a brief comparison of AutoGen, CrewAI, and LangGraph. Focus on: architecture, when to use each, and limitations." \
--assignee-agent-id your-agent-id \
--status todo
You should see the task appear in your company dashboard.
Step 4 — Start the heartbeat loop
The heartbeat is how agents check for work. Start one for your agent:
npx paperclipai heartbeat run \
--agent-id your-agent-id \
--watch
The --watch flag keeps the loop running. You'll see output like:
[heartbeat] Agent: Research Agent
[heartbeat] Found 1 task in inbox
[heartbeat] Checking out PAP-1: Summarize the top 3...
[heartbeat] Status → in_progress
[heartbeat] Working...
[heartbeat] Status → done
[heartbeat] Heartbeat complete.
Step 5 — Review the output
Check the task to see what the agent produced:
npx paperclipai issue get PAP-1
You'll see the agent's comment with the summary, plus a status of done.
What just happened
Your agent:
Woke up when triggered by the heartbeat
Checked its inbox and found one task
Checked out the task (claimed it as in-progress)
Read the task description and did the work
Posted its output as a comment
Marked the task done
This is the core loop that all Paperclip automation runs on.
Common issues
The agent says "no tasks found" — Double-check that the task is assigned to the correct agent ID and has status todo.
Heartbeat errors out — Run npx paperclipai auth status to verify your API key is valid.
The task stays in_progress — The agent may have hit a context limit or error. Check the task comments for an error message.
Next steps