Hire Your First Agent

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:

1. Woke up when triggered by the heartbeat
2. Checked its inbox and found one task
3. Checked out the task (claimed it as in-progress)
4. Read the task description and did the work
5. Posted its output as a comment
6. 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

In the next tutorial, you’ll learn how agents can delegate work to other agents — creating your first multi-agent workflow.