Register External Agents

Prerequisites

You might need to take additional steps to enable this feature based on your organization's subscription service agreement. Your organization is either on the Main Service Agreement (MSA) or the Universal Main Service Agreement (UMSA). To determine your organization's subscription service agreement:

Select your profile avatar on Workday Community.

Select

Profile

On your profile page, select your organization's name, which is beneath your name and next to your job title.

View your

Subscription Service Agreement

value.

If the value is:

UMSA
, the feature is automatically available. Keep data contributions enabled to ensure full agent functionality. For more information on Machine Learning data contributions, see Concept: Workday AI for Universal Main Subscription Agreement Customers.

MSA
, your organization must opt in to UMSA and enable this feature through Innovation Services.

UMSA is required for non-production and production tenants for Workday-Built agents. UMSA is not required for non-production tenants for self-built agents.

For information about how using agents impacts your Flex Credits, see: Workday Flex Credits Community page.

Set Up Agent System of Record.

Security:

Agent Management Hub
domain in the Agent System of Record functional area. Required for validating that the agent is registered in Workday.

Manage Agents
domain in the Agent System of Record functional area. Required for activation and skill configuration.

Set Up: Tenant Setup - Security
domain in the System functional area. Required for registration.

Context

Currently, you can only register and define external agents in Workday by using the ASOR API. External agents are defined and registered simultaneously using the API, they are not two separate steps. You can use any API client of your preference to invoke the API.

Refer to ASOR v1.2 API documentation on Github and ASOR JSON Swagger documentation sample for troubleshooting.

Registration endpoints:

REST API Endpoint:

https://us.agent.workday.com/asor/v1/agentDefinition.

Token Endpoint:

https://us.agent.workday.com/auth/oauth2/<Tenant_Name>/token

Authorize Endpoint:

https://us.agent.workday.com/auth/authorize/<Tenant_Name>?response_type=code&client_id=<client_id>&state=test3pagent1&redirect_uri=<redirect_uri>

For information related to other regional availability outside of the U.S, see the Agent Gateway documentation: Reference: Regional Availability of Agent Gateway.

Authentication Options:

To register external agents, you need an access token in your ASOR API invocation. Below are the different options to obtain a token to invoke the ASOR API call.

Option 1: Manually Authenticate an API Client

Access the

task.

Client Name:

Enter a unique identifiable name for your agent. We recommend that you use a separate client for each agent so that they are easier to manage.

Client Grant Type:

Authorization Code Grant
.

Access Token Type:

Bearer
.

Redirection URI:

Enter a URL to redirect users to after authorization.

Scope (Functional Areas):

Agent System of Record
.

Include Workday Owned Scope:

Select this check box.

Copy and save the

Client ID

and

Client Secret

values. You can use these to get an access token to call the Definition API.

Paste this URL into a new window. It should redirect you to google.com with an appended code which you can use to call the API:

https://us.agent.workday.com/auth/authorize/<Tenant_Name>?response_type=code&client_id=<client_id>&state=test3pagent1&redirect_uri=<redirect_uri>

Create a new request using an external API Client (Example: Bruno): https://<tenantHost>/ccx/oauth2/<tenantName>/token

Body: grant_type=authorization_code&code=<authorizationCode>&client_id=<clientID>&client_secret=<ClientSecret>

Auth: Username = <ClientID>
, Password = <ClientSecret>
.

This generates an access token and refresh token that you can use to call the ASOR Agent Definition API.

As you complete this step, consider: Concept: External Agent ASU Considerations.

The user registering the agent must have access to the Setup: Agents domain in the Agent System of Record functional area to register an agent using the ASOR API.

Option 2: Authenticate Using Extend

If you're a Workday Extend or Workday Orchestrate user, you can retrieve an access token through Workday's developer site.

Access developer.workday.com and sign in.

On the top-right, click the user menu. The menu should display your current company name.

Click

Tenant

Select your environment and tenant and click

Connect to Tenant

Sign in to the tenant. You must sign in with an account that has access to the Setup: Agents
domain in the Agent System of Record functional area to register an agent using the ASOR API.

Register an External Agent Using the ASOR API

Prerequisites:

An access token for an account that has access to the Setup: Agents
domain in the Agent System of Record functional area.

An API Client of your choice.

Security: These domains in the System functional area:

Custom Report Creation

Manage: All Custom Reports

Report Tag Management

Context:

To register an external agent, you must:

Find the Workday Identifiers (WIDs) of the relevant Workday APIs (SOAP and REST) you intend to include in your agent’s Tools Definition by creating a custom report.

Find the Agent Provider using the

View Agent Provider

task.

Call the ASOR REST API

Finding SOAP and REST-based WIDs for Agent Tools Definition

Access the

Create Custom Report

task.

As you create the report, consider:

Option	Description
Report Type	Select Advanced .
Optimized for Performance	Unselect this check box.
Data Source	Select Public Web Services for SOAP APIs and All Public Service Operations for REST APIs.

For SOAP APIs: On the

Edit Custom Report

page, on the

Columns

tab of the report definition, add these rows:

Business Object	Field
Web Service	Web Service
Web Service Operation	Web Service Operation Name
Web Service Operation	Workday ID

For REST APIs: On the

Edit Custom Report

page, on the

Columns

tab of the report definition, add these rows:

Business Object	Field
Service Operation	Service
Service Operation	Name
Service Operation	Workday ID

Save and run the report.

As you retrieve WIDs for your APIs, you can also cross-reference these lists:

REST API WIDs

REST APIs Not Available for Ambient Agents

Graph API WIDs

Find the Agent Provider

Agent providers refer to who has built the agent and are displayed in the

Built By

field on the agent’s profile.

Access the

View Agent Provider

task, secured to the Setup: Agents
domain in the Agent System of Record functional area.

Use the Provider ID in your agent registration API call.

Find the Agent Platform

Agent platforms refer to the external platform or system the agent is developed and run on and are displayed in the

Built On

field on the agent’s profile.

Access the

View Agent Platforms

task, secured to the Setup Agents domain in the Agent System of Record functional area.

Use the Platform ID in your agent registration API call.

Call the ASOR REST API

Create a new request to register your agent using an external API Client, Example: Bruno.

As you create the request, consider:

Endpoint:

https://us.agent.workday.com/asor/v1/agentDefinition

Operation:

POST

Body:

Refer to ASOR v1.2 API documentation on Github and ASOR JSON Swagger documentation sample.

Headers:

Authorization: Bearer <token>

wd-agent-tenant-alias:<your tenant name>

Agent Management Hub

After you successfully load your agent definition into Workday, you can verify that it is registered by viewing it in the

Agent Management Hub

Access the

Agent Management Hub

report.

Click

Agent Registry

to display a list of your agents.

Click an agent to display overview information for it.

Next Steps

Configure your agent in Workday.

Sample ASOR API Agent Definition