Skip to main content
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. For the underlying execution model, read Convex-Native Agents. This page focuses on the authoring decisions.

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.
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.

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. 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.

Decide once vs decide per node

The hardest authoring mistake to undo is overloading the definition with capabilities the agent rarely needs. 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; 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 — 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. For the dispatch-time resolution flow, see Agent 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 — platformQuery, runAnalysis, graphAuthoring, factoryDispatch, etc. Each name maps to a fixed list of tools; see Tool sets. 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.
  • 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 for provider and policy setup. For the canonical tool registry and what each tool set contains, see Tool sets.

Set governance metadata

Four fields drive the Trust Fabric pipeline at dispatch: For the gate order, see the generated sequence on Trust Fabric concepts; for each gate’s inputs, see Governance Pipeline.

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. 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