Skip to main content
This quickstart covers the complete integration path: credential, agent, readiness, workflow, durable run, and readback. Pick the tab for your stack:
  • Console walkthrough uses Console for workflow authoring and HTTP API v3 for integration. Start here if this is your first run; the other tabs dispatch the workflow it publishes.
  • Raw HTTP walks the API from any HTTP client, with curl examples.
  • Next.js calls Forge from a Next.js server route and deploys it to Vercel.
An AI host such as Claude Code uses the MCP host quickstart instead.

Prerequisites

You need Console access for agent setup and workflow authoring, an External App owned by an org unit, and curl plus jq. Use a deployment with an available inference provider and a model your agent can use. Creating an agent is reserved for External App credentials. See Access and credentials before continuing if you do not have these.

1. Prepare a caller

In Console, register an External App owned by an org unit, and give it roles holding agents:read, agents:write, workflows:use and runs:read, plus switches:use at platform scope for the activation in step 3. Of the system roles, only Platform admin holds switches:use. Request matching token scopes; scopes only narrow the app’s role grants. See Access and credentials.
Store the secret server-side and renew the token before its expires_in lifetime ends. The granted permissions can be narrower than the requested scopes.

2. Create the agent

Send JSON with bearer auth to POST /api/v3/agents. Use a stable agent identifier and idempotency key for this creation intent:
With no status, the agent is created as a draft, homed at the app’s owning org unit.

3. Activate the agent

Activating gives the agent the worker that runs its workflow steps. A status change is an operator control: without switches:use at the platform the request is 403 forbidden and nothing changes. Active status does not bypass readiness, permissions, tool credentials, or governance checks at dispatch.

4. Finish the agent’s setup in Console

An agent created by an org-unit-owned External App has no owner, sits in no position, and has no attested identity, so the runtime refuses to give it work until a person finishes its setup. Open Workforce → Agents, select Demo Summariser, and on its Overview tab work through Ready to run until the status reads Ready:
  1. Choose a position places the agent in a vacant position an agent can hold, or Create a position makes one. Choose a Job then gives that position its Job.
  2. Assign owner names the person who answers for the agent; then Acknowledge review if the checklist asks for it.
  3. Attest identity confirms the owner and the agent’s current definition.
  4. Give Access appears only if the agent lacks the Access its steps need.
Each fix names the permission it needs; without it, Request setup sends the gaps to people who hold it. See Check that an agent is ready to run.

5. Publish a workflow in Console

In Console, open Production → Workflows and create a workflow. The builder names a new workflow untitled-workflow-<timestamp>; click the name and rename it summarise-input, because the dispatch calls below find the workflow by that name. Then:
  1. Add a required workflow input named text with type string.
  2. Add an Agent step named summarise.
  3. Set Assigned to → AI and select Demo Summariser. The picker shows each agent’s readiness; it should read Ready.
  4. In the step’s Prompt, write Summarise this text: {{workflow.text}}. A new Agent step declares no inputs, so there is nothing to bind: {{workflow.text}} reads the run’s text argument directly. See Reference a workflow input from inside a node.
  5. In the step’s Properties panel, add an output named summary under Outputs; a new output is a string. Leave the step’s Validation Strategy on Schema, its starting value. summarise is the last step, so its summary becomes the workflow’s output; the builder has no separate workflow-output editor. See Declare step and workflow outputs. Then publish the draft and record its active version.
If the publish check reports a missing agent, worker, owner, output, or permission, fix that gate rather than overriding it. Programmatic authoring is documented under the generated workflow operations; MCP hosts can use forge_ask_workflow_architect to propose and revise a draft.

6. Dispatch one logical intent

Choose an explicit Idempotency-Key for this logical dispatch intent. Keep that key if a timeout leaves the outcome unknown; use a new key only for a deliberately new run.
The response uses {data,meta} and includes meta.requestId. For a failed or unknown mutation outcome, reconcile the authorized resource state before deciding whether another effect is appropriate.

7. Inspect the run

Copy data.runId from the dispatch response. Open that run in Console to inspect status, holds, evidence, and output. For a direct read:
A successful dispatch means a run was accepted; it does not mean the work completed. Check the returned run status and any hold or failure before using its output. For paginated run history, follow meta.nextCursor while meta.hasMore is true.Read the HTTP conventions and errors pages for response metadata, denial handling, and retries.

Next steps