The end state
When the recipe is done:- The agent definition has a stable
agentId,name,agentType: "WORKER", prompt, model configuration, and governance classification. - A unique active
workersrow pairs the agent with the organization; dispatch refuses an invalid or ambiguous pairing. - Skill and tool-set grants live in canonical assignment tables, while context-bound tools such as
file_get,file_put,load_skill, andsandbox_actionare injected only by eligible dispatch sites. - A test workflow completes with an expected
stepResultsrecord, a governance decision, and the tool/model evidence relevant to the path you exercised.
Prerequisites
- An External App token to create the agent, with
agents:writeandagents:readat the app’s owning org unit. The create call this recipe uses,POST /api/v3/agents, accepts only an External App token. Activating it needsswitches:useat the platform. - Console access to finish the agent’s Ready to run checklist (owner, position and identity) and to publish the test workflow.
- A Personal key or platform API key with
workflows:useto dispatch the test workflow andworkflows:readwhere the run lives to read its audit packet. The audit packet refuses an External App token.
The four steps
1
Define the agent
Create a workspace agent through Workforce → Agents → New. Platform-shipped system agents are source-controlled fixtures and are not an appropriate starting point for an operator recipe. The persisted contract is component-owned; the public create body (The create body carries no grants, governance or constraints: set skill and tool-set grants, the governance tier (worker, personal, or system, not a numeric autonomy level) and constraints in Console. The independent autonomy rung is one of
POST /api/v3/agents) takes these fields:assistive, retrieval, supervised, or bounded and is managed by the agent controls that enforce rung transitions. Seat the Worker agent in the org chart and confirm exactly one active AGENT worker points at the definition before testing dispatch.2
Bind skills and tools
Skills provide reusable instructions; tool sets grant static capabilities. Forge records each grant as its own skill or tool-set assignment on the agent and resolves them at dispatch through agent composition. They are not lists stored inside the agent definition.For this recipe, author a workspace skill (use Expected result: the agent detail shows the two skill grants and only the selected static tool set. The test workflow additionally advertises
contract-summarizer-system for this example) in Platform → Skills → Create, or with POST /api/v3/skills, then activate it. See Skill Authoring for the three authoring paths and the review a skill passes before activation.Select the narrowest live sets shown by Platform → Tools and the TOOL_SETS reference. Do not invent a READ_ONLY set. A workflow node with a declared file input/output receives bound file_get and file_put tools from the dispatch context; those tools cannot be granted through an assignment.file_get / file_put because its node contract authorizes file input/output. A grant narrows the tool surface; it does not prove the prompt, external system, or data itself is safe. Trust Fabric decisions, credential scope, file bindings, and provider controls remain independent boundaries.3
Wire governance and budgets
Choose an autonomy rung from the action profile you intend to allow.
retrieval is appropriate for a summarizer that reads bounded inputs and returns a result; supervised or bounded is relevant only when the agent performs controlled writes. Do not map command tiers (Tier 1 typed catalog commands and Tier 3 free-form sandbox commands) onto agent autonomy—they are different contracts.If the agent must always pause for review before running, attach an approval policy to the agent or the workflow node that dispatches it. The hold disposition that the approvalRequired gate records when the policy matches is what creates the row in approvals — see the approval lifecycle flow for the state machine.Attach the applicable budget through the budget surface and add an approval policy if this workflow must pause. There is no defaultBudgetUsd field on the agent definition. Run preflight and confirm the intended policy and envelope are selected before launch.4
Observe what it did
Launch a workflow that supplies one non-sensitive test contract and declares one structured summary output. Verify each system in its own operator surface:
- Run detail: the node reaches the expected terminal status and its
stepResultsrow identifies the agent, model used, timing, and output. - Trust Fabric decisions: the launch/dispatch decision shows the real subject and disposition; a hold is released only through the linked approval.
- Tool activity:
file_getreads only the input file ID, andfile_putbinds the result to the declared output key. - Cost and audit views: token/cost records and lifecycle/configuration events appear where that path emits them. Do not claim a single
auditEventsrow is the universal store for all four kinds of evidence.
Do it over the API
These calls use theFORGE_BASE and ACCESS_TOKEN set up in the Raw HTTP tab of the quickstart. The two ends need different credentials: creating the agent accepts only an External App token, and reading the audit packet refuses one, so read it with a Personal key or a platform API key. The HTTP create takes the identity, model and prompt fields; set skill and tool-set grants, governance and constraints in Console.
Create the agent. This call accepts only an External App token, and the app owns the agent:
agents:write and agents:read at the app’s owning org unit; an unknown field is 400. The agent is created as a draft. Activate it, which also gives it the worker that runs its steps; a status change needs switches:use at the platform:
runtimeArgs matching its inputs), which needs workflows:use:
workflows:read where the run lives:
forge_call_operation:
forge_call_read_operation:
When to reach for something else
- You want the agent to act outside the workflow graph. Chat, factory, copilot, and PA dispatch sites all run governance and write audit, but they are conversational rather than DAG-driven. Use a workflow when you need retry, checkpoint, or HITL approval; use chat when you need a back-and-forth with a human in a session.
- You only need a local experiment. Prototype outside a production workflow, then bring it into Forge when you need governed identity, durable execution, and operator evidence.
- You need the agent to persist working memory across sessions. Add a memory configuration — the three-layer model (session, channel, long-term) handles continuity without expanding the audit surface.

