> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Define an agent

> How to author a Forge agent — the three definition layers, the dispatch pipeline you're feeding, and the decisions you make once vs the ones you make per node.

Last updated 2026-11-11

·
applies to 2026-11-07

·
main

This guide is for the operator authoring a new agent — picking its purpose, attaching its skills, declaring which tools it may invoke, and setting the governance metadata that the Trust Fabric reads at dispatch. The thing you are filling in is an agent definition; the thing it becomes is a worker.

For the dispatch-time mechanics — how Forge reads your definition and builds the agent's configuration on every turn — read [Agent composition](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-composition). For the underlying execution model, read [Convex-Native Agents](https://docs.gloo.com/forge/architecture/system-overview.md#agent-dispatch). This page focuses on the authoring decisions.

When to reach for something else

If you only need a one-off LLM completion — no governance, no skills, no audit trail — call the model SDK directly from your own code. Forge is the production layer. It carries cost: a row to maintain, a Trust Fabric pipeline to satisfy, an audit log that grows. If you need a workflow node to run a single anonymous prompt and never run again, the workflow's inline prompt field is the right path. Reach for an agent definition when the same identity will run more than once, will be assigned skills, will appear in analytics, or will need a manager to oversee it.

***

## Create and activate an agent

Create the agent in Console, or over the API from an External App. The sections after this one explain each decision the form asks for.

> [tab] Console
>
> **1. Open the create form**
>
> In Forge Console, open **Workforce → Agents** and click **Create Agent**. (**With Agent Builder** starts a guided conversation instead.)
>
> **2. Fill in Identity**
>
> Enter a **Name** and an **Agent ID**; both are required. The Agent ID is the agent's stable slug, used in API paths. Add a **Purpose** (one sentence), a **Description** and **Tags** if you want them.
>
> **3. Write the core prompt and pick a model**
>
> Under **Core Prompt**, write the instructions the agent always carries. Under **Model**, pick a **Model ID** from the catalog; a model that is not in the catalog is refused.
>
> **4. Set constraints and governance**
>
> Set **Max Tool Calls** and **Timeout Seconds** under **Constraints**, then the **Tier** and **Data Scope** under **Governance**. **Risk Classification** sets the agent's autonomy rung.
>
> **5. Deploy**
>
> Click **Deploy Agent**. If its risk tier allows auto-approval, the agent is created as a `draft`; click **Finish setup** to give it a position, an owner and the Access it needs to run. A higher-risk agent is **pending review** instead: the request goes to an approver, and **View Approvals** opens the queue.
>
> **6. Clear the readiness checks**
>
> The agent's overview shows its **Ready to run** card. Each blocking check offers the fix that clears it, such as choosing a position, assigning an owner or granting Access. A `draft` agent has no worker yet, so its card starts blocked on its worker, and the position, owner and Access checks wait for that worker. Activating the agent creates its worker. The Console has no activate control: its status controls are the emergency-stop pause, resume and terminate, and the agent edit form never changes status. The worker check's fix says so: only the platform team can clear it for an agent created in the Console. The activation in the HTTP API and MCP tabs works only for an agent an External App created, on that app's own credential, and needs `switches:use`, which the Platform admin role holds. After activation, clear the remaining checks and read the card again.

> [tab] HTTP API
>
> These calls use the `FORGE_BASE` and `ACCESS_TOKEN` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md). Creating an agent requires an **External App** credential: the app owns the agent, which is homed at the app's owning org unit, and any other credential is `403 forbidden`. The app needs `agents:write` and `agents:read` there.
>
> ```bash theme={null}
> curl -sS -X POST "$FORGE_BASE/api/v3/agents" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -H "Idempotency-Key: support-triage-create-v1" \
>   -d '{
>     "agentId": "support-triage",
>     "name": "Support Triage",
>     "description": "Triages incoming support tickets by urgency.",
>     "purpose": "Sort incoming support tickets by urgency.",
>     "status": "draft",
>     "prompt": { "core": "You triage support tickets. Reply with urgency (low, medium, high) and one sentence of reasoning." },
>     "model": { "default": "anthropic/claude-haiku-4-5" }
>   }' | jq '.data | {id, agentId}'
> ```
>
> The body is strict; an unknown field is `400 bad_request`, and an existing `agentId` is `409 conflict`. Then read the agent's readiness report. Each check says whether it blocks dispatch and which governance gate applies it:
>
> ```bash theme={null}
> curl -sS "$FORGE_BASE/api/v3/agents/support-triage/readiness" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" \
>   | jq '.data | {status, blocking: [.checks[] | select(.blocksDispatch) | {id, message, action}]}'
> ```
>
> `status` is `ready`, `attention` or `blocked`. A new `draft` agent reports `blocked`: `worker_present` fails because it has no worker yet, and the position, owner and Access checks wait for that worker. Activating the agent creates its worker. Only the External App that owns the agent can change its `status` with a patch; a platform or personal key can patch the agent's definition fields but not its status. A patch that changes `status` is an operator control, so the app also needs `switches:use` at the platform, which the Platform admin role holds:
>
> ```bash theme={null}
> curl -sS -X PATCH "$FORGE_BASE/api/v3/agents/support-triage" \
>   -H "Authorization: Bearer $ACCESS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -H "Idempotency-Key: support-triage-activate-v1" \
>   -d '{ "status": "active" }' | jq '.data'
> ```
>
> Then read the readiness report again and clear each check that still blocks, such as the agent's position, owner and Access, until `status` is `ready`.

