Publishing GraphN workflows: drafts, resources, and production versions

Published: August 13, 2026
Reading time: 9 min

A GraphN workflow is an orchestration document, while agents, functions, and MCP servers remain reusable workspace resources. Publishing creates the reviewed production version that applications can run.

The most useful question about an agent workflow is not “what does the canvas look like?” It is: which reviewed version is production using?

That question becomes difficult when prompts, tools, code, models, and data can all change independently. GraphN addresses part of the problem with a constrained workflow DSL and published workflow versions. The broader AI workflow platform lifecycle connects authoring to production execution and inspection. The DSL describes control flow and data flow. Workspace resources describe the agents and capabilities used by that flow. Publishing separates editable work from the version selected for production runs.

This article explains that boundary, including what it does not freeze.

Workflow versus resource

A workflow defines inputs, named steps, dependencies, expressions, and outputs. It answers orchestration questions:

Which step runs?
What data does it receive?
Which earlier results does it depend on?
Where can work branch, loop, or run in parallel?
What becomes the workflow output?

Resources answer different questions. An agent holds instructions, a model selection, and configured tools. A function holds workspace-owned Python. An MCP server exposes structured tools. Knowledge bases provide retrieval over indexed content; storage holds files; secrets provide credentials; models perform inference.

The distinction matters because several workflows can refer to a reusable resource, while a workflow still owns its own graph. The GraphN core concepts guide presents the workflow as the orchestration container and the other objects as resources it connects.

This is a resource graph, not an execution trace. An agent may choose whether to call one of its configured tools during a run. A workflow-level mcp_tool step, by contrast, makes that tool invocation explicit in the graph. Both are useful, but they express different amounts of orchestration intent.

One definition across canvas and YAML

GraphN's canvas and YAML tab are two views of the same workflow definition. The canvas is useful for arranging and inspecting nodes. The YAML is useful for review, precise expressions, and repository workflows. There is no second graph that must be kept in sync.

The DSL is intentionally bounded. A document declares its version, input contract, optional resource names, steps, and output. Steps use supported calls such as agent, function, mcp_tool, conditional, for_each, while, parallel_analyzer, handoff_router, and judge_loop. Expressions such as ${ steps.lookup.output } move results through the graph and also imply dependencies. Top-level dependencies must remain acyclic; bounded loop steps represent iteration.

Canvas layout is presentation-only. Moving a node changes how the workflow is arranged for a builder; it should not change the behavior expressed by the DSL.

This shared representation gives reviewers a concrete artifact. They can inspect whether a side effect is an explicit tool step, whether two branches are independent, whether a loop has a bound, and whether the final output points to the intended step. It does not make a model response deterministic; it makes the surrounding orchestration inspectable.

A compact Support Router-style workflow

The public Support Router blueprint uses triage and specialist agents with a bundled mock store integration. The shortened example below isolates one order-status path so the agent/tool boundary is visible:

yaml

document:
  dsl: "1.0.0"
  name: Support Order Lookup
  version: "0.1.0"

agents:
  Order_Specialist: {}
mcp_servers:
  Store_API: {}
chat_hints: "Provide a customer message and order ID to verify order status."

input:
  message:
    type: string
    required: true
  order_id:
    type: string
    required: true

steps:
  lookup:
    call: mcp_tool
    server: Store_API
    tool: lookup_order
    input:
      order_id: "${input.order_id}"
    output: order

  answer:
    call: agent
    agent: Order_Specialist
    after: [lookup]
    input_template: |
      Customer message: ${input.message}
      Verified order record: ${steps.lookup.output}
    output: response

output:
  result: "${steps.answer.output}"

This shape was validated against the current GraphN DSL: resource names are declared at the top, the MCP step supplies structured arguments, the agent consumes the tool result, and the workflow names its result. A published test run completed lookup before answer and grounded the response in the mock order record.

The full blueprint uses a handoff_router to select among order, return, and product specialists. This reduction is better for studying the execution model because the store lookup is explicit rather than hidden inside an agent's optional tool use.

During draft authoring, resource declarations can use readable names. Before publishing, validate that every declared resource exists and that the workflow refers to the intended agent, function, or MCP server.

What publishing means to a builder

The public product contract is straightforward: publishing creates a versioned workflow with its DSL and linked resource snapshots. Production runs use published state rather than an unfinished draft, and prior versions remain available for inspection.

