- 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
curlexamples. - Next.js calls Forge from a Next.js server route and deploys it to Vercel.
- Console walkthrough
- Raw HTTP
- Next.js
Prerequisites
You need Console access for agent setup and workflow authoring, an External App owned by an org unit, andcurl 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 holdingagents: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.expires_in lifetime ends. The granted permissions can be narrower than the requested scopes.2. Create the agent
Send JSON with bearer auth toPOST /api/v3/agents. Use a stable agent identifier and idempotency key for this creation intent:status, the agent is created as a draft, homed at the app’s owning org unit.3. Activate the agent
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:- 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.
- Assign owner names the person who answers for the agent; then Acknowledge review if the checklist asks for it.
- Attest identity confirms the owner and the agent’s current definition.
- Give Access appears only if the agent lacks the Access its steps need.
5. Publish a workflow in Console
In Console, open Production → Workflows and create a workflow. The builder names a new workflowuntitled-workflow-<timestamp>; click the name and rename it summarise-input, because the dispatch
calls below find the workflow by that name. Then:- Add a required workflow input named
textwith typestring. - Add an Agent step named
summarise. - Set Assigned to → AI and select Demo Summariser. The picker shows each agent’s readiness; it should read Ready.
- 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’stextargument directly. See Reference a workflow input from inside a node. - In the step’s Properties panel, add an output named
summaryunder Outputs; a new output is astring. Leave the step’s Validation Strategy on Schema, its starting value.summariseis the last step, so itssummarybecomes 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.
forge_ask_workflow_architect to propose and revise a draft.6. Dispatch one logical intent
Choose an explicitIdempotency-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.{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
Copydata.runId from the dispatch response. Open that run in Console to inspect status, holds, evidence, and output. For a direct read:meta.nextCursor while meta.hasMore is true.Read the HTTP conventions and errors pages for response metadata, denial handling, and retries.Next steps
- HTTP conventions, errors, and idempotency for response metadata, denial handling, and retries.
- Choose an interface to compare Console, HTTP API v3, and MCP.
- MCP host quickstart to use Forge as tools inside an AI host.

