Register External Agents for Workday-Enabled Adaptive Instances

Prerequisites

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 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 Concept: Workday 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.

Manually Authenticate an API Client

Access the

Register API Client

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>

Example:

https://us.agent.workday.com/auth/authorize/envops_gms1wd2-impl-services1?response_type=code&client_id=ZDBlZTMtdfgrdOGIwZC00NzRjLThmOWEtZTg4MGNjY2FmNDc2&state=test3pagent1&redirect_uri=https://www.workday.com

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.

Example:

curl --request POST \ --url https://wd2-impl-services1.workday.com/ccx/oauth2/envops_gms1/token \ --header 'authorization: Basic {base64 encoded client_id:client_secret}' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=authorization_code \ --data code=64yme4ubli3a4wj2oflqaq1k

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.

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.

Context:

To register an external agent, you must find the Workday Identifiers (WIDs) of the relevant Adaptive MCP tools you intend to include in your agent tool definition:

Tool Name	Tool Workday ID
metadata-search-by-term	77f25aa828701000149e3f8767a80000
metadata-search-by-ids	31b453fd7cfe100017abb68e5abb0000
data-modeled-query	77f25aa82870100014ab15b4da9f0000
data-dimensional-query	31b453fd7cfe1000178c39ce38100000
execute_matrix_report	31b453fd7cfe1000192d23c38b560000
report_matrix_get	31b453fd7cfe100017a100f2fec70000
sheet-get	93de9801ec82100029f6897560dc0000
sheet-get-definition	31b453fd7cfe100019382f0fdc340000
model-account-get-formula	31b453fd7cfe100017b61642ba100000
model-account-get-drivers	31b453fd7cfe100019135daf0cb40000
model-account-get-downstreams	31b453fd7cfe1000190ba5237abe0000
model-account-get-driver-leafs	31b453fd7cfe1000191c871ddd570000
model-dimension-get-overview	31b453fd7cfe100019001f4b7bec0000
model-links-get	31b453fd7cfe1000192579d00aea0000
get_activity_audit_events	31b453fd7cfe1000177aeda6c8ec0000
load_skill	31b453fd7cfe1000193fe7fe1e160000

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>

Example body:

{
  "name": "External Adaptive Agent",
  "description": "Greenco Adaptive Agent to access MCP tools",
  "provider": {
    "id": "Provider=SELF-BUILT"
  },
  "platform": {
    "id": "Platform=OTHER"
  },
  "url": "https://agent.workday.com",
  "skills": [
    {
      "description": "Adaptive MCP tools",
      "id": "AdaptiveSkillID",
      "inputModes": [
        {
          "type": "application/json"
        }
      ],
      "name": "Adaptive Skill",
      "outputModes": [
        {
          "type": "application/json"
        }
      ]
    }
  ],
  "workdayConfig": [
    {
      "workdayResources": [
        {
          "description": "Adaptive Tool Resource - metadata-search-by-term",
          "tool_name": "metadata-search-by-term",
          "agent_resource": {
            "id": "77f25aa828701000149e3f8767a80000"
          }
        },
        {
          "description": "Adaptive Tool Resource - data-modeled-query",
          "tool_name": "data-modeled-query",
          "agent_resource": {
            "id": "77f25aa82870100014ab15b4da9f0000"
          }
        }
      ],
      "executionMode": {
        "id": "Mode=Delegate"
      },
      "skillId": "AdaptiveSkillID"
    }
  ],
  "capabilities": {
    "stateTransitionHistory": false,
    "streaming": false,
    "pushNotifications": false
  },
  "supportsAuthenticatedExtendedCard": false,
  "version": "v1"
}

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. See Configure External Agents