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.- Console
- HTTP API
- MCP
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.
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-completionis 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.”
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 theload_skilltool when needed. Use for bulky reference material (>1000 tokens) or rarely-needed skills.
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’stoolSets[] 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 anyon_demandskill is permitted.file_put— injected when a dispatch may write files. For a workflow output, the call uses aworkflow_outputbinding with one of the node’s declared output keys and returns afileId. The legacyputFilename 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 totoolExecutionLogasrefused_by_skill_constraint.
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.
maxToolCallsandtimeoutare realistic. A chat agent atmaxToolCalls: 50is asking for runaway loops; a factory worker attimeout: 60_000will time out before the build finishes. Look at similar operator agents and copy their constraints.executionModel: "native"is set. Always.
See also
- Agent composition — how Forge builds an agent’s configuration from its definition for each dispatch
- Agent dispatch — how agent turns are dispatched
- Author a skill — the three skill-authoring paths and the canonical skill shape
- Configure a sandbox — when and how to give an agent isolated code execution
- Workforce Concept — why agents are workers, not bots, and what that buys you
- Tool Sets reference — the canonical tool registry

