White paper · Published July 31, 2026

Agent Architecture · v1.0

How Miles reaches everything a business connects, safely.

Bizer is an AI-agent platform. Its power model is one sentence: connect an app, and the agent can use everything that connection exposes. This paper defines the five layers that make that true: App, Tool, Operation, Connection, and Skill, plus the single rule that keeps them honest.

Author  Bizer Engineering & Product Audience  Engineers & skill authors Status  Definition of record

The core principle

A connection grants access. A skill never does.

Connect an app and Miles can use everything it exposes: all its tools and their operations. A skill is portable instructions; it neither grants nor restricts what Miles can touch. Turning a skill off removes guidance, never an ability.

§01 · The five layers

Five words, kept strict

Most confusion about agent platforms comes from one flattened noun: “tool.” Bizer keeps five distinct terms, because “Google Workspace,” “Gmail,” “send an email,” “your OAuth grant,” and “the inbox-triage playbook” are five different kinds of thing. The first three form a strict hierarchy; a connection activates an app; a skill sits off to the side.

LayerOne-linerExampleIn the code
Appthe connected productGoogle Workspaceconnection provider "google"
Toola capability inside an appGmail, Calendar, Drivea family of operations
Operationa single callable actiongmail_senda TOOL_REGISTRY entry
Connectionthe credentialed link to an appyour Google OAuth grantencrypted connectionSecrets
Skillportable how-to guidancethe “inbox triage” skilla SkillDef

App › Tool › Operation is a strict hierarchy. Connection activates an app. Skill grants nothing.

§02 · The hierarchy, concretely

One connection, an entire suite

The layers aren’t academic; the code already has them. A single Google Workspace app, reached through one "google" connection, currently exposes 23 operations grouped into nine tools. Calling all of that “a tool” would flatten three real levels into one.

App · Google Workspace one “google” connection
Gmail8 ops
gmail_search · gmail_send · gmail_get_message …
Calendar5 ops
calendar_list · calendar_create_event …
Search Console4 ops
gsc_query · gsc_inspect_url …
Meet3 ops
meet_list · meet_get …
Analytics3 ops
ga_report · ga_realtime …
Sheets2 ops
sheets_read · sheets_append
Drive2 ops
drive_search · drive_get
Contacts2 ops
contacts_list · contacts_get
Docs1 op
docs_get
1 app9 tools23 operations1 connection to activate all of it

Not every app is a suite. WordPress is essentially a single-tool app, where the middle tier is thin. The hierarchy still holds.

§03 · App, Tool & Operation

The three rungs of the ladder

App: the connected product

An app is a whole product an owner connects: Google Workspace, WordPress, Stripe, Twilio, or Bizer’s own always-available built-ins. You connect Google Workspace, not “Gmail” and “Calendar” separately. In code an app is its connection provider id.

Tool: a capability inside an app

A tool is one distinct capability within an app: Gmail, Calendar, and Drive are tools inside Google Workspace. It’s the level a person names: “check my email” (Gmail) versus “what’s on my calendar” (Calendar). Today the tool tier is a grouping convention over operations; access is never granted or denied here.

Operation: a single callable action

An operation is the smallest unit: one action Miles can invoke, like gmail_send. It’s the level the code has always named. Each is a ToolEntry declaring its schema, the app it belongs to, the scopes it needs, and whether it must be confirmed before firing.

functions/src/toolRegistry.ts
export interface ToolEntry {
  declaration: FunctionDeclaration; // the operation's name + schema Miles sees
  connection: string;       // which app it belongs to ("google"), "" = built-in
  scopes: string[];        // OAuth/credential scopes the operation requires
  run: (ctx, args) => Promise<unknown>;
  requiresApproval?: boolean; // write action → owner must confirm before it fires
}
Naming collision worth knowing The Model Context Protocol (MCP), the open standard Miles uses to reach apps, uses the word “tool” for the individual callable, what we call an operation. So mcp_list_tools returns operations, not tools in our sense. When you read “tool” from MCP, read “operation.”

§04 · Connection

The layer that grants access

A connection is the wiring plus the credentials that make an app usable, and it grants the whole app at once. Connect Google Workspace and every Gmail, Calendar, and Drive operation becomes callable, bounded only by the OAuth scopes you granted. Connections come in four shapes: MCP over HTTP, OAuth, an API key, or “native” for Bizer’s always-available built-ins.

