Hiring Your First Agent

POST /api/agents: choosing an adapter type, setting the agent's role name, writing the initial system prompt, and navigating the human approval gate that guards agent creation.

Hiring Your First Agent

What you'll learn

Create an agent record, understand every field in the agents table, and connect the agent to an adapter so the heartbeat can invoke it.

What is an Agent?

An agent in Paperclip AI is a persistent row in the database that represents one autonomous worker. It stores:
- What the agent is supposed to do (role, system prompt)
- Which adapter to use to invoke it (Claude Code, OpenAI, HTTP…)
- Its cost limits and current status
- Its position in the org chart (reports_to)

Agents don't run continuously. They are invoked by the heartbeat on each tick when there is unclaimed work.

Hiring via the UI

1. Open your company dashboard → Agents → Hire Agent.
2. Fill in:
3. Name — e.g. Researcher
4. Role — e.g. Research Analyst
5. System prompt — the standing instruction this agent always receives
6. Adapter — choose claude-code for local dev
7. Monthly budget — start with $5.00
8. Click Hire.

Hiring via the API

curl -X POST http://localhost:3100/api/companies/${COMPANY_ID}/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Researcher",
    "role": "Research Analyst",
    "system_prompt": "You are a research analyst. When given a topic, produce a concise 3-paragraph summary with key facts and sources.",
    "adapter_type": "claude-code",
    "monthly_budget_usd": 5.00
  }'

Hiring via SQL (seed scripts)

INSERT INTO public.agents (
  company_id, name, role, system_prompt, adapter_type, monthly_budget_usd, status
)
VALUES (
  '01929f3a-...',   -- your company id
  'Researcher',
  'Research Analyst',
  'You are a research analyst. When given a topic, produce a concise 3-paragraph summary.',
  'claude-code',
  5.00,
  'active'
)
ON CONFLICT (company_id, name) DO UPDATE SET
  role = EXCLUDED.role,
  system_prompt = EXCLUDED.system_prompt;

The agents Table Reference

After Hiring

Once an agent exists it will be picked up by the heartbeat on the next tick — but only if there are open issues assigned to it. In the next lesson you'll create your first task to give the agent something to do.

Checkpoint ✓

• [ ] Agent created and visible in the Agents list
• [ ] Agent has a system prompt, an adapter, and a monthly budget
• [ ] You understand the difference between adapter_type and adapter_config