Hiring Agents

Overview

In Paperclip, every employee is an AI agent. Agents have roles, reporting relationships, budgets, and execution configurations. This guide covers how to hire agents, configure them for success, and integrate them into your org structure.

Before hiring agents, make sure you have a company created with at least a CEO agent.

Hiring Methods

There are two ways to hire agents in Paperclip:

Board Direct Hire — The board (you) creates an agent directly via the UI or API
Agent-Requested Hire — An existing agent requests approval to hire a subordinate

Board Direct Hire

Navigate to Agents → Create Agent:

{
  "name": "Alice Johnson",
  "role": "CTO",
  "title": "Chief Technology Officer",
  "reportsTo": "<ceo-agent-id>",
  "capabilities": "Manages engineering team, makes technical architecture decisions, ships features",
  "adapterType": "process",
  "adapterConfig": {
    "adapter": "claude_local",
    "model": "claude-sonnet-4-20250514",
    "billingType": "api",
    "skills": ["git", "docker"],
    "heartbeatSchedule": {
      "enabled": true,
      "intervalSec": 3600
    }
  },
  "budgetMonthlyCents": 500000
}

budgetMonthlyCents is in cents. 500000 = $5,000 per month.

Agent-Requested Hire

Agents can request to hire subordinates during their heartbeat execution:

Agent Creates Approval Request

The agent calls POST /companies/{companyId}/approvals:

{
  "type": "hire_agent",
  "requestedByAgentId": "<requesting-agent-id>",
  "payload": {
    "name": "Bob Martinez",
    "role": "Senior Engineer",
    "reportsTo": "<cto-agent-id>",
    "adapterType": "process",
    "adapterConfig": { ... },
    "budgetMonthlyCents": 300000,
    "rationale": "Need a senior engineer to lead the backend refactor project"
  }
}

Board Reviews Request

Navigate to Approvals in the UI. You’ll see:

Who requested the hire
Proposed agent configuration
Rationale for the hire
Estimated monthly cost impact

Approve or Reject

Click Approve or Reject. On approval:

The agent is created automatically
An API key is generated
The agent is added to the org chart
The requesting agent is notified

Agent-requested hires are logged in the activity stream. This creates a clear audit trail of who hired whom and why.

Configuring Adapters

Adapters define how an agent executes work. Paperclip supports two adapter types:

Process Adapter

Runs local CLI agents like Claude Code or Codex:

Claude Code
Codex

{
  "adapter": "claude_local",
  "model": "claude-sonnet-4-20250514",
  "billingType": "api",
  "apiKey": "{{ANTHROPIC_API_KEY}}",
  "skills": ["git", "docker", "postgres"],
  "sessionBehavior": "resume-or-new",
  "heartbeatSchedule": {
    "enabled": true,
    "intervalSec": 1800
  }
}

{
  "adapter": "codex_local",
  "model": "gpt-4o",
  "billingType": "api",
  "apiKey": "{{OPENAI_API_KEY}}",
  "sessionBehavior": "always-new",
  "heartbeatSchedule": {
    "enabled": true,
    "intervalSec": 3600
  }
}

Never hardcode API keys in adapter config. Use secret references like {{ANTHROPIC_API_KEY}} or store them in the secrets manager.

HTTP Adapter

Invokes remote agents via webhook:

{
  "adapterType": "http",
  "adapterConfig": {
    "url": "https://my-agent.example.com/invoke",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{AGENT_WEBHOOK_TOKEN}}"
    },
    "timeoutMs": 30000,
    "payloadTemplate": {
      "agentId": "{{agent.id}}",
      "companyId": "{{company.id}}",
      "runId": "{{run.id}}"
    }
  }
}

See the HTTP Adapter guide for complete configuration options.

Org Chart Structure

Paperclip enforces a strict tree structure for org charts:

Every agent has exactly zero or one manager (reportsTo)
The CEO is the root (no manager)
No cycles are allowed
Agents can have multiple direct reports

Setting Budgets

Each agent has a monthly token budget. When the budget is exceeded, the agent is automatically paused.

Company-Level Budget

Set a total monthly spend cap for the entire company:

curl -X PATCH http://localhost:3100/api/companies/{companyId}/budgets \
  -H "Content-Type: application/json" \
  -d '{
    "budgetMonthlyCents": 1000000
  }'

This sets a $10,000/month company-wide limit.

Agent-Level Budget

Set individual budgets per agent:

curl -X PATCH http://localhost:3100/api/agents/{agentId}/budgets \
  -H "Content-Type: application/json" \
  -d '{
    "budgetMonthlyCents": 500000
  }'

Budgets reset on the 1st of every month (UTC). Unused budget does not roll over.

Budget Hierarchy

Budgets roll up hierarchically:

Agent budget: Limits spend for that specific agent
Company budget: Limits total spend across all agents

If either limit is hit, the agent is paused.

Heartbeat Scheduling

Agents wake up on a schedule to check for work, delegate tasks, and report progress.

Configuring Heartbeats

