Skip to main content
This recipe creates a workspace Worker agent, grants only the capabilities it needs, runs it through a workflow, and verifies the evidence Forge actually records. Audit coverage is path-specific: governance decisions, model usage, tool execution, and workflow results have related but distinct records. Verification is therefore part of shipping, not an assumption.

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 workers row 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, and sandbox_action are injected only by eligible dispatch sites.
  • A test workflow completes with an expected stepResults record, 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:write and agents:read at the app’s owning org unit. The create call this recipe uses, POST /api/v3/agents, accepts only an External App token. Activating it needs switches:use at 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:use to dispatch the test workflow and workflows:read where 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 (POST /api/v3/agents) takes these fields:
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 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 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.
Expected result: the agent detail shows the two skill grants and only the selected static tool set. The test workflow additionally advertises 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 stepResults row 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_get reads only the input file ID, and file_put binds 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 auditEvents row is the universal store for all four kinds of evidence.
Recovery: if the run is refused, start from the governance explanation and worker pairing. If file access is refused, compare the workflow node’s declared file inputs/outputs with the concrete file IDs and output key. If the model differs, inspect the node override, routing decision, and active catalog status before changing the agent.

Do it over the API

These calls use the FORGE_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:
This needs 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:
An agent the app creates has no owner, position or attested identity yet. Before publishing the test workflow, finish its setup on the agent’s Ready to run checklist in Console; see Check that an agent is ready to run. After the test workflow is published, dispatch it (use your workflow’s name and add runtimeArgs matching its inputs), which needs workflows:use:
Read the run’s audit packet, which needs workflows:read where the run lives:
Audit explains each field of the packet. Over MCP, dispatch with forge_call_operation:
and read the packet with 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.