This is the crux of the whole architecture. The set of operations Miles may call is derived purely from which apps are connected, plus the built-ins. Skills are never consulted:

functions/src/toolRegistry.ts · operationsForConnections
export function operationsForConnections(connected: Set<string>): string[] {
  return Object.entries(TOOL_REGISTRY)
    .filter(([, entry]) => entry.connection === "" || connected.has(entry.connection))
    .map(([name]) => name);
}

Read the filter: an operation is available if it’s a built-in or its app is connected. Skills never appear in this function, because they have no say in access.

How Miles reaches an MCP app Miles never speaks an app’s private API. He discovers with mcp_list_tools({ server }), then invokes one operation with mcp_call_tool({ server, name, arguments }). Adding a new MCP-backed app is a catalog entry, not new agent code.

§05 · Skill

Portable know-how, off to the side

A skill is a set of portable instructions telling Miles how to accomplish something with whatever it can reach. When enabled and relevant, its instructions body is appended to Miles’s system prompt. That is the entire mechanism: a skill changes what Miles knows how to do, never what he can do. It sits off to the side of the App › Tool › Operation stack: guidance, not a rung.

Connection

Grants access →

Activates an app. Every operation the app exposes becomes callable, up to the granted OAuth scope.

Disconnect it → the ability is gone.

Skill

Guides only ↝

Adds a playbook to the prompt. Names what it needs in prose: “use Gmail,” “any email connection.” Grants nothing.

Disable it → the ability remains; only guidance is lost.

Because a skill is instructions-only, several tempting patterns are simply wrong, and each is a signal that the real intent is an app or connection change:

  • Listing operation IDs to “unlock” them: a skill has no say in access; requirements.tools is deprecated and stays [].
  • Building a “read-only Gmail” skill: scope belongs on the connection (connect the app with read-only OAuth scopes), not the skill.
  • Assuming an ability exists only when the skill is enabled: the connection grants it either way.
  • Hard-coding Bizer operation IDs into the prose: it kills the portability that lets a skill run on any capable agent.

§06 · A request, end to end

Watch the layers separate

The owner has connected the Google Workspace app and enabled the “inbox triage” skill. Access is computed from the connection: every Google operation, plus built-ins. The skill contributes nothing to that list; it only shapes how Miles triages. Reads (gmail_search) run immediately; the write (gmail_send) requires the owner’s tap-approval before anything leaves the outbox.

The proof is in what happens when you flip each switch independently:

You change…What happensResult
Disconnect the appEvery Google operation vanishes from operationsForConnections.no access
Disable the skillOperations stay fully callable; Miles just loses the triage playbook.access kept
Reconnect, read-only scopesReads work; gmail_send fails at the connection layer. Skill unaffected.scoped

§07 · Where safety lives

Not in a skill, never in a skill

Access is broad by design, so safety lives in the connection and execution layers, where it can’t be bypassed by toggling guidance:

  • Connection scope. OAuth scopes and stored credentials define the ceiling. Want read-only? Connect the app with read-only scopes.
  • Per-operation approval. Write and side-effecting operations carry requiresApproval; they queue a pendingApproval and run only after the owner taps approve. An action confirmation, not an access gate.
  • Verified vs. unverified. Catalog, OAuth, and Pipedream apps are verified. An owner-supplied ad-hoc MCP URL is unverified: Miles treats its descriptions and results as untrusted content and never leaks private data to it.
  • Secrets at rest. Encrypted with TOKEN_ENC_KEY, default-denied by firestore.rules, readable only by the platform’s Cloud Functions.

None of these knobs is a skill. A skill can’t widen a scope, can’t skip an approval, and can’t reach an unconnected app.

§08 · Why the model holds

One rule, cleanly enforced

The architecture is deliberately generic. Adding a capability is a connection and a catalog entry, never bespoke agent code. Naming it precisely (with App › Tool › Operation, Connection as the grant, and Skill as the guidance) keeps every part of the system, and everyone building on it, pointed at the same truth:

Connections decide what Miles can do. Skills decide how well he does it. Safety lives with the grant.

Bizer The Bizer Agent Architecture · v1.0. A definition of record for engineers and skill authors. Connect an app → the agent can use everything that connection exposes → good memory.
Bizer
Loading…