Connected agents vs native agents: choosing the right integration model

BehalfID has two agent types: native and connected. They share the same passport and verify model, but they exist for different reasons and come with meaningfully different enforcement guarantees.

A native agent is an identity you create and own inside BehalfID. It has an API key, a passport, and a verify integration that your code controls end-to-end. The agent can be anything — a script, a workflow runner, an LLM with tool use — as long as your code calls behalf.verify() before executing each action.

import { BehalfID } from "@behalfid/sdk";

const behalf = new BehalfID({ apiKey: process.env.BEHALFID_AGENT_KEY });

const decision = await behalf.verify({
  agentId: "agent_my_workflow",
  action: "send_email",
  vendor: "gmail.com"
});

if (!decision.allowed) throw new Error(decision.reason);
await sendEmail(recipient, body);

Because you control the integration, enforcement is automatic. If you wire the verify call correctly and fail closed on denial, BehalfID's decision is binding. The executor never runs without an explicit allow.

A connected agent manually represents an external tool you don't control at the protocol level — ChatGPT, Claude, Zapier, Make, Ollie, or any other service where you can't inject a verify call before the agent acts.

When you create a connected agent in BehalfID, you record its provider and any metadata. You then generate a passport link— a scoped URL that exposes the agent's active permission scopes. The external agent (or you) can read that link to understand what it's allowed to do before acting.

For connected agents that can't call the verify API, BehalfID offers three manual surfaces to communicate constraints:

• Passport link. A #token=… URL that exposes the active scopes. Works for agents that can fetch URLs and execute JavaScript. Most consumer AI assistants cannot.
• Agent memory block.A structured plain-English copy of the scopes. Paste into the agent's memory or system prompt. Treated as best-effort — agents may compress or ignore saved memory.
• Per-task permission prompt.A full scope list, a blocked-actions section, and three questions the agent should answer before proceeding. Paste directly into the active chat. More reliable than memory because it's in the active context window, not stored state.

If you are building the integration, use a native agent. You control the code, you can wire the verify call, and enforcement is automatic and binding. The passport is enforced at the decision boundary, not communicated as guidance.

If you are working with an external agent you can't modify — an assistant product, a no-code automation, a third-party workflow — use a connected agent. The passport gives the agent a readable record of its constraints. Combined with a per-task prompt, it's the most reliable available option short of integration-level enforcement.

Developer integration remains the only path to automatic enforcement. Connected agents are a testing and communication tool for agents you don't own.