When to reach for something else
- A two-node sequential workflow is faster to draft by hand in the builder than to converse with the Architect about. Reach for the Architect when there’s real structure — branches, joins, human gates, multiple agents.
- Edits that are purely cosmetic — renaming a node, tightening a description — are quicker on the canvas. The Architect’s strength is structural reasoning, not button-clicking.
- You already have a published version that runs cleanly and you only want to tweak one prompt. Edit the agent definition directly. Don’t open the Architect to perturb a working graph.
- Truly novel orchestration — patterns the Architect’s
workflow-authoringskill doesn’t recognize — may need a hand-authored prototype first. Once you’ve shown the shape works, the Architect can replicate it for the next 10 graphs that look similar.
The authoring loop
The Architect’sworkflow-authoring skill enforces a four-phase discipline on every turn — plan, execute, checkpoint, final-validate — but from the operator side the loop is simpler: state intent, watch the proposal, review on the canvas, ship. The discipline exists so the proposal is structurally sound before it lands in front of you.
The plan guardrails are in Plan cards below. MCP hosts can ask the Architect through forge_ask_workflow_architect; sending a message requires a Personal key and confirmation.
How to invoke the Architect
The Architect lives in the workflow builder in the Forge Console at/production/workflows/convex/builder-v2. There are two entry points:
- Ask the Architect (drawer). On any workflow draft, click the purple ✨ Ask the Architect button in the toolbar. A drawer opens on the right, bound to the draft you’re editing. The drawer is a system-scoped DM channel — closing it doesn’t end the conversation; reopening picks up where you left off, with full thread history and graph memory intact.
-
Fix-with-Architect (from a failed run). On a workflow run detail page where
status === "failed", the Fix with Architect action clones the pinned version into a fresh draft, opens a scoped Architect channel, and seeds the conversation with the failure context: the failing step’s name, the structured error, and the node JSON. You arrive in the builder with the drawer open and the Architect already aware of what went wrong. This is the fix-with-architect protocol — see “The fix-with-architect protocol” below.
Attaching files
You can attach one or more files to the conversation so the Architect can work from a source document — a requirements doc, a runbook, a CSV of the inputs your workflow has to handle, a PDF of an existing process. Attachments are available at both entry points:- On the entry screen. When you start a new AI-assisted workflow, stage files alongside your opening message before you submit. The files travel with the first turn.
- Mid-conversation, in the drawer. Attach files to any follow-up message. New attachments join the conversation from that turn forward.
read_attachment tool when a file is relevant to the work at hand. Small text files attached on the current turn are inlined automatically so the Architect can react immediately; everything else is read only if and when the Architect decides it needs to. This keeps large or numerous attachments from crowding out the conversation.
Every file you attach also appears in the builder’s left rail while the drawer is open, so you have a running view of what the Architect is working from. The rail updates reactively as you add files mid-run — no refresh needed.
Attachments are governed like any other file in Forge: each one is checked for your ownership before it reaches the Architect, and the Architect can only read the files attached to this conversation’s channel.
Phrasing intent that produces good graphs
The Architect translates intent into structure. Sharp intent yields sharp graphs; vague intent yields graphs that look right and behave wrong. The patterns that work — and the ones that confuse the Architect — fall into a small number of buckets.Intent that produces good graphs
-
State the trigger, the work, the destination. “On a Slack message in
#vendor-risk, classify the vendor, look up the risk score, and post a summary back to the thread” gives the Architect three nodes, two edges, a clear input shape, and a publish target. It will draft the graph on the first turn and walk you through it. -
Name the human gates. “Before any email goes out, a human in
#growth-opsapproves” is a one-line instruction the Architect turns into ahumannode, the right edges in and out, and the approval policy on the human’s input. Don’t trust the Architect to infer where humans belong — it errs on the side of full automation. Tell it. - Be explicit about fan-out / fan-in. “Run the analysis in parallel across the four regions, then join the results” is what the Architect needs to draft a router-and-join shape. Without the word “parallel” it tends toward sequential.
- State the failure mode. “If classification confidence is below 0.7, route to a human; otherwise auto-publish” is a router with two branches and a confidence-based predicate. The Architect handles this well when you give it the threshold and both branches.
-
Reference patterns by name. “Same fan-out/fan-in shape as the vendor-risk workflow” points the Architect at
getExampleGraphsToolpatterns. It will copy the topology, not the specifics.
Intent that confuses the Architect
- “Make it smarter.” Smarter how? The Architect won’t know whether to add a model, change the prompt, swap the skill, or insert a router. State the failure mode and the fix you want.
- Mixing build and run concerns. “Build a workflow and also set up monitoring.” The Architect builds graphs. Observability lives elsewhere in the platform. Keep the conversation about structure.
- Embedded code or implementation details. “Use this regex to extract the company name.” The Architect doesn’t write agent prompts well from regex — and Agent nodes aren’t where regex belongs. Describe the behavior you want; the agent prompt is the Architect’s job.
- Multiple workflows in one ask. “First do A, and also a separate workflow that does B.” Two conversations, two drafts. The Architect operates on the one draft it was opened against.
- Vague success conditions. “Make sure it works.” Works how? “The workflow’s output validates against schema X” is a check; “make sure it works” is not.
When the Architect asks you a question
The skill trains the Architect to ask before structural commitments — three or more new nodes, a rewire that reshapes existing flow. When it does, answer specifically. “Yes, that’s right” with no detail accepts the plan as stated; “Add a human gate before the publish step and rename nodesummarize to summarize-vendor” amends it. The Architect treats your reply as the authoritative plan and proceeds.
Plan cards: propose, then confirm
Before the Architect commits a structural change, it proposes a plan and waits for you:- Search and propose. The Architect searches your workspace catalog for skills, agents and procedures that fit the intent. If something is missing, it asks synthesis to create it. It then shows a plan card: the proposed topology, nodes, edges and missing pieces.
- Wait for you. While a plan card is pending, the Architect’s next turn can use only read-only tools. It can describe and refine the plan as often as you ask, but it cannot write, synthesize or change state.
- Confirm, edit or reject. Choose Confirm to use the plan as proposed, Edit to amend and then confirm it, or Reject. Your decision is recorded.
- Build the graph. On confirmation, the Architect writes the nodes and edges into your draft.
A person can opt in to always proceed. The plan card is still recorded, but it is confirmed
automatically in the same turn. Reserve this for people who already know what the Architect will do.
Search first, then synthesize
Before proposing a plan, the Architect looks for something to reuse:- For each intended node, it searches the workspace catalog for primitives that fit.
- A relevance judge grades each candidate.
- High-scoring candidates are reused; the rest are marked as gaps.
- For each gap, a Builder synthesizes a provisional primitive, within the workspace synthesis budget.
- When synthesis completes, the Architect shows the plan card.
Reviewing the proposal
The Architect’s tool calls render live in the drawer asToolCard rows — createNodesTool, createEdgesTool, validateGraphTool. You see exactly what changed and when. Don’t only read the chat; read the canvas. The chat tells you the Architect’s intent; the canvas tells you the Architect’s effect.
A pre-publish checklist:
The Publish button is in the builder toolbar, not in the drawer. The Architect literally cannot reach it —
publishWorkflowTool lives in a separate tool set (graphAuthoringPublish) that the Architect’s conversational dispatch never receives.
For an outcome-routed draft, also verify that expected business exceptions are declared as output
values and routed separately from technical failures. The Architect may propose the structure, but
publication freezes the runtime contract, failure bindings, and required operator targets. That
marker does not activate production execution: deployment admission is a separate, fail-closed
operator decision. Never ask the Architect to work around an unknown external effect by adding a
retry node; reconcile the retained operation before changing the graph.
The fix-with-architect protocol
When a workflow run fails, the Fix with Architect action is the supported repair path. The flow:- Forge clones the pinned version into a new editable draft.
- A scoped Architect channel is opened for that draft.
- The first system message in the channel carries the failure context —
failingStepName,errorCode,errorMessage, and the failing node’s JSON. - The Architect is not dispatched yet. The channel is seeded.
- You arrive in the builder with the drawer open. Your first user turn is what dispatches the Architect — and that turn passes through Trust Fabric like any other.
- “What failed and why?” — The Architect summarizes the error in plain language, points at the node, and offers a hypothesis. Read it before you tell it what to fix.
- “Fix the routing so this can’t happen again.” — Use this when the failure is structural (e.g., an edge to nowhere, an unguarded API call). The Architect proposes a graph edit.
- “Tighten the prompt on the failing agent so it asks for confirmation when uncertain.” — Use this when the failure is in the agent’s reasoning, not the topology. The Architect rewrites the prompt.
DRAFT_EXISTS error and prompts you to either open the existing draft (and append the new failure context to its Architect channel) or cancel. The one-row-per-workflow draft policy is intentional — you can’t have two parallel “fix” attempts diverging.
What the Architect won’t do
Five guardrails that exist by construction:
These aren’t preferences. They’re enforced in the dispatch path, the tool registry, and the skill content. The Architect is a powerful tool because the boundary is rigid.
Graded by the Architect Judge
Architect turns that materially change the graph are graded by the Architect Judge (judge-architect) on a five-criterion rubric:
The verdict appears on the run with links to the nodes it concerns, and verdicts roll up into judge
metrics over time. A drop in the Architect Judge’s scores is how you see the Architect’s design
quality drift before more graphs ship. See Judges.
Do it over the API
You can hold the same conversation over HTTP. These calls use theFORGE_BASE set up in the Raw HTTP tab of the quickstart, but only a Personal key starts or continues a conversation: the turn acts for the key’s owner, narrowed to the key’s scopes, and an External App or platform API key answers 403 with personRequired: true. Send your Personal key as the bearer in place of $ACCESS_TOKEN (see Choose a credential).
1
Start the conversation
The call creates the workflow and its draft, opens the Architect conversation with your brief, and starts the first turn:This needs
workflows:write and workflows:read where the workflow is homed. Each start or send spends one of the key’s Architect turns, 60 an hour with a burst of 10; past that the answer is 429 with Retry-After.2
Wait for the turn to finish
The turn runs in the background. Poll the conversation no faster than every 2 seconds until Each read returns one page, oldest first: 20 messages by default, up to 50 with This read needs
turn.state is "idle" (a turn ends within 9 minutes), then read the new architect items:limit. When nextCursor is not null, the newest reply is on a later page. Pass it as cursor and repeat until nextCursor is null:workflows:write, because the transcript carries your brief.3
Check for a plan waiting on you
proposal is null unless the Architect proposed a plan and waits for a person to confirm it; then it names the humanTaskId to decide, as the plan card does in the drawer. This needs workflows:read.POST {"text": "…"} to the same architect-messages path. While a turn is running, queued or stopping, a new message is refused with 409 before any write; the API never queues a message.
Over MCP, forge_ask_workflow_architect holds the conversation in one tool, in the default start job. Omit workflowId to create a workflow, and omit message on a later call to follow a turn that is still working:
See also
- Workflow node types — what
produce/router/join/publishmean (and howproducecovers both agent and human workers), so you can name the shape you want - Workflow execution flow — what happens after you publish: the durable orchestrator, the governance pipeline, the per-node dispatch
- Architect channels in Chat — how the drawer’s chat is scoped, persisted, and resumed
- Synthesis — how missing primitives are created, reviewed and budgeted