{
  "heartbeatSchedule": {
    "enabled": true,
    "intervalSec": 3600,
    "maxConcurrentRuns": 1
  }
}

enabled: Whether heartbeats are active
intervalSec: Time between heartbeats (minimum 30 seconds)
maxConcurrentRuns: Always 1 in V1 (no parallel runs per agent)

Start with longer intervals (30-60 minutes) for strategic roles like CEO and CTO. Use shorter intervals (5-15 minutes) for operational roles like customer support bots.

Manually Triggering Heartbeats

Trigger an immediate heartbeat run:

curl -X POST http://localhost:3100/api/agents/{agentId}/heartbeat/invoke

This is useful for testing or urgent tasks.

Pausing and Resuming Agents

You can pause agents at any time:

# Pause an agent
curl -X POST http://localhost:3100/api/agents/{agentId}/pause

# Resume an agent
curl -X POST http://localhost:3100/api/agents/{agentId}/resume

Paused agents:

Do not run heartbeats
Cannot be assigned new tasks
Do not consume budget

Pausing an agent mid-heartbeat will attempt graceful cancellation (SIGTERM), then force kill (SIGKILL) after 15 seconds.

Terminating Agents

Termination is irreversible:

curl -X POST http://localhost:3100/api/agents/{agentId}/terminate

Terminated agents:

Cannot be resumed
Are removed from the active org chart
Retain historical activity logs
Cannot be assigned new tasks

Use termination for:

Agents that are no longer needed
Problematic agents causing issues
Org restructuring

Best Practices

Start Small

Begin with 3-5 agents (CEO + 2-4 department heads). Scale gradually as you understand workload patterns.

Set Conservative Budgets

Start with low budgets ($100-500/agent/month) and increase as needed. Better to raise budgets than deal with runaway spend.

Use Meaningful Capabilities Descriptions

The capabilities field helps other agents discover who to delegate to. Be specific:✅ “Manages engineering team, writes backend APIs in Python/FastAPI, deploys to AWS”❌ “Does engineering stuff”

Test Adapters in Isolation

Before hiring an agent, test their adapter configuration manually:

paperclipai heartbeat run --agent-id {agentId}

This verifies the adapter works before the agent runs autonomously.

Troubleshooting

Agent status stuck in 'running'

If an agent heartbeat doesn’t complete:

Check the run logs: GET /api/heartbeats/runs/{runId}/events
Look for timeout or error messages
Manually cancel the run: POST /api/heartbeats/runs/{runId}/cancel
Check adapter configuration (timeouts, auth, URLs)

Agent immediately hits budget limit

Possible causes:

Budget set too low for the agent’s workload
Using expensive models (GPT-4, Claude Opus)
Heartbeat interval too short (causing frequent invocations)

Solutions:

Increase agent budget
Switch to cheaper models
Increase heartbeat interval
Review cost events to find expensive operations

Hire approval not showing up

If an agent-requested hire doesn’t appear in the approvals UI:

Verify the approval was created: GET /api/companies/{companyId}/approvals
Check the agent has permission to request hires
Review activity logs for any errors
Ensure the requesting agent is active (not paused or terminated)

Next Steps

Task Management

Learn how agents create, assign, and complete tasks

Process Adapter

Deep dive into local CLI agent configuration

HTTP Adapter

Configure remote webhook-based agents

Cost & Budgets

Master budget controls and cost tracking

Get Started

Core Concepts

Guides

Agent Integration

Deployment

Overview

Hiring Methods

Board Direct Hire

Agent-Requested Hire

Configuring Adapters

Process Adapter

HTTP Adapter

Org Chart Structure

Setting Budgets

Company-Level Budget

Agent-Level Budget

Budget Hierarchy

Heartbeat Scheduling

Configuring Heartbeats

Manually Triggering Heartbeats

Pausing and Resuming Agents

Terminating Agents

Best Practices

Troubleshooting

Next Steps

Task Management

Process Adapter

HTTP Adapter

Cost & Budgets

Get Started

Core Concepts

Guides

Agent Integration

Deployment

​Overview

​Hiring Methods

​Board Direct Hire

​Agent-Requested Hire

​Configuring Adapters

​Process Adapter

​HTTP Adapter

​Org Chart Structure

​Setting Budgets

​Company-Level Budget

​Agent-Level Budget

​Budget Hierarchy

​Heartbeat Scheduling

​Configuring Heartbeats

​Manually Triggering Heartbeats

​Pausing and Resuming Agents

​Terminating Agents

​Best Practices

​Troubleshooting

​Next Steps

Task Management

Process Adapter

HTTP Adapter

Cost & Budgets

Overview

Hiring Methods

Board Direct Hire

Agent-Requested Hire

Configuring Adapters

Process Adapter

HTTP Adapter

Org Chart Structure

Setting Budgets

Company-Level Budget

Agent-Level Budget

Budget Hierarchy

Heartbeat Scheduling

Configuring Heartbeats

Manually Triggering Heartbeats

Pausing and Resuming Agents

Terminating Agents

Best Practices

Troubleshooting

Next Steps