🧩 The Capability Model
The agent capability model is built in three concentric layers. Each layer builds on the one below it.AGENT CAPABILITY MODEL
Agent· Actor — Identity, memory, routing, governance
IdentityMemoryRoutingGovernance
Skill· Instruction — Packaged domain knowledge (SKILL.md)
githubcode-reviewdata-analysisresearch
Tool· Runtime Primitive — Functions the agent can invoke
execreadweb_searchbrowser
github skill knows how to work with GitHub (the skill’s SKILL.md tells it the conventions), and it uses the exec tool to actually run gh commands.
🏗️ The Four-Layer Definition Model
Every in Forge is structured across four layers. Layers 1—3 live in theagentDefinitions table. Layer 4 is a separate agentDeployments record that binds a definition to a runtime.
FOUR-LAYER AGENT DEFINITION
agentDefinitions
Layer 1: Identity· What the agent IS
agentId, name, description, purpose, version, status, owner, tags, identity (emoji, avatar, theme)
↓
Layer 2: Capability· What the agent CAN DO
Skills array, tools (required + optional), subagents, input/output modes
↓
Layer 3: Runtime Config· How the agent RUNS
Model (default + constraints), prompt (core + extension), memory config, constraints (max tool calls, timeout, tokens, sandbox)
separate table: agentDeployments
↓
Layer 4: Deployment· Where the agent LIVES
Gateway binding, provider (OpenClaw, Claude Agent SDK, Vercel AI, Convex-native), deployment overrides, sync status
Layer Immutability Rules
Deployments can override certain fields, but the override rules are strict:| Field | Overridable at Deployment? | Notes |
|---|---|---|
| Core prompt | No | Immutable. Defines agent identity. |
| Required tools | No | Part of the capability contract. |
| Skills | No | Bound at definition time. |
| Governance tier | No | Set by the definition author. |
| Model | Yes | Can swap model, but not below minTier. |
| Extension prompt | Yes | Additional context for this deployment. |
| Optional tools | Yes | Can add tools from the optional set. |
| Constraints | Yes | Can tighten (never loosen) timeout, tool call limits, sandbox mode. |
🛡️ Governance
Every agent definition carries governance metadata:| Field | Type | Purpose |
|---|---|---|
tier | string | Agent tier: operator, department, or personal |
trustLevel | number (1—10) | Autonomy score. 1—3 = supervised, 4—6 = semi-autonomous, 7—10 = autonomous. |
dataScope | string | Declared data access boundary (e.g., "tickets:read,slack:post") |
🤖 The Agent Fleet
Agents are organized into tiers that determine their authority scope, model assignment, and governance requirements.Agent Tiers
| Tier | Scope | Governance | Example |
|---|---|---|---|
| Operator | Platform-wide coordination | Highest trust required. Changes audit-logged. | Factory Manager (gloo) |
| Department | Single domain or function | Moderate governance. Budget-capped. | Finance (sage), Legal (ivy), Trust & Safety (knox) |
| Individual | Single-user assistant | Personal trust boundary. | cleo, pearl |
| Specialized | Task-specific, no persistent identity | Ephemeral. Spun up per-task. | Workflow step executors |
Built-in Agents
| Agent | Tier | Execution | Model | Role |
|---|---|---|---|---|
| gloo | Operator | Convex-native | Sonnet | Platform coordinator, cross-cutting operations, Factory Manager |
| sage | Department | Bridge | Sonnet | Finance — analysis, approvals, budget oversight |
| ivy | Department | Bridge | Sonnet | Legal — contracts, compliance, regulatory review |
| knox | Department | Bridge | Sonnet | Trust & Safety — policy, risk, incident response |
| cleo | Individual | Bridge | Opus | Full-capability personal assistant |
| pearl | Individual | Bridge | Opus | Full-capability personal assistant |
| hazel | Specialized | Bridge | Sonnet | General-purpose, restricted tool access |
| piper | Specialized | Bridge | Sonnet | General-purpose assistant |
| atlas | Specialized | Bridge | Sonnet | General-purpose assistant |
🔀 Dual Execution Model
Forge runs two execution paths, and the agent definition model works for both.DUAL EXECUTION MODEL
Agent Definition
executionModel: “native” | “managed"
"native” ↙↘ “managed”
Convex-Native· Durable AgentsRuns inside Convex via @convex-dev/agents. Persistent threads, tool access, durable state. Does NOT go through Bridge.
Factory MgrTask ManagerCopilot
Bridge-Dispatched· Gateway WorkersRouted through Bridge to gateway adapters. Stateless per-step. Callbacks return results to Convex.
OpenClawClaude Agent SDKVercel AI
Bridge (Execution Router)
When to Use Which
| Use Case | Execution Path | Why |
|---|---|---|
| Factory orchestration | Convex-native | Needs durable state, persistent threads, tool access within Convex |
| Workflow step execution | Bridge-dispatched | Steps are stateless units of work routed to the best available runtime |
| Copilot analysis | Convex-native | Needs access to Convex data for run analysis and recommendations |
| Chat-based agent work | Bridge-dispatched | Gateway handles session state, model selection, tool execution |
executionModel field on the agent definition declares which path is used: "managed" for Bridge-dispatched, "native" for Convex-native.
🔍 Agent Discovery
Agent definitions support discovery via thepublishedForDiscovery flag. When enabled, the agent’s identity and capabilities are exposed through the , allowing other agents and external systems to discover and interact with the agent programmatically.
🗂️ Registries
All three layers of the capability model are formally registered in Convex:- Agent Definitions (
agentDefinitions) — the canonical agent registry. Stores layers 1—3. - Agent Deployments (
agentDeployments) — layer 4 bindings. Links definitions to gateways with provider-specific config. - Skill Definitions (
skillDefinitions) — skill content, metadata, quality review status. See Skills & Tools. - Model Catalog (
modelCatalog) — multi-provider model inventory with capabilities and cost data. See Models.
The four-layer definition model separates what an agent is from where it runs. This means the same agent definition can be deployed to OpenClaw today and Claude Agent SDK tomorrow — without changing a single field in layers 1—3.