> [tab] MCP
>
> The MCP call tools run as the connection's credential, so creating an agent works only on a connection made with External App credentials (a local server); a Personal key or a person's hosted sign-in is refused. `forge_call_operation` and `forge_call_read_operation` are in the default `start` job.
>
> Create the agent with `forge_call_operation`:
>
> ```json theme={null}
> {
>   "operationId": "createAgent",
>   "idempotencyKey": "support-triage-create-v1",
>   "input": {
>     "agentId": "support-triage",
>     "name": "Support Triage",
>     "description": "Triages incoming support tickets by urgency.",
>     "purpose": "Sort incoming support tickets by urgency.",
>     "status": "draft",
>     "prompt": { "core": "You triage support tickets. Reply with urgency (low, medium, high) and one sentence of reasoning." },
>     "model": { "default": "anthropic/claude-haiku-4-5" }
>   }
> }
> ```
>
> Read its readiness with `forge_call_read_operation`:
>
> ```json theme={null}
> { "operationId": "getAgentReadiness", "input": { "id": "support-triage" } }
> ```
>
> A new `draft` agent reports `blocked` until it is activated, because it has no worker yet. Activate it with `forge_call_operation`, which creates the worker, then read the readiness again and clear what still blocks:
>
> ```json theme={null}
> { "operationId": "updateAgent", "idempotencyKey": "support-triage-activate-v1", "input": { "id": "support-triage", "status": "active" } }
> ```

***

## The three layers of a definition

Every agent is three concentric layers. You author them top to bottom; the platform reads them bottom up at dispatch.

THE AGENT DEFINITION — IDENTITY, CAPABILITY, RUNTIME

<ol aria-label="THE AGENT DEFINITION — IDENTITY, CAPABILITY, RUNTIME" />

**Identity** is the contract with the rest of the platform — the name a human sees in chat, the agent ID a workflow node references, the kind (`WORKER`, `PERSONAL`, or `SYSTEM`), the owner who answers when something goes wrong. Identity is the cheap layer to change later; rename freely.

**Capability** is the expensive layer. `skills[]` lists the skill IDs the agent is *permitted* to use; `toolSets[]` lists the named tool sets it may receive at dispatch. Both are intersected with workflow-node `capabilityHints` at dispatch time, so adding a skill to the definition is a permission grant, not a guarantee that every node uses it. Get capability right and per-node tuning becomes a one-line override; get it wrong and you fork the definition into three near-clones.

**Runtime** is what the agent runs *as* — the model (default + constraints), the core prompt, the per-skill token budget, the maximum tool-call count, the timeout. Runtime is the layer that varies most across deployments — Haiku in dev, Sonnet in production — and the layer where role bindings let the same definition target different model fleets without copying it.

Native execution

Current create contracts accept `executionModel: "native"` and default to it when omitted. Native execution uses Forge's governed runtime; execution placement can still be inline or detached.

***

## Decide once vs decide per node

The hardest authoring mistake to undo is overloading the definition with capabilities the agent rarely needs.

| Decision | Live where? |
| - | - |
| **Identity, tier, owner, governance metadata** | Definition. Stable across nodes. |
| **The full set of skills the agent could ever need** | Definition's `skills[]` (permission). |
| **The full set of tool sets the agent could ever invoke** | Definition's `toolSets[]` (permission). |
| **Default model + cost ceiling** | Definition's `model.default` and `constraints`. |
| **Which subset of skills/tools applies to *this* node** | Workflow node's `capabilityHints`. |
| **The exact prompt for *this* node** | Workflow node's `prompt`. |
| **Which model variant to use in staging vs prod** | Deployment-level role binding (overrides the definition). |

