> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the Workflow Architect

> How to author workflows by talking to the Workflow Architect — a Forge-native agent that turns intent into a validated graph you review and ship.

The **Workflow Architect** is the way you author workflows in Forge without writing graph nodes by hand. You describe what you want; the Architect proposes a draft graph; you review every tool call as it happens; you publish only when the graph is right. The Architect is a Workforce agent like any other — composed from its definition, governed by the Trust Fabric before each turn, and deliberately given no permission to publish. You stay in the loop on every structural change, and the **Publish** button is yours alone.

This page is the operator's guide: when to reach for the Architect, how to phrase intent so it produces good graphs, how to use the **Fix-with-Architect** path when a run fails, and when to author the graph manually instead.

***

## 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-authoring` skill 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.

If you do reach for the Architect, the rest of this page assumes you're in the Forge Console, on the workflow builder, with a draft open and the **Ask the Architect** button visible in the toolbar.

***

## The authoring loop

Workflow Architect Authoring Loop

<ol aria-label="Workflow Architect Authoring Loop" />

The Architect's `workflow-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](#plan-cards-propose-then-confirm) 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:

1. **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.

2. **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.

The Architect is a normal Convex-native agent. Each turn runs through the Trust Fabric gate sequence, is composed from the Architect's agent definition, and writes to the database through governed tools. There is no "express mode" that bypasses governance.

***

## 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.

You can attach several files to a single message, and the conversation accumulates attachments across turns — a file you added on turn one is still available on turn five.

The Architect does **not** ingest the full contents of every attachment into the prompt. Instead it sees a manifest — each file's name, type, and size — and reads file contents **on demand** with its `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-ops` approves" is a one-line instruction the Architect turns into a `human` node, 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 `getExampleGraphsTool` patterns. 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](https://docs.gloo.com/forge/run/observability.md). 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 node `summarize` 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:

