DEV Community: Workday Developers

Lawful Agents, Part 1: Your agent is reading an API that was never written for it

Obinna Ekwuno — Wed, 21 Oct 2026 15:22:11 +0000

If you have ever pointed an agent at an enterprise API, you will know how it goes. The response comes back five levels deep, the model spends half its context working out where the manager's name lives, it retries when a field is not where it expected, and eventually it fills the gap with something it made up. Then you spend the afternoon wondering whether the problem is your prompt.

It usually is not your prompt. Most enterprise APIs were designed for a developer who reads the documentation once and writes code against it. Your agent does not get that luxury. It meets the API fresh on every call and has to work it out from whatever is in front of it.

This series is about building agents you can actually trust with enterprise systems, the kind that stay inside the rules of the organisation they work for. I am starting with the tools those agents call, using Workday's Agent-Ready MCP tools, because how a tool is designed decides most of what happens next.

What changes when the tool is written for the model

Agent-Ready tools cover areas such as Workforce, Financials, Talent, Payroll and Recruiting, and three choices make them behave differently from the APIs you are used to.

The first is that the schemas are flat. Instead of something like this:

{
  "supervisoryOrganization": {
    "id": "SO-1180",
    "manager": { "worker": { "...": "..." } }
  }
}

your agent gets one layer of clearly named fields. Less structure to navigate means fewer tokens spent parsing, faster responses and far less room for invention.

The second is that every tool describes itself. Each one carries metadata about what it does and what each parameter expects, so when an agent sends "Oct 1" to a field that wants an ISO-8601 date, the error gives it enough to fix the value on the next attempt instead of guessing again. I have written before about APIs that already know what went wrong, and this is that idea applied to a reader that never gets tired of retrying.

The third is that they speak a standard. The tools follow the MCP JSON-RPC 2.0 specification behind a single endpoint for your tenant:

https://{agentGatewayRegionEndpoint}/{tenantName}/mcp

Your agent connects once, and the model handles tool selection and call syntax from there.

Bring your own agent

This is the bit I find most interesting as a developer, because you do not have to build inside Workday to use any of this. If your agent lives in Claude, Cursor, Copilot Studio or Google Agentspace, it can call the same tools a Workday Custom Agent does. The difference is that you do the registration yourself.

A Custom Agent built in Workday discovers and registers its tools automatically when you save and deploy. A third-party agent has to be registered in the Agent System of Record (ASOR) first, with the tools it is allowed to use listed in its agent definition. Here is a trimmed version of the documented example, a preferred name change agent built on Google Agentspace:

{
  "name": "Preferred Name Change Agent",
  "provider": "SELF-BUILT",
  "platform": "GOOGLE_AGENTSPACE",
  "workdayConfig": [{
    "skillId": "preferred_name_change",
    "executionMode": { "id": "Mode=Delegate" },
    "workdayResources": [
      { "tool_name": "create_worker_preferred_name_change", "agent_resource": { "id": "..." } },
      { "tool_name": "list_name_titles", "agent_resource": { "id": "..." } },
      { "tool_name": "list_name_salutations", "agent_resource": { "id": "..." } },
      { "tool_name": "list_hereditary_name_suffixes", "agent_resource": { "id": "..." } },
      { "tool_name": "list_social_name_suffixes", "agent_resource": { "id": "..." } }
    ]
  }]
}

Registering the agent gives you an Agent System User (ASU) token. Authentication is OAuth 2.1 with PKCE only, which most agent platforms and MCP clients already handle natively, so in practice connecting looks like adding any other remote MCP server to your client of choice and pointing it at your tenant's endpoint.

You might be wondering why that example lists five tools when the agent only does one thing. That is down to prompt tools, which are worth understanding before you register anything.

The tool type that will catch you out

You will see three kinds of tool in the catalogue.

Type	What it does
Basic	Reads data
Advanced	Writes data
Prompt	Reads the valid options a write tool needs

Lots of Workday fields only accept a value from a predefined list, and a write tool needs the Workday ID (WID) of the right option rather than a string the model came up with. So before create_worker_preferred_name_change can submit anything, the agent calls the four prompt tools to fetch valid titles, salutations and suffixes, picks the right one and passes its WID along.

