HTTP Webhook Adapter

Calling any external REST endpoint as an agent: request shape, polling strategy for async completion, timeout handling, and mapping HTTP response fields to Paperclip run status.

The HTTP Adapter: Local and Custom Models

What you'll learn

Use the HTTP adapter to connect Paperclip agents to Ollama, a custom inference server, or any REST-based AI service.

When to Use the HTTP Adapter

Local models via Ollama — run Llama 3, Mistral, or Phi-3 without cloud API costs
Azure OpenAI — same API shape as OpenAI but different endpoint and auth
Your own fine-tuned model — self-hosted FastAPI inference server
External AI services — Cohere, Mistral AI Cloud, Groq, etc.

Ollama Example

Start Ollama with Llama 3:

ollama pull llama3
ollama serve  # starts on localhost:11434

Configure the agent:

{
  "adapter_type": "http",
  "adapter_config": {
    "url": "http://localhost:11434/api/generate",
    "method": "POST",
    "headers": { "Content-Type": "application/json" },
    "body_template": "{\"model\": \"llama3\", \"prompt\": \"{{system_prompt}}\\n\\n{{task_prompt}}\", \"stream\": false}",
    "response_path": "response"
  }
}

response_path is a dot-notation path to extract the text from the response JSON. For Ollama the full text is at .response.

Azure OpenAI Example

{
  "adapter_type": "http",
  "adapter_config": {
    "url": "https://my-resource.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-02-01",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json",
      "api-key": "{{env.AZURE_OPENAI_KEY}}"
    },
    "body_template": "{\"messages\": [{\"role\": \"system\", \"content\": \"{{system_prompt}}\"}, {\"role\": \"user\", \"content\": \"{{task_prompt}}\"}], \"max_tokens\": 2048}",
    "response_path": "choices.0.message.content"
  }
}

{{env.VAR_NAME}} substitutes the named environment variable at invocation time — keys never appear in the database.

Template Variables

Variable	Value
`{{system_prompt}}`	Agent's system prompt
`{{task_prompt}}`	Assembled task description
`{{run_id}}`	This invocation's run ID
`{{agent_id}}`	Agent's database ID
`{{env.VAR_NAME}}`	Environment variable

Async HTTP Adapters

If your endpoint is long-running and returns a job ID, configure async_mode:

{
  "adapter_config": {
    "url": "https://my-service.com/jobs",
    "async_mode": true,
    "status_url": "https://my-service.com/jobs/{{run_id}}",
    "status_path": "job.status",
    "output_path": "job.result",
    "poll_interval_ms": 5000
  }
}

Paperclip polls status_url every poll_interval_ms until status_path is "completed" or "failed", then reads the output from output_path.

Checkpoint ✓

[ ] You can configure an Ollama-backed agent using the HTTP adapter
[ ] You understand template variables and how {{env.VAR}} keeps secrets safe
[ ] You know the difference between sync and async HTTP adapters