1. **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](https://docs.gloo.com/forge/run/synthesis-budgets-and-curator.md)
   to create it. It then shows a **plan card**: the proposed topology, nodes, edges and missing pieces.
2. **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.
3. **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.
4. **Build the graph.** On confirmation, the Architect writes the nodes and edges into your draft.

A plan card ends in one of these states:

| State | When |
| - | - |
| Pending | Waiting for your decision |
| Confirmed | You chose Confirm |
| Edited and confirmed | You amended the plan, then confirmed it |
| Rejected | You chose Reject or force-stopped the session |
| Expired | Nobody decided before the card expired; a nightly sweep closes it |

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:

1. For each intended node, it searches the workspace catalog for primitives that fit.
2. A relevance judge grades each candidate.
3. High-scoring candidates are reused; the rest are marked as gaps.
4. For each gap, a Builder synthesizes a provisional primitive, within the workspace synthesis budget.
5. When synthesis completes, the Architect shows the plan card.

The plan card separates **existing primitives** from **newly synthesized, provisional ones**, so you
can see at confirmation time which nodes are new.

***

## Reviewing the proposal

The Architect's tool calls render live in the drawer as `ToolCard` 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:

| Check | Why it matters |
| - | - |
| **Agent prompts on Agent nodes** | The Architect tends toward thoroughness; tighten prompts that ramble. A focused prompt is the difference between a usable agent and a slow one. |
| **Capability hints (skills + tool sets)** | The Architect requests *more* than fewer. Drop skills and tool sets you don't need before publishing — capability sprawl is the most common cause of slow, unfocused Agent nodes. |
| **Terminal paths end at `publish`** | Every path through the graph should end at a `publish` node or an explicitly terminal agent. A path that just stops is almost always a bug. |
| **Human gates on irreversible actions** | Sending email, calling external APIs, posting to public channels — the Architect doesn't always insert a human-worker step. You should. |
| **Declared timeouts on long-running nodes** | The Architect sizes a node's budget from `items × per-item` arithmetic (and from measured history when the node has run before) and states it in the proposal — "Adjudicate (detached VM, \~40 min budget)". Check the item count it assumed. A node whose input is a work list and whose timeout is inline-sized will die at the action wall; see [Declare the runtime budget](https://docs.gloo.com/forge/build/compose-a-workflow.md#declare-the-runtime-budget). |
| **Validation status** | The Architect calls `validateGraphTool` at the end of every turn. The status must be `"clean"` before you publish. If it's `"warnings"`, read each warning and decide whether to address it. `AGENT_BUDGET_UNDERSIZED` is a sizing prompt, not noise — it means a work-list node needs a bigger declared timeout. |

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:

1. Forge clones the pinned version into a new editable draft.
2. A scoped Architect channel is opened for that draft.
3. The first system message in the channel carries the failure context — `failingStepName`, `errorCode`, `errorMessage`, and the failing node's JSON.
4. The Architect is *not* dispatched yet. The channel is seeded.
5. 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.

That last point is the critical guardrail: the failure-seed is data, not authority. Nothing happens until you talk to the Architect.

When you do talk, the high-leverage opener is one of:

* **"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.

If a draft already exists for this workflow when you click Fix with Architect, Forge throws a structured `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:

| Guardrail | What it means |
| - | - |
| **No publish authority** | `publishWorkflowTool` is in a tool set the Architect's conversational dispatch never receives. Promotion is always yours. |
| **No new workflow rows** | The conversational flow pre-creates the `workflows` row and its `workflowDrafts` workspace — including when you open with file attachments. The Architect always operates on an existing `draftId` and is explicitly told never to call `createWorkflowDefinitionTool`. |
| **No silent mutations** | Every action is a visible `ToolCard` row in the drawer. Hidden writes don't exist. |
| **No turn without governance** | Every Architect turn passes through the Trust Fabric gate sequence. The same pipeline runs for the Architect as for any factory worker, copilot run, or chat agent. |
| **No skipping validation** | The skill mandates `validateGraphTool` at the end of every turn. The Architect won't tell you it's done with a graph that hasn't passed validation. |

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:

| Criterion | Weight | What it checks |
| - | - | - |
| Decomposition fit | 30% | Does the graph factor the business intent into the right nodes? |
| Procedure bias | 25% | Where work admits a procedure shape, was a procedure chosen? |
| Edge and input/output correctness | 20% | Are types matched, with no dangling required inputs and no cycles? |
| Node primitive choices | 15% | Is each node the right kind: agent, procedure, router, join, human or publish? |
| Missed synthesis opportunities | 10% | Were there gaps the Architect should have filled with synthesis? |

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](https://docs.gloo.com/forge/concepts/trust-fabric.md#judges).

***

## Do it over the API

You can hold the same conversation over HTTP. These calls use the `FORGE_BASE` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md), 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](https://docs.gloo.com/forge/console/settings/personal-keys.md#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:

```bash theme={null}
WORKFLOW_ID=$(curl -sS -X POST "$FORGE_BASE/api/v3/workflows/start-architect-conversation" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vendor-invoice-intake-architect-v1" \
  -d '{"initialText": "When a vendor invoice arrives, extract the header fields, match it to the purchase order, and route mismatches over 500 USD to a person for approval."}' \
  | jq -r '.data.workflowId')
```

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 `turn.state` is `"idle"` (a turn ends within 9 minutes), then read the new `architect` items:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/architect-messages" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '{turn: .data.turn.state, items: [.data.items[] | {role, text}], nextCursor: .meta.nextCursor}'
```

Each read returns one page, oldest first: 20 messages by default, up to 50 with `limit`. When `nextCursor` is not null, the newest reply is on a later page. Pass it as `cursor` and repeat until `nextCursor` is null:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/architect-messages?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '{items: [.data.items[] | {role, text}], nextCursor: .meta.nextCursor}'
```

This read needs `workflows:write`, because the transcript carries your brief.

**3. Check for a plan waiting on you**

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/architect-plan" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data.proposal'
```

`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](#plan-cards-propose-then-confirm) does in the drawer. This needs `workflows:read`.

To continue, `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:

```json theme={null}
{ "message": "When a vendor invoice arrives, extract the header fields, match it to the purchase order, and route mismatches over 500 USD to a person for approval." }
```

```json theme={null}
{ "workflowId": "<workflow id>", "maxWaitSeconds": 40 }
```

***

## See also

* [Workflow node types](https://docs.gloo.com/forge/concepts/workflows-and-runs.md#node-types) — what `produce` / `router` / `join` / `publish` mean (and how `produce` covers both agent and human workers), so you can name the shape you want
* [Workflow execution flow](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md) — what happens after you publish: the durable orchestrator, the governance pipeline, the per-node dispatch
* [Architect channels in Chat](https://docs.gloo.com/forge/build/talk-to-agents.md#pick-a-channel-scope) — how the drawer's chat is scoped, persisted, and resumed
* [Synthesis](https://docs.gloo.com/forge/run/synthesis-budgets-and-curator.md) — how missing primitives are created, reviewed and budgeted


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.