The catch is that every prompt tool a write depends on has to be in your agent definition too. Leave one out and the write cannot complete. The MCP Explorer lists the required prompt tools in each tool's Details section, so check there before you register.

Finding the tools you need

The MCP Explorer on developer.workday.com is where I would start. You can filter by type, read each tool's description and schema, and copy the WIDs you need.

If you would rather do this from a script or a build pipeline, the ASOR Agent Resource Search API gives you the same catalogue programmatically:

curl "https://us.agent.workday.com/asor/agentResourceSearch/v1?searchString=time%20off&toolType=AGENT_READY&protocol=MCP" \
  -H "Authorization: Bearer [token]"

searchString is required and matches partial, case-insensitive names. You can narrow results with toolType (AGENT_READY for native tools, or AGENT to find Workday agents your agent can call as tools), operationType (CREATE, PATCH or VIEW) and protocol=MCP. Each result includes the wid that goes into agent_resource.id when you register. You will need Extend Professional and a token for a user with the Setup: Agents domain, and depending on your subscription agreement the API may need enabling first.

Guardrails you do not have to write

Good tools fix the performance problem. What gets an agent past a security review is knowing what stops it doing something it should not, and here none of that lives in your prompt.

The question	The answer
Who is it acting as?	Its own Agent System User, authenticated with OAuth 2.1 and PKCE
Whose data can it see?	In delegate mode, never more than the person it is acting for
What can it call?	Only the tools in its agent definition, with security set per skill and per tool

That last row is the one I would point a security team at. You are not asking the model to please stay in its lane. The platform enforces identity, permissions and an explicit allowlist, whether the agent was built in Workday or in your own stack.

Build for change, not for a version

Read this section twice before you ship anything. Agent-Ready tools are one continuous, unversioned surface that Workday keeps optimising for how models use it. Names, schemas, field names and descriptions can change without notice, and the MCP Explorer updates every Tuesday with a CSV change log you can download.

That is a fair trade for tools that keep getting better for agents, but it changes how you build:

Use them from agents only. Hard-coded UIs and standard integrations on these tools are not permitted, and anything that depends on a specific tool name, field or structure will eventually break.
Keep tool names out of your prompts and let the agent discover tools at runtime from their descriptions.
Know what counts as breaking. Workday keeps it narrow: a tool removed with no replacement, a validation you cannot satisfy, or a security change that takes away access you had. Those come with advance notice. Renames and automatic migrations do not.
Expect your results to vary. The tools themselves run deterministically, but the model, client, instructions and prompt around them do not.
Watch for long tool names, which some MCP hosts fail on. If one causes trouble, drop it from your registration and report it.

It also helps to know the limits up front, which are 2,000 concurrent requests, with a refresh rate and burst limit of 500 requests each. The server supports MCP protocol versions 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25, so most current clients will connect without any fuss.

Start here

If you want to try this yourself, join the Workday Developer Program to get access to the MCP Explorer, the docs and a community of people building agents on Workday.

Try this with your own agent:

Browse the MCP Explorer and pick one read tool and one write tool.
Note the WIDs, including every prompt tool the write needs.
Register your agent in ASOR with those tools in its definition.
Connect your MCP client to your tenant's endpoint and ask it to do something useful.

The interesting part of building enterprise agents was never getting the model to call a tool. It is making sure the tool tells the model enough to get it right, and that the platform refuses when the model gets it wrong.

In Part 2, I look at what happens when the job does not stop at Workday's edge, and how Custom Agent Actions let you turn your own workflows and third-party services into tools that carry the same guardrails.

Your Workday orchestration in VS Code, drawn the way the builder draws it

Obinna Ekwuno — Wed, 30 Sep 2026 14:05:22 +0000

NOTE: This is a read-only viewer. It renders exported files for reference and clarity. Orchestration Builder remains the source of truth for what will or won't validate or compile the viewer never edits anything.

Workday Orchestration Builder is a browser-based, low-code drag-and-drop tool on the Workday Developer Site used to create real-time, event-driven workflows and integrations. You get a trigger at the top, steps flowing downward, branches fanning out, loops with their bodies tucked inside, and the whole thing validates and compiles as you go. Then you export the project from your app, open the folder in VS Code, click any .orchestration file, and all of that visual clarity collapses into one line.

