Envelope

Choosing an adapter

Adapters connect each agent in your team to the model or service that runs it. Choosing the right one determines what deployers need to provide — and what your agents can actually do.

What adapters are

Every agent in an Envelope team has an adapter — a thin runtime bridge that translates Envelope's standard invocation protocol into whatever the underlying model or service expects. When a deployer's Paperclip instance runs your team, Envelope hands each agent's prompt and context to its adapter, which calls the real service and returns the result.

You set the adapter per-agent when you build the team. Different agents in the same team can use different adapters — for example, a planner agent on Claude and an executor agent on OpenAI.

The builder / deployer contract

The adapter choice is a contract. As the builder, you pick the adapter — and that determines exactly what credentials or configuration the deployer must supply at install time. Envelope surfaces those requirements automatically; you don't need to document them yourself.

Builder owns:

  • Which adapter each agent uses
  • The system prompt and agent structure
  • The model variant (where the adapter supports it)

Deployer owns:

  • API keys and credentials
  • Runtime mode for HTTP agents (managed or custom URL)
  • Any tool-specific setup (for example, a Cursor installation)

Think carefully about deployer friction. Every field a deployer must fill in at install time is a barrier. Adapters that require widely-held credentials (like an OpenAI API key) convert much better than ones that require bespoke setup.

All adapters

Claude (Anthropic)

Sweet spot: Reasoning, writing, analysis, long-context tasks

The most capable general-purpose adapter. Claude handles nuanced instructions well and has a very large context window — good for agents that need to reason over long documents or maintain complex state.

Deployer provides: Anthropic API key

OpenAI (GPT-4 family)

Sweet spot: Code generation, debugging, technical scaffolding

Routes to OpenAI's GPT-4 family. Ideal for engineering-focused agents — code review bots, PR summarisers, test generators. Deployers almost certainly already have an OpenAI key, keeping friction low.

Deployer provides: OpenAI API key

Gemini (Google)

Sweet spot: Multimodal tasks, Google Workspace integration

Connects to the Gemini API. Strong choice when your agent needs to process images or PDFs alongside text, or when the deployer's stack is already Google-centric.

Deployer provides: Google API key

OpenCode

Sweet spot: Autonomous coding tasks in local repos

Routes to the OpenCode open-source coding agent. Best for teams that operate directly on a codebase — cloning, editing, and opening PRs. Deployers need to provide repository access on top of the API key.

Deployer provides: OpenCode API key, repo path or remote URL

Cursor

Sweet spot: Deployers already using Cursor as their IDE

Invokes Cursor's local agent against the deployer's active workspace. Zero cold-start for Cursor shops — but requires the deployer to have Cursor installed, which makes it a narrower fit than other coding adapters.

Deployer provides: Cursor installation, Cursor API token

HTTP (Envelope managed or custom)

Sweet spot: Lowest deployer friction — managed or custom execution

Managed mode: Envelope runs a full agentic loop — the deployer clicks one button, no URL or API key required. Envelope handles the model, tool calls, and secret injection automatically.

Custom mode: The deployer pastes their own endpoint URL. Their server owns the model, tooling, and agentic loop entirely.

Deployer provides: Nothing in managed mode, or a custom webhook URL in custom mode

Choosing an adapter

Start with the question: who is my deployer and what do they already have?

| Deployer situation | Recommended adapter | |---|---| | Has an OpenAI key (most common) | OpenAI (GPT-4) | | Needs reasoning over long docs | Claude (Anthropic) | | Processes images or PDFs | Gemini (Google) | | Operates a codebase (open-source tooling) | OpenCode | | Team lives in Cursor already | Cursor | | Easiest install — deployer doesn't hold API keys | HTTP managed |

If you're building for a broad audience and don't know who your deployers are yet, Claude and OpenAI have the lowest barrier — most companies already hold keys for Anthropic or OpenAI.

HTTP adapter in depth

The HTTP adapter tells Paperclip to call an HTTP endpoint when the agent is triggered — instead of running a local model. At install time, the deployer chooses between two runtime modes.

Managed by Envelope: The deployer clicks one button — no API key, no server, no URL to paste. Envelope runs a full agentic loop: up to 10 model iterations, external API calls via a built-in request tool, and deployer secrets injected automatically into any URL or header.

Custom webhook: The deployer provides their own endpoint URL. Paperclip calls that URL on each trigger — useful for teams that already run inference on their own infrastructure or want full control over the model and runtime.

Runtime capability comparison

| What each runtime can do | Managed | Custom | Local model | |---|:---:|:---:|:---:| | Text generation — summarise, classify, draft, answer | ✓ | ✓ | ✓ | | Call external APIs (Slack, Zendesk, GitHub, email…) | ✓ | ✓ | ✓ | | Inject deployer secrets into API calls | ✓ | ✓ | ✓ | | Multi-step agentic loops (up to 10 iterations) | ✓ | ✓ | ✓ | | Read or write files on the deployer's machine | — | ✓ | ✓ | | Zero deployer setup | ✓ | — | — |

Managed runtime capabilities. The managed runtime runs a full agentic loop powered by a hosted model. It includes a built-in tool for calling external APIs and injects deployer secrets automatically. The one thing it cannot do is access the local file system — for that, use a local model adapter or a custom webhook.

How custom webhook mode works

  1. Deployer installs the team and pastes their own HTTPS endpoint URL.
  2. Paperclip sends the trigger payload to that URL on every agent invocation.
  3. The deployer's server handles everything: fetching the agent config, calling whatever model it likes, running any agentic loop or tooling, and returning the response.
  4. Paperclip records the run and routes the response through the org structure. Envelope never sees the model call — only the final text the server returns.

Custom mode gives full control over the model, runtime, and execution environment. The payload format and required response shape are documented in the Runtime API reference.

What deployers see at install time

When someone installs your team, Envelope inspects every agent's adapter and generates an install form with exactly the fields required — no more, no less. You don't need to document this yourself; Envelope handles it.

For adapters that need credentials, the deployer fills them in once at install time — Envelope stores them encrypted and injects them at runtime, never visible to you as the builder. For HTTP agents in managed mode, no credentials are needed at all — Envelope handles the model call on your behalf.

‹ All guidesDocs ›