Capability sprawl is the most common cause of slow, unfocused agents. A definition with 12 skills permitted runs every dispatch with a 12-skill budget calculation; the workflow node's `capabilityHints.skills` narrows it down for the dispatch, but a definition that genuinely uses 12 skills across dozens of nodes is *one* agent doing the work of three. Split it.

The reverse mistake — forking the definition every time you need a new prompt — produces a fleet of near-identical definitions whose drift no operator can audit. Use **node-level prompts** and **role bindings** before you copy a definition.

***

## Pick a starting point: template, fork, or blank

Three paths into a fresh definition:

* **Template.** A reusable blueprint — base definition + pre-attached skills + default model + governance constraints. Browse the gallery in Forge Console (Workforce → Agents → Templates), pick one (Code Reviewer, Technical Writer, Research Analyst, Personal Agent), customise the extension prompt and the optional tool sets, and activate. The new row is fully independent from that point on. Templates carry **usage counts** so you can see what's adopted; they're versioned and tagged separately from the agents deployed from them. Choose a template when its role and constraints match your task.

* **Capture.** Export an existing running agent as a template, then deploy from that. Useful when you've tuned a chat agent into shape and want to fan it out across teams without manually re-creating its skill stack.

* **Blank.** The from-scratch form, for a role no template fits. The platform's own system agents (including Factory Manager, Factory Worker, Task Manager, Forge Analyst, the authoring agents such as Workflow Architect and Skill Builder, and the judge agents) are not built this way: Forge seeds them with the platform, and a workspace does not author them.

For the dispatch pipeline that builds the agent at runtime, see [Agent composition](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-composition); the composition step is the same regardless of how the row was created.

***

## Attach skills