Not one object —one line —thousands of characters long, every value wrapped in a _type and _value envelope, and your editor dutifully renders it as an infinite horizontal scroll. You know there is a flow in there. You built it. You just cannot see it from here.

Workday already bridges part of this with Local Disk Sync, which saves your app to a local folder and keeps the builder and disk in step. That gets the files into git. It doesn't help when you're reading a colleague's branch, reviewing a pull request, or working somewhere Chrome isn't open.

The builder is where a flow gets made, and the repo is where it gets reviewed, versioned and shared, and I wanted the second place to be as readable as the first.

So I built a small extension that carries the builder's picture of a flow into the editor. It is called Orchestrate Flow Viewer, it works in VS Code and Cursor, and it renders .orchestration and .suborchestration files as interactive flow diagrams drawn the way the builder draws them.

This post is the what, the why, and enough of the how that you could build something similar yourself.

What it does

Any Workday app can be exported so a developer can see its underlying folder structure. Choose any app that has an orchestration in it, export it, and open it up using this tool (any app with appManifest.json and an orchestration/ directory).

Click a flow file, and you get the same picture the builder would show you, right there in your editor. The Start or trigger step sits at the top and the steps flow downward along a spine.

Branch on Conditions arms fan out side by side, in the same left to right order the builder evaluates them under little white pills and reconverges at a join. When it comes to Loop bodies, they are nested under their loop card behind a chevron you can collapse.

Error handlers are the one place I deliberately depart from the builder. There, local and global handlers open on their own canvas. A static diagram can't click through, so the viewer pulls them inline: the global handler as a detached region below the main flow, and local handlers as a badge on the step that owns them, borrowing the builder's lightning bolt icon.

If you can read a flow in Orchestration Builder, you can read it here, because the visual language is the same on purpose.

Selecting any step opens a details panel loaded with context straight from the builder:

Step Context: Review assignments, expressions, branch conditions, loop iterators, add integration message severity, and store-document settings.
Resource Resolution: Inspect CSV columns resolved directly from the flow's resources alongside suborchestration parameters.
Subflow Navigation: Click Call Subflow cards to instantly jump to target suborchestrations across your workspace without waiting for page loads.
Developer Environment Tools: Enjoy full editor support with pan, zoom, a minimap, live re-rendering on edit, theme matching, and a toggle for pretty-printed raw JSON.

Why a viewer, and why read-only

Orchestration Builder remains the place to create orchestrations—this project doesn't change that. But once you download the source, you're dealing with files. And files belong where developers already work: in repositories, branches, and pull requests ready for review.

As Workday expands its developer platform, it brings an expectation that you can work in standard development environments. You build in Orchestrate, then review, version, and share in VS Code or GitHub just like any other code you ship.

However, the file reads like it was written for the compiler, not for you. The IntelliJ plugin takes the same view, treating the orchestration folder as read-only and pointing you back to Orchestration Builder to edit. The viewer follows that convention.

The goal is intentionally focused: make exported files readable right where they live—nothing more. It isn't a secondary editor or a replacement for the builder. The viewer simply renders what is in the file, which doesn't guarantee the flow will validate or compile.

What the file knows, and what the builder knows

To reconstruct the builder's visual layout from an exported file, I first examined the underlying file structure. Two key characteristics stood out immediately. First, every single value is wrapped inside a type envelope, as shown when pretty-printing a flow:

{
  "_type": "CreateValues",
  "_value": {
    "name": { "_type": "String", "_value": "InputFile" },
    "isDisabled": { "_type": "Boolean", "_value": false },
    "errorHandler": {
      "_type": ["Opt", "ErrorHandler"],
      "_value": { "_type": "ErrorHandler", "_value": { "…": "…" } }
    }
  }
}

Taking errorHandler as an example, it is represented as an ["Opt", "ErrorHandler"] wrapper enclosing another inner wrapper. Optional fields effectively create nested envelopes, where an absent optional evaluates to an envelope wrapping null. Furthermore, certain exporter versions emit un-wrapped bare objects for group bodies, requiring the parser to handle both representation styles seamlessly.

