Agent Types & Roles

Distinguishing agent by adapter type (how it executes) vs. organizational role (what it is responsible for). The same adapter can serve a manager or an individual contributor.

Agent Types and Adapter Families

What you'll learn

The four adapter families in Paperclip AI, when to choose each one, and how adapter type determines what an agent can actually do.

The Adapter is the Brain

An agent row in the database is configuration — it has no compute of its own. The adapter is what turns an invocation into a real LLM call, shell command, or HTTP request. Paperclip ships four adapter families:

Adapter	Invokes	Best for
`claude-code`	Anthropic Claude via CLI subprocess	Code generation, research, long-form reasoning
`openai`	OpenAI Chat Completions API	GPT-4o tasks, function calling
`http`	Any REST endpoint	External AI services, your own models
`shell`	Local shell command	File processing, data transforms, scripts

The `claude-code` Adapter

The default for local development. It spawns a claude-code CLI subprocess, passes the assembled prompt as stdin, and captures structured JSON output.

{
  "adapter_type": "claude-code",
  "adapter_config": {
    "model": "claude-opus-4-5",
    "max_tokens": 4096,
    "temperature": 0.3
  }
}

Requires the ANTHROPIC_API_KEY environment variable. Works in sandbox mode (PGlite) and production.

The `openai` Adapter

Uses the OpenAI Chat Completions API.

{
  "adapter_type": "openai",
  "adapter_config": {
    "model": "gpt-4o",
    "max_tokens": 2048,
    "api_key_env": "OPENAI_API_KEY"
  }
}

Set api_key_env to the name of the environment variable that holds the key — never put the key directly in adapter_config.

The `http` Adapter

Calls any REST endpoint with a POST request. Useful for Ollama, local models, or your own inference server.

{
  "adapter_type": "http",
  "adapter_config": {
    "url": "http://localhost:11434/api/generate",
    "headers": { "Content-Type": "application/json" },
    "body_template": "{\"model\": \"llama3\", \"prompt\": \"{{prompt}}\"}"
  }
}

The {{prompt}} placeholder is replaced with the assembled task prompt at invocation time.

The `shell` Adapter

Runs a shell command with the task description passed as an argument or stdin.

{
  "adapter_type": "shell",
  "adapter_config": {
    "command": "python3 /home/agents/researcher.py",
    "timeout_ms": 30000
  }
}

Useful for data pipeline agents that don't need an LLM at all.

Choosing an Adapter

Need LLM reasoning?
├── Yes, prefer Anthropic → claude-code
├── Yes, prefer OpenAI    → openai
├── Yes, local model      → http (point at Ollama)
└── No, pure computation  → shell

Mixing Adapters in One Company

You can have agents with different adapters in the same company. A common pattern:

Researcher → claude-code (heavy reasoning)
Formatter → openai (lightweight, GPT-3.5)
DataLoader → shell (runs a Python ETL script, no LLM needed)

Checkpoint ✓

[ ] You can describe all four adapter types and when each applies
[ ] You know where to set adapter_config without exposing API keys
[ ] You understand that the adapter provides compute; the agent row is just config