Yes. You connect a custom-built agent to Workday by registering it in Agent System of Record (ASOR), giving it a skill that lists the Workday tools it may call, choosing which security groups can use it, and then having it authenticate through Workday's Agent Gateway. Workday's agent documentation does not use an Integration System User for this: each agent gets its own Agent System User (ASU) that Workday creates for you.

Which route you take depends on where the agent runs. An agent built in Workday registers itself. An agent that runs on another platform is registered through an API.

What are the ways a custom agent can reach Workday data?

Workday documents these, and the rest of this page covers the first two:

  • Built in Workday. A custom agent built in App Builder is registered in ASOR automatically in a development tenant. Its tool calls go through Workday's own runtime. See what Workday Extend lets you build.
  • Built outside Workday. An agent on another platform is an external agent. You register it with the ASOR API, configure it in Workday, and it calls Workday through Agent Gateway.
  • Agent-Ready Tools from an outside platform. A registered external agent can also call Workday's Agent-Ready Tools through Workday's Model Context Protocol endpoint. Workday names Claude, Cursor, Copilot Studio and Google Agentspace as examples of platforms that do this. Workday says that connecting an external agent this way is for Extend Professional users, the SKU it has since renamed Extend AI.
  • Traditional APIs with an ISU. Workday's agent documentation says all third-party agents that call Workday APIs must route through Agent Gateway using ASU security. If you connect a non-agent integration the old way, the integration system user and API client guide applies instead.

Step 1: Set up Agent System of Record in the tenant

You do this in each tenant, because Workday says there is no way to migrate the configuration.

  1. Run Maintain Functional Areas and select Agent System of Record.
  2. Run Activate Pending Security Policy Changes.
  3. Open the Domain Security Policies for Functional Area report, choose Agent System of Record, and enable these domains: Agent Compliance, Agent Management Hub, Manage: Agents, Reports: Agent Reporting and Setup: Agents. Enable Reports: AI Agent Security in the System functional area as well.
  4. In Maintain Permissions for Security Group, give the security group that will manage agents View and Modify on those domains. Workday notes you can currently use only unconstrained groups on these policies.
  5. Run Activate Pending Security Policy Changes again.

Workday says you do not need an extra SKU to use ASOR. Registering a self-built agent in a non-Production tenant does not require the Universal Main Service Agreement (UMSA); registering a Workday-built agent does.

Step 2: Find the tools the agent will call

Each tool is identified by a Workday ID (WID). There are two ways to find them:

  • Browse the tools explorer on the Developer Site, or call the ASOR Agent Resource Search API. Basic tools read, Advanced tools write, and Prompt tools are read-only helpers some Advanced tools need. Copy the WID of each one.
  • For SOAP and REST operations that are not Agent-Ready Tools, run Create Custom Report as an Advanced report on the data source Public Web Services (SOAP) or All Public Service Operations (REST), and add the operation name and its Workday ID as columns. Workday also publishes spreadsheets of REST and Graph API WIDs, and a list of REST APIs not available to ambient agents.

Step 3: Register the agent with the ASOR API

You need an access token for a user in the Setup: Agents domain. Workday gives two ways to get one:

  • Run Register API Client with the Authorization Code Grant type, Bearer token type and the scope (functional area) Agent System of Record, with Include Workday Owned Scope selected. Workday recommends one client per agent.
  • Or, if you use Extend, sign in to the tenant from the Developer Site under Tenant > Sign In to Tenant and take the token from there.

Look up two IDs first: the provider, with the View Agent Provider task, and the platform the agent runs on, with View Agent Platforms. Then send a POST to https://us.agent.workday.com/asor/v1/agentDefinition (swap us for your region) with the headers Authorization: Bearer <token> and wd-agent-tenant-alias: <your tenant>.

The body names the agent, its provider and platform, its skills, and under workdayConfig the tools (each with a tool_name and the WID as agent_resource.id) and the skill's executionMode: delegate or ambient. The ASOR API v1.2 documentation on Workday's GitHub pages has the schema. Sending the same name, version and provider again updates the definition instead of creating a second one.

Step 4: Configure the agent and choose who can use it

In the Agent Management Hub report, open the Agent Registry tab, select the agent and click Configure Agent.

  1. In the Status column, switch on each skill.
  2. For each delegate skill, fill the Available To prompt with the security groups that may use it.
  3. For delegate skills, enter the Redirect URI of your agent. For ambient skills, enter an X.509 public key that no other agent uses.
  4. Confirm. The first time you configure the agent, Workday shows its OAuth details: the authorize and token endpoints, the client ID, the client secret for delegate skills, and the ASU username for ambient ones. Copy the client ID and secret now. Workday states the page will not appear again.
  5. Back in the registry, select the agent and click Activate Agent.

Workday then creates the Agent System User and assigns an Agent Security Group. Find them in the All AI Agent Accounts report. An agent can have up to two ASUs, one for delegate and one for ambient mode. Activation can take up to a minute to reach Agent Gateway.

Step 5: Give the agent access to exactly what it needs

This step controls what the agent can act on. Run View Security for Agent Skill, which shows each tool's API with the domain or business process security policy behind it. For every policy, edit the permissions:

  • For a delegate agent, add the security groups of the people who will invoke it.
  • For an ambient agent, add the Ambient Agent Security Group that Workday generated.

Grant View or Modify, and Get or Put where the report shows an integration permission. Then activate the pending changes. Workday states that at runtime it checks both that the user may use the agent and that the user may use the APIs behind its tools, and that the security groups on Available To do not need to match the API policy groups one to one. Check that they overlap. The security checklist for ASOR walks through the delegate and ambient differences, and securing custom agents covers testing.

Workday's agent documentation does not list OAuth scopes for the agent at runtime. Access comes from the security groups above, not from scopes on the client.

Step 6: Authenticate through Agent Gateway

Every call goes through Agent Gateway, using the regional host for your tenant, for example us.agent.workday.com. Each request needs a wd-agent-tenant-alias header with your tenant alias. Through the gateway an agent can use all public REST and SOAP operations, the Graph API, WQL and RaaS.

For a delegate agent, use the OAuth 2.0 authorization code grant:

  1. Send the user to the authorize endpoint, https://us.agent.workday.com/auth/authorize/<tenant alias>, with client_id and response_type=code. The user signs in and sees an Allow/Deny page where they grant the agent access to their account.
  2. Exchange the returned code at https://us.agent.workday.com/auth/oauth2/<tenant alias>/token with the client ID and secret.

Workday says an external agent's access token is valid for 4 hours, that you cannot change that, and that the refresh token lasts 24 hours. Handle the expires_in value as either a number or a string, as Workday recommends. An ambient agent does not use a login. It signs a JWT with the key pair whose public half you registered, with the client ID as issuer and the ASU username as subject.

What can you audit afterwards?

  • View AI Agent User Audit Trail shows activity and separates By User from On Behalf Of User. For a delegate agent the agent is recorded as the actor and the person as the one it acted for; for an ambient agent the ASU is the actor.
  • All AI Agent Accounts lists the agents' accounts.
  • For a custom agent built in Workday, agent traces show what ran, the inputs and outputs of each step, for the latest 100 runs. Workday keeps traces for 30 days and limits them to the Admin, Developer and Specialist roles.
  • Workday recommends you examine the audit log for agent actions regularly.

Workday's input-and-output compliance reports are marked as available only for Workday-built agents, so do not count on them for an external agent. Log what your own agent sends on its side.

Where this leaves a first connection

Start with a delegate agent with one read-only tool, give it to one security group, and sign in as someone outside that group to see it refused before you add anything that writes.

Sources checked