The second, more subtle realization influenced the entire architectural approach: diagram information exists within the Orchestration Builder interface rather than the source file itself. The exported file stores structural data rather than graphical layout—omitting explicit edges, node identifiers, or spatial coordinates. Execution sequence is inferred from array ordering, branching is established through element containment, and loop bodies are structured as nested lists. While this compact format is optimized for platform execution and compilation, re-creating the builder's interactive diagram within VS Code required translating these structural semantics back into a visual node graph.

This led to a multi-stage pipeline architecture designed to make implicit relationships explicit, enforcing a clear separation of concerns at each phase:

.orchestration file (text)
        │
        ▼
  src/core/parse.ts      unwrap the envelopes → typed FlowModel
        │
        ▼
  src/core/graph.ts      synthesise nodes and edges → FlowGraph
        │
        ▼
  src/core/layout.ts     assign x/y/w/h to every node
        │
        ▼
  src/webview/…          render with React Flow inside VS Code

All components in src/core/ consist of pure TypeScript without any VS Code API dependencies. Consequently, the core pipeline can execute in standalone Vitest suites or standard browser environments. The VS Code extension itself acts as a lightweight wrapper around this core logic—a design boundary that significantly simplified testing and maintenance.

Teach the parser the envelope, once

Before building the parser, I established a clear vocabulary for interpreting the format: eight utility functions in src/core/unwrap.ts designed to handle any output variation from the exporter. The core work is handled by peel:

/**
 * Peel wrapper-of-wrapper layers (e.g. Opt<ErrorHandler> whose _value is the
 * wrapped ErrorHandler) down to the innermost wrapper. A null Opt stays put,
 * so callers see unwrap(peel(v)) === null for absent optionals.
 */
export function peel(v: unknown): unknown {
  let cur = v;
  while (isWrapped(cur) && isWrapped(cur._value)) {
    cur = cur._value;
  }
  return cur;
}

Building on this foundation are field, str, bool, num, list, and record. Each helper safely evaluates wrapped or bare objects, returning undefined or an empty list for unexpected shapes instead of throwing an error. Routing all property access through these utilities encapsulates envelope parsing entirely. This enforces a core architectural rule across the project: malformed input degrades gracefully rather than crashing the application.

Assume Workday will ship something you have not seen

Workday releases new Orchestrate components regularly. This means the parser will inevitably encounter step types it hasn't seen before—and it will meet them in real user projects, not just in test fixtures. The default case of parseStep gracefully handles these situations using a two-tiered approach:

default: {
  // Unseen component types must never break the diagram. If the payload
  // carries a body of child steps (loop-like components such as Batch
  // Loop / Join Loop), render it as a container so the children survive.
  const groupRaw = field(raw, 'group');
  const hasGroup = list(field(groupRaw, 'nodes')).length > 0;
  const directNodes = list(field(raw, 'nodes'));
  if (hasGroup || directNodes.length > 0) {
    warnings.push(`Unknown container type "${rawType}" (${id}) — rendered generically.`);
    const group = hasGroup
      ? parseGroup(groupRaw, childPath, warnings)
      : { id, name, steps: directNodes.map((n) => parseStep(n, childPath, warnings)) };
    return { ...base, kind: 'genericContainer', group, entries: leafEntries(raw, new Set(['group', 'nodes'])) };
  }
  warnings.push(`Unknown step type "${rawType}" (${id}) — rendered generically.`);
  return { ...base, kind: 'generic', entries: leafEntries(raw) };
}

If a component I haven't written a parser for contains child steps, it is parsed as a generic container. This allows any nested steps to be parsed normally and displayed as functional cards. Any other unrecognized structure becomes a generic step, displaying a raw dump of its fields in the details panel for complete visibility. Both paths increment a warning counter in the toolbar. While an unseen component might lack a custom icon, it will never break the visual diagram.

Why I wrote 150 lines instead of using dagre

When it came to the layout stage, using an existing graph library like Dagre or ELK seemed like the obvious choice. However, I decided to build a custom solution instead. General-purpose layout engines tend to produce organic structures that shift dynamically as the graph changes. In contrast, the Orchestration Builder interface relies on a consistent, highly predictable layout: a single vertical spine flanked by neatly aligned branch arms.