`agentDefinitions.skills[]` is a list of skill IDs the agent is **permitted** to use. Every entry must already exist in [the skill catalog](https://docs.gloo.com/forge/build/author-a-skill.md) — assigning a skill that doesn't exist is a validation error.

Pattern that works: keep the permitted set narrow but not micro-narrow.

* A Factory Worker permitted to use `software-engineering`, `code-review`, `verification-before-completion` is doing real work. Each skill carries weight.
* A Factory Worker permitted to use 11 skills, half of which never get activated by any node, is signalling "I don't know what this agent does."

Skills declare an `activationMode`:

* **`always`** — full skill content inlined into the system prompt every turn. Use for short, consistently-relevant skills.
* **`on_demand`** — one-line menu entry; the agent calls the `load_skill` tool when needed. Use for bulky reference material (>1000 tokens) or rarely-needed skills.

When you attach a skill to a definition, you also accept its `allowedTools` constraint. A skill that declares `allowedTools: ["queryOrgChart", "queryPeople"]` will refuse any other tool call while that skill is active — the constraint enforces at the tool wrapper, not at compose time. Read the skill's content before you attach it.

For the full skill-authoring path — platform skills (builtin and Anthropic), workspace (Console or API), imported (marketplace/ClawHub) — see [Author a skill](https://docs.gloo.com/forge/build/author-a-skill.md). For the dispatch-time resolution flow, see [Agent composition](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-composition).

***

## Attach tool sets

The agent's `toolSets[]` lists the named tool sets the agent may receive. Tool sets are the unit of [tool grouping](https://docs.gloo.com/forge/concepts/tool-registry.md) — `platformQuery`, `runAnalysis`, `graphAuthoring`, `factoryDispatch`, etc. Each name maps to a fixed list of tools; see [Tool sets](https://docs.gloo.com/forge/reference/tool-sets.md).

The same intersection logic applies: the workflow node's `capabilityHints.toolSets` narrows the resolved tool set per dispatch, so add tool sets to the definition that the agent could legitimately need across all its dispatch sites — the per-node intersection handles narrowing.

A few injections happen automatically and don't need to be declared:

* **`load_skill`** — auto-injected whenever any `on_demand` skill is permitted.
* **`file_put`** — injected when a dispatch may write files. For a workflow output, the call uses a `workflow_output` binding with one of the node's declared output keys and returns a `fileId`. The legacy `putFile` name is a deprecated alias. See [Files and bindings](https://docs.gloo.com/forge/architecture/files-and-bindings.md).
* **Skill-constrained wrappers** — when an active skill declares `allowedTools`, every tool is wrapped with a refuse-at-call-time check. Refusals log to `toolExecutionLog` as `refused_by_skill_constraint`.

For **isolated code execution**, configure a sandbox capability and let the dispatch site inject `sandbox_action`. It is not a static tool-set member and cannot be granted by naming it in an agent definition. Follow [Configure a sandbox](https://docs.gloo.com/forge/build/configure-sandbox.md) for provider and policy setup.

For the canonical tool registry and what each tool set contains, see [Tool sets](https://docs.gloo.com/forge/reference/tool-sets.md).

***

## Set governance metadata

Four fields drive the Trust Fabric pipeline at dispatch:

| Field | Purpose |
| - | - |
| `agentType` | `WORKER`, `PERSONAL`, or `SYSTEM`: what kind of agent this is. Older definitions carried the kind as `governance.tier` (`worker`, `personal`, `system`, or the legacy `operator`). Not the agent's `tier` field, which is its LLM routing tier (`nano`, `low`, `mid`, `high`, or `frontier`). |
| `rung` | The autonomy rung: `assistive`, `retrieval`, `supervised`, or `bounded`. Coarser banding that informs approval routing. Read by the `autonomyHoldTable` gate (13th in the engine sequence); an agent with no stored rung is evaluated as `assistive` when it acts in a position and as `supervised` outside one. |
| `dataScope` | Declared data-access boundary string (e.g., `"tickets:read,slack:post"`). Stored, but no governance gate currently reads it — the `nhiEntitlement` gate (14th) grades a credential-scope result from the NHI provider. |

Agent composition does not run Trust Fabric

This is the single most common misunderstanding. Agent composition builds the agent's prompt, skills, tools and model. It does not run governance gates. Each dispatch (chat, factory, copilot, personal agent, Architect, workflow Agent node) runs the Trust Fabric gate sequence separately, before the turn. See [Coverage](https://docs.gloo.com/forge/run/trust-fabric.md#coverage-—-what-runs-through-governance-and-what-does-not).

For the gate order, see the generated sequence on [Trust Fabric concepts](https://docs.gloo.com/forge/concepts/trust-fabric.md#the-gate-sequence); for each gate's inputs, see [Governance Pipeline](https://docs.gloo.com/forge/architecture/flows/governance-pipeline.md).

***

## Walk the lifecycle

An agent definition is a single dimension on the row: `draft → active → deprecated → archived`. Composition happens at dispatch time, so a change to an `active` row takes effect on the **next dispatch** — there is no rollout window, no caching layer, no redeploy step.

| Stage | Resolvable? | Purpose |
| - | - | - |
| `draft` | No | Authoring in progress. Not visible to dispatch. |
| `active` | Yes | The primary operational state. Editable; every change is captured in `agentConfigRevisions`. |
| `deprecated` | Yes (with warning) | Migration window — every dispatch logs a deprecation warning. |
| `archived` | No | Terminal. Preserved for audit and revision diffs. |

Suspension is an **out-of-band** control independent of the lifecycle stage — an active agent can be suspended in response to an incident, blocked at the `agentStatus` gate (3rd in the engine sequence), and reinstated later. Suspension entries appear in the audit trail with the actor and reason.

Every revision is recorded in `agentConfigRevisions` with field-level diff, actor, and timestamp — the Forge Console **Revisions** tab shows the diff viewer, and rollback to any prior revision is a single mutation.

In-flight turns finish with the config they were composed from. There is no mid-turn config swap, even for `prompt.core` changes.

***

## What you should double-check before activating

* **Permitted skills are narrow.** If you attached six and only three matter, drop the other three.
* **Default model matches the role.** Chat assistants on Haiku; factory workers on Sonnet/Opus where reasoning matters; analytics agents on whatever the cost-per-run column tolerates.
* **`maxToolCalls` and `timeout` are realistic.** A chat agent at `maxToolCalls: 50` is asking for runaway loops; a factory worker at `timeout: 60_000` will time out before the build finishes. Look at similar operator agents and copy their constraints.
* **`executionModel: "native"` is set.** Always.

***

## See also

* [Agent composition](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md#2-composition) — how Forge builds an agent's configuration from its definition for each dispatch
* [Agent dispatch](https://docs.gloo.com/forge/architecture/system-overview.md#agent-dispatch) — how agent turns are dispatched
* [Author a skill](https://docs.gloo.com/forge/build/author-a-skill.md) — the three skill-authoring paths and the canonical skill shape
* [Configure a sandbox](https://docs.gloo.com/forge/build/configure-sandbox.md) — when and how to give an agent isolated code execution
* [Workforce Concept](https://docs.gloo.com/forge/concepts/workforce.md) — why agents are workers, not bots, and what that buys you
* [Tool Sets reference](https://docs.gloo.com/forge/reference/tool-sets.md) — the canonical tool registry


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.