Workflows

A workflow groups the steps of an app that makes several kinds of model call: one agent and one key per step. A workflow only groups and observes; it never blocks a call.

Why one key per app is a problem

Forgebench treats one key as one agent, so with one key for a whole app:

1. One model serves every call. The agent's configured model serves every call made with its key, whatever model the call asks for.
2. The hardest step blocks savings. Routing doesn't recommend a cheaper model if any kind of task would get worse, so one hard step vetoes a cheaper model for all of them.
3. Evidence is pooled. The routing window, recommendation, canary and budget cover the whole agent, so a regression in one step is averaged away.

With one agent per step, each step is judged, approved, canaried and budgeted on its own.

When to split a step

Give a step its own agent and key when it:

• needs a different model from the other steps;
• is a different kind of work, for example grading versus drafting;
• makes roughly 200 or more calls per routing window, enough for a confident recommendation.

Keep small steps that share a model and kind of work on one agent. A step with a handful of calls never gets a confident recommendation.

Register a workflow

Each method creates the workflow, one agent per step, and the edges between steps in one go. If any part fails, nothing is created.

Console

1. Open the register form

   Go to Agents, open the Inventory, and choose Register workflow (beside Register agent).

2. Describe the workflow

   Fill in Workflow name, an optional Slug and Description, and the Owner.

3. Add the steps and edges

   Use Add step for each step: a name and a model, plus an optional monthly budget and description. Each step becomes its own agent with its own key. Use Add edge to connect the steps.

4. Create it and copy the keys

   Choose Create workflow. Each step's key is shown once; copy them now.

Workflows are listed under the Workflows tab. A workflow's page shows its steps, routing status and checks, with a Step setup list for each step's agent.

REST

POST /v1/workflows:

{
  "name": "Question paper",
  "slug": "question-paper",
  "owner_identity_id": "<identity uuid>",
  "steps": [
    {"name": "grading", "model": "mock-gpt"},
    {"name": "retry",   "model": "mock-gpt"}
  ],
  "edges": [{"from": "grading", "to": "retry", "kind": "sequence"}],
  "issue_credential": true
}

The response has the workflow and one credential per step. Keys are shown once. Set issue_credential to false to register the agents without keys and claim them later. A step can also set allowed_models, description and monthly_budget_usd. A workflow has at most 25 steps and 100 edges.

MCP

1. Plan

   forgebench_workflows with action: register returns a change plan without creating anything.

2. Apply

   Apply the plan with forgebench_apply_plan. Each step's agent is created without a key. A plan with task edges, or with more agents than your workspace allows in one apply, needs confirming in the console.

3. Claim the keys

   Claim each step's key with forgebench_agents issue_credential. The key is revealed once, in the browser.

4. Wire and verify

   forgebench_integrate with action: workflow gives per-step code. forgebench_verify with workflow set checks the wiring.

See Forgebench MCP for connecting the server.

SDKs

The Python, TypeScript and Java SDKs register workflows and run them with one key per step:

created = client.workflows.register(
  name="Question paper",
  owner_identity_id=client.whoami().identity_id,
  steps=[{"name": "grading", "model": "mock-gpt"},
         {"name": "retry", "model": "mock-gpt"}],
  edges=[{"from": "grading", "to": "retry", "kind": "sequence"}],
)
keys = {c["step"]: c["credential"]["api_key"] for c in created["credentials"]}

with client.workflow("question-paper", keys=keys).run() as run:
  run.step("grading").chat(model="mock-gpt", messages=[...])
  run.step("retry").chat(model="mock-gpt", messages=[...])  # parent = grading's call

const run = forgebench.workflow("question-paper", keys).run();
await run.step("grading").chat({ model: "mock-gpt", messages });
await run.step("retry").chat({ model: "mock-gpt", messages }); // parent = grading's call

Workflow.Run run = client.workflow("question-paper", Map.of("grading", keyA, "retry", keyB)).run();
run.step("grading").chat(request);
run.step("retry").chat(request);   // parent = grading's call

OWNER=$(curl -s https://api.forgebench.ai/v1/auth/whoami \
-H "Authorization: Bearer $FORGEBENCH_API_KEY" | jq -r .identity_id)

CREATED=$(curl -s -X POST https://api.forgebench.ai/v1/workflows \
-H "Authorization: Bearer $FORGEBENCH_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "name": "Question paper",
  "owner_identity_id": "'"$OWNER"'",
  "steps": [{"name": "grading", "model": "mock-gpt"},
            {"name": "retry", "model": "mock-gpt"}],
  "edges": [{"from": "grading", "to": "retry", "kind": "sequence"}]
}')
GRADING_KEY=$(echo "$CREATED" | jq -r '.credentials[] | select(.step == "grading") | .credential.api_key')
RETRY_KEY=$(echo "$CREATED" | jq -r '.credentials[] | select(.step == "retry") | .credential.api_key')

# Each step calls with its own key; the first call of a run is its root.
CALL_ID=$(curl -s -X POST https://api.forgebench.ai/v1/chat/completions \
-H "Authorization: Bearer $GRADING_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "mock-gpt", "messages": [{"role": "user", "content": "..."}]}' | jq -r .call_id)

curl -s -X POST https://api.forgebench.ai/v1/chat/completions \
-H "Authorization: Bearer $RETRY_KEY" \
-H "X-Parent-Call: $CALL_ID" \
-H "Content-Type: application/json" \
-d '{"model": "mock-gpt", "messages": [{"role": "user", "content": "..."}]}'   # parent = grading's call

Each step call uses that step's own key and sends the previous call's id as X-Parent-Call. The first call of a run is its root. The Java helper covers chat completions only, not streaming. See the Python, TypeScript and Java SDK pages for more.

Edges: sequence and task

An edge declares how two steps relate. It never blocks a call.

• sequence: the app runs step A, then step B, and passes A's call id to B. Forgebench checks this against the lineage it observes.
• task: agent A sends tasks to agent B (agent-to-agent). This creates an agent-to-agent binding, shown as pending until approved.

Removing a task edge or detaching a step keeps the binding. To revoke it too, pass revoke_binding=true on DELETE /v1/workflows/{slug}/edges/{edge_id}.

Lineage

1. Every governed response returns call_id in the body, and X-Call-Id as a header. A stream gets it from the header.
2. Send that id as X-Parent-Call on the next call.
3. Forgebench records the call's parent and the root of its run.

Lineage is self-reported by the caller and not verified. Use it to see the shape of a run, not to audit who did what. See Call lineage.

To see lineage on the agent graph, call GET /v1/agents/graph?include_lineage=true. Add workflow=<slug> to limit it to one workflow.

Routing per step

Each step gets its own routing window, recommendation, approval and canary. The workflow page sums spend, calls and routing across steps without pooling the evidence.

One live key per agent

Claiming or issuing a key on an agent that already has one rotates it: the old key stops working. For a second caller, create a second agent.

Checks

GET /v1/workflows/{slug}/checks (or forgebench_workflows with action: checks, or workflows.checks in the SDKs) reports whether the workflow is wired, threaded and seeing traffic:

Next