The practical consequence is the important part: editing a workflow or linked resource after publication does not by itself change an already published version. Publish again when reviewed changes should become the production version.

Use the workflow-version view or API response as the record of what was published. Keep a useful publish message so reviewers can connect a version to the reason it changed.

Draft, test, publish, and run are different boundaries

Treat the lifecycle as four separate operations.

Draft: editable workspace state

Saving updates the current workflow DSL, layout, and associated draft resources. It is where names, prompts, code, and graph structure can change. Save is not production promotion.

Validate and test: evidence about a candidate

Validation checks the DSL's structure and references. A dry-run can execute an inline definition without persisting it. Editor test and preview paths let builders exercise candidate inputs and inspect results. These operations are feedback loops, not declarations that the production version changed.

Tests should cover representative inputs, malformed tool responses, missing optional fields, and failure paths. A successful example proves only that the tested candidate completed under those conditions.

Publish: create a production version

Publish creates the version that production runs use. Include a short message that says why the behavior changed; “tighten return eligibility routing” is more useful than “update.”

Run: execute the published contract

Applications run the published workflow through the GraphN CLI or workspace API. Longer work can use asynchronous execution; the next article explains how to design reliable async workflows. The important point here is that sync versus async changes the request lifecycle, not which workflow version should define production behavior.

Practical publish checklist

Before publishing:

Read the diff. Compare DSL, agent instructions, function files, MCP configuration, input/output contracts, and supported run modes.
Validate the DSL. Check resource names, expressions, dependency cycles, required inputs, and bounded loops.
Classify every capability. Use an agent for model-driven judgment, a function for workspace-owned code, and an MCP tool for a structured external action.
Exercise failure cases. Test missing inputs, tool errors, empty retrieval results, malformed structured output, and timeouts relevant to the workflow.
Check side effects. Identify which steps can write to an external system and confirm the test environment will not affect production data.
Review credentials separately. Confirm secret bindings exist and have the intended scope; do not paste credentials into YAML or prompts.
Publish with intent. Add a useful message, then verify the returned workflow version.
Run the published version. Use a known input and inspect status, output or error, and available trace details.

For a terminal-based loop, the developer guide for GraphN agents covers validate, dry-run, publish, and production-run commands.

What publishing does not guarantee

A published version narrows change, but it does not freeze the world.

It does not copy the outside world. Model artifacts, knowledge content, and external records remain governed by their own services and data lifecycles.
Credentials and permissions can change. A published workflow can later encounter a rotated credential or a changed downstream permission.
External systems remain mutable. An MCP server configuration can be versioned while the API, records, permissions, or service behind it changes.
Validation is not semantic verification. Valid YAML and resolvable resources do not prove that instructions are correct, tool output is trustworthy, or an answer satisfies a business policy.
Publishing is not workflow checkpointing. A published version records the workflow definition. It is not a promise of arbitrary step replay, time travel, or user-addressable checkpoints during a run.
Runtime failures still exist. Models, tools, storage, and downstream services can be unavailable or return errors. Versioning makes the intended definition clearer; it does not make every dependency durable.

These limits should shape design reviews. Put stable orchestration in the DSL, test resource behavior independently, and treat tool output and retrieved content as data rather than authority. The related article on agent trust boundaries for MCP tools, functions, and grounded retrieval goes deeper into that separation.

The useful mental model

Think of GraphN as three layers:

The DSL defines the graph and data movement.
Workspace resources define the actors and capabilities referenced by that graph.
The published version records the reviewed workflow state used for production execution.

Keeping those layers separate makes change review concrete. You can ask whether the graph changed, whether a linked resource changed, and whether either change has actually crossed the publish boundary.

Start with the complete workflow DSL reference, then deploy the Support Router blueprint and inspect its YAML before and after publishing.

Primary sources

GraphN core concepts
Defines workflows, agents, functions, MCP servers, knowledge bases, storage, secrets, and models as related workspace concepts.
GraphN workflow DSL
Documents the YAML structure, resource declarations, step types, expressions, dependencies, loops, and canvas-to-DSL relationship.
GraphN AI workflow platform
Describes the compose, validate, publish, invoke, and inspect lifecycle and the separation between drafts and published resource snapshots.
Support Router blueprint
Provides the customer-support routing example, including triage, specialist agents, and mock store tools.
GraphN FAQ
Documents workspace scope, sync and async runs, execution results, secrets, and the developer-facing CLI lifecycle.