Branch order matters too, Orchestrate evaluates Branch on Conditions arms left to right and runs the first that's true, so a layout engine that reorders arms is misreporting execution order. A custom algorithm guarantees this exact structure every time—ensuring identical input always yields identical output.

layoutGraph operates using two recursive tree passes. The first pass measures bottom-up, memoizing each subtree's bounding box so branch arms know their required width before placement. The second pass places elements top-down, centering items along the spine and advancing a y-cursor. Branch arms are centered as rows beneath their root node, and joins are placed at the measured bottom so all paths reconverge seamlessly.

Centralizing node dimensions in a single lookup table makes global visual adjustments simple:

const SIZES: Record<NodeKind, { w: number; h: number }> = {
  trigger: { w: 300, h: 118 },
  end: { w: 220, h: 64 },
  step: { w: 280, h: 84 },
  branchRoot: { w: 280, h: 84 },
  globalError: { w: 280, h: 84 },
  pill: { w: 132, h: 36 },
  expander: { w: 26, h: 26 },
  join: { w: 10, h: 10 },
};

Deterministic layout also makes the visual structure fully unit-testable. For instance, a key test suite iterates through every node pair across all test fixtures to verify that no elements overlap:

it("has no overlapping nodes", () => {
  for (let i = 0; i < graph.nodes.length; i++) {
    for (let j = i + 1; j < graph.nodes.length; j++) {
      const a = graph.nodes[i];
      const b = graph.nodes[j];
      expect(overlaps(a, b), `${a.id} overlaps ${b.id}`).toBe(false);
    }
  }
});

If a measurement pass undercounts a subtree, overlapping cards immediately fail the test with the precise node IDs responsible. This test caught several real layout bugs during development—an advantage made possible solely by deterministic positioning, which third-party layout engines cannot reliably guarantee.

The rest is plumbing

The webview component renders via React Flow. Since the layout phase computes absolute node positions in advance, the webview primarily maps graph nodes directly to locked React Flow elements—ideal for a read-only viewer.

Edges use right-angle elbow connectors rather than bezier curves, categorized by function so horizontal segments route exactly where the Orchestration Builder would place them. Furthermore, because all color styles leverage VS Code's CSS variables, light and dark themes work seamlessly out of the box without requiring custom styling code.

On the extension side, a CustomTextEditorProvider allows VS Code to handle document state, text editing, and file watching natively, leaving the extension focused entirely on rendering. Communication between the host and webview relies on a lightweight, typed protocol. Incoming edits stream in with debouncing so side-by-side editing won't trigger heavy re-layouts on every keystroke. Additionally, a workspace index scans orchestration IDs, enabling Call Suborchestration cards to display target names and open corresponding files on click.

Key Takeaways

If you're building a similar extension or tool, here are three core principles worth applying:

Identify the core problem first: The goal was never just to render raw JSON, but rather to bring Orchestration Builder's visual clarity directly into the editor environment. Defining this goal made designing the processing pipeline straightforward.

Keep core logic decoupled: Avoiding VS Code API dependencies in the core pipeline enabled comprehensive unit testing against exported files, allowed fast diagram iteration in a standalone browser harness, and minimized webview complexity.

Design for future schema changes: Implementing a two-tiered fallback mechanism alongside a warning counter ensures that newly released Workday components render gracefully without breaking the layout achieved in about thirty lines of code.

Start here

Getting started takes only a couple of minutes:

Install the extension: Orchestrate Flow Viewer on VS Code Marketplace
Open a downloaded: Select any project folder containing an appManifest.json and an orchestration/ directory.
View the flow: Click any flow file and toggle the JSON view once to compare the formatted diagram against raw source data.

The source code is available on GitHub under the MIT license at https://github.com/Ekwuno/workday-orchestrate-viewer . Upcoming roadmap features include breadcrumb navigation for subflow drill-ins and PNG/SVG export options. If you encounter rendering issues with an exported flow, please open an issue in the repo

Orchestration Builder has always understood your flow's visual layout now your editor does too. Head to developer.workday.com and join the Workday Developer Program, where you'll find the guides, the community and